代码库入职引导 是做什么的？
系统性地分析不熟悉的代码库，生成结构化的入职引导指南。适用于加入新项目或首次在现有仓库中配置 Claude Code 的开发者。
使用时机
- 首次使用 Claude Code 打开项目
- 加入新团队或仓库
- 用户请求“帮我理解这个代码库”
- 用户请求为项目生成 CLAUDE.md
- 用户说“引导我入门”或“带我浏览这个仓库”
工作原理
阶段 1：侦察
在不读取每个文件的情况下，收集项目的原始信号。并行执行以下检查：
1. 包清单检测
→ package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,
Gemfile, composer.json, mix.exs, pubspec.yaml
2. 框架指纹识别
→ next.config.*, nuxt.config.*, angular.json, vite.config.*,
django settings, flask app factory, fastapi main, rails config
3. 入口点识别
→ main.*, index.*, app.*, server.*, cmd/, src/main/
4. 目录结构快照
→ 目录树的顶层两层，忽略 node_modules、vendor、.git、dist、build、__pycache__、.next
5. 配置与工具检测
→ .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,
docker-compose*, .github/workflows/, .env.example, CI 配置
6. 测试结构检测
→ tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,
pytest.ini, jest.config.*, vitest.config.*
阶段 2：架构映射
从侦察数据中，识别：
技术栈
- 语言及版本约束
- 框架及主要库
- 数据库和 ORM
- 构建工具和打包工具
- CI/CD 平台
架构模式
- 单体应用、单体仓库、微服务或无服务器
- 前后端分离或全栈
- API 风格：REST、GraphQL、gRPC、tRPC
关键目录 将顶层目录映射到其用途：
src/components/ → React UI 组件
src/api/ → API 路由处理
src/lib/ → 共享工具函数
src/db/ → 数据库模型和迁移
tests/ → 测试套件
scripts/ → 构建和部署脚本
数据流 跟踪一个请求从入口到响应的完整路径：
- 请求从哪里进入？（路由器、处理函数、控制器）
- 如何验证？（中间件、模式、守卫）
- 业务逻辑在哪里？（服务、模型、用例）
- 如何到达数据库？（ORM、原生查询、仓库模式）
阶段 3：惯例检测
识别代码库已遵循的模式：
命名规范
- 文件命名：kebab-case、camelCase、PascalCase、snake_case
- 组件/类命名模式
- 测试文件命名：
*.test.ts、*.spec.ts、*_test.go
代码模式
- 错误处理风格：try/catch、Result 类型、错误码
- 依赖注入或直接导入
- 状态管理方法
- 异步模式：回调、Promise、async/await、channel
Git 惯例
- 从最近分支推断分支命名
- 从最近提交推断提交消息风格
- PR 工作流（squash、merge、rebase）
- 如果仓库没有提交或历史过浅（例如
git clone --depth 1），跳过此部分并注明“Git 历史不可用或过浅，无法检测惯例”
阶段 4：生成入职工件
输出两个产物：
输出 1：入职指南
# 入职指南：[项目名称]
## 概述
[2-3 句话：该项目的作用及服务对象]
## 技术栈
<!-- 以 Next.js 项目为例 — 替换为检测到的栈 -->
| 层 | 技术 | 版本 |
|----------|--------------|-------|
| 语言 | TypeScript | 5.x |
| 框架 | Next.js | 14.x |
| 数据库 | PostgreSQL | 16 |
| ORM | Prisma | 5.x |
| 测试 | Jest + Playwright | - |
## 架构
[描述组件如何连接的图示或文字]
## 关键入口点
<!-- 以 Next.js 项目为例 — 替换为检测到的路径 -->
- **API 路由**：`src/app/api/` — Next.js 路由处理
- **UI 页面**：`src/app/(dashboard)/` — 已认证页面
- **数据库**：`prisma/schema.prisma` — 数据模型真实来源
- **配置**：`next.config.ts` — 构建和运行时配置
## 目录映射
[顶层目录 → 用途映射]
## 请求生命周期
[跟踪一个 API 请求从入口到响应的完整路径]
## 惯例
- [文件命名模式]
- [错误处理方法]
- [测试模式]
- [Git 工作流]
## 常见任务
<!-- 以 Node.js 项目为例 — 替换为检测到的命令 -->
- **启动开发服务器**：`npm run dev`
- **运行测试**：`npm test`
- **运行 lint**：`npm run lint`
- **数据库迁移**：`npx prisma migrate dev`
- **构建生产版本**：`npm run build`
## 查阅指南
<!-- 以 Next.js 项目为例 — 替换为检测到的路径 -->
| 我想... | 请查看... |
|------------------------|----------------------|
| 添加一个 API 端点 | `src/app/api/` |
| 添加一个 UI 页面 | `src/app/(dashboard)/` |
| 添加一个数据库表 | `prisma/schema.prisma` |
| 添加一个测试 | 对应源码路径的 `tests/` |
| 更改构建配置 | `next.config.ts` |
输出 2：入门级 CLAUDE.md
根据检测到的惯例生成或更新项目特定的 CLAUDE.md。如果 CLAUDE.md 已存在，先读取并增强它——保留现有项目特定指令，并清晰标注新增或修改的内容。
# 项目说明
## 技术栈
[检测到的技术栈摘要]
## 代码风格
- [检测到的命名规范]
- [要遵循的检测到的模式]
## 测试
- 运行测试：`[检测到的测试命令]`
- 测试模式：[检测到的测试文件惯例]
- 覆盖率：[如果配置了，覆盖率命令]
## 构建与运行
- 开发：`[检测到的开发命令]`
- 构建：`[检测到的构建命令]`
- Lint：`[检测到的 lint 命令]`
## 项目结构
[关键目录 → 用途映射]
## 惯例
- [可检测到的提交风格]
- [可检测到的 PR 工作流]
- [错误处理模式]
最佳实践
- 不要阅读所有文件——侦察时应使用 Glob 和 Grep，而不是逐个 Read 每个文件。仅针对不明确的信号选择性读取。
- 验证，不要猜测——如果从配置检测到某个框架，但实际代码使用不同的框架，信任代码。
- 尊重现有的 CLAUDE.md——如果已存在，增强而非替换。标注哪些是新增的，哪些是原有的。
- 保持简洁——入职指南应在 2 分钟内可浏览完。细节应放在代码中，而非指南中。
- 标记未知项——如果不能可靠检测到某个惯例，请如实说明，而非猜测。“无法确定测试运行器”优于给出错误答案。
应避免的反模式
- 生成的 CLAUDE.md 超过 100 行——保持聚焦
- 列出所有依赖——仅突出影响编码方式的依赖
- 描述显而易见的目录名——
src/不需要解释 - 复制 README——入职指南补充了 README 缺少的结构性洞察
示例
示例 1：第一次进入新仓库
用户：“引导我入门这个代码库”
操作：执行完整的 4 阶段工作流 → 生成入职指南 + 入门级 CLAUDE.md
输出：入职指南直接打印到对话中，并在项目根目录写入 CLAUDE.md
示例 2：为现有项目生成 CLAUDE.md
用户：“为这个项目生成一个 CLAUDE.md”
操作：执行阶段 1-3，跳过入职指南，仅生成 CLAUDE.md
输出：包含检测到的惯例的项目特定 CLAUDE.md
示例 3：增强现有 CLAUDE.md
用户：“用当前项目惯例更新 CLAUDE.md”
操作：读取现有的 CLAUDE.md，执行阶段 1-3，合并新的发现
输出：新增内容清晰标注的更新版 CLAUDE.md