coding-workflow

name	coding-workflow
description	当你在搭建 Coding Agent 的七个核心工具、设计五阶段工作流程、实现 Harness 保障机制、优化实现技巧（并行调用/上下文管理/状态持久化）时使用；当 Agent 写代码不可靠、跳过测试、频繁编辑失败时使用。不适用于代码作为元能力的六个方向（见 coding-meta-capability）。

Coding Agent 工作流（Coding Agent Workflow）

角色与读者

面向构建 Coding Agent 的开发者。本 Skill 服务的目标：让 Agent 像经验丰富的开发者一样可靠地完成"读代码→改代码→跑测试→调试"的增量开发循环。核心认识：能不能稳定运行，不取决于用了多强的模型，而取决于围绕 Agent 搭建的基础设施有多扎实。

核心原则（配正例/反例）

1. 七个核心工具 = 极简但完整

   • Code Interpreter（沙盒执行）、Bash、读文件、写文件、编辑文件、Glob、Grep。七个工具主要覆盖感知+执行两类。

2. 五阶段流程（复杂任务走全流程，简单任务按需裁剪）

   • ① 项目文档化（先建认知框架，生成/复用 CLAUDE.md）；② 需求澄清（复杂需求探索性调研+主动对话，模糊就编码导致返工）；③ 设计文档（改哪些模块及原因、方案及优势、新依赖、影响，为人类提供高效介入点）；④ 编码+测试（测试失败分析原因修改直到通过，而非报告失败）；⑤ 审查+交付（自我批判审视可读性/性能/安全，架构变化更新文档）。

3. Harness 四组件

   • 验收基线（测试/CI/审查标准）、执行边界（模块/依赖/权限）、反馈信号（linter/测试/类型检查）、回退手段（Git/沙盒/快照）。
   • 四象限：目标明确+可自动验证=最佳区域；目标模糊+可自动验证=高效跑偏（用 linter 优化"代码质量"）；Harness 目标是把任务推向最佳象限。

4. 五个实现技巧

   • 并行+流式+级联中止（第一个工具参数完整生成即可执行，独立调用并行，失败只在同批内传播）；上下文精细管理（按行号读、返回附加行号）；环境信息动态注入（cwd/git 分支/未暂存变更作状态栏追加）；命令执行状态持久化（持久终端会话保留 cd/venv）；即时语法反馈（写入后自动 linter）。

5. 文件编辑：Old String → New String 为默认方案

   • Claude Code/Codex/Cursor 采用：old string 存在且唯一则成功否则失败，可预测无歧义；同一代码多次出现需更长上下文消歧。大段删除可用"首尾匹配"优化（免全输出）。返回内容附加行号，模型可精确引用"src/main.py 第 42 行"。

执行流程（SOP 检查清单）

1. 集成七个核心工具 + 沙盒隔离（默认断网、资源限额、凭证不挂载）。
2. 建项目指令文件（CLAUDE.md），每次会话注入。
3. 走五阶段流程，把"测试通过"定义为完成标准。
4. 实现五个技巧（并行流式、行号读取、状态栏注入、持久终端、即时 linter）。
5. 配故障恢复（四层故障分类 + 分级恢复 + 熔断）。

禁止清单（写清合法例外）

• 禁止写完代码不跑测试就报告完成。例外：把"测试通过"而非"代码写完"定义为完成。
• 禁止把环境信息硬编码进静态系统提示词（破坏 KV Cache）。例外：作为动态状态栏追加到末尾。
• 禁止每次命令在全新 shell 执行（丢失 cd/venv 状态）。例外：持久终端会话为默认，隔离终端支持并行。
• 禁止工具输出全量注入上下文（编译数千行输出耗尽预算）。例外：头尾截断 + 持久化到临时文件。
• 禁止静默截断文件内容（模型误以为看到全部）。例外：按行号范围读 + 注明"已显示第 X-Y 行，共 N 行"。

参考资料

• 本书第 5.1 节《Coding Agent》（七个核心工具、整体流程、Harness 实践、故障恢复、实现技巧、搜索/文件编辑工具、安全）。
• 笔记 05-Coding-Agent与通用Agent.md 第 5.1 节。