从“四 AI 分工框架“到“Harness 融合架构“：一个 AI 辅助开发项目的解剖与重构

qq_22786633

440人浏览 · 2026-06-05 20:58:32

qq_22786633 · 2026-06-05 20:58:32 发布

从"四 AI 分工框架"到"Harness 融合架构"：一个 AI 辅助开发项目的解剖与重构

一次将 39 个文件、300+ 行重复配置、零健康检查的 agentGroup，改造为 33 个文件、57 行项目地图、自动化验证的 aiRole 的完整记录。

一、那个让你眼前一亮的项目，其实是一匹没缰绳的野马

我在 GitHub 上看到了 agentGroup——一个基于 Claude Code 的四 AI 角色分工协作框架。项目的 README 很诱人：

“四 AI 专业分工协作框架：设计 + 开发 + 测试 + 管理”

它把软件团队的四个角色——PM（Max）、设计师（Ella）、开发（Jarvis）、测试（Kyle）——分别映射到独立的 Claude Code 会话，通过 shared/ 目录下的 JSON 文件通信，用 tmux 多面板并行运行。每个 Agent 有专属的 CLAUDE.md 行为指令和 PERSONA.md 人设。

Token 优化声称能节省 67-85%。有交互式启动面板。有强制检查点流程。

第一眼看，你会觉得：这就是 AI 辅助开发的未来。

但当你真的把它拆开来看，问题就浮现了。

四个 Agent 的 CLAUDE.md，每个 300 多行，其中约 60% 的内容是逐字复制粘贴的"强制检查点序列"。skills/ 目录全是空的——技能需要从外部 GitHub 仓库下载。没有健康检查脚本，没有任何机制告诉你"这个 Harness 是否已经腐化"。跨 Agent 通信用的是裸 JSON 文件，没有文件锁——两个 Agent 同时写 status.json 就炸了。

更根本的问题是：它的所有约束都是 prompt 级软约束。CLAUDE.md 里写着"第 0 检查点：必须先读 token-optimization.md"，但 AI 完全可以输出一句"📖 已读取"而实际上跳过了——没有任何东西能强制它真的读。

这是一匹爆发力极强的野马。但它没有缰绳。

二、HARNESS_ENGINEERING_GUIDE：一个让问题本质浮现的方法论

就在分析 agentGroup 的同时，我读到了 HARNESS_ENGINEERING_GUIDE。

它提出了一个概念框架——Harness Engineering（驾驭工程）——将大模型比作野马，而 Prompt Engineering 是教它听懂指令，RAG 是给它补充地图，Harness Engineering 是给它设计缰绳、马鞍、围栏和赛道系统。

这个指南定义了五代 AI 开发范式的演进：

阶段	核心	能做什么	局限
Prompt Engineering	单次 prompt 的"魔法咒语"	问答、翻译、摘要	无法处理长周期任务
Context Engineering	填充上下文窗口	带背景的复杂回答	只管"输入什么"，不管"如何运转"
Harness Engineering	设计运行环境与制度体系	多步骤、多会话、可验证	需要系统性架构思维

五个核心原则，每一个都直击 agentGroup 的软肋：

1. 渐进式披露——给 AI 的文档应该是地图（≤200 行），不是百科全书（2000 行 AGENTS.md）。agentGroup 的每个 CLAUDE.md 300+ 行，严重违反。

2. 状态外化——“上下文窗口不是存储”。AI 的记忆必须写入文件，每次会话从文件系统恢复。agentGroup 的 Agent 依赖对话历史来"记住"上次在做什么，没有结构化的 session-state。

3. 分离做事与评判——同一个流程中显式区分 Planner（规划）、Generator（执行）、Evaluator（审查）。agentGroup 把这三个角色拆成了四个 Agent，但每个 Agent 内部没有这个循环。

4. 约束即生产力——“架构边界通过代码和配置强制执行，而非文档约定”。agentGroup 的所有"铁律"都是 prompt 文字，没有 linter、没有 git hook、没有审计脚本。

5. 熵管理——“Harness 自身会随时间腐化”。文档漂移、规则过时、依赖膨胀。必须有定期健康检查。agentGroup 完全没有这一层。

这五个原则形成了一个评判框架。用它来审视 agentGroup，问题不再是"这里好像不太对"，而是"这违反了第几条原则"。

三、两张表，一眼看穿差距

把两者放在一起对比，差距是结构性的：

维度	agentGroup	HARNESS_ENGINEERING_GUIDE
性质	Claude Code 绑定的可运行框架	平台无关的方法论指南
CLAUDE.md 行数	每 Agent 300-400 行，60% 重复	建议 ≤200 行（模板 50 行）
约束类型	Prompt 软约束（AI 可跳过）	配置 + Linter + Hook 硬约束
文档体系	无契约文档、无决策记录	contracts.md + ADR 决策记录
会话恢复	依赖对话历史	session-state.md 结构化恢复
健康检查	无	audit-harness.js 自动化验证
熵管理	无概念	每次模型升级后审视约束必要性

但这不意味着 agentGroup 没有价值。它在一个关键维度上远超 HARNESS——

agentGroup 是可运行的。HARNESS 只是文档。

HARNESS 告诉你"应该做什么"，但不提供可执行的实现。agentGroup 相反，它提供了一个立即可用的多角色协作系统，只是缺乏长期的维护机制。

它们的互补性几乎完美。

四、融合设计：把缰绳套上野马

融合方案的核心思路很简单：

以 agentGroup 的多角色架构为骨架（可运行），注入 HARNESS 的方法论为神经系统（可维护）。

具体来说，做了五年事：

第一件事：建立根级 CLAUDE.md 作为项目地图。

原来 agentGroup 没有根级 CLAUDE.md——每个 Agent 各自为政，没有全局视图。按照 HARNESS 的模板，新建了包含"全局约束 + 角色分工 + 关键路径 + 工作流"的项目地图。

HARNESS 说 CLAUDE.md 应该 ≤200 行。第一版写出了 188 行。后来进一步精简到 57 行。

第二件事：用正式契约取代模糊约定。

原来 agentGroup 的 Agent 间通信靠的是"大家都知道 status.json 是干什么的"。但当新成员加入或 Agent 行为漂移时，没有权威的接口定义。

引入了 docs/contracts.md，登记了五个正式契约：

C-001：Agent 状态更新（任意 Agent → status.json）
C-002：Agent 间通知（源 Agent → notifications.json）
C-003：设计稿交付（Ella → designs/）
C-004：审查报告交付（Kyle → reviews/）
C-005：会话状态恢复（所有 Agent → session-state.md）

每条契约包含：名称、方向、模式、参数格式、副作用、安全级别、并发控制方式。先写文档，后写代码。

第三件事：状态外化——给每个 Agent 一个"记忆文件"。

创建了 memory/session-state.md，每个 Agent 在会话结束时更新自己的段落：当前任务、已完成的变更、待解决问题、下次会话的建议入口。

这意味着即使 Claude Code 的对话历史完全清空，下一个会话也能从文件系统中精确恢复上下文。不再依赖不可靠的对话记忆。

第四件事：让约束可验证——健康检查脚本。

这是最关键的一步。创建了 scripts/audit-harness.js 和 scripts/audit-harness.ps1 双版本，在每次运行后告诉你：

核心文件是否存在
所有 Agent 的 CLAUDE.md 是否 ≤200 行
status.json 和 notifications.json 是否格式正确
是否缺少必要的目录结构

退出码约定：0 = 健康，1 = 阻塞性错误，2 = 仅警告。可以集成到 git hook 或 CI。

第五件事：给共享文件加上锁。

创建了 shared/scripts/file-lock.sh，用 mkdir 的原子性实现文件锁。所有涉及 status.json 和 notifications.json 的写入操作必须先获取锁。

五、删：比写更重要的工程动作

融合后的项目有 39 个文件。但并非每个都有存在的理由。

按"三个问题"法则逐一审视每个文件：

有 Agent 读它吗？
有 Agent 写它吗？
它被某个契约引用吗？

砍掉了 6 个文件：

文件	删除原因
`README-IMPLEMENTATION.md`	初始分析文档，已被 CLAUDE.md + docs/ 取代
`HARNESS_ENGINEERING_GUIDE.md`	方法论原文，核心已融入各文件，保留只会漂移
`shared/CHANGELOG.md`	工件日志，docs/contracts.md 已有变更记录
`shared/operation-log.md`	操作日志，无任何契约或 Agent 引用
`scripts/clean-system-files.sh`	通用工具，与 Harness 核心无关
`panel.sh`	tmux 面板，与 start-*.sh 重复，Windows 不可用

然后又砍掉了 3 个空目录：shared/docs/、shared/templates/、max/memory/。

接下来是"删行"——把根级 CLAUDE.md 从 188 行压到 57 行：

**ASCII 架构图（26 行）**→ 一行文字：用户 → Max → Ella/Jarvis/Kyle → shared/
**目录结构树（36 行）**→ "关键路径"表格：只列 AI 需要知道的 10 个路径
**设计原则（5 条）**→ 全删。AI 只需要执行，不需要理解方法论
已知限制→ 全删。人类文档，AI 的行为不会因读到它而改变
何时更新本文件→ 全删。维护清单，不影响 AI 行为
技术栈锁定→ 全删。Harness 自己的运行环境 AI 不需要知道
装饰性描述→ 全删。"融合 Harness Engineering 方法论与 agentGroup 多角色架构"这种句子对 AI zero value

最后，四个 Agent 的 CLAUDE.md 也从原来的 300+ 行压缩到 79-98 行。砍掉的内容主要是：

重复的检查点流程（改为引用根 CLAUDE.md 的全局约束）
冗长的 Token 统计格式说明（改为一行的精简格式）
重复的共享区目录树（改为"关键路径"引用）

六、最终产物

改造后的 aiRole，33 个文件，每个都有明确的"谁读写、为什么"：

airole/
├── CLAUDE.md                    57 行  ← 根级项目地图
├── docs/
│   ├── architecture.md                 ← 系统架构
│   ├── contracts.md                    ← 5 个正式接口契约
│   └── decisions/
│       ├── ADR-001-hybrid-architecture.md
│       └── ADR-002-multi-agent-model.md
├── memory/
│   └── session-state.md                ← 4 个 Agent 的会话恢复点
├── scripts/
│   ├── audit-harness.js                ← 健康检查 (Node.js)
│   └── audit-harness.ps1               ← 健康检查 (PowerShell)
├── max/  (CLAUDE.md 91行 + PERSONA.md + skills/)
├── ella/ (CLAUDE.md 79行 + PERSONA.md)
├── jarvis/(CLAUDE.md 97行 + PERSONA.md + skills/)
├── kyle/ (CLAUDE.md 98行 + PERSONA.md + skills/)
├── shared/
│   ├── status.json / notifications.json
│   ├── tasks/ (meetings / todos / projects)
│   └── scripts/ (file-lock + 通知 + 状态工具)
└── start-*.sh / start-all.ps1

运行 node scripts/audit-harness.js：

🔍 aiRole Harness 健康检查

━━━ 核心文件 ━━━
  ✅ 根级项目地图 — 存在
  ✅ CLAUDE.md — 57行 ✅

━━━ Agent 配置 ━━━
  ✅ max/CLAUDE.md — 91行 ✅
  ✅ ella/CLAUDE.md — 79行 ✅
  ✅ jarvis/CLAUDE.md — 97行 ✅
  ✅ kyle/CLAUDE.md — 98行 ✅

━━━ 共享工作区 ━━━
  ✅ status.json 格式验证通过
  ✅ notifications.json 格式验证通过

━━━ 文档体系 ━━━
  ✅ docs/architecture.md — 存在
  ✅ docs/contracts.md — 存在
  ✅ docs/decisions/ — 存在

━━━ 状态外化 ━━━
  ✅ memory/session-state.md — 存在

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Harness 状态：健康

七、三条最重要的教训

1. Prompt Engineering 管一次，Harness Engineering 管长期。

agentGroup 的"强制检查点"写得再详细，也无法阻止 AI 在第五十次对话后开始偷懒。HARNESS 的答案是：不要靠 prompt 约束行为，靠脚本验证状态。prompt 告诉你应该做什么，audit 验证你真的做了。

2. 文件数量不是资产，是负债。

39 → 33 个文件，188 → 57 行，300+ → 79-98 行。每一次削减都在减少"文档漂移"的表面积。你维护的每一样东西，都需要在未来审核它是否仍然正确。少一点，就是好一点。

3. 好的 Harness 让 AI 少读、让人类少想。

57 行的根级 CLAUDE.md 之所以成立，是因为 AI 不需要知道"为什么"，只需要知道"去哪里找"。详细的架构在 docs/architecture.md，详细的接口在 docs/contracts.md，详细的决策在 docs/decisions/。CLAUDE.md 只是地图——地图上不需要画每一棵树。