Claude Code 如何接手已有项目：从读懂代码到完成第一个改动

让 Claude Code 接手已有项目，建议先选一个你想弄清楚的行为，让它找出入口、实现和测试，再动手改代码。同样的方法也适用于 Codex。

“理解整个仓库并优化它”很难验收。“找出搜索页在哪里拼接 URL，解释它如何保留筛选条件，并找到对应测试”则有明确的检查对象。

下面是一套可以直接使用的首轮任务模板。读懂代码后，如果想做一个完整练习，可以继续看带可运行示例的 Bug 修复教程。

1. 先确认你正在操作哪一份项目

让 Agent 开始之前，先确认工作目录和分支。在 Git 仓库里，可以运行下面这些只读命令：

git status --short --branchgit diff --statgit log -1 --oneline

已有改动很重要。告诉 Agent 哪些属于当前任务，其余需要保留。如果目录没有使用 Git，先复制一份再允许修改。

接着读项目自己的安装说明和依赖配置。项目声明的包管理器与锁文件，比凭经验猜一个安装命令更可靠。不清楚脚本会做什么时先确认，因为安装依赖也可能执行项目脚本。

2. 沿一个行为查代码，不要求泛泛介绍整个仓库

把方括号内容换成你的任务：

我刚接手这个仓库，请调查【一个具体行为】。暂时不要修改文件或安装依赖。
读取适用于相关文件的仓库说明。从【界面操作、路由或命令】追踪到实现。找到最接近的已有测试或示例。
请给出：1. 入口与相关文件，附具体位置。2. 当前行为，以及一个重要边界情况。3. 能检查该行为的最小命令。4. 仅靠仓库还无法确认的事情。
调查范围保持在这个行为上。

以搜索功能为例，有用的回答应该能串起“表单提交 → URL 工具函数 → 查询参数解析 → 测试”。这只是输出结构示例，不是对你项目的事实判断；让 Agent 提供真实文件路径。

自己抽查两三个位置：处理函数真的调用了这个工具函数吗？测试导入的是同一份实现吗？一段流畅的架构介绍，如果指向旧代码，仍然不能帮助你做决定。

3. 区分仓库规则与本次任务背景

Claude Code 和 Codex 使用的说明机制不同。Claude Code 的官方最佳实践介绍了 CLAUDE.md、聚焦上下文与验证；Codex 则说明了如何发现 AGENTS.md 指令。不要假设给某个 harness 配置的文件会自动配置所有其他 harness。

先读已有说明，不要为了重复本次任务又创建一个长期规则文件。临时要求放在会话里；影响整个项目的规则应由维护者明确决定。

切换 harness 时，把重要约束直接交给新会话，并确认它读过相关项目规则。Harness 与模型的区别解释了为什么换执行工具和换模型是两件事。

4. 修改前先确认基线

准备执行项目命令后，在正确目录运行最相关的已有检查，保留修改前的结果。

如果基线里有无关失败，不要笼统要求“把所有测试改绿”。明确本次负责哪个失败，并保留原始输出。

5. 第一个改动，要小到你能读完

理解调用路径与基线后，再给第二轮任务：

在刚才定位的路径中实现【具体行为】。保留【已有行为】和我无关的本地改动。沿用当前项目约定与依赖。
验收：- 【可观察的结果】- 【重要边界情况】- 【相关已有检查】
返回改动文件和实际验证输出。如果需要修改公共合同、删除数据或扩大范围，先停下来说明。

阅读 diff，而不是只读最终总结。检查有没有增加依赖、删掉校验、放宽测试，或修改调用路径以外的文件。这些行为有时确实必要，但需要解释它们与任务的关系。

6. 下次继续时，不必重做一遍调查

结束时，把当前结果、验证命令和下一步放在一起。有效记录可以很短：“搜索已保留 sort 参数，URL 工具函数测试通过，浏览器行为尚未检查。”这样能区分证据与剩余工作。

在 Agent.Space，项目可以围绕保存的文件和受支持的 Agent 会话组织。先按首个 Workspace 教程准备相关项目文件，再从实时产品中选择可用 harness 和兼容模型，不预设所有模型都能搭配所有 harness。

切换会话不会转移私有推理；共享 Workspace 也不意味着并发编辑自动隔离。个人的首个任务，一个写入者加一个可审阅的小改动就够了。之后需要换 Agent，再使用上下文交接清单。

本文为原创工作流指南，不是 Agent 性能对比实测。官方说明核对于 2026 年 10 月 8 日。