Claude Code 接手老项目：先读懂代码库、用 /init 生成 CLAUDE.md、再用计划模式小步修改

本文根据 Claude Code 官方文档《Common workflows》《How Claude remembers your project》《Best practices for Claude Code》《Commands》《Checkpointing》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

• 刚接手一个没人讲得清楚的老项目，打算让 Claude Code 帮忙上手的人；
• 已经用过 Claude Code，但每次开新会话都要重新解释项目结构的人；
• 想知道 /init 到底生成什么、生成之后该怎么改的人。

通用的「让 AI 读懂陌生代码」思路本站已有 /guides/ai-read-unfamiliar-codebase，本文只讲 Claude Code 自己的做法：命令、文件和设置。

结论先说

1. 先探索，后动手：官方的做法是从宽到窄提问，先要整体概览，再追问架构、数据模型、认证流程，这一步不改任何文件。
2. /init 生成 CLAUDE.md 只是起点：官方说它会分析代码库，写出它发现的构建命令、测试说明和项目约定；已有 CLAUDE.md 时，它给出改进建议而不是覆盖。生成后的工作主要是删行。
3. CLAUDE.md 只写 Claude 读代码读不出来的东西：官方建议每个文件控制在 200 行以内，写得具体、能验证。
4. 改动前先进计划模式，Claude 只读文件、提方案，你批准后才会动手；每一步都让它跑测试，并用 /rewind 兜底。

图：本站根据 Claude Code 官方文档：Common workflows 整理的示意图

第一步：只读探索，不要急着改

官方的流程很朴素：进入项目根目录，输入 claude 启动，然后先问高层问题。官方给的例子是 give me an overview of this codebase，接着再追问 explain the main architecture patterns used here、what are the key data models?、how is authentication handled?。官方的小贴士有三条：先宽后窄；问项目用到的编码约定；让它整理一份项目专用术语表。

找某个功能的代码时，官方也是三步：先让它找出相关文件，再问这些文件怎么配合，最后让它沿着执行流程从前端追到数据库。提问时多用项目里的专业词汇。

提示词 1：只读概览（可直接复制）

text
这是一个我刚接手的项目，请先只读不改，不要创建或修改任何文件。
请给我一份概览：1）这个项目是做什么的；2）目录结构和每个顶层目录的职责；3）用了哪些主要技术和框架；4）怎么安装依赖、启动、跑测试（给出具体命令，并说明你是从哪个文件看到的）；5）你看不懂或觉得可疑的地方，单独列出来。
凡是你没有在代码里直接看到的内容，请标注「推测」，不要写成确定的事实。

读大仓库时，探索会往上下文里塞很多文件内容。官方的建议是把探索交给子智能体（subagent）：它在自己的上下文窗口里读文件，只把结论汇报回来。官方的写法是直接说 use a subagent to investigate how our auth system handles token refresh。

提示词 2：交给子智能体调查

text
请用一个子智能体去调查「订单状态是怎么流转的」：从接口入口追到数据库写入，列出涉及的文件和函数，画出状态变化的顺序。
只把结论和关键文件路径汇报给我，不要把大段源码贴回来。

第二步：用 /init 生成 CLAUDE.md，然后删行

在会话里运行 /init。官方说明：Claude 会分析代码库并生成一个起始 CLAUDE.md，包含它发现的构建命令、测试说明和项目约定；如果文件已经存在，它建议改进而不是覆盖。如果项目里有 Cursor 规则（.cursor/rules/ 或 .cursorrules）或 Copilot 指令（.github/copilot-instructions.md），/init 会把相关部分读进来。想要更完整的交互式流程，可以先把环境变量 CLAUDE_CODE_NEW_INIT 设为 1，再运行 /init，这时它会问你要设置哪些东西（CLAUDE.md、技能、钩子）。另有 /import 命令，可以把别的编码代理的配置（例如 AGENTS.md）带进来。

生成之后别直接用。官方在最佳实践里的判断标准是两个问题：这件事 Claude 读代码能找到吗？它真的会去找吗？两个都是「是」就别写。适合留下的是：

• 怎么验证工作：测试、类型检查、静态检查的确切命令，以及怎么只跑一个测试文件；
• 代码里有误导性的地方：满处都是但新代码不该照抄的老写法，看起来没用其实还在用的目录；
• 仓库里没有的决定：团队约定的错误处理方式、部署流程、哪些改动要做迁移评审；
• 你已经纠正过两次以上的事。

官方给的 CLAUDE.md 示例只有十来行：命令、约定、坑三段。官方还建议：每个 CLAUDE.md 控制在 200 行以内；写法要具体可验证（「使用 2 空格缩进」而不是「格式要规范」）；只对部分目录有用的规则放进 .claude/rules/ 并用 paths: 限定范围；个人偏好放 CLAUDE.local.md 并加进 .gitignore。

写完后在会话里运行 /context all，检查「Memory files」列表里有没有它；运行 /doctor 可以建议删掉哪些 Claude 本来就能从代码推出来的内容，/doctor prompt-audit 会找出过时、指向不存在的文件或互相矛盾的指令，但官方说明它只出报告，你让它改它才改。关于 CLAUDE.md 与 AGENTS.md 的关系，见 /guides/claude-md-agents-md。

提示词 3：精简刚生成的 CLAUDE.md

text
请检查项目根目录的 CLAUDE.md：
1）删掉你读代码就能知道的内容；
2）保留并补全：安装、启动、跑全部测试、跑单个测试文件、类型检查、静态检查的确切命令；
3）把「这个项目里容易踩的坑」单独列一节，每条一句话，并注明依据的文件；
4）总长度控制在 100 行以内。
先给我修改后的全文和删减清单，我确认后再写入文件。

第三步：计划模式，先看方案再动手

官方提供三种进入计划模式的方式：启动时 claude --permission-mode plan；会话中按 Shift+Tab 切换，直到状态栏出现 ⏸ plan mode on；或者直接 /plan 加一句描述，例如 /plan fix the auth bug。计划模式下 Claude 读文件、提方案，批准之前不会改文件。更多说明见 /guides/claude-code-plan-mode。

提示词 4：计划模式下的小改动

text
我要修改的是：【具体需求，例如：订单列表按创建时间倒序，目前是正序】。
请只读不改，先告诉我：1）要改哪些文件、哪几个函数；2）现有的测试在哪里、能否覆盖这个改动；3）改动可能影响哪些调用方；4）你建议的最小改法，以及需要新增的测试。
不要顺手重构无关代码。

不知道自己想要什么的时候，官方还给了一个办法：让 Claude 采访你，写成规格文件。例如「Interview me until you could write the spec, then write it to SPEC.md」，之后开一个新会话照着 SPEC.md 做。

第四步：小步改、跑检查、能回退

官方的重构建议是小步、可测试地增量进行，并要求保持行为不变；改完让它运行测试。最佳实践里更强调：给 Claude 一个能返回通过或失败的检查，比如测试文件、构建的退出码、静态检查工具，没有它，Claude 只能凭「看起来做完了」收工。

提示词 5：带检查的小步修改

text
按刚才确认的方案实施，只改计划里列出的文件。
改完后运行【测试命令】，如果有失败，读输出并修复后再跑，直到通过。
最后告诉我：改了哪些文件，运行了什么命令，输出结果是什么。不要只说「测试通过」，要把命令和关键输出贴出来。

出错了怎么办：连按两次 Esc，或输入 /rewind，可以选择回退代码、回退对话，或两者同时回退。但官方明确说明有边界：只由 Bash 命令改动、且 Claude 没用文件编辑工具改过的文件不会被追踪，这类改动要用 Git 来撤销。老项目务必先确认工作区是干净的，或者先建一个分支。回退细节见 /guides/claude-code-rewind-checkpoints-undo。

图：本站根据官方 Best practices 与 Checkpointing 文档整理的示意图

常见问题

Q：对话越来越长，Claude 开始忘事怎么办？

重要结论写进 CLAUDE.md，别只留在对话里；对话本身的整理见 /guides/claude-code-context-compact。官方还提到，会话中可以用 /context 看是什么占满了上下文。

Q：下次接着做，怎么找回上次的会话？

官方写的是 claude --continue 恢复当前目录最近的会话，claude --resume 从列表里选。

Q：大型 monorepo 也这样做吗？

官方有单独一页讲 monorepo 和大型代码库的配置，思路是在子目录放嵌套的 CLAUDE.md，让规则只在对应目录生效。

订阅和额度

Claude Code 需要付费订阅账号登录，读大项目、跑多轮会话会消耗较多额度。想了解订阅选择可以看 /chongzhi/claude-code，价格和额度以官方页面当前显示为准。

相关教程

• /guides/claude-code-getting-started：安装、登录和第一个任务
• /guides/claude-code-best-practices：官方最佳实践整理
• /guides/ai-read-unfamiliar-codebase：通用的读陌生代码思路

参考资料

• Claude Code 文档：Common workflows — https://code.claude.com/docs/en/common-workflows
• Claude Code 文档：How Claude remembers your project — https://code.claude.com/docs/en/memory
• Claude Code 文档：Best practices for Claude Code — https://code.claude.com/docs/en/best-practices
• Claude Code 文档：Commands — https://code.claude.com/docs/en/commands
• Claude Code 文档：Checkpointing — https://code.claude.com/docs/en/checkpointing