The reviewed guide body for this track is currently maintained in Chinese.
预计阅读时间: 17 分钟
大型仓库里使用 Claude Code，核心能力不是“生成更多代码”，而是快速读懂边界：入口在哪里、数据怎么流动、哪些行为不能变、哪里适合小步重构。
这一篇讲如何让 Claude Code 帮你读仓库和做低风险重构。
阅读大型仓库的入口
给 Claude Code 的第一句话可以是：
请先不要改文件。帮我理解 <功能> 的调用链，列出入口、核心模块、数据结构和测试位置。
它应该优先找：
- 路由或 API 入口。
- 组件树或服务调用链。
- 数据模型和类型定义。
- 配置文件。
- 测试文件。
- 相关文档。
如果仓库很大，不要让它“读全仓库”。给一个功能域或报错入口更好。
要求它输出结构化地图
一个好的代码阅读输出可以这样：
入口：
- src/app/learn/page.tsx
数据：
- src/lib/learning.ts
渲染：
- src/app/components/LearningPageContent.tsx
- src/app/components/LearningArticle.tsx
SEO：
- src/app/sitemap.ts
- createPageMetadata
风险：
- 新专题必须进入 learningTopics，否则不会生成静态路由。
这种地图比单纯解释代码更有用，因为它能直接变成实施计划。
重构前先定义行为不变
重构提示：
我要重构 <模块>，目标是 <目标>。
请先列出必须保持不变的行为，并找出能验证这些行为的测试或检查。
例如学习模块的行为不变可能包括：
- 中文路由不变。
- 英文镜像不变。
- sitemap 包含所有 published topic 和 article。
- 文章内容在构建期静态渲染。
- 页脚备案号不消失。
- 图片缩放仍可用。
没有不变性，重构就是重写。
分步重构
要求 Claude Code 拆小步：
请把重构拆成 3 到 5 个可验证步骤。每一步说明改动范围和检查方式。
好的拆法：
1. 抽出重复函数，不改变调用。
2. 更新调用点，运行类型检查。
3. 删除旧路径，运行测试。
4. 检查生成页面关键内容。
坏的拆法：
重构整个模块，让它更清晰。
后者没有边界。
处理不确定代码
Claude Code 遇到不确定时，应该把假设说出来：
我看到这段逻辑可能同时影响 A 和 B。请先确认它们是否共用同一数据源，再改。
你也可以要求：
对不确定的地方只做分析，不要修改。
这适合权限、计费、数据迁移、兼容性和跨服务调用。
避免上下文污染
长时间重构容易发生上下文污染：前面讨论过的想法被当成当前事实，或者未完成方案混入实现。解决方法：
- 每个任务有明确目标。
- 每轮开始时让它总结“已确定事实”和“待确认假设”。
- 使用 Git diff 审查实际变化。
- 对并行任务使用分支或 worktree。
- 不在同一轮里混合产品设计、重构、部署和数据迁移。
如果任务已经偏离，直接让它停下整理：
暂停实现。请列出当前 diff、原始目标、已经偏离的地方和建议的收敛方案。
重构验收清单
- 行为不变性已列出。
- 只修改了目标模块。
- 没有顺手改无关样式和文案。
- 类型检查或测试通过。
- 关键页面或接口仍能工作。
- 文档中的架构说明同步更新。
如果缺少其中任何一项，就不要急着合并。
参考资料
- Claude Code common workflows: https://code.claude.com/docs/en/common-workflows
- Claude Code memory: https://code.claude.com/docs/en/memory
- Claude Code troubleshooting: https://code.claude.com/docs/en/troubleshooting