codebase-onboarding

原文涵盖的主题

• 代码库入门引导
• 使用时机
• 工作原理
• 阶段 1：初步侦察
• 阶段 2：架构映射
• 阶段 3：规范检测
• 阶段 4：生成入门工件
• 输出 1：入门指南

系统性地分析一个不熟悉的代码库，并生成结构化的入门指南。专为加入新项目的开发者或首次在现有仓库中设置 Claude Code 的用户设计。 首次使用 Claude Code 打开项目时 加入新团队或新仓库时 用户询问“帮我理解这个代码库” 用户要求为项目生成 CLAUDE.md 文件 用户说“带我入门”或“带我浏览这个仓库” 在不阅读每个文件的情况下，收集关于项目的原始信息。并行运行以下检查： 根据侦察数据，识别： 技术栈 语言及版本限制 框架及主要库 数据库及 ORM 构建工具和打包器 CI/CD 平台 架构模式 单体、单体仓库、微服务，还是无服务器 前端/后端分离，还是全栈 API 风格：REST、GraphQL、gRPC、tRPC 关键目录 将顶级目录映射到其用途： 数据流 追踪一个请求从入口到响应的路径： 请求从哪里进入？（路由器、处理器、控制器） 如何进行验证？（中间件、模式、守卫） 业务逻辑在哪里？（服务、模型、用例） 如何访问数据库？（ORM、原始查询、存储库） 识别代码库已遵循的模式： 命名规范 文件命名：kebab-case、camelCase、PascalCase、snake\case 组件/类命名模式 测试文件命名：.test.ts、.spec.ts、test.go 代码模式 错误处理风格：try/catch、Result 类型、错误码 依赖注入还是直接导入 状态管理方法 异步模式：回调、Promise、async/await、通道 Git 规范 根据最近分支推断分支命名 根据最近提交推断提交信息风格 PR 工作流（压缩合并、合并、变基） 如果仓库尚无提交记录或历史记录很浅（例如 git clone --depth 1），则跳过此部分并注明“Git 历史记录不可用或过浅，无法检测规范” 生成两个输出： 根据检测到的规范，生成或更新项目特定的 CLAUDE.md。如果 CLAUDE.md 已存在，请先读取它并进行增强——保留现有的项目特定说明，并明确标注新增或更改的内容。 1. 不要通读所有内容 —— 侦察阶段应使用 Glob 和 Grep，而非读取每个文件。仅在信号不明确时有选择性地读取。 2. 验证而非猜测 —— 如果从配置文件中检测到某个框架，但实际代码使用了不同的东西，请以代码为准。 3. 尊重现有的 CLAUDE.md —— 如果文件已存在，请增强它而不是替换它。明确标注哪些是新增内容，哪些是原有内容。 4. 保持简洁 —— 入门指南应在 2 分钟内可快速浏览。细节应留在代码中，而非指南里。 5. 标记未知项 —— 如果无法自信地检测到某个规范，请如实说明而非猜测。“无法确定测试运行器”比给出错误答案更好。 生成超过 100 行的 CLAUDE.md —— 保持其聚焦 列出每个依赖项 —— 仅突出那些影响编码方式的依赖 描述显而

这里只展示节选，请以完整原文和当前要求为准。