文章目录 / 点击展开
接手陌生项目时，Claude Code 最有价值的能力不是立即生成代码，而是帮助建立仓库地图、追踪请求路径和暴露缺失上下文。先理解、再计划、最后小步修改，能显著降低“改对一处、破坏另一处”的风险。
适用场景与使用边界
这套流程适合接手旧项目、修复跨文件缺陷、评估新需求影响和准备代码评审。它不适合在没有运行权限、测试方式和业务规则的情况下直接执行大规模重构。
开始前确认仓库是否允许交给外部模型处理，排除密钥、生产数据、客户信息和内部证书。只给工具完成当前任务所需的最小目录权限。
第一步：建立仓库地图
先让 Claude Code 列出入口、核心模块、数据存储、外部服务、测试目录和构建脚本，并说明每个判断来自哪个文件。
请只分析仓库，不修改文件。
输出：技术栈、启动入口、核心目录、主要数据流、外部依赖、测试与构建命令、仍需确认的问题。
每条结论引用具体路径；无法确认时明确说明，不要猜测。仓库地图应控制在一页以内。若输出只是逐目录复述，应继续追问“用户请求从哪里进入、经过什么模块、最终在哪里产生结果”。
第二步：追踪目标功能的运行路径
围绕一个真实任务追踪调用链，例如“创建订单”“登录失败”或“导出报表”。要求区分同步路径、异步任务、缓存、数据库和第三方调用。
不要一次追踪多个功能。每找到一个关键函数，就核对调用方、输入、返回值和错误处理。模型引用不存在的函数或忽略条件分支时，立即停止并补充证据。
第三步：确认仓库规则
搜索适用的 AGENTS.md、README、贡献指南、代码格式、测试命令和最近同类实现。让工具总结必须遵守的约束，但不要允许它用“更现代”的个人偏好覆盖已有项目风格。
根据仓库现有文件，总结本任务必须遵守的规则：
代码风格、模块边界、错误处理、测试位置、命名、依赖限制和发布要求。
区分明确规则与从代码推断的惯例。第四步：生成影响范围清单
在提出方案前，列出需要修改、需要读取但不修改、需要新增测试和明确不应触碰的文件。对数据库、API、配置和公共组件变化单独标记兼容性风险。
要求每个风险配验证方法。例如“可能影响缓存”必须说明检查哪个键、指标或测试，而不是停留在泛泛提醒。
第五步：形成可执行计划
计划应拆成可以独立验证的小步骤，每一步包含目标、文件、行为变化、测试和回滚方式。先完成最小闭环，再处理可选优化。
基于已确认的运行路径和仓库规则，制定最小改动计划。
每步写：行为目标、涉及文件、实现要点、验证命令、失败时如何回退。
不要加入与需求无关的重构或依赖升级。实施检查清单
- 是否先建立仓库地图并核对关键路径。
- 所有结论是否引用真实文件和函数。
- 是否找到适用的项目规则和测试方式。
- 改动范围是否包含明确的“不修改区域”。
- 每一步是否可以独立验证和回滚。
- 是否先运行针对性测试，再运行更广测试。
- 最终 diff 是否只包含任务相关变化。
常见问题
Claude Code 可以直接扫描整个电脑吗
不应提供不必要的目录权限。只在目标仓库中运行，并排除密钥、备份、下载目录和其他项目。
仓库没有测试怎么办
先找到可重复的手工验证路径，再为高风险行为补充最小回归测试。不要因为没有测试就扩大改动范围。
为什么不先让它生成代码
陌生仓库最缺的是上下文。先生成代码容易违反模块边界、错误处理和兼容要求，后续返工成本更高。
需要进入具体编码阶段时，可配合 Cursor 结对编程工作流，完成后使用 GitHub Copilot 代码审查流程 做独立复核。