Harness Engineering 实战：Everything Claude Code 的系统化约束之道

TL;DR

everything-claude-code 是 Harness Engineering 的完整实战案例。它证明了：AI 工程的核心不是 prompt 调优，而是构建系统化的约束机制（Harness）。通过 Eval Harness、Rules Engine、自动化 Hooks 和持续学习机制，将不可控的 LLM 输出转化为可预测、可测试、可进化的工程系统。这篇文章从 Harness 的四大支柱出发，深度解析如何用系统化方法”驯服”AI。

什么是 Harness Engineering？

一句话定义：把 AI 行为装进一个可测试、可约束、可进化的系统。

不是相信 AI 会做对，而是确保 AI 必须做对。

Harness Engineering 的本质

为什么传统方法失败了？

大多数开发者使用 AI 的方式：

问题：

• Prompt 调优是一次性技巧，无法复用
• AI 行为不可预测，同样的输入可能产生不同输出
• 没有积累机制，每次都从零开始
• 质量不可控，依赖 AI “自觉”

Harness Engineering 的定义

Harness Engineering = 把 AI 行为装进一个可测试、可约束、可进化的系统

借用 OpenAI 的定义：

“Harness 是让 AI Agent 保持可控的工具和实践集合。”

但 everything-claude-code 更进一步：

• 不是给 AI 一套工具让它更自由
• 而是给 AI 一套约束让它更可靠

💡 Key Insight

Harness Engineering 的核心不是”给 AI 更好的工具”，而是”给 AI 更严的约束”。工具让 AI 更容易做你想做的事；约束让 AI 不容易做你不想它做的事。

核心思想对比

everything-claude-code 的 Harness 设计

这个项目是 Harness Engineering 的完整实战案例：

核心洞察：

“不是相信 AI 会做对，而是确保 AI 必须做对。”

Harness 的四大支柱

everything-claude-code 的 Harness 体系由四个核心支柱构成：

支柱 1：Eval Harness（测试层）

核心问题：如何知道 AI 做得对不对？

解决方案：把 AI 输出当作产品，建立测试体系。

关键洞察：

• AI 输出不是”艺术品”，而是”产品”
• 产品必须有质量标准
• 标准必须可测试

💡 Key Insight

把 AI 输出当作产品，建立测试体系——这是 Harness Engineering 最反直觉的核心洞察。传统开发者花时间 prompt 调优；Harness 开发者花时间建 Eval。

支柱 2：Rules Engine（约束层）

核心问题：如何防止 AI 做错？

解决方案：系统化强制（不是建议）。

约束类型：

• 硬约束：必须满足，不满足则拒绝（如安全规则）
• 软约束：建议满足，不满足可讨论（如代码风格）
• 流程约束：必须按特定步骤执行，不执行则阻塞（如 TDD）

💡 Key Insight

Rules Engine 的核心是把”建议”变成”强制”。软约束和硬约束的区别不是强弱，而是后果——一个是警告，一个是拒绝提交。

支柱 3：Hooks & Automation（执行层）

核心问题：如何自动化执行 Harness？

解决方案：自动触发机制。

核心价值：无人值守的自动化流水线。

支柱 4：Continuous Learning（进化层）

核心问题：如何让 Harness 越用越强？

解决方案：经验自动沉淀为机制。

关键突破：

• 传统 AI：每次都是 fresh start
• Harness：每次都在进化

Eval Harness：把 AI 行为变成可测试对象

为什么需要 Eval Harness？

LLM 的核心问题：非确定性

人类工程师：

• 可以 review 代码质量
• 可以判断是否符合需求
• 可以指出具体问题

但这个过程是人工、耗时、不可规模化的。

Eval Harness 的设计

核心理念：把”判断 AI 做得对不对”也变成可自动化的任务。

1. Capability Eval（能力评估）

问题：AI 是否具备完成特定任务的能力？

执行流程

Eval Harness 的执行流程分为三个层次：

2. Regression Eval（回归评估）

问题：新功能是否破坏了旧功能？

关键设计：

• 每次修改后自动运行全量测试
• 对比 baseline 确保没有退化
• 量化指标（响应时间、错误率等）

3. pass@k 指标

问题：AI 的成功率有多高？

定义：k 次尝试中至少成功 1 次的概率。

应用场景：

• 评估不同 prompt 的效果
• 评估不同模型的能力
• 追踪项目随时间的改进

Eval Harness 在 everything-claude-code 中的实现

Eval Harness 在 everything-claude-code 中通过 eval-harness Skill 实现自动化。开发者通过简单的命令触发完整的评估流程，无需手动运行测试。

触发方式

通过 /eval 命令触发评估流程，系统自动运行所有已注册的测试用例并生成报告。

实际工作流：开发者在完成一个功能后输入 /eval，eval-harness Skill 自动加载预设的测试用例集，对当前代码执行全量评估。以 CRM 标签推荐为例，测试用例可能包括：给定客户资料和标签库，验证返回的标签数量是否在合理范围内、标签相关性评分是否超过阈值、响应时间是否低于 200ms。

输出示例

评估完成后，系统输出结构化报告，包含以下关键指标：

Capability Eval Results:
  - test_tag_relevance: PASS (score: 0.87 >= 0.80 threshold)
  - test_empty_customer: PASS
  - test_concurrent_requests: PASS (P99: 145ms)
  - Overall: 12/12 PASS

Regression vs Baseline:
  - 3 new failures detected
  - 9 improvements, 0 regressions
  - pass@3: 0.94 (up from 0.89 baseline)

核心价值：Eval 把 AI 输出从”主观感受”变成”客观数据”。没有 pass@k 指标，团队只能靠人工 review 判断 AI 表现；有了 Eval，每一次改进都可以量化追踪。

Rules Engine：系统化约束（不是建议）

Prompt vs Rule：本质区别

示例对比

Rules 和 Prompt 的核心差异在于约束力。Prompt 是一种请求，AI 可以选择忽略或偏离；而 Rule 是一种硬性约束，系统会强制执行，不满足则拒绝。

Rules 的分类

Rules Engine 中的规则分为三类，分别应对不同的约束场景：

💡 Key Insight

Rules Engine 的核心价值在于将”建议”转化为”强制”。当约束被系统化执行，质量保障就不再依赖人的自觉性。

1. 硬约束（Hard Constraints）

定义：必须满足，不满足则拒绝。

示例（security.md）：Rule 文件定义绝对禁止的操作，如禁止在代码中硬编码密钥、禁止将敏感数据写入日志、禁止未经验证直接操作数据库。Reviewer Agent 扫描到违规项时直接中止流程并返回错误，而不是继续执行。

# security.md 片段
rules:
  - id: no-hardcoded-secrets
    description: "禁止硬编码密钥或 token"
    pattern: "(api_key|secret|password)\s*=\s*['\"][^'\"]{8,}"
    severity: blocking
    action: reject
  - id: no-sensitive-log
    description: "禁止记录敏感字段"
    pattern: "log.*(password|token|credit_card)"
    severity: blocking
    action: reject

2. 软约束（Soft Constraints）

定义：建议满足，不满足可以讨论。

示例（coding-style.md）：定义代码风格规范，如命名 convention、函数长度限制、注释覆盖率。Reviewer Agent 发现违规时输出警告，提示开发者修改，但不阻塞流程。

# coding-style.md 片段
rules:
  - id: function-length
    description: "函数不超过 50 行"
    severity: warning
    action: warn
  - id: docstring-required
    description: "公共 API 必须有 docstring"
    pattern: "^(async )?function \w+\(.*\):"
    require_match: "docstring"
    severity: warning

3. 流程约束（Process Constraints）

定义：必须按特定流程执行。

示例（tdd-process.md）：强制 TDD 开发流程——先写测试，再写实现。违反顺序则 Reviewer Agent 拒绝提交。

# tdd-process.md 片段
rules:
  - id: tdd-order
    description: "必须先有 failing test，再有实现代码"
    check: |
      1. 存在新增/修改的测试文件
      2. 该测试在实现前是 RED 状态
      3. 实现文件在测试之后出现
    severity: blocking
    action: reject
  - id: test-before-commit
    description: "提交前所有测试必须 GREEN"
    severity: blocking
    action: reject

Rules Engine 的实现

Rules Engine 的核心是一个基于 YAML 规则文件的执行引擎。每个规则文件定义具体的约束条件，系统在 AI 输出时自动检查是否满足。Reviewer Agent 读取规则文件，对照检查输出，违规时触发相应的处理逻辑。

实际执行流程：

1. 规则加载：Reviewer Agent 启动时读取 .claude/rules/ 目录下所有 .md 文件，构建规则库
2. 输出扫描：AI 的每次输出（如生成的代码、文档、回复）都经过 Reviewer Agent 扫描
3. 模式匹配：规则引擎对输出内容执行正则匹配或语义检查
4. 违规处理：根据规则定义的 action（reject / warn / log）执行对应操作

# 规则引擎执行示例
rule_file: coding-style.md
matched: function-length
severity: warning
message: "函数 handle_customer_tag 长度为 67 行，建议拆分"
action: warn

Reviewer Agent 的工作流程

Reviewer Agent 是 Rules Engine 的执行者。它接收 AI 的输出，与规则库逐一比对，检查安全边界、代码风格、流程合规性等多个维度。任何违规项都会生成详细的报告，供开发者后续处理。

完整工作流：

1. 开发者输入 /review 命令，或 Hook 在 pre-commit 时自动触发
2. Reviewer Agent 加载本次会话的所有输出（代码、测试、设计文档）
3. 按优先级依次扫描：安全规则 → 流程规则 → 风格规则
4. 汇总所有违规项，输出结构化报告
5. 若存在 blocking 级别违规，中止提交并显示修复建议

实际输出示例：

Reviewer Agent Report
=====================
[BLOCKING] security: no-hardcoded-secrets
  → api-service.ts:23 发现了硬编码的 API key

[WARNING] coding-style: function-length
  → tag-recommender.ts:45 函数超出 50 行限制（实际 67 行）

[WARNING] tdd-process: docstring-required
  → get_embedding() 缺少 docstring

Result: 1 blocking, 2 warnings
Action: COMMIT BLOCKED — 请修复后重试

Rule 文件的演进

Rules 不是一成不变的，它们随着项目发展不断演进：

V1: 静态规则 — 硬编码的规则集合，适合单一场景。规则以字符串形式写在代码里，新增规则需要修改源码。

V2: 参数化规则 — 规则支持参数配置，适应不同环境。同一套规则模板通过参数覆盖适应多个项目，减少重复维护。

V3: 自适应规则 — 根据历史数据自动调整规则权重和阈值。Continuous Learning 从 review 历史中提取高频违规模式，自动加强对应规则的检查粒度。

Hooks & Automation：无人值守的执行层

为什么需要 Hooks？

问题：Harness 需要人工触发，效率低、容易遗漏。

解决方案：自动化触发机制。

Hook 类型

1. 代码生命周期 Hooks

示例（.claude/hooks.yaml）展示了完整的 Hook 配置，包括触发时机、动作和执行条件。

2. 会话生命周期 Hooks

3. 条件触发 Hooks

基于状态的条件触发机制允许 Hook 根据系统当前状态自动决定是否执行。例如，当错误率超过阈值时自动触发回归测试，当检测到性能下降时自动触发优化流程。

实现示例：在 .claude/hooks.yaml 中定义条件触发规则：

hooks:
  - trigger:
      type: metrics
      condition: "error_rate > 0.05"
    action: run-diagnostic-skill
  - trigger:
      type: performance
      condition: "p99_latency > 200ms"
    action: run-regression-eval
  - trigger:
      type: pattern
      condition: "same_error_3times"
    action: query-knowledge-base

这种机制的价值在于：问题刚出现就能被捕获，而不是等到人工发现。传统的 AI 使用依赖开发者在使用过程中”感觉哪里不对”；条件触发 Hook 把这种主观判断自动化成了客观规则。

Automation 的价值

Automation 将 Harness 从手动触发转变为自动执行，确保每个环节都不会因为人为遗漏而失效。

传统流程 vs Harness 自动化流程对比：

关键差异：传统流程依赖人的记忆和自觉性，Harness 自动化把每个环节都变成系统行为，不会因为忙碌或遗忘而遗漏。这正是”确保 AI 必须做对”的核心——不是信任 AI 会自觉遵守规则，而是用系统强制执行。

💡 Key Insight

Hooks 是 Harness 的”神经系统”——它们将各个组件连接成自动化流水线。没有 Hooks，Eval 和 Rules 只能靠人工触发，无法形成真正的系统。

Continuous Learning：经验如何变成机制

传统 AI 的遗忘问题

问题：AI 没有长期记忆，同样的错误会反复出现。

Continuous Learning 的设计

核心理念：把人工纠正变成系统能力。

💡 Key Insight

把人工纠正变成系统能力——这是 Continuous Learning 的核心贡献。传统 AI 使用中，经验随着会话结束而消失；Harness 把每一次人工纠正都变成了系统能力的积累。

学习流程

Continuous Learning 的学习流程是一个自动化的闭环系统，每次会话结束后自动运行，将人工经验转化为系统能力。

三步闭环：评估有效性 → 模式提取 → 生成 Skill

实现细节

Continuous Learning 的实现分为三个步骤：

Step 1: 评估有效性 — 系统评估本次会话中的纠正是否真正解决了问题，筛选出有价值的经验。例如，开发者在会话中纠正了 AI 对 FastAPI 依赖注入的理解错误，系统记录这次纠正并验证新规则是否生效。

Step 2: 模式提取 — 从有效的纠正中提取重复模式，判断是否可以泛化到其他场景。如果同一个依赖注入错误在多个会话中重复出现，系统判断这是一个值得泛化的模式。

Step 3: 生成 Skill — 将提取的模式封装为可复用的 Skill，供后续会话使用。Continuous Learning 会生成一个新的 fastapi-di-checker Skill，记录依赖注入的正确模式，以后遇到类似场景 AI 自动应用。

实际学习效果示例：

Week 1: 遇到 FastAPI 依赖注入错误 3 次，每次开发者人工解释
Week 2: continuous-learning 生成 Skill，遇到同类错误 1 次，开发者补充
Week 3: AI 自动调用 Skill，错误消失

这是一个从”每次从零开始”到”每次都在进化”的本质转变。传统 AI 使用中，经验随着会话结束而消失；Harness 的 Continuous Learning 把每一次人工纠正都变成了系统能力的积累。

Agent OS：Harness 的载体与实现

everything-claude-code 的完整系统可以用五层架构来理解，每一层都将 Harness 的一个支柱落地为具体实现：

Layer 5: 角色层 — 多 Agent 分裂

核心思想：避免”一个脑子”问题。

传统单 Agent 架构中，一个 AI 同时负责规划、编码、审查——上下文相互污染，能力互相干扰。everything-claude-code 将角色分裂为独立的 Planner、Coder、Reviewer Agent，每个 Agent 有明确的职责边界，通过结构化输出协作。

关键设计：

• 每个 Agent 有明确的职责边界
• Agent 之间通过结构化输出协作（如 Planner 输出设计文档，Coder 按文档实现）
• 避免上下文污染和能力混淆

Layer 4: 能力层 — 可复用技能模块

Skill 的定义：封装特定能力的”AI 插件 + 行为模板”。

Skill 是项目中积累的实战知识单元：TDD Skill 封装了红-绿-重构的流程规范；eval-harness Skill 封装了评估执行逻辑；continuous-learning Skill 封装了经验沉淀机制。有了 Skill，AI 每次会话不需要从零推导项目规范，而是直接读取已有的 Skill。

Layer 3: 控制层 — 机械约束（不是建议）

核心思想：把工程规范”编译进系统”。

Rules 不是给 AI 的”建议”，而是系统强制执行的约束。coding-style.md 定义编码规范、security.md 定义安全红线、tdd-process.md 强制 TDD 流程。Reviewer Agent 对照规则检查输出，违规则拒绝——这不是建议，是机械执行。

关键区别：Prompt 是建议，AI 可以选择不听；Rules 是约束，系统强制执行。

Layer 2: 执行层 — 结构化命令

Command 是用户与系统交互的接口：

设计原则：

• 每个命令对应明确的执行模式
• 命令内部有严格的执行流程
• 用户不需要记住复杂的 prompt，只需要知道 /plan / /tdd / /eval 等少数几个命令

Layer 1: 工具层 — MCP 直接操作世界

MCP（Model Context Protocol）：AI 直接操作外部系统的标准接口。

通过 GitHub MCP，AI 可以直接提交代码、创建 PR；通过 Supabase MCP，AI 可以直接查询数据库、验证数据。核心价值：消灭”人工搬运”环节——不需要人在 AI 和真实系统之间充当传话筒。

真实场景推演：CRM 标签推荐系统

我们用完整的 everything-claude-code 系统来开发一个真实功能。

💡 Key Insight

真实场景推演展示了 Harness 四大支柱如何协同工作：Eval 提供度量、Rules 提供约束、Hooks 提供自动化、Continuous Learning 提供进化。

需求

开发一个 SaaS CRM 的「客户标签推荐系统」

功能：根据客户行为和资料，自动推荐标签

阶段 1：规划（/plan）

用户输入

系统内部：

1. Command Router 识别 /plan 命令
2. Planner Agent 启动
3. 输出结构化规划：

核心价值：避免”直接写代码 → 重构地狱”

阶段 2：TDD 开发（/tdd）

开发者输入 /tdd 命令启动 TDD 开发流程。系统内部进入一个循环执行模式，由 TDD Skill 驱动整个红-绿-重构周期。

用户输入

TDD 开发流程包含以下阶段：

系统内部执行循环

系统内部执行循环是 TDD 的核心，它强制开发者先写测试，再写实现，最后重构。

🔴 RED（先写测试）

TDD Skill 触发后，首先编写一个会失败的测试用例，明确功能预期。

TDD Skill 触发

TDD Skill 自动加载 TDD 流程规范，确保每个步骤都遵循红-绿-重构的节奏。

🟢 GREEN（实现功能）

Coder Agent 编写最简单可行的代码让测试通过，不做多余优化。

Coder Agent 编写代码

Coder Agent 接收设计文档和测试用例，按规范实现功能代码。

🔵 REFACTOR（优化）

重构代码结构：

• 提取 embedding 逻辑到服务层
• 优化数据库查询
• 添加缓存

✅ VERIFY

运行测试

开发者在 TDD 循环的每个阶段都可以运行测试验证当前状态。

边界检查：

• 空客户资料处理
• 大量标签性能
• 并发请求

阶段 3：实时评估（eval-harness）

开发者输入 /eval 命令启动实时评估，系统调用 eval-harness Skill 执行完整的测试套件。

用户输入

eval-harness Skill 执行：

核心价值：AI 开发的”单元测试系统”

阶段 4：代码审查（/review）

开发者输入 /review 命令触发代码审查流程。Reviewer Agent 根据 Rules Engine 中的规则逐项检查代码。

Reviewer Agent 检查清单

Reviewer Agent 的检查清单包括代码风格、安全性、性能和可维护性等多个维度。

阶段 5：系统验证（/verify）

边界测试：

• 空客户资料
• 极大标签数量
• 并发请求

异常路径：

• 数据库连接失败
• Embedding 服务不可用
• 向量搜索超时

性能分析：

• P50 响应时间: 45ms
• P99 响应时间: 120ms
• 吞吐量: 1000 req/s

阶段 6：Checkpoint（关键设计冻结）

在关键节点保存系统状态，确保重要的设计决策和上下文不会丢失。

保存关键状态

在 Checkpoint 阶段，系统执行以下保存操作：

系统保存：

• 当前架构设计
• 关键决策记录
• 上下文摘要
• 经验教训

用于：

• 长期项目记忆
• 新成员 onboarding
• 架构演进追踪

为什么必须 Harness？

因为 LLM 的本质特性：

1. 非确定性：同样的输入可能产生不同输出
2. 幻觉倾向：可能生成看似正确但实际错误的内容
3. 上下文限制：无法一次性记住所有约束
4. 错误累积：小的偏差会随时间放大

解决方案：用系统约束代替”靠 AI 自觉”

关键洞察：AI 工程的未来形态

1️⃣ AI 工程的核心不是”模型”，是”控制系统”

everything-claude-code 证明：模型能力正在快速收敛（GPT-4、Claude、Gemini 差距缩小），系统设计的差异将成为核心竞争力。

💡 Key Insight

模型能力正在快速收敛，系统设计的差异将成为核心竞争力。当所有 AI 都能写代码时，能系统化约束 AI 行为的团队才是真正的赢家。

持续学习不是可选项，是必选项。

3️⃣ 未来软件工程形态

开发者角色的转变：从执行者变成设计师，从编码者变成系统架构师。

总结：从使用 AI 到设计系统

everything-claude-code 不是一个工具，而是一个工程范式。

它告诉我们：

1. 不要只关注 Prompt — 那是表层技巧
2. 投资系统设计 — 这才是长期价值
3. 建立约束机制 — 不要相信 AI 自觉
4. 持续学习沉淀 — 把经验变成机制
5. 量化度量一切 — 不可测量的无法改进

最后思考

当我们谈论”AI 编程”时，大多数人想到的是：

“让 AI 帮我写代码”

everything-claude-code 展示的是另一个愿景：

“设计一个系统，让 AI 在约束下高效、可靠地工作”

这不是替代人类工程师，而是升级人类工程师的角色——从执行者变成设计师，从编码者变成系统架构师。

Harness Engineering 可能是软件工程下一个十年的核心范式。

参考与延伸阅读

• everything-claude-code GitHub - 开源项目
• Skills.sh - everything-claude-code - Skill 市场
• Harness Engineering - Martin Fowler - 理论基础
• Building Effective Agents - Anthropic - Agent 设计最佳实践

深度阅读时间：约 21 分钟

本文基于 everything-claude-code 开源项目的深度架构分析。

发布于 aazh2026.github.io