拆 Harness，一个生成 Agent Team 的 Meta-Skill

大家好，我是若风。

前阵子在拆 ai-website-cloner-template 的「工头模式」时就在想，谁来设计 Agent Team 的队形？工程师每次手搓一次 Agent 编排，从 leader 写到 specialist、从 spec 写到 review gate，每次都重新发明轮子。

revfactory/harness 给了一个直接答案，它是一个 Meta-Skill，专门生成 Agent Team。

7658 stars，1053 forks，2026 年 3 月 26 日开仓，6 月 24 日还在更新。作者 Hwang, M. 还写了一篇正式论文，Harness: Structured Pre-Configuration for Enhancing LLM Code Agent Output Quality。

这篇文章拆 Harness 的核心创新、6 种队形架构、Agent Team vs Subagent 决策树，以及那个传播很广的 +60% 数据到底有多硬。

一句话定位，Harness 到底是什么

Harness 是一个 Claude Code 插件，定位是 Team-Architecture Factory。

你说一句「Build a harness for this project」，它根据你的领域描述，自动生成 .claude/agents/ 下的 Agent 定义文件 + .claude/agents/ 下的 Skills 文件，并按需选择 6 种预定义的 Agent Team 架构之一。

注意它生成的是队形本身，不是某个具体 Agent 或某个具体 Skill。它的输出是「这个项目应该用什么形态的 Agent Team、谁和谁通信、谁向谁汇报、用什么 gate 控制质量」。

这是 Meta 层的工程。把它和之前的 ai-website-cloner-template 放一起对比一下就清楚。

ai-website-cloner-template 是单一队形（工头 + N 个并行 builder）的工程实现，整个项目就是为了把一个固定队形跑好。Harness 不解决具体任务，它生成队形，让你拿到任何任务都能选到合适的编排。

L3 Meta-Factory，Harness 给自己定的位置

README 里 Harness 给自己划了一个分类体系，把 Claude Code 周边项目分了四层。

L0 是单 Agent / 单 Skill。L1 是 harness（具体的项目级 Agent 编排）。L2 是 cross-harness 工作流标准化层，比如 affaan-m/ECC。L3 是 Meta-Factory，生成其他 harness 的工厂。

L3 又分两个子层。Runtime-Configuration Factory，代表是 coleam00/Archon，生成确定性的运行时配置。Team-Architecture Factory，就是 Harness 自己，生成 Agent team 的队形结构。

这种自我定位很清醒，不抢 Archon 的饭碗，明确说「需要确定性运行时配置走 Archon，需要 team 架构走 Harness，两个可以串起来用」。

Pick Archon for runtime determinism, Harness for team architecture, or combine them.

这种「诚实画地盘」反而让 Harness 的可信度上升一档。吹能做一切的 Meta 框架，往往是没人在长期维护。

6 种 Agent Team 架构，是这套项目最值钱的部分

Harness 的核心资产是 6 种预定义的队形架构。任何写 Agent 编排的人都该把这 6 种记住，就像 23 种设计模式之于面向对象。

1. Pipeline（流水线）。前一个 Agent 的输出是后一个的输入。

[分析] → [设计] → [实现] → [验证]

适合每一步都强依赖前一步的场景，比如小说创作，世界观 → 角色 → 剧情 → 写作 → 编辑。

最大风险是瓶颈，慢的一环拖死整条线。设计时尽量让每一段独立。

2. Fan-out / Fan-in（扇出扇入）。同一份输入并行发给多个专家，最后合并。

       ┌→ [专家A] ─┐
[分发] ┼→ [专家B] ─┼→ [整合]
       └→ [专家C] ─┘

适合需要多视角分析的任务，比如综合调研，官方 / 媒体 / 社区 / 背景同时挖。

Harness 的文档直接写，这是 Agent Team 模式最自然的形态，强烈推荐用 Agent Team 而不是 Subagent。原因很具体，team 成员之间能实时互相挑战、互相修正方向，单个 Agent 的发现能即时改写其他人的调查路径。

3. Expert Pool（专家池）。路由器根据输入类型动态调用合适的专家。

[Router] → { 专家A | 专家B | 专家C }

适合输入类型多样的场景，比如代码 review，安全 / 性能 / 架构只在相关时才调用。

Harness 在这里明确推荐 Subagent 而非 Agent Team。理由是「按需调用就够了，常驻 team 是浪费」。

4. Producer-Reviewer（生产-审核）。一个生成、一个审核，反复迭代。

适合质量敏感任务，文案、关键代码、合规审查。Reviewer 的存在把 LLM 的幻觉率压下来。

5. Supervisor（主管）。中央 Agent 动态分发任务给手下的 worker。

[Supervisor] ⇄ { worker × N }

适合任务结构事先不确定，需要 supervisor 实时决定「下一步谁干」的场景。比 Pipeline 灵活，比 Hierarchical 轻。

6. Hierarchical Delegation（层级委派）。自顶向下递归委派。

适合复杂项目的子任务拆分，一个 supervisor 把大任务拆给中层 manager，manager 再拆给底层 worker，类似真实公司的层级。

Agent Team vs Subagent，什么时候用哪个

Harness 把执行模式分成两种，默认是 Agent Team。

Agent Team 模式下，leader 用 TeamCreate 拉一支队伍，队员是独立的 Claude Code 实例，互相用 SendMessage 通信，共享一份 TaskCreate / TaskUpdate 任务列表自我协调。队员之间能直接对话、互相挑战、互相验证，不经过 leader。

Subagent 模式下，main Agent 用 Agent 工具调起 subagent，subagent 只把结果回给 main，互相之间不通信。

决策树是这套项目的另一个亮点。

agent ≥ 2 个吗？
├── 是 → 它们之间需要通信吗？
│        ├── 是 → Agent Team（默认）
│        └── 否 → Subagent 也可以
└── 否 → Subagent（单 agent 不需要组队）

核心原则用一句话总结，Agent Team 是默认值，每次想选 Subagent 时反问一句「队员之间真的不需要通信吗」。

这里还有几个反常识的约束值得记。一个 session 同时只能有一个 active team，但 phase 之间可以解散重组。不能嵌套 team（队员不能拉自己的小弟 team）。Leader 固定不能传。代价是 token 成本高。

如果项目跑多 phase，每个 phase 需要不同专家组合，推荐「先保存产出 → 解散 → 建新队」的模式。前一个 team 的产出存到 _workspace/，新 team 用 Read 接力。

6 阶段工作流，从领域描述到可验证 team

Harness 跑一次的完整流程。

Phase 1: Domain Analysis         领域拆解
   ↓
Phase 2: Team Architecture       选 6 种架构之一
   ↓
Phase 3: Agent Definition        生成 .claude/agents/*.md
   ↓
Phase 4: Skill Generation        生成 .claude/skills/* 
   ↓
Phase 5: Integration             写编排协议、消息格式、错误处理
   ↓
Phase 6: Validation              trigger 验证、dry-run、对比测试

输出是一整套文件。

your-project/
├── .claude/
│   ├── agents/
│   │   ├── analyst.md
│   │   ├── builder.md
│   │   └── qa.md
│   └── skills/
│       ├── analyze/
│       │   └── SKILL.md
│       └── build/
│           ├── SKILL.md
│           └── references/

我之前写 Skills 工程时的最大体会是，Phase 6 的 Validation 是项目能不能长期用的关键。Harness 给了三种验证，trigger 验证（Skill 该不该被触发）、dry-run（不真跑只预演）、with-skill vs without-skill 对比测试。没有第三种，Skill 写得好不好就成了玄学。

那个 +60% 数据，到底有多硬

README 高亮一个数据，+60% avg quality（49.5 → 79.3），15/15 win-rate，−32% variance。

很多人会本能地怀疑「+60% 是不是吹过头了」。作者把这个怀疑直接放进 FAQ 第一条，这是项目最让我欣赏的地方。

数据来源是这样。在姐妹仓 revfactory/claude-code-harness 上做了 15 个软件工程任务的 A/B，一组不带 harness、一组带 harness，作者自己测的。

更细的发现是效果随任务复杂度上升而上升。Basic 任务 +23.8 分，Advanced +29.6 分，Expert +36.2 分。

也就是说，Harness 对简单任务作用有限，对复杂任务收益最大。这其实非常符合直觉。简单任务本来一个 Agent 一次跑完就行，多一层 harness 反而拖累；复杂任务需要分工和审核，harness 的价值才被释放。

作者在 README 里反复强调，任何引用 +60% 这条数据的场合，必须把「n=15, author-measured, third-party replications pending」写在同一句话里，并强烈建议你自己做 2-4 周的内部 pilot 测自己的数字。

坦白讲，看到这种自我约束，我对这个项目的信任度立刻调高。一个项目敢于把「我是作者自测、等第三方复现」写在显眼位置，作者在认真做长期信誉，不是冲一波 star 就跑。

诚实边界，Harness 自己承认的限制

FAQ 里另两条也很诚实。

Q：为什么 Claude Code only？。A：当前官方 runtime 只支持 Claude Code，Codex 的同概念移植 SaehwanPark/meta-harness 已经开源，跨 runtime 的脚手架 Gizele1/harness-init 也在路上。Harness 选择「Claude-Code-native, deep」而不是「multi-runtime, shallow」。

Q：和 Archon 不是竞争吗？。A：不是。Archon 是 Runtime-Configuration Factory 生成确定性运行时配置，Harness 是 Team-Architecture Factory 生成队形结构。两个子层互补，可以串起来用，先 Harness 设计架构、再 Archon 部署运行时。

还有一条更技术的边界。Agent Team 模式依赖实验性功能，必须先开 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。不开就用不了，只能降级到 Subagent 模式。这种依赖实验性 flag 的项目，使用前要先评估你的 Claude Code 版本是否兼容。

几个值得偷的工程思路

除了上面这些，还有几个小亮点值得记下来。

Progressive Disclosure（渐进式披露）。Harness 生成的 Skill 都遵循这条原则，SKILL.md 主文件只放骨架，详细参考放在 references/ 下，按需读。这种设计能让主 Skill 文件保持精简、context 占用低，需要细节时再按需展开。我自己的 Skills 工程也在用这套，效果明显。

Harness-100 作为「队形样本库」。姐妹项目 revfactory/harness-100 直接发布 100 套生产可用的 Agent team harness，覆盖 10 个领域，英文韩文各一份，共 200 包，1808 个 markdown 文件。哪怕你不装 Harness 插件，把这些 markdown 当 reference 读一遍，对理解 Agent Team 设计都有帮助。

Team Reconstruction Pattern。phase 之间用「保存产出 → 解散 → 重组」切换专家组合。这个模式打破了「一个 session 一个 team」的限制，让复杂项目的多阶段编排变成可能。这点和 ai-website-cloner-template 的「worktree 隔离并行 builder」是同一类思路的不同实现，都是为了绕过单 team / 单 process 的约束。

L3 / L2 / L1 的自我定位语言。Harness 不只给自己定位，还给周边项目画地盘。这种「我是什么 + 我不是什么 + 我和邻居怎么协作」的表述方式，值得任何想做开源生态的项目学习。比起吹「我们无所不能」，画清楚自己的位置反而更容易被组合使用。

我从 Harness 里学到的

如果说 ai-website-cloner-template 教会我们「Foreman 模式 + spec 即合约」这一种队形的极致实现，Harness 教会我们队形本身是一个可枚举、可选择、可工程的独立维度。

Agent 编排不再是每次重新发明轮子，而是从 6 种已知架构里挑一种，再按决策树选 Agent Team 还是 Subagent，再生成对应文件。抽象层级提升一档。

我现在再去看自己维护的几个 Skill，已经能立刻判断它们分别属于哪种 pattern。比如 rf-daily-ai-news 是 Fan-out/Fan-in（多源抓取 + 整合），rf-github-to-blog 是 Pipeline（抓取 → 分析 → 写作 → 检查）。这种命名让我能更容易复用之前的工程经验，而不是每次都从头想。

说真的，7658 stars、Apache 2.0、3 个月活跃迭代，加上作者愿意把自己的 A/B 写得这么诚实，Harness 已经进入我「值得长期 follow」的项目清单。

感兴趣直接去 revfactory/harness 仓库，README 的 Self-Positioning 部分和 agent-design-patterns.md 是最值得反复读的两段。装插件用 /plugin marketplace add revfactory/harness 一行命令，跑前记得开 Agent Teams 实验性 flag。

读完记得回来告诉我，你最常写的 Agent 编排属于 6 种里的哪一种。