最近我们用这套流程交付了一个原本预估 6 PD 的需求。人用了约 0.5 PD 澄清需求、补齐边界并确认技术方案；后续约 0.5 PD 由 Claude Code 完成开发，人没有持续介入。Claude Code 根据技术方案拆分并实现任务，Hooks 在修改过程中检查代码是否符合仓库规范，编译通过后继续调试；它读取异常、日志和测试结果，依据具体证据修改实现，直到达到交付条件。
需求澄清、技术方案、仓库规则、Hooks、编译、调试和异常信息构成了连续流程：每一步的产出都是下一步的输入。失败结果包含可定位的问题，并返回实现阶段处理。人的工作集中在定义需求边界、技术决策和最终确认。
这类实践符合 Harness Engineering 的描述：围绕模型补齐上下文、工具、约束和反馈，使 Agent 在给定条件下执行任务。Harness 定义运行环境和规则；Loop 描述一次需求在“实现 → 检查 → 调试 → 修复 → 再检查”之间的处理过程。
Claude Code 的执行能力与项目工程责任
本文使用 Claude Code，但 Harness Engineering 不属于某个编码产品的使用技巧。Claude Code 提供代码浏览、编辑、命令执行、子任务、Hooks 和会话上下文等能力；项目仍需定义 Agent 应读取的信息、允许执行的动作、完成条件和失败处理方式。使用其他 Coding Agent 时，同样需要处理这些工程问题。
我在 2024 年做 Agent 时处理过工具描述、结构化错误、状态外置、上下文压缩、权限边界、运行验证和评估。这些经验是本次 Claude Code 实践的前提：早期需要自行搭建 Agent 运行时并设计每个环节；Claude Code 已提供部分通用运行时，工程团队仍需将项目事实、约束和反馈接入其中。本文讨论这种衔接，不将 Claude Code 视为独立于既有 Agent 实践的方法。
传统软件工程默认开发者能够从代码、文档、口头约定和历史经验中补齐上下文，并在评审中识别不合适的实现。Agent 缺少这些默认前提。它可以在几分钟内生成大量代码，但可能不了解既有架构、领域规则和依赖边界；如果团队仍由人工评审承担全部检查，代码生成速度会超过人工处理能力。
AI 友好型工程系统需要为 Agent 组织获取信息、执行任务和接收反馈的运行环境。
人负责设计执行条件
人仍需对需求边界、架构取舍和交付风险负责，工作重心从直接实现转向工程设计与反馈设计。
Claude Code 的实现不符合预期时，需要检查它是否缺少完成任务所需的知识、工具或约束，以及这些能力能否表示为 Agent 可读取、可执行和可验证的形式。研究和实现可以拆分：一个会话调查代码库、比较方案并形成技术路径；路径确认后，使用干净的执行会话处理实现，避免调研过程的内容影响编码上下文。这延续了早期 Agent 中规划与执行分离的做法，Claude Code 的会话和子任务能力提供了相应支持。
代码生成量增加后，逐个阅读 PR 会成为人工评审的瓶颈。规则明确的检查可交由系统执行，UI 状态、日志、网络请求和测试结果可作为 Claude Code 的反馈；人处理产品取舍、异常风险和无法通过规则判定的问题。Review 可以前置为规则和检查，由独立 Agent 或确定性工具执行重复验证。早期 Agent 实践要求工具返回可修复的证据；在 Coding Agent 场景中，这些证据进入下一轮执行。
Prompt、Context 与 Harness 的作用范围
这三个概念作用于不同范围：
- Prompt Engineering 通过任务描述、角色和示例改善一次调用的输出，但难以覆盖复杂任务中的工具使用、状态变化和跨会话协作。
- Context Engineering 将文档、记忆、RAG、工具结果和工作状态组织为上下文，使 Agent 基于项目事实工作。
- Harness Engineering 围绕模型建立任务拆分、工具权限、质量门禁、观测和反馈回路，使 Agent 在约束下持续完成工作。
模型能力提高后，影响交付质量的许多变量位于模型之外：Agent 能否获得正确知识、调用必要工具，违反架构时是否被拦截，以及失败后是否获得可操作的反馈。Harness 将这些条件组织为工程系统。
OpenAI 在 Harness engineering 中提出，人负责引导和决策，Agent 负责执行。团队需要将 Agent 失败时缺少的信息、工具或约束，整理为可复用的系统能力。
将工程资产提供给 Agent
传统工程资产主要面向人阅读。长文档、网页操作、会议纪要和分散的注释需要读者自行拼接上下文。工程资产还需要具有机器可读、可发现和可执行的形态。
需要处理以下三类工程资产：
- 知识表达。 架构原则、领域模型、接口契约和依赖边界不应只依赖团队经验，应通过规则、Schema、元数据、ADR 或版本化文档表达。
- 机器接口。 原本只能通过 GUI 完成的查询、诊断和操作，应尽量提供 CLI、API 或受控工具调用，使 Agent 可以稳定发现和使用这些能力。
- 任务上下文。 一次性提供全部文档会增加噪声。Agent 可从项目总览开始，再按目录、模块和任务逐层读取所需规则。
Harness 的组成
早期 Agent 实践中的检索与记忆，对应仓库规则、专项知识和按任务加载的上下文；工具 Schema、权限与状态机，对应受控命令、Hooks、工作区和人工确认；工具返回、测试与轨迹，对应类型检查、CI、浏览器、日志和运行指标。产品形态不同，但 Harness 仍需定义 Agent 行动所依据的事实、受限动作，以及基于何种证据继续或停止。
AI 友好型架构包含三个相互依赖的部分：Agent 可读性、受控执行和反馈回路。
1. Agent 可读性
仓库除存放代码外，还应提供可导航的知识。Agent 先读取项目级说明，再根据修改目录加载局部规则、领域知识和接口说明。这样可以减少全量上下文带来的噪声，并明确规则的作用范围。
分层上下文可以按以下方式组织：
| 层级 | 加载时机 | 适合放置的内容 |
|---|---|---|
| 会话常驻 | 每次会话 | 项目概览、运行命令、安全约束 |
| 目录规则 | 进入对应目录 | 模块边界、依赖方向、代码约定 |
| 专项知识 | 调用特定能力时 | 接口文档、研究结论、历史决策、Skill |
AGENTS.md、CLAUDE.md 或目录级规则文件应让 Agent 根据任务位置找到范围足够小且准确的上下文。架构决策可使用 ADR 记录并随系统变化维护；过期决策会成为错误上下文的一部分。
ADR 可在 Agent 参与方案设计、PRD 对齐和架构检查时提供架构事实，记录决策背景、可选方案、约束、结论和失效条件。还需要定义更新与清理机制。已废弃的决策、与实现不一致的规则和过期的接口说明，都会使 Agent 依据错误上下文行动。
2. 受控执行
人工 Code Review 无法单独承担 AI 场景中的质量控制。对于规则明确的约束，应将检查设为自动化门禁，避免评审者重复发现同类问题。
常见边界包括：
- 静态检查：依赖方向、命名、禁止 API、Lint 规则；
- 类型检查：严格 TypeScript 配置、减少
any和未声明的边界； - 自动化测试：单元测试、集成测试和端到端测试；
- 权限与隔离：将读取、修改、部署等工具能力分开，避免 Agent 因任务数据间接获得更高权限；
- 独立审查：由不同上下文或不同 Agent 检查设计一致性、代码风险和测试覆盖，避免由编码 Agent 自行验收。
约束需要具备确定性。Agent 可以探索实现方案；违反依赖、类型或安全规则时，系统应阻止其进入下一阶段。错误信息应包含修复线索，使失败结果可用于下一轮执行。
3. 反馈回路
约束定义禁止的动作，反馈提供调整依据。Agent 需要可定位问题的证据，而不是只有失败状态。
反馈可按距离分为三层：
- 开发反馈：Lint、类型错误、单元测试和本地浏览器验证；
- 交付反馈：CI 中的集成测试、性能回归、冲突检测和预览环境；
- 运行反馈：日志、追踪、指标、异常和真实用户链路。
Chrome DevTools Protocol、日志查询和指标平台使 Agent 能检查代码运行后的状态。截图、DOM 快照、网络请求、错误堆栈和指标变化提供的反馈比自然语言描述更容易定位问题。缺少这些通路时，Agent 只能根据代码推断结果。
无 UI 或逻辑与视图分离时，反馈不必等待端到端页面测试。可将业务状态、Service 方法和调试能力通过受控工具提供给 Agent：先发现可用能力，再执行业务动作、读取状态、注入必要的调试信息，并根据实际状态或异常修改实现。这些接口用于在功能尚未完成、页面用例难以编写时提供开发阶段的运行时反馈。完成逻辑验证后，仍应由集成测试、端到端测试或人工验收覆盖真实用户路径。
使用专业化 Agent 提供反馈
拥有全部上下文和工具的通用 Agent，未必比职责受限的多个 Agent 更可靠。专业化可以限制每个 Agent 携带的信息和拥有的权限，使其与当前阶段相符。
可按以下职责分工：
| 角色 | 主要职责 | 输入与产出 |
|---|---|---|
| 需求评审 Agent | 发现歧义，给出需要确认的选项 | PRD → 可执行需求 |
| 研究与规划 Agent | 探索代码库、拆分任务、选择实现路径 | 需求 → 技术方案与任务列表 |
| 执行 Agent | 在受限工作区完成单个任务 | 任务 → 代码与变更说明 |
| 审查 Agent | 检查方案一致性、风险和遗漏 | 变更 → 问题清单 |
| 测试 Agent | 用独立测试与真实交互验证功能 | 构建产物 → 缺陷与证据 |
| 清理 Agent | 定期发现过期文档、重复实现和规则偏差 | 仓库状态 → 小范围修复 PR |
角色拆分不要求每个任务经过完整流程。低风险改动可以直接执行并运行确定性检查；涉及多个模块、运行时行为或外部副作用的任务，需要增加研究、审查和测试等独立阶段。
将长任务状态保存在仓库中
一次会话能完成的任务可直接使用前述流程。任务跨越多个上下文窗口时，新的 Agent 不知道上一轮的进度；会话结束后，对话历史中的状态无法继续使用。长任务需要将状态外置为版本化工程资产。
一个最小组合包括统一启动方式、任务清单、进度记录和可回滚的提交。初始化阶段建立运行环境和验收基线；后续每轮领取一个可独立完成的任务，检查当前工作区和已有验证结果，完成后更新任务状态、记录遗留风险并提交变更。任务清单应通过结构化字段描述优先级、完成条件和验证证据，避免只写“差不多完成”。
这种状态管理使下一轮能够从可验证的工作状态继续，而不必重新探索整个项目，也为失败恢复提供依据。提交、检查点、幂等操作和明确的重试上限应在交付过程中定义。
维护仓库规则与实现的一致性
Agent 会使用仓库已有模式，其中可能包含过时或低质量的实现。代码生成吞吐量提高而规范更新、文档校验和冗余清理仍依赖人工临时处理时，系统复杂度会持续增加。
Harness 需要维护机制：定时检查过期知识，在发布后校验文档与代码的一致性，通过小 PR 修复可自动确认的问题，并周期性审查重复或违反架构的实现。清理能力需要与新增代码量相匹配。
并行任务还需管理共享工作区。任务应有明确所有者或锁，修改在独立分支或工作区完成，再通过测试和合并流程汇合。彼此独立的调研、测试和问题定位适合并行；多个 Agent 同时修改同一处核心逻辑时，冲突协调成本可能高于收益。
建立流程的顺序
可从已有交付流程开始，逐步补齐：
- 将项目结构、目录边界和运行命令写成短小的分层规则；
- 将已有的类型检查、Lint、测试和架构检查接入 Agent 可执行的反馈；
- 为日志、浏览器验证和指标查询提供受控工具入口；为逻辑层提供查询状态和执行受限业务动作的工具；
- 将编码、审查和测试分成独立步骤，先在中低风险需求上验证；
- 为跨会话任务维护版本化任务清单、进度记录、验证证据和可回滚提交；
- 记录重复出现的失败原因，将其转为规则、测试或工具能力；
- 为自动循环设置停止条件，例如最大重试次数、预算上限和必须转人工的异常类型，避免错误路径无限运行。
工程师负责定义目标、设计边界、选择反馈信号，并处理无法机械化的判断。Agent 可以加快实现速度；长期交付质量取决于工程系统能否提供约束、执行边界和基于真实结果的反馈。
参考资料
- OpenAI: Harness engineering
- Martin Fowler: Harness Engineering
- Anthropic: Effective harnesses for long-running agents
- Anthropic: Building a C compiler with a team of parallel Claudes
- Architecture Decision Records: adr.github.io
