适用读者：要做代码类 Agent、或想判断"我的团队/仓库对 Agent 是否友好"的人。
前置：S21-J08（Agent 定义）、J09（上下文）、J11（工具）；S24-J01（Claude Code 实践）。
覆盖旧文：A-4571（Coding Agent 与通用 Agent，第 5 章，47,340 字符）→ 19 小节 / 约 4.7 万字符。
扩展点：E-S21-038（项目指令文件 = 项目级系统提示）、E-S21-039（七步流程与"完成标准"）、E-S21-040（Harness 五要素在编码场景的落点）。
上一篇：S21-J11 · 工具：分类、ACI 与披露策略
下一篇：S21-J13 · 交互：观察与动作空间的扩展。
1. 一句话结论
Coding 是 Agent 的元能力：代码既能表达思考（写脚本验证假设），又能约束规则（把业务约束写成可执行检查），还能适配系统（生成调用其他系统的胶水）。而 Coding Agent 是否可靠，取决于完成标准——"测试通过"而不是"代码写完"。
出处：《AI Agent 深入理解》第 5 章（
A-4571）。
2. 项目文档化：Agent 的第一件事（E-S21-038）
新工程师第一天不会直接提代码，Agent 同理。关键文档缺失时，Agent 应先承担文档化责任：读代码库 → 识别模块/抽象/依赖 → 生成架构概览、目录结构、测试运行指南。
Agent 专用形态：项目指令文件
| 文件 | 约定什么 | 类比 |
|---|---|---|
CLAUDE.md / AGENTS.md / .cursorrules |
在这个项目里该怎么干活 | 项目级 system prompt |
SOUL.md |
Agent 是谁（身份与行为规则） | 全局人格 |
MEMORY.md |
跨会话经验沉淀 | 长期记忆 |
指令文件该写什么：
## 构建与测试
- 用 `pnpm test`，不要用 `npm test`
## 代码风格
- 禁用 `any` 类型
## 禁区
- 不要改动 `migrations/` 目录
为什么它是最经济的稳定前缀：内容不随任务变化 → 天然对 KV Cache 友好（J09 §3.1）。
"AI-ready" 的简单指标：一个远程新人只靠代码仓库和文档，能不能独立开展工作。 能，Agent 也能。
3. 七步流程与完成标准（E-S21-039）
① 项目文档化（先建认知框架）
② 任务理解与需求澄清（目标？可接受的权衡？瓶颈在哪？）
③ 编写设计文档（改哪些模块/为什么/方案比较/新依赖/影响）
└─ 交人审查 ← 审一页设计比审几百行代码容易
④ 代码实现
⑤ 测试（正常路径/边界/异常）→ 失败则分析-定位-修复循环
⑥ 代码自审（可读性/lint/性能/安全/子 Agent 评审）
⑦ 文档同步（架构变了就更新文档；过时文档比没有更糟）
| 门 | 判定 | 反面 |
|---|---|---|
| 进入实现 | 设计已批准 | 需求模糊就开始写 → 大返工 |
| 任务完成 | 测试通过 + 自审通过 | "写完就报完成"（最常见的偷懒） |
| 交付 | 文档已同步 | 文档与代码脱节 |
判据：把"验证通过"当作停机条件，这就是 Loop 工程（J01）在编码场景的落地。
现实裁剪：Claude Code / Codex 会按任务复杂度裁剪——小 bug 跳过设计文档；大改才走全套。
3.1 "何时停止收集信息、开始行动"是模型行为
同一 Harness 里换模型，这个阈值会变；换 Harness 用同一模型，阈值可能保持。说明它首先是模型学到的行为策略，不是界面风格。 提示词与预算只能放大或抑制，不必是来源。
4. Harness 在编码场景的五个落点（E-S21-040）
| 要素 | 在 Coding Agent 里 |
|---|---|
| 上下文 | 项目指令文件、目录树、相关文件片段、测试输出 |
| 工具 | 搜索、读文件、编辑、执行命令、跑测试 |
| 约束 | 禁区目录、禁止命令、审批点 |
| 验证 | 编译 + lint + 测试（自动反馈） |
| 纠正 | 失败 → 读日志 → 改 → 重跑（循环上限） |
为什么编码领域最受益于 Harness：它有廉价、确定、自动的验证器——编译器与测试。别的领域往往要靠人判断。
5. 故障与错误恢复
| 故障 | 处理 |
|---|---|
| 编译报错 | 读错误 → 定位 → 改 → 重编（别猜） |
| 测试失败 | 先判断是"实现错"还是"测试错" |
| 编辑未命中 | old_string 必须与文件逐字节一致（见 J11 参数保真） |
| 陷入重复尝试 | 迭代上限 + 换策略提示（"换一种方法"） |
| 上下文被日志灌满 | 只回填摘要 + 关键片段 |
判据：错误信息是最高性价比的上下文。 把完整报错（含文件名/行号）回填，比加一段"请仔细检查"有效得多。
6. 搜索与编辑工具的设计要点
| 工具 | 设计要点 |
|---|---|
搜索（grep/find/语义检索） |
先粗后细：文件名 → 符号 → 内容；输出要限量（前 N 条 + 命中数） |
| 读文件 | 支持范围读取（offset/limit），避免整文件灌入 |
| 编辑 | 基于精确匹配的替换；不做静默规范化；失败要给"最接近的匹配"提示 |
| 执行 | 超时、输出截断、退出码透出 |
反例：只给"未找到匹配"而不给近似命中，模型会进入无限重试（J11 的弯引号案例）。
7. 安全：编码 Agent 的边界
| 风险 | 手段 |
|---|---|
破坏性命令（rm -rf、强推） |
命令白名单 + 需确认 |
| 触碰生产/密钥 | 禁区目录、环境变量隔离 |
| 越权提交 | 分支策略、禁止直推主分支 |
| 供应链 | 新增依赖需人工批准 |
| 数据外泄 | 网络出口限制（沙箱） |
判据：编码 Agent 的动作空间最大、验证最便宜，所以"用沙箱换自由度"是最划算的取舍。
8. 代码作为元能力
| 用法 | 例子 |
|---|---|
| 思考工具 | 写脚本算一遍，而不是"心算"（同 J10 §6 的 User as Code） |
| 规则约束 | 把业务规则写成可执行检查，失败即红线 |
| 多媒体生成 | 用代码生成图表/动画/SVG，而不是拼文字描述 |
| 系统适配器 | 缺 API 就写胶水脚本，不必等工具封装 |
| 生成式 UI | 输出可运行的界面，而不是截图 |
| 自举 | 代码生成代码：Agent 写脚本改进自己的工具链 |
判据：能用代码验证的，就不要用自然语言推理。 这是"确定性优先"原则在 Agent 上的最大应用面。
9. 自测
- 项目指令文件与 README 的区别？为什么它对缓存友好？
- 七步流程里，哪一步是"人最该介入"的点？为什么？
- Coding Agent 的完成标准应该是什么？
- 为什么编码领域最适合"验证驱动的 Loop"？
- "何时开始动手"的阈值由什么决定？
答案
- README 面向人；指令文件是给 Agent 的行为约定，内容稳定 → 可做静态前缀缓存。
- 设计文档评审：审一页设计远比审几百行代码便宜。
- 测试通过 + 自审通过，不是"代码写完"。
- 有廉价、自动、确定的验证器（编译 + 测试）。
- 主要是模型学到的行为策略，Harness 只能放大或抑制。
10. 下一篇
S21-J13 · 交互：观察与动作空间的扩展 —— 回合制不是环境的性质；异步与事件驱动的三种机制、语音的三条时序路线、Computer Use 的动作空间与视觉定位、VLA 的控制结构。
本篇属于系列《S21 · Agent 工程与 MCP》。旧文来源：A-4571（第 5 章）；扩展点 E-S21-038/039/040。文中产品/版本事实（如 GPT-6 Astra 原生异步、Anthropic CU 参数）按原文快照记录，属待核。