生成代码只是交付循环中最显眼的一小段。真正困难的是让 Agent 理解仓库、控制修改范围、解释失败、验证结果，并留下下一位开发者可以接手的状态。
这篇文章面向已经能使用 Codex 或其他编码 Agent 的开发者。你需要一个带版本控制和测试命令的真实仓库；示例不依赖特定语言。
编码 Agent 首先要理解工作环境
开始修改之前，Agent 应先阅读仓库规则、目录结构、依赖脚本、测试入口和当前 Git 状态。这个阶段的目标不是提出宏大方案，而是建立边界：哪些文件可以改、哪些生成目录不能碰、什么命令代表完成。
仓库级 AGENTS.md 应像环境地图，包含适用范围、关键命令、内容规范和安全限制。它不需要解释全部历史，但必须让 Agent 知道在哪里找到更具体的规则。
# Scope
- Applies to `src/` and `content/`.
# Verification
- npm test
- npm run lint
- npm run build
# Change rules
- Preserve unrelated user changes.
- Do not edit generated output.任务合同把需求变成可审阅范围
一句“修一下导航”会迫使 Agent 自行决定问题、方案和完成标准。任务合同应同时写明用户行为、允许范围、禁止项、验收证据和停止条件。
好的合同让 Agent 可以自主执行细节，同时把产品判断和风险授权留给人类。
查看图示源码
flowchart LR
subgraph S1["01 理解"]
direction TB
A["仓库规则"] --> B["复现与诊断"] --> C["批准方向"]
end
subgraph S2["02 实现"]
direction TB
D["小批实现"] --> E["针对性测试"] --> F{"符合用户行为"}
end
subgraph S3["03 交付"]
direction TB
G["完整验证"] --> H["交付说明"]
end
C --> D
F -- "否" --> B
F -- "是" --> G先诊断再批准方向
当问题涉及体验、架构或不明确错误时，先要求 Agent 提供证据：复现路径、相关文件、可能根因和两个以内的解决方向。确认方向后再写代码。
这个暂停点很重要。Agent 的搜索速度很快，也可能快速沿着错误假设修改大量文件。一次简短的诊断批准，通常比事后审查一个巨大 diff 更省时间。
小批修改让反馈保持清晰
把工作拆成可以独立验证的批次：先复现问题并增加测试，再实现最小修复，随后处理边界与可访问性，最后运行完整验证。
每批完成后检查改动统计和具体 diff，而不是等到最后才看。修改范围突然扩大时，应暂停并确认新增文件是否由验收标准真正需要。
git diff --stat
git diff --check测试是反馈系统而不是通关仪式
推荐从最快的针对性测试开始，再运行相关模块测试、lint、类型检查、生产构建和必要的浏览器验证。每条命令回答不同问题，不能互相替代。
测试失败时，先解释失败与本次修改的关系。删除断言、扩大忽略范围或关闭类型检查，只是让仪表盘变绿，并没有提高交付质量。
代码评审还要分成两个角度：实现是否正确、安全、简洁，以及它是否真的解决了用户问题。页面不再报错但仍然难用，不能算完成。
可接手状态才是最终产物
交付说明应让下一位开发者在一分钟内知道完成了什么、修改了哪些范围、运行了哪些验证，以及还剩下什么风险。不要只写“已完成”。
经验如果会重复使用，就回写到仓库规则、测试、脚本或 Skill 中。这样下一次 Agent 不必依赖更长的聊天记录，而能从版本化环境中获得稳定上下文。
下一步阅读为 AI Agent 设计工具，把可靠流程变成 Agent 可发现和验证的接口。