3.7 第一次真实任务会话 Walkthrough¶

阅读完本节后，你应该能在一个真实 repo 里完成一次可控的 Claude Code / Codex / OpenCode 任务：读代码、定计划、改文件、跑验证、看 diff、收尾。

不要拿“写一个贪吃蛇”作为第一次练习。真正有价值的练习应该发生在一个已有项目里，哪怕任务很小。

第 0 步：准备工作区¶

你应该先确认工作目录和工作区状态：

git status

pwd

ls

这里不是教终端，而是提醒你：Agent 的工作目录必须正确，且你要知道当前是否已有未提交改动。

如果工作区是脏的，你要告诉 Agent：

当前工作区已有用户改动。不要回滚、覆盖或格式化无关文件。修改前先检查 git diff，并只触碰本任务相关文件。

第 1 步：让 Agent 只读分析¶

第一条消息不要让它实现。

先不要修改文件。

任务：给现有导出功能补一个 `--format json` 参数。

请先：
1. 阅读项目结构和相关代码。
2. 找出已有 CLI 参数处理方式。
3. 找出相关测试。
4. 总结要改的文件、风险和验证命令。

好的 Agent 回答应该包含：

找到了哪些文件。
现有模式是什么。
准备改哪些文件。
可能影响什么。
计划跑什么验证。

第 2 步：要求明确计划¶

如果它直接开始写代码，打断它。

先给计划，不要实施。
计划需要包含：
- 文件范围。
- 每个文件为什么要改。
- 是否需要新增测试。
- 验证命令。
- 不做什么。

你确认计划时重点看：

是否有无关文件。
是否引入不必要依赖。
是否遗漏测试。
是否理解了项目已有风格。

第 3 步：小步实施¶

确认后再让它动手。

按这个计划实施。保持最小改动，不要重构无关代码。每完成一组相关改动后运行对应验证。

如果任务稍大，可以要求分批：

先只完成参数解析和测试，不要改导出实现。完成后停下来给我看 diff 摘要。

这种分批方式比一次性全改更安全。

第 4 步：验证¶

不要接受“应该可以”。

请运行你计划里的验证命令。失败时不要换方案，先解释失败原因，然后做最小修复。

如果环境缺依赖或命令无法运行，合格回答应该说明失败命令、失败原因、是否和本次改动有关，以及用户应该如何复现验证。

第 5 步：看 diff¶

让 Agent 自查一次。

请基于当前 diff 做 review，重点检查：
- 是否有无关改动。
- 是否破坏兼容性。
- 是否缺测试。
- 是否有临时代码或调试输出。
- 是否需要更新文档。

你也要自己看：

git diff

Agent 写了代码，不代表你不需要 review。你的角色从“手写每一行”变成“定义目标、控制边界、验收质量”。

第 6 步：记录经验¶

任务结束时问：

这次任务里有没有可以沉淀到 AGENTS.md / CLAUDE.md / docs / skill 的规则？
只列真正会复用的，不要泛化废话。

应该沉淀的例子：

项目必须用 pnpm test:unit，不要用 npm test。
CLI 参数统一在 src/cli/options.ts 注册。
API 错误必须用 AppError，不要直接 throw string。

不应该沉淀的例子：

“写高质量代码”。
“注意边界情况”。
“保持简洁”。

完整会话模板¶

你是本 repo 的本地 coding agent。请按以下流程工作。

任务：
[一句话目标]

约束：
- 先只读分析，不要修改文件。
- 优先复用项目已有模式。
- 保持最小改动。
- 不要引入新依赖，除非你先说明理由并等待确认。
- 不要回滚或覆盖无关用户改动。

第一步请输出：
1. 你阅读了哪些文件。
2. 现有实现模式是什么。
3. 计划修改哪些文件。
4. 风险是什么。
5. 验证命令是什么。

等我确认后再实施。

如果使用 OpenCode，可以额外补一句：

如果当前阶段不需要写文件，请使用只读 planning / explore 模式；只有在我确认计划后再切换到可写实现。

第一次练习的合格标准¶

[ ] Agent 先读代码而不是直接写。
[ ] 计划里文件范围合理。
[ ] 改动小于你预期的最大范围。
[ ] 至少运行了一个验证命令，或清楚说明为什么不能运行。
[ ] 你看过 diff。
[ ] 没有把“顺手优化”混进任务。
[ ] 任务结束后有一条可复用经验被记录或明确不需要记录。