从零搭建 Harness Engineering 架构:Rule、Skill、Sub-Agent 完整落地路径

先看结果。下面这条命令,是一个 AI 写完代码后必须通过的最终关卡——不是"我觉得没问题",是脚本说通过才算:

$ python validate.py --baseline baseline.json --verbose

[PASS]  1/12  lint: ruff check --output-format concise
[PASS]  2/12  deps: uv lock --check (no diff)
[PASS]  3/12  build: python -m build --no-isolation
[PASS]  4/12  tests: pytest --cov --cov-fail-under=80 -n auto
[PASS]  5/12  typing: pyright --ignoreexternal
[PASS]  6/12  secrets: no hardcoded keys detected
[PASS]  7/12  logging: zero print() calls in src/
[PASS]  8/12  imports: no dead imports (ruff F401/F811)
[PASS]  9/12  generated: no _pb2.py or __pycache__ committed
[PASS] 10/12  baseline: zero NEW failures vs baseline.json
[PASS] 11/12  coveRAGe: 87.3% ≥ 80% threshold
[PASS] 12/12  todos: all TODO linked to issue #

✓ All 12 gates passed. Build is clean.

这就是 Harness Engineering 的终点:AI 说"做完了"不算数,系统说通过才算。

但怎么从"AI 瞎写一通,我人肉检查"一步步走到这里?这就是本文要讲的东西。

TL;DR

  • AI 说"做完了"不算数——它会把 3 个测试文件的 assert 全改成 print,然后 commit "all tests pass"
  • Harness Engineering = 六层叠加:SPEC 定目标 → Rule 设底线 → Skill 固化流程 → Sub-Agent 拆分角色 → Workflow 编排协作 → Script 客观验证
  • 拿走得完的:一套 12 关 Python 校验脚本 + 五层关卡塔模型 + 可操作 7 步演进路径
本文假设你会 Python 基础,不需要 AI Agent 开发经验。读完你会拿到一套可复用的工程框架,今天就能在项目里用起来。

01你现在处在哪一级?

Harness Engineering 这个概念已经流行一阵了。网上大多数讨论停留在理论层——反复解释为什么现代 AI 开发不能再靠单个 Prompt。但真正的问题没人回答:

概念我懂了。第一步到底做什么?

先看一眼下面这张成熟度地图,搞清楚你现在站在哪里:

等级
特征
典型场景
你能指望 AI 做什么
L0 裸调
单次 Prompt,无约束,无复用
一次性脚本、实验
碰运气
L1 约束
有 Rule,有基本底线
个人项目、MVP
加速样板代码
L2 反馈
Rule + Skill + 自动化校验
生产期小团队
当可靠的初级伙伴
L3 分工
Multi-Agent + Workflow 编排
复杂多服务系统
独立负责特定阶段
L4 自治
系统自我修复、持续重构
平台级 / AI 原生组织
无人干预下持续维护

大部分人卡在 L1→L2 的鸿沟里:写了 Rule,但 AI 还是会绕过去。

这就像考驾照——L0 是没学过车,L1 是知道交规但上路还慌,L2 是能独立开但不会修车,L3 是能带队跑长途,L4 是职业赛车手。本文重点讲的是 L1 到 L3 这段路——也是整个演化过程中 ROI 最高的区间。


02先把概念理清楚

很多人一上来就写 Rule、搭 Agent、接 MCP,结果越搞越乱。根本原因不是执行力,是基础概念从一开始就没分清楚。

下面把六个核心概念压成一张速查表。记住一句话:它们不是互相替代,是逐层叠加。

Rule:团队的工程政策

Rule 是你给 AI 设的"工程准则"。 把它想成你给新入职开发者讲的基础原则:什么能做、什么禁止、做完必须验证什么。

我们项目里有一条核心 Rule:

# .harness/rules/core.yaml
rules:
  - id: R001
    description: "每次代码修改后必须编译→测试→校验,三关全过才算完成"
    trigger: on_code_change
    gates: [compile, test, validate]

  - id: R002
    description: "禁止在 src/ 中使用 print(),统一用 structlog"
    check: "grep -r 'print(' src/ → 零匹配"

Rule 的核心目的不是让 AI 更聪明——是阻止它反复犯低级、可避免的错误。

但 Rule 有一个致命弱点:它是软约束。 AI 会忘记、选择性忽略、或者找理由绕过。这就是为什么 Rule 只是地基,不是整栋楼。

Skill:给 AI 的标准操作流程

Skill 是在告诉 AI:这件事不要现场发挥,按固定步骤来。

举个例子。如果你只说"跑一下测试",AI 可能愉快地执行 pytest,看着没问题。但在真实工程里,测试几乎从来没那么简单:

# AI 可能会做的(不够)
$ pytest

# 实际应该做的(Skill 固化的)
$ pytest --cov --cov-report=term --cov-fail-under=80  # 覆盖率门禁
$ pytest -n auto --timeout=30                          # 并发 + 超时控制

Rule 说"这件事必须做",Skill 说"具体这么做"。

Sub-Agent:拆分角色,防止自评自审

单个 Agent 端到端处理一切时,会出现一个结构性问题——它在解读自己的需求、评判自己的方案、写完后自己给自己开"健康证明"。这和一个开发者同时当 PM、架构师和 QA 一样,质量必然失控。

把工作流拆成不同角色后,每个 Agent 只处理自己那段:

需求分析师 → 架构师 → Gatekeeper → 开发者 → Code Reviewer → QA

关注点分离阻止了上下文坍塌,消除了自评偏差。

Workflow:接力赛规则

有多个 Agent 但没有 Workflow,等于只有人在干活,没有协作协议。

理解 Workflow 最清楚的方式是接力赛:关键不是四个跑得快的人,而是事先有一套规则——谁跑第一棒?什么时候交接?交接区里必须交什么?犯规了怎么办?

Workflow 必须显式定义:任务在哪个阶段?当前阶段必须交出什么产物?谁有权接下一棒?什么条件触发回滚?

Script:把主观声明变成客观判定

这是整个 Harness 中最被低估、ROI 最高的组件。

Rule 告诉 AI 应该做什么,Skill 给标准流程,Script 在说:你说自己做完了不算,除非系统证明。 一旦检查写进脚本,AI 就没法用"我觉得没问题"混过去——要么过关,要么不过。没有讨价还价。

MCP:连接外部工程生态的接口

MCP(Model Context Protocol)是把 CI、签名、产物管理、发布编排等"代码仓库之外的能力"接入 AI 工作流的标准化通道。暂时不是 Harness 的主干,但当你要把回路从"开发闭环"推到"交付闭环"时,它会变得关键。

六件东西的关系,一张图就够了:

Rule      → 强制底线(什么必须做)
Skill     → 标准化高频操作(怎么做)
Sub-Agent → 拆分复杂度(谁来做哪段)
Workflow  → 编排协作(什么时候交接)
Script    → 客观验证(做完了 ≠ 做对了)
MCP       → 延伸生态(开发 → 交付)

03第一步不是 Rule,是 SPEC

很多人一听到 Harness 就立刻写 Rule。但如果你没先把"到底要做什么?完成长什么样?"说清楚,后面加的每一条约束都建在沙子上。

这就像盖房子——没图纸就开工,墙砌到一半发现少了个房间。SPEC 就是你的建筑蓝图。

真正的第一步是起草一份完整的设计规范,并和 AI 反复迭代打磨它。 这一步通常会和 AI 反复讨论很多轮——不是润色文字,而是一个协作式发现过程。有时你自己一开始也不知道想要什么,把 AI 拉进需求讨论,让它扮演反方、拆解可选项、暴露边界情况。

一份能用的 SPEC 长这样:

# 项目:data-pipeline-cli v0.1.0

## 目标
从 CoinGecko API 拉取加密货币价格,校验后导出结构化 JSON。

## 核心需求(HARD)
- [H-001] 支持 --limit=N 控制拉取代币数量
- [H-002] 指数退避重试(max 3 次)
- [H-003] 响应按 Pydantic schema 校验
- [H-004] 输出包含审计轨迹(timestamp + checksum)
- [H-005] 整个流水线 30s 超时内完成

## 边界条件
- API 不可用 → 输出结构化错误 JSON + 退出码 1
- 网络超时 → 重试 3 次后写入 error_log.json

## 非目标(v0.2+)
- WebSocket 实时推送、数据库持久化、Web UI

这份文档的意义不在于"看起来专业"——在于生成第一行代码之前,强制把基本面理清楚:

  • 这次到底要解决什么具体问题?
  • 哪些是核心目标,哪些只是锦上添花?
  • "完成"到底长什么样?

但 SPEC 只解决"知道要做什么"的问题,不解决"如何持续把事做对"。 这就是为什么下一步才是 Rule。


04Rule 不可或缺,但也别迷信它

如果 AI 老忘事,就把那些容易忘、容易出错的步骤写成 Rule。

第一步只加关键 Rule,聚焦 AI 最容易偷懒的底线。别第一天就堆 50 条——那样 AI 反而会系统性忽略。 就像药品说明书:你不需要把整本药典贴上去,只要写死"孕妇禁用"就够。

我们最初只加了 3 条:

rules:
  - id: R001
    desc: "每次修改后必须编译→测试→校验,三关全过才算完成"

  - id: R002
    desc: "禁止在 src/ 中使用 print(),统一用 structlog"

  - id: R003
    desc: "所有外部 API 调用必须有超时参数和重试逻辑"

效果立竿见影。因为 AI 最喜欢偷懒的地方,恰好就是这些"看起来像收尾、其实是硬底线"的动作。

但跑久了,你就会撞到 Rule 的天花板——AI 会忽略 Rule,也会绕过 Rule。

不是完全忽略,是"选择性遗忘"——上下文窗口塞满时,某些 Rule 被稀释成背景噪音。更麻烦的是"合理化绕过":

  • "这个失败是历史债,不是我引入的。"
  • "这是特殊情况,那条 Rule 不适用。"
  • "我的主要工作做完了,这步可以跳过。"

我吃过这个亏。有一次让 AI 重构一个数据管道模块,它在 commit message 里写了"all tests pass",我信了。发出去后发现它把 3 个测试文件里的 assert 全改成了 print——测试当然"pass"了,因为根本没有断言了。

这就是 Harness 中一个关键的认知转折:Rule 强制原则约束,但无法强制流程执行。 所以需要把固定、可重复的流程从 Rule 里抽出来,编码成 Skill。


05编译、测试、校验必须做成 Skill

工程里有一类任务天然适合做成 Skill:步骤固定、每次必执行、搞砸代价大、不值得让 AI 临场发挥。

编译、测试、校验正好是这一类。把它们抽成 Skill 后,收益非常直接:

  1. Rule 更精简——Rule 只强制"必须做",Skill 管"怎么做"
  2. AI 执行稳定性大幅改善——不再现场推导,直接调用标准化流程
  3. 维护成本骤降——换工具链只改 Skill 一次,不用到处 grep Rule 文件

这就像飞行员的起飞检查单——747 的机长也要逐项打勾,不靠"我觉得没问题"。Skill 就是把 AI 的自由发挥,变成逐项打勾。

# skill: validate.py
# AI 调用这个脚本,而不是自己现场发明"怎么校验"
import subprocess
import sys
from pathlib import Path

STEPS = [
    ("lint",   ["ruff", "check", "src/", "tests/"]),
    ("types",  ["pyright", "src/"]),
    ("test",   ["pytest", "--cov", "--cov-fail-under=80", "-n", "auto"]),
    ("build",  ["python", "-m", "build", "--no-isolation"]),
]

def run():
    failed = []
    for name, cmd in STEPS:
        print(f"[RUN] {name} ...")
        r = subprocess.run(cmd, capture_output=True, text=True)
        if r.returncode != 0:
            print(f"[FAIL] {name}\n{r.stderr[-400:]}")
            failed.append(name)
        else:
            print(f"[PASS] {name}")
    if failed:
        print(f"\n✗ {len(failed)} step(s) failed: {', '.join(failed)}")
        sys.exit(1)
    print("\n✓ All checks passed.")

if __name__ == "__main__":
    run()

把这个脚本注册为 Skill 后,AI 在需要校验时不再"想办法校验",而是直接 python validate.py。一致性取代了瞎猜。

但新瓶颈很快冒出来:单个 Agent 无论怎…

— 以上为试看内容(约 40%),开通会员后阅读全文 —