从零搭建 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 步演进路径
01你现在处在哪一级?
Harness Engineering 这个概念已经流行一阵了。网上大多数讨论停留在理论层——反复解释为什么现代 AI 开发不能再靠单个 Prompt。但真正的问题没人回答:
概念我懂了。第一步到底做什么?
先看一眼下面这张成熟度地图,搞清楚你现在站在哪里:
大部分人卡在 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 后,收益非常直接:
Rule 更精简——Rule 只强制"必须做",Skill 管"怎么做" AI 执行稳定性大幅改善——不再现场推导,直接调用标准化流程 维护成本骤降——换工具链只改 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 无论怎…