用途
Codebase Onboarding 用于系统化分析一个陌生的代码库，并产出一份结构化的上手引导文档。它面向刚加入新项目的开发者，或首次在既有仓库中配置 Claude Code 的用户。
适用时机包括：首次用 Claude Code 打开某个项目；加入新团队或新仓库；用户提出“帮我理解这个代码库”；用户要求为项目生成 CLAUDE.md；用户说“onboard me”或“walk me through this repo”。
工作流程
该技能分四个阶段执行。
阶段一：侦察
在不逐文件阅读的前提下收集项目原始信号，并并行执行以下检查：
- 包清单检测：package.json、go.mod、Cargo.toml、pyproject.toml、pom.xml、build.gradle、Gemfile、composer.json、mix.exs、pubspec.yaml
- 框架指纹识别：next.config.、nuxt.config.、angular.json、vite.config.*、django settings、flask app factory、fastapi main、rails config
- 入口点识别：main.、index.、app.、server.、cmd/、src/main/
- 目录结构快照：目录树的前两层，忽略 node_modules、vendor、.git、dist、build、pycache、.next
- 配置与工具检测：.eslintrc*、.prettierrc*、tsconfig.json、Makefile、Dockerfile、docker-compose*、.github/workflows/、.env.example、CI 配置
- 测试结构检测：tests/、test/、tests/、_test.go、.spec.ts、.test.js、pytest.ini、jest.config.、vitest.config.*
阶段二：架构映射
基于侦察数据识别以下内容。
技术栈：语言及版本约束；框架与主要库；数据库与 ORM；构建工具与打包器；CI/CD 平台。
架构模式：单体、monorepo、微服务或 serverless；前后端分离或全栈；API 风格 REST、GraphQL、gRPC 或 tRPC。
关键目录：将顶层目录映射到其用途，例如 src/components/ 对应 React UI 组件，src/api/ 对应 API 路由处理器，src/lib/ 对应共享工具，src/db/ 对应数据库模型与迁移，tests/ 对应测试套件，scripts/ 对应构建与部署脚本。
数据流：追踪一次请求从入口到响应的完整路径，包括请求在哪里进入（router、handler、controller）、如何校验（middleware、schemas、guards）、业务逻辑在哪里（services、models、use cases）、如何到达数据库（ORM、raw queries、repositories）。
阶段三：约定识别
识别代码库已有的模式。
命名约定：文件命名（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 历史不可用或过浅，无法识别约定”。
阶段四：生成上手产出
产出两项内容。
产出 1：Onboarding Guide（上手引导），包含 Overview、Tech Stack 表格、Architecture、Key Entry Points、Directory Map、Request Lifecycle、Conventions、Common Tasks、Where to Look 等章节。资料中的示例以 Next.js 项目为例，实际应替换为检测到的技术栈与路径。
产出 2：Starter CLAUDE.md，基于检测到的约定生成或更新项目专属的 CLAUDE.md。如果已存在 CLAUDE.md，先阅读再增强，保留既有项目专属指令，并明确标注新增或修改的内容。内容包含 Tech Stack、Code Style、Testing（运行测试命令、测试模式、覆盖率命令）、Build & Run（Dev、Build、Lint）、Project Structure、Conventions。
最佳实践
不要读所有文件——侦察应使用 Glob 和 Grep，而不是对每个文件 Read，仅在信号含糊时有选择地读取。
验证而非猜测——如果配置检测到某框架，但实际代码使用别的框架，以代码为准。
尊重现有 CLAUDE.md——若已存在，应增强而非替换，并标注哪些是新增、哪些是原有。
保持简洁——引导文档应在 2 分钟内可扫读，细节属于代码而非文档。
标记未知项——若无法确定某约定，应说明而非猜测，“Could not determine test runner”好过错误答案。
应避免的反模式
生成超过 100 行的 CLAUDE.md，应保持聚焦。
列出所有依赖，只应突出影响编码方式的依赖。
描述显而易见的目录名，src/ 不需要解释。
复制 README——上手引导应补充 README 所缺的结构性洞察。
使用示例
示例 1：首次进入新仓库。用户说“Onboard me to this codebase”，执行完整四阶段流程，产出上手引导与入门 CLAUDE.md，引导直接打印到对话中，CLAUDE.md 写入项目根目录。
示例 2：为既有项目生成 CLAUDE.md。用户说“Generate a CLAUDE.md for this project”，执行阶段一到三，跳过上手引导，仅产出 CLAUDE.md。
示例 3：增强现有 CLAUDE.md。用户说“Update the CLAUDE.md with current project conventions”，读取现有 CLAUDE.md，执行阶段一到三，合并新发现，输出带有明确新增标注的更新版 CLAUDE.md。
限制
资料未提供该技能的定价、调用平台支持范围、具体版本要求或性能指标，这些信息暂未提供。