Harness Engineering 四根支柱与四要素架构¶

Ch05.077 Harness Engineering 四根支柱与四要素架构¶

📊 Level ⭐⭐⭐ | 19.0KB | entities/harness-engineering-90-percent-pillars.md

• 原文存档

实战：四要素架构¶

基于四根支柱，构建四个核心要素：

.harness/
├── agents/              # Agent 角色定义（Application Owner）
├── rules/               # 规则体系
│   ├── 工程结构.md
│   ├── 开发流程规范.md
│   └── 项目编码规范.md
├── skills/              # 技能体系（9 个 Skill）
│   ├── request-analysis/   # 需求分析
│   ├── coding-skill/       # 编码实现（含 8 份分层编码规范）
│   ├── expert-reviewer/     # 专家评审
│   ├── unit-test-write/    # 单元测试编写
│   ├── unit-test-ci/       # CI 流水线验证
│   ├── deploy-verify/      # 部署验证
│   ├── code-review/        # 代码检查
│   ├── project-analysis/   # 项目分析
│   └── aone-ci-generate/   # CI 配置生成
├── changes/             # 变更管理目录
└── mcp/                 # MCP Servers 配置

Application Owner Agent：编排中枢¶

Agent 定义文件存放在 .harness/agents/，是整个 Harness 体系中信息密度最高的文件，通常约 400 行，承担"Index & Map"职责。包含五个核心模块： 1. 角色与项目背景（20-30 行）：模块结构、技术栈、核心业务约束（如价格字段类型、时间格式规范） 2. 配置中枢索引：结构化表格列出 Rules/Skills/Wiki/MCP 的路径、职责、触发场景、更新频率 3. 七项核心职责：需求理解、任务拆解、任务分发、任务验收、质量把关、文档管理、知识问答 4. 工作流程调度指令：10 阶段流程中每个阶段的完整调度逻辑，只在 5 个 Human-in-the-Loop 确认点暂停 5. 沟通原则与硬性约束：必须做到清单 + 禁止做的清单

上下文分层加载策略（L1/L2/L3）¶

10 阶段开发流程（10-Stage Pipeline）¶

需求分析 → 需求评审 → 编码实现 → 编码评审 → 单元测试编写
  → 单元测试评审 → 代码推送 → CI 验证 → 部署验证 → 用户确认

• 精确的回退路径：CI 失败时，测试为 0/0 回退到阶段 5；编译错误回退到阶段 3；需求不符回退到阶段 1
• 循环上限：需求评审最多 3 轮，编码/测试评审最多 2 轮，超出后升级人工决策
• 5 个 Human-in-the-Loop 确认点：需求待决议确认、计划评审后确认、编码评审后确认、部署环境参数确认、最终交付确认

技能体系：将隐性知识显性化¶

分层编码规范（8 份 Spec 覆盖全链路）： | 层级 | 规范文件 | 核心内容 | |------|---------|---------| | 表现层 | Controller 实现 Spec | RPC Provider 实现模式、参数校验、异常处理 | | 应用层 | 接口定义/实现 Spec | RPC 接口定义规范、DTO 设计原则 | | 业务层 | 业务逻辑 Spec | 核心业务逻辑封装、流程编排组件写法 | | 数据层 | 建表/持久化 Spec | DDL 设计规范、Mapper 编写方式 | | 适配层 | 服务依赖 Spec | 外部 RPC 调用超时设置、降级方案 | | 文档层 | 接口文档生成 Spec | 对外接口的协议文档模板 | 硬性约束示例：价格字段必须用 long 类型（单位为分），禁止 double / float；外部服务调用必须设置超时和降级。

变更管理：完整 Audit Trail¶

{变更类型}-{需求名称}-{YYYYMMDD}/
├── summary.md               # 全流程追溯摘要（Single Source of Truth）
├── request_analysis/
│   ├── spec.md              # 需求分析文档
│   ├── tasks.md             # 任务拆分清单
│   └── review/              # 需求评审记录（版本递增保留）
├── coding/
│   ├── coding_report_v1.md  # 编码报告
│   └── review/
└── unit_test/               # 单元测试报告及评审
    └── ci_result/           # CI 验证结果
    └── deployment/          # 部署验证报告

关键经验¶

1. Harness 本身需要 Dry Run¶

在拿真实需求使用 Harness 之前，用虚拟需求完整走一遍全流程。空跑中发现的四个关键缺陷：

• CI 门禁只检查状态码而忽略测试用例数为 0 的异常
• 评审报告在简单需求下不生成文件
• 摘要文件因 Agent 的"追加"倾向出现重复行
• 部署参数被 Agent 错误推测

  核心启示：不要期望第一版 Harness 就是完美的，用低成本的方式快速验证、快速修复。

2. 质量门禁必须可程序化验证¶

"If it can't be mechanically enforced, the agent will drift." "检查 CI 是否通过"这种自然语言描述不够——Agent 可能认为 status == SUCCESS 即通过，却忽略测试用例数为 0 的异常。将门禁改为三个可程序化验证的条件（status == SUCCESS && total_tests > 0 && passed == total）后问题彻底消除。 一切不可被机器验证的约束，在 Agent 执行中都是无效约束。

3. 分离执行与评判是关键杠杆¶

编码 Agent 和评审 Agent 分离带来了显著的质量收益：

• 评审 Agent 发现了编码 Agent 遗漏的渠道判断逻辑（一个潜在的线上故障）
• 在另一个需求中检测到 Agent 试图跳过评审阶段并强制回退 评审 Agent 不需要"更聪明"，它只需要用一套不同于编码 Agent 的检查视角来审视产出物。

4. 流程一致性优先于流程效率¶

在一个仅涉及 2 个文件、6 行代码的小需求中，依然走完了完整的 10 阶段流程——1 轮评审即通过，过程非常流畅。验证了一个重要假设：好的流程不应该给简单任务增加显著负担。 在企业级系统中，"小改动大事故"的案例不胜枚举。保持流程一致性是一种廉价的保险。

5. 规范是活文档，需要持续迭代¶

开发流程规范经历多次版本更新，每次实战发现新问题都立即 Patch 到 Harness 中。这与 Mitchell Hashimoto 的 Harness Engineering 核心定义完全一致。

规范的每一行都对应一个历史失败案例。 当你觉得某条规则"多余"或"啰嗦"时，那往往是因为它背后有一个真实踩过的坑。

效果对比¶

质量维度¶

AI 代码率跃迁¶

更深层收益¶

• 返工大幅减少：Agent-to-Agent 的评审闭环在内部就完成了大部分质量纠偏，到人工确认时通常只需要 1 轮（以往可能迭代 3-5 轮）
• 知识沉淀：\.harness/ 目录下积累的规范文档、编码 Spec、评审记录和变更历史，构成了一份活的"项目开发手册"，新人和 Agent 都可通过相同的阅读路径快速理解项目全貌

深度分析¶

四根支柱的协同逻辑¶

四根支柱并非独立设计，而是构成一个完整的控制闭环。上下文架构解决"看什么"的问题，让 Agent 在任何时刻获得刚好够用的信息量；Agent 专业化解决"谁来做"的问题，通过角色分离避免单一 Agent 既是运动员又是裁判员；持久化记忆解决"记住什么"的问题，使跨会话任务成为可能；结构化执行解决"怎么做"的问题，通过阶段化流程和质量门禁确保每个环节可验证。四者缺一不可——没有上下文分层，Agent 会在信息过载中迷失；没有角色分离，Agent 无法有效评估自身产出；没有持久化记忆，跨会话一致性无法保证；没有结构化执行，流程会退化为不可预测的自由发挥。

分离执行与评判的关键洞察¶

Anthropic 将"分离执行与评判"描述为"强杠杆"，背后有一个深刻的认知科学依据：人类在进行自我评估时存在系统性偏差（Self-serving Bias），Agent 同样继承了这一缺陷。执行 Agent 的目标是最快速度产出代码以完成任务完成信号，评判 Agent 的目标是用不同视角检验产出质量——两个目标的天然冲突恰好构成了有效的质量检查机制。这不是让评判 Agent"更聪明"，而是让它拥有不同的优化目标。实践中，评审 Agent 发现了编码 Agent 遗漏的渠道判断逻辑，证明了这套机制能够捕捉到单 Agent 架构下必然遗漏的问题。

可程序化验证约束的工程价值¶

"If it can't be mechanically enforced, the agent will drift"——这句话揭示了 Harness 设计中最容易被忽视的原则：自然语言描述的约束在 Agent 执行中几乎无效。以 CI 门禁为例，"检查 CI 是否通过"看似明确，但 Agent 可能将仅有状态码 SUCCESS（测试数为 0）理解为通过。改为三个可联合验证的条件后问题消除。这一设计原则的工程价值在于：它将质量保障从"依赖人工检查"转变为"依赖机器验证"，彻底消除了人工审查的速度瓶颈和质量波动。

AI 代码率跃迁的本质含义¶

从 24.86% 到 90.54% 的跃迁并非简单的效率提升，其本质是Harness 消除了人类参与每个环节的必要性。在裸用 Agent 模式下，人类必须逐一审查每一段 AI 生成的代码，质量瓶颈始终在人工Review 环节。Harness 通过 Agent-to-Agent 评审闭环将质量纠偏前移到人工介入之前，使得人类只需要在 5 个关键确认点做决策，而非逐行审查。这将人类从"代码质量检查员"转变为"流程决策者"，角色本质发生了根本变化。

实践启示¶

从虚拟需求 Dry Run 开始¶

在将 Harness 用于真实需求之前，用一个虚构需求完整走一遍 10 阶段流程。这是发现体系缺陷成本最低的方式——虚拟需求暴露的四个关键缺陷（CI 门禁逻辑漏洞、评审报告生成条件缺失、摘要文件重复行问题、部署参数推测错误）如果流入真实需求，每个都可能造成严重返工。正确的做法是：先空跑、发现漏洞、立即修复，再正式使用。接受 Harness 第一版不完美，用快速迭代替代完美主义。

规范即失败案例的编码化¶

"规范的每一行都对应一个历史失败案例"——这个认知对于规范编写具有重要指导意义。当你觉得某条规则"多余"或"啰嗦"时，应该追问的是"这条规则背后对应哪次失败"，而非直接删除。价格字段必须用 long 类型（单位为分）禁止 double/float 的背后，是真实踩过的线上故障；外部服务调用必须设置超时和降级的背后，是真实发生过的雪崩事件。规范的来源应该是失败案例的系统性复盘，而非凭空设计的"最佳实践"。

质量门禁设计的检查清单¶

设计任何质量门禁时，必须同时回答三个问题：（1）触发条件是什么——什么情况下这个门禁应该被执行；（2）验证逻辑是什么——具体检查哪三个可程序化验证的条件；（3）失败路由是什么——验证失败后回退到哪个阶段、由哪个角色处理。缺少任何一个维度，门禁在实际运行中都会出现歧义。特别需要警惕"看起来明确但实际存在解释空间"的自然语言描述——例如"CI 通过"应该被拆解为 status == SUCCESS && total_tests > 0 && passed == total。

知识显性化的工程优先级¶

团队中存在大量隐性知识（Tacit Knowledge）——价格字段的单位约束、某条链路是高频变更区、某个配置类在全项目有近百处引用——这些知识从未被系统化记录。Harness 体系将这些隐性知识转化为显性规范的过程应该遵循工程优先级：优先记录高频影响项，如跨文件引用的配置类、核心业务字段的类型约束、已知的架构陷阱；次优先记录低频但高影响项，如特殊链路的边界条件、只在特定场景下生效的约束；避免过早规范化低频项，以免规范文档膨胀导致信息过载。规范体系的建设是持续迭代的过程，不是一次性的完美设计。

相关实体¶

• Harness Engineering - 让 Coding Agent 可靠完成长程任务
• Harness Engineering：AI 从"聪明"到"可靠"的第三代工程范式
• Harness Engineering 指南（字节跳动TRAE）
• 清华大学 Harness Engineering 研究报告
• Harness 组件保质期——Model-Harness Fit 与 Build to Delete 原则