npx skills add https://github.com/borghei/claude-skills --skill codebase-onboarding层级: 强大 类别: 工程 / 开发者体验 维护者: Claude Skills 团队
分析任何代码库,并生成针对受众量身定制的生产级入门文档。生成包含系统图的架构概览、带注释的关键文件映射、分步本地设置指南、常见开发者任务操作手册、包含实际错误解决方案的调试指南以及贡献指南。支持 Markdown、Notion 和 Confluence 输出格式。
代码库入门,开发者体验,文档,架构概览,设置指南,调试指南,贡献指南,代码走查,新员工入职
git clone 到运行测试的分步指南广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
在生成任何文档之前,运行这些分析命令来收集数据。
# 1. 包清单和脚本
cat package.json 2>/dev/null | python3 -c "
import json, sys
pkg = json.load(sys.stdin)
print(f\"Name: {pkg.get('name')}\")
print(f\"Scripts: {list(pkg.get('scripts', {}).keys())}\")
print(f\"Deps: {len(pkg.get('dependencies', {}))}\")
print(f\"DevDeps: {len(pkg.get('devDependencies', {}))}\")
" || echo "No package.json found"
# 2. 目录结构(前 3 层,排除干扰项)
find . -maxdepth 3 \
-not -path '*/node_modules/*' \
-not -path '*/.git/*' \
-not -path '*/.next/*' \
-not -path '*/__pycache__/*' \
-not -path '*/dist/*' \
-not -path '*/.venv/*' | \
sort | head -80
# 3. 最大的源文件(复杂度指标)
find src/ app/ lib/ -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.go" 2>/dev/null | \
xargs wc -l 2>/dev/null | sort -rn | head -20
# 4. API 路由
find . -name "route.ts" -path "*/api/*" 2>/dev/null | sort # Next.js
grep -rn "router\.\(get\|post\|put\|delete\)" src/ --include="*.ts" 2>/dev/null | head -30 # Express
# 5. 数据库模式位置
find . -name "schema.ts" -o -name "schema.prisma" -o -name "models.py" 2>/dev/null | head -10
# 6. 测试基础设施
find . -name "*.test.ts" -o -name "*.spec.ts" -o -name "test_*.py" 2>/dev/null | wc -l
# 7. 近期重大变更(最近 90 天)
git log --oneline --since="90 days ago" | grep -iE "feat|refactor|breaking|migrate" | head -20
# 8. CI/CD 配置
ls .github/workflows/ 2>/dev/null || ls .gitlab-ci.yml 2>/dev/null || echo "No CI config found"
# 9. 代码中引用的环境变量
grep -rh "process\.env\.\|os\.environ\.\|os\.getenv" src/ app/ lib/ --include="*.ts" --include="*.py" 2>/dev/null | \
grep -oE "[A-Z_]{3,}" | sort -u | head -30
根据收集到的事实,对项目进行分类:
| 信号 | 架构模式 |
|---|---|
包含 page.tsx 的 app/ 目录 | Next.js App Router(基于文件的路由) |
包含 Express 导入的 src/routes/ | Express REST API |
| FastAPI 装饰器 | Python REST/异步 API |
包含多个服务的 docker-compose.yml | 微服务 |
包含处理程序的单一 main.go | Go 单体应用 |
根目录下的 packages/ 或 apps/ | 单体仓库 |
| Prisma/Drizzle 模式文件 | ORM 管理的数据库 |
k8s/ 或 terraform/ 目录 | 基础设施即代码 |
## 架构
### 系统图
[使用下面的 ASCII 图模式 — 它在任何 markdown 查看器中都能渲染]
浏览器 / 移动应用 │ v [API 网关 / 负载均衡器] │ ├──> [Web 服务器:Next.js / Express / FastAPI] │ ├── 认证(JWT / OAuth) │ ├── 业务逻辑 │ └── 后台作业 │ ├──> [主数据库:PostgreSQL] │ └── 由 [ORM] 管理的迁移 │ ├──> [缓存:Redis] │ └── 会话、速率限制、作业队列 │ └──> [对象存储:S3 / R2] └── 文件上传、静态资源
外部集成: ├── [Stripe] — 支付 ├── [SendGrid / Resend] — 事务性邮件 └── [Sentry] — 错误跟踪
### 技术栈
| 层级 | 技术 | 用途 |
|-------|-----------|---------|
| 前端 | [框架] | [选择原因] |
| API | [框架] | [路由、中间件] |
| 数据库 | [数据库 + ORM] | [数据存储、迁移] |
| 认证 | [提供商] | [认证方法] |
| 队列 | [系统] | [后台处理] |
| 部署 | [平台] | [托管、CI/CD] |
| 监控 | [工具] | [错误、性能] |
## 关键文件
优先文件 — 首先阅读这些以理解系统:
| 优先级 | 路径 | 功能 | 何时阅读 |
|----------|------|-------------|-------------|
| 1 | `src/db/schema.ts` | 数据库模式 — 数据模型的单一事实来源 | 第一天 |
| 2 | `src/lib/auth.ts` | 认证配置和会话处理 | 第一天 |
| 3 | `app/api/` | 所有 API 路由处理程序 | 第一周 |
| 4 | `middleware.ts` | 请求中间件(认证、日志记录、速率限制) | 第一周 |
| 5 | `.env.example` | 所有带描述的环境变量 | 设置日 |
危险文件 — 修改前需协调:
| 路径 | 风险 | 所需协调 |
|------|------|----------------------|
| `src/db/schema.ts` | 模式变更影响所有服务 | 需数据库所有者进行 PR 审查 |
| `middleware.ts` | 影响每个请求 | 变更后进行负载测试 |
| `lib/stripe.ts` | 支付处理 | 通知财务团队 |
## 本地设置(目标:10 分钟内)
### 先决条件
| 工具 | 所需版本 | 安装命令 |
|------|-----------------|----------------|
| Node.js | 20+ | `nvm install 20` |
| pnpm | 9+ | `corepack enable && corepack prepare pnpm@latest` |
| Docker | 24+ | [docker.com/get-docker](https://docker.com/get-docker) |
| PostgreSQL | 16+ | 通过 Docker(见步骤 3) |
### 步骤
**步骤 1:克隆并安装** (2 分钟)
```bash
git clone [repo-url]
cd [repo-name]
pnpm install
步骤 2:配置环境 (1 分钟)
cp .env.example .env
# 编辑 .env — 最小必需值:
# DATABASE_URL=postgresql://dev:dev@localhost:5432/myapp
# APP_SECRET=$(openssl rand -base64 32)
步骤 3:启动基础设施 (1 分钟)
docker compose up -d
# 启动:PostgreSQL, Redis
# 验证:docker compose ps(所有应显示 "running")
步骤 4:设置数据库 (1 分钟)
pnpm db:migrate
pnpm db:seed # 可选:加载测试数据
步骤 5:启动开发服务器 (30 秒)
pnpm dev
# 应用运行于 http://localhost:3000
http://localhost:3000/api/health 返回 {"status": "ok"}
pnpm test 通过且无失败
您可以使用种子测试用户登录(凭据见 .env.example)
## 调试指南
### 常见错误及修复
**`Error: connect ECONNREFUSED 127.0.0.1:5432`**
原因:PostgreSQL 未运行 修复:docker compose up -d postgres 验证:docker compose ps postgres(应显示 "running")
**`Error: relation "users" does not exist`**
原因:迁移尚未应用 修复:pnpm db:migrate 验证:pnpm db:migrate status(应显示全部已应用)
**`TypeError: Cannot read property 'id' of null`**
原因:会话为 null — 通常是缺少或过期的认证令牌 修复:检查请求是否包含有效的 Authorization 头 调试:在路由处理程序中添加 console.log(session) 以检查
### 日志查找位置
| 环境 | 位置 | 命令 |
|-------------|----------|---------|
| 本地开发 | 运行 `pnpm dev` 的终端 | 在终端中向上滚动 |
| 本地数据库 | Docker 日志 | `docker compose logs postgres` |
| 预发布 | [平台仪表板] | [预发布日志链接] |
| 生产 | [平台仪表板] | [生产日志链接] |
### 有用的诊断命令
```bash
# 检查数据库连接性
psql $DATABASE_URL -c "SELECT 1"
# 查看活跃的数据库连接
psql $DATABASE_URL -c "SELECT count(*), state FROM pg_stat_activity GROUP BY state"
# 检查特定迁移是否已应用
pnpm db:migrate status
# 清除本地缓存
redis-cli FLUSHDB
# 验证环境变量是否已加载
node -e "console.log(process.env.DATABASE_URL ? 'Set' : 'MISSING')"
## 针对受众的定制
### 初级开发者补充
- 首次使用时解释缩写词(ORM、RLS、JWT 等)
- 添加包含 5 个文件的"先读这些"有序阅读列表
- 包含 UI 相关流程的截图
- 链接到关键技术的外部学习资源
- 为特定领域术语添加"术语表"部分
### 高级工程师补充
- 链接到架构决策记录
- 包含性能基准
- 记录已知的技术债务和计划改进
- 提供包含威胁边界的安防模型概览
- 分享扩展限制和计划的容量变更
### 承包商补充
- 定义范围边界("仅修改 src/features/your-feature/ 中的文件")
- 指定沟通渠道和响应期望
- 记录所需系统的访问请求流程
- 包含时间记录要求和报告周期
- 列出禁止的操作(直接推送到 main、模式变更等)
## 质量验证
生成入门文档后,使用此清单进行验证:
1. **全新机器测试** — 新开发者能否在干净的机器上逐字遵循设置指南?
2. **10 分钟目标** — 本地设置是否能在 10 分钟内完成?
3. **错误覆盖** — 文档记录的错误是否与开发者实际遇到的相符?
4. **链接有效性** — 所有指向外部资源和内部文档的链接是否都能解析?
5. **时效性** — 所有版本号、命令和截图是否都是最新的?
## 常见陷阱
- **文档只写一次,从不更新** — 在 PR 模板中添加文档更新检查
- **缺少架构决策的"原因"** — 记录原因,而不仅仅是内容
- **未经测试的设置说明** — 每季度在全新机器上测试文档
- **没有调试部分** — 对于新员工来说,调试指南是最有价值的部分
- **为错误受众提供过多细节** — 承包商需要特定任务的文档,而非深入的架构
- **过时的截图** — UI 截图很快会过时;尽可能链接到运行实例
## 最佳实践
1. **保持设置在 10 分钟以内** — 如果耗时更长,请修复设置流程,而不是文档
2. **测试文档** — 让新员工严格按照文档操作,并修复他们遇到的每个问题
3. **链接,而非重复** — 引用 ADR、问题和外部文档,而不是复制内容
4. **在与代码变更相同的 PR 中更新文档** — 文档漂移是首要的失败模式
5. **特定版本的注释** — 指出近期版本的变化,以便回归的开发者能跟上进度
6. **操作手册优于理论** — "运行此命令"比"系统使用 Redis 进行缓存"更有用
7. **关键文件映射是必需的** — 每个项目都应有一个包含 10-20 个最重要文件的注释列表
每周安装次数
1
代码仓库
GitHub 星标数
29
首次出现
今天
安全审计
安装于
zencoder1
amp1
cline1
openclaw1
opencode1
cursor1
Tier: POWERFUL Category: Engineering / Developer Experience Maintainer: Claude Skills Team
Analyze any codebase and generate production-quality onboarding documentation tailored to the audience. Produces architecture overviews with system diagrams, annotated key file maps, step-by-step local setup guides, common developer task runbooks, debugging guides with real error solutions, and contribution guidelines. Supports Markdown, Notion, and Confluence output formats.
codebase onboarding, developer experience, documentation, architecture overview, setup guide, debugging guide, contribution guidelines, code walkthrough, new hire onboarding
git clone to running testsRun these analysis commands to collect data before generating any documentation.
# 1. Package manifest and scripts
cat package.json 2>/dev/null | python3 -c "
import json, sys
pkg = json.load(sys.stdin)
print(f\"Name: {pkg.get('name')}\")
print(f\"Scripts: {list(pkg.get('scripts', {}).keys())}\")
print(f\"Deps: {len(pkg.get('dependencies', {}))}\")
print(f\"DevDeps: {len(pkg.get('devDependencies', {}))}\")
" || echo "No package.json found"
# 2. Directory structure (top 3 levels, excluding noise)
find . -maxdepth 3 \
-not -path '*/node_modules/*' \
-not -path '*/.git/*' \
-not -path '*/.next/*' \
-not -path '*/__pycache__/*' \
-not -path '*/dist/*' \
-not -path '*/.venv/*' | \
sort | head -80
# 3. Largest source files (complexity indicators)
find src/ app/ lib/ -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.go" 2>/dev/null | \
xargs wc -l 2>/dev/null | sort -rn | head -20
# 4. API routes
find . -name "route.ts" -path "*/api/*" 2>/dev/null | sort # Next.js
grep -rn "router\.\(get\|post\|put\|delete\)" src/ --include="*.ts" 2>/dev/null | head -30 # Express
# 5. Database schema location
find . -name "schema.ts" -o -name "schema.prisma" -o -name "models.py" 2>/dev/null | head -10
# 6. Test infrastructure
find . -name "*.test.ts" -o -name "*.spec.ts" -o -name "test_*.py" 2>/dev/null | wc -l
# 7. Recent significant changes (last 90 days)
git log --oneline --since="90 days ago" | grep -iE "feat|refactor|breaking|migrate" | head -20
# 8. CI/CD configuration
ls .github/workflows/ 2>/dev/null || ls .gitlab-ci.yml 2>/dev/null || echo "No CI config found"
# 9. Environment variables referenced in code
grep -rh "process\.env\.\|os\.environ\.\|os\.getenv" src/ app/ lib/ --include="*.ts" --include="*.py" 2>/dev/null | \
grep -oE "[A-Z_]{3,}" | sort -u | head -30
Based on gathered facts, classify the project:
| Signal | Architecture Pattern |
|---|---|
app/ directory with page.tsx | Next.js App Router (file-based routing) |
src/routes/ with Express imports | Express REST API |
| FastAPI decorators | Python REST/async API |
docker-compose.yml with multiple services | Microservices |
Single main.go with handlers | Go monolith |
packages/ or at root |
## Architecture
### System Diagram
[Use the ASCII diagram pattern below — it renders in any markdown viewer]
Browser / Mobile App │ v [API Gateway / Load Balancer] │ ├──> [Web Server: Next.js / Express / FastAPI] │ ├── Authentication (JWT / OAuth) │ ├── Business Logic │ └── Background Jobs │ ├──> [Primary Database: PostgreSQL] │ └── Migrations managed by [ORM] │ ├──> [Cache: Redis] │ └── Sessions, rate limits, job queue │ └──> [Object Storage: S3 / R2] └── File uploads, static assets
External Integrations: ├── [Stripe] — Payments ├── [SendGrid / Resend] — Transactional email └── [Sentry] — Error tracking
### Tech Stack
| Layer | Technology | Purpose |
|-------|-----------|---------|
| Frontend | [framework] | [why chosen] |
| API | [framework] | [routing, middleware] |
| Database | [database + ORM] | [data storage, migrations] |
| Auth | [provider] | [authentication method] |
| Queue | [system] | [background processing] |
| Deployment | [platform] | [hosting, CI/CD] |
| Monitoring | [tool] | [errors, performance] |
## Key Files
Priority files — read these first to understand the system:
| Priority | Path | What It Does | When to Read |
|----------|------|-------------|-------------|
| 1 | `src/db/schema.ts` | Database schema — single source of truth for data model | First day |
| 2 | `src/lib/auth.ts` | Authentication configuration and session handling | First day |
| 3 | `app/api/` | All API route handlers | First week |
| 4 | `middleware.ts` | Request middleware (auth, logging, rate limiting) | First week |
| 5 | `.env.example` | All environment variables with descriptions | Setup day |
Dangerous files — coordinate before modifying:
| Path | Risk | Coordination Required |
|------|------|----------------------|
| `src/db/schema.ts` | Schema changes affect all services | PR review from DB owner |
| `middleware.ts` | Affects every request | Load test after changes |
| `lib/stripe.ts` | Payment processing | Finance team notification |
## Local Setup (Target: under 10 minutes)
### Prerequisites
| Tool | Required Version | Install Command |
|------|-----------------|----------------|
| Node.js | 20+ | `nvm install 20` |
| pnpm | 9+ | `corepack enable && corepack prepare pnpm@latest` |
| Docker | 24+ | [docker.com/get-docker](https://docker.com/get-docker) |
| PostgreSQL | 16+ | Via Docker (see step 3) |
### Steps
**Step 1: Clone and install** (2 min)
```bash
git clone [repo-url]
cd [repo-name]
pnpm install
Step 2: Configure environment (1 min)
cp .env.example .env
# Edit .env — minimum required values:
# DATABASE_URL=postgresql://dev:dev@localhost:5432/myapp
# APP_SECRET=$(openssl rand -base64 32)
Step 3: Start infrastructure (1 min)
docker compose up -d
# Starts: PostgreSQL, Redis
# Verify: docker compose ps (all should show "running")
Step 4: Set up database (1 min)
pnpm db:migrate
pnpm db:seed # Optional: loads test data
Step 5: Start dev server (30 sec)
pnpm dev
# App runs at http://localhost:3000
http://localhost:3000 loads the app
http://localhost:3000/api/health returns {"status": "ok"}
pnpm test passes with no failures
You can log in with the seeded test user (see .env.example for credentials)
## Debugging Guide
### Common Errors and Fixes
**`Error: connect ECONNREFUSED 127.0.0.1:5432`**
Cause: PostgreSQL is not running Fix: docker compose up -d postgres Verify: docker compose ps postgres (should show "running")
**`Error: relation "users" does not exist`**
Cause: Migrations have not been applied Fix: pnpm db:migrate Verify: pnpm db:migrate status (should show all applied)
**`TypeError: Cannot read property 'id' of null`**
Cause: Session is null — usually a missing or expired auth token Fix: Check that the request includes a valid Authorization header Debug: Add console.log(session) in the route handler to inspect
### Where to Find Logs
| Environment | Location | Command |
|-------------|----------|---------|
| Local dev | Terminal running `pnpm dev` | Scroll up in terminal |
| Local DB | Docker logs | `docker compose logs postgres` |
| Staging | [Platform dashboard] | [Link to staging logs] |
| Production | [Platform dashboard] | [Link to production logs] |
### Useful Diagnostic Commands
```bash
# Check database connectivity
psql $DATABASE_URL -c "SELECT 1"
# View active database connections
psql $DATABASE_URL -c "SELECT count(*), state FROM pg_stat_activity GROUP BY state"
# Check if a specific migration was applied
pnpm db:migrate status
# Clear local caches
redis-cli FLUSHDB
# Verify environment variables are loaded
node -e "console.log(process.env.DATABASE_URL ? 'Set' : 'MISSING')"
## Audience-Specific Customization
### Junior Developer Additions
- Explain acronyms on first use (ORM, RLS, JWT, etc.)
- Add "read this first" ordered reading list of 5 files
- Include screenshots for UI-related flows
- Link to external learning resources for key technologies
- Add a "glossary" section for domain-specific terms
### Senior Engineer Additions
- Link to Architecture Decision Records (ADRs)
- Include performance benchmark baselines
- Document known technical debt and planned improvements
- Provide security model overview with threat boundaries
- Share scaling limits and planned capacity changes
### Contractor Additions
- Define scope boundaries ("only modify files in src/features/your-feature/")
- Specify communication channels and response expectations
- Document access request process for required systems
- Include time logging requirements and reporting cadence
- List prohibited actions (direct push to main, schema changes, etc.)
## Quality Verification
After generating onboarding docs, validate with this checklist:
1. **Fresh machine test** — can a new developer follow the setup guide verbatim on a clean machine?
2. **10-minute target** — does local setup complete in under 10 minutes?
3. **Error coverage** — do the documented errors match what developers actually encounter?
4. **Link validity** — do all links to external resources and internal docs resolve?
5. **Currency** — are all version numbers, commands, and screenshots current?
## Common Pitfalls
- **Docs written once, never updated** — add doc update checks to the PR template
- **Missing "why" for architecture decisions** — document why, not just what
- **Untested setup instructions** — test the docs on a fresh machine quarterly
- **No debugging section** — the debugging guide is the most valuable section for new hires
- **Too much detail for the wrong audience** — contractors need task-specific docs, not deep architecture
- **Stale screenshots** — UI screenshots go stale fast; link to running instances when possible
## Best Practices
1. **Keep setup under 10 minutes** — if it takes longer, fix the setup process, not the docs
2. **Test the docs** — have a new hire follow them literally and fix every gap they hit
3. **Link, do not repeat** — reference ADRs, issues, and external docs instead of duplicating
4. **Update docs in the same PR as code changes** — documentation drift is the number one failure mode
5. **Version-specific notes** — call out what changed in recent versions so returning developers catch up
6. **Runbooks over theory** — "run this command" is more useful than "the system uses Redis for caching"
7. **Key file map is mandatory** — every project should have an annotated list of the 10-20 most important files
Weekly Installs
1
Repository
GitHub Stars
29
First Seen
Today
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
zencoder1
amp1
cline1
openclaw1
opencode1
cursor1
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
147,400 周安装
apps/| Monorepo |
| Prisma/Drizzle schema file | ORM-managed database |
k8s/ or terraform/ directories | Infrastructure as Code |