QQ音乐Harness Engineering实践
公众号名称：腾讯云开发者
作者名称：黄欣欣
发布时间：2026-05-21 08:45
关注腾讯云开发者，一手技术干货提前解锁👇
当 AI 开始快速生成大量代码，真正的瓶颈就不再是”写不出来”，而是”看不完、想不清、管不住”。 本文基于一个落地在大仓多服务（Monorepo Microservices）场景中的开源工程框架，回答一个核心问题：如何把 AI 协作从对话式编码，升级为可控、可审计、可复用的工程过程？
01
从 “Vibe Coding” 到 Harness Engineering
AI 辅助编程的发展脉络，大致经历了三代演进：代码补全 → 对话式编码（Chat） → 自主式 Agent。每一代都在提升 AI 的自主性，但同时也把一个更深层的问题暴露得更彻底。
在对话式编码阶段，一种典型的工作模式逐渐流行：开发者把需求丢给 AI，扫一眼输出”看起来对”就直接采纳，不审 diff、不追问逻辑、不验证边界。Andrej Karpathy 给这种做法起了一个名字 —— vibe coding：凭感觉写代码。在脚手架搭建、原型验证、一次性脚本等低风险场景下，vibe coding 确实好用 —— 简单、快、爽，几乎没有认知负担。
然而，一旦进入生产级代码库，vibe coding 的三个结构性缺陷会迅速暴露：
| 维度 | vibe coding 的典型表现 | 生产级工程的要求 |
|---|---|---|
| 信息损耗 | 同一句话多次执行给出不同实现；AI 按自己的理解”猜”需求 | 需求→设计→代码每一步都要有显式产出和可追溯关系 |
| 知识孤岛 | AI 只知训练语料里的通用知识，不懂团队历史决策和私有约束 | 团队知识需要被持久化为 AI 可消费、可演进的工程制品 |
| 验证断档 | ”能跑”就直接提交，概率性错误顺着 MR 滑进主干 | 每个关键节点都要有可机读的质量门禁和审计记录 |
GitHub、Anthropic 等机构的公开研究都指向同一个结论：AI 能显著提升编码效率。但这里有一个容易被忽略的配套事实 —— 生成速度在提升，验证能力却没有同步提升。代码出得越快，错误积累得也越快；AI 自主性越强，偏离正确轨道时的修正成本就越高。生成快、验证慢、错误累积 —— 这就是 AI 时代软件工程的核心矛盾。
解决这个矛盾，靠的不是更长、更复杂的 prompt，而是工程化。
Harness Engineering 的核心理念是：AI 参与问题分析、方案设计、编码实现、审查和验证，但最终判断权始终留在工程师手中。Engineering 的本质是约束下的优化 —— 在质量、安全、可维护性等约束下寻找最优可行解。Harness Engineering 正是在这个框架里把 AI 当作协作者，而不是让 AI 成为”绕过约束的捷径”。
换一种说法：vibe coding 的底层逻辑是”让 AI 尽量自由地生成”，而 Harness Engineering 的底层逻辑是”让 AI 在正确的轨道上尽量高效地生成”。自由和高效并不矛盾 —— 真正的高效，恰恰来自正确的约束。
02
核心公式：代码产出 = AI 能力 × 上下文质量
如果说第 1 节回答了”为什么需要工程化”，这一节要回答的是”工程化的杠杆点在哪里”。
2.1 为什么是乘法，不是加法
代码产出 = AI 能力 × 上下文质量 —— 这个乘号至关重要。
如果公式是加法（ AI 能力 + 上下文质量 ），那么模型足够强的时候，上下文差一点也无妨，大不了靠能力硬补。但乘法的含义截然不同：当上下文质量趋近于零时，模型再强，产出也是零。一个不了解服务拓扑的 AI，即使参数量再大，也会在跨服务需求面前持续犯错；一个不掌握团队规范的 AI，即使推理能力再强，也会产出不符合约束的代码。
这不是理论推演，而是日常现实：模型能力在过去两年快速提升，但 AI 在真实业务仓中的”可用度”并没有同步提升 —— 瓶颈不在模型，而在上下文。
2.2 真实业务仓里的上下文缺口
在真实业务仓里，AI 拿不到的上下文远比想象中多。这些缺口大致可以归为五类：
| 缺口类型 | 典型问题 | AI 的”盲区” |
|---|---|---|
| 隐性规范 | 团队约定的锁机制、埋点规则、错误码空间 | AI 不知道这些规范存在，更不知道它们的具体约束 |
| 历史决策 | ”为什么当时选了 A 方案不选 B” | 训练语料里没有团队内部的决策记录 |
| 服务契约 | IDL 字段的冻结状态、下游是否强依赖 | AI 看到的是文本，不理解哪些字段动不得 |
| 跨服务依赖 | 同一个需求要改哪几个服务、谁调谁 | AI 缺乏全局视角，不知道改动的影响面 |
| 演进轨迹 | 某个模块上次大改的坑、灰度策略 | AI 没有跨会话记忆，无法继承团队的经验教训 |
每一类缺口，都在拉低上下文质量这个乘数因子。而当前行业的主流解法 —— 写更长的 prompt、贴更多的文档 —— 本质上是在用人力填补上下文，成本高、不可持续、无法复用。
2.3 工程化的杠杆点：系统性提升上下文质量
Harness Engineering 的核心思路，是把”补上下文”从一项每次重复的人工操作，变成一项一次投入、持续生效的工程基建：
-
隐性规范 → 写进 context/team/，所有 AI 会话自动继承
-
历史决策 → 沉淀到 context/project/{module}/experience/，新人新模型都能读到
-
服务契约 → 编码进 .service-matrix/dependencies.yaml 和 IDL 门禁，AI 不再”猜”依赖关系
-
跨服务依赖 → 由服务矩阵自动解析，影响面分析从”搜索”变成”查表”
-
演进轨迹 → 通过 Self-Refinement 闭环，让每次纠错都沉淀为团队资产
这就是为什么核心公式的乘号如此重要 —— 提升上下文质量，是比提升模型能力更高效的杠杆。因为模型能力的提升依赖外部厂商，而上下文质量的提升，完全掌握在团队自己手中。
03
什么是 Harness Engineering？
要理解为什么我们的框架叫 Harness Engineering，先看看 “Harness” 这个词在 AI 工程语境中的含义变化。
3.1 为什么是”Harness”？一个词的语义迁移
“Harness” 在英语里本义是马具 / 挽具：把一匹原始力量巨大但方向不定的马，通过缰绳、鞍具、辔头接入可控系统。这个隐喻被 AI 工程社区借用后，恰好概括了当下 LLM 应用的本质矛盾：
┌─────────────────────────────────────────────┐
│ 原始 LLM = 一匹烈马 │
│ ┌──────────────────────────────────────┐ │
│ │ 能力强 ✅ 方向不定 ❌ │ │
│ │ 速度快 ✅ 走不了远路 ❌ │ │
│ │ 理解广 ✅ 没有持久记忆 ❌ │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
│
▼ 加上 Harness（挽具）
┌─────────────────────────────────────────────┐
│ Harness = 让烈马能拉动真实生产载荷的一整套 │
│ 挽具、缰绳、辔头、套绳 │
│ ┌──────────────────────────────────────┐ │
│ │ 工具编排 / 记忆 / 沙箱 / 校验 / 反馈 │ │
│ │ 上下文工程 / 生命周期 / 人机协同 │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
│
▼
**一个能稳定完成复杂任务的 Agent**3.2 Harness Engineering 的四大标准组件
业界对 Harness Engineering 的共识拆解为四大子系统：
┌──────────────────────────────────────────────────────────┐
│ Harness Engineering │
│ │
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ ① 运行时控制系统 │ │ ② 上下文工程 │ │
│ │ │ │ │ │
│ │ 工具编排 │ │ Context Window 优化 │ │
│ │ 状态持久化 │ │ 动态检索 / 摘要 │ │
│ │ 错误恢复 │ │ 防 Context Rot │ │
│ │ 反馈循环 │ │ 信息优先级 │ │
│ └─────────────────┘ └─────────────────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ ③ 工具集成与防护 │ │ ④ 生命周期管理 │ │
│ │ │ │ │ │
│ │ API 调用标准化 │ │ 多步长任务 │ │
│ │ 预执行校验 │ │ Checkpoint / Crash Recovery │ │
│ │ 阻止幻觉执行 │ │ Human-in-the-Loop │ │
│ │ 安全护栏 │ │ 跨会话状态 │ │
│ └─────────────────┘ └─────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────┘3.3 QQ音乐 Harness Engineering
但真实的企业级研发场景里，一个需求从开始到上线要经历多个 Agent、多个工具、多个服务、多个仓库的协同。这一层业界留白了：
┌────────────────────────────────────────────────────────────────┐
│ │
│ ▼ │
│ Harness Engineering 接管的范围 │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Team Agent Governance │ │
│ │ = Multi-Agent × Multi-Service × Multi-Lifecycle │ │
│ │ （让团队的 AI 协作跨会话、跨工具、跨服务可治理） │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘04
QQ音乐 Harness Engineering 框架实现
如果没有真实业务压力，任何工程框架都容易变成“为了框架而框架”。Harness Engineering 不是从抽象方法论开始的，而是从音乐商业化团队每天面对的研发复杂度里长出来的。
我们的业务不是单体应用，也不是一个人维护的小仓库，而是一个典型的单仓多服务与多仓协同场景：业务代码分布在 50+ 微服务中，需求经常横跨多个模块；同时还要处理业务仓、IDL 契约仓和 Harness 规范仓之间的一致性。一个看似简单的需求，背后可能牵动服务调用链、配置、灰度、埋点、错误码、接口契约和历史兼容性。
4.1 真实业务场景：AI 面对的不是“代码”，而是“业务拓扑”
以音乐商业化业务为例，一个需求可能从 TAPD 单开始，经过需求评审、技术方案、服务影响面分析、IDL 契约变更、业务代码实现、测试验证、CR、灰度上线，最后才进入稳定运行。
在这个过程中，AI 需要回答的不是一个简单问题：
“帮我写一个接口。”
而是一组工程问题：
-
这个接口属于哪个业务域？
-
需要改哪个服务？是否还有上游调用方和下游依赖方？
-
是否涉及 IDL？如果涉及，契约仓路径在哪里？字段是否允许修改？
-
业务仓、IDL 仓、Harness 仓是否在同一个需求分支上？
-
需求文档、设计文档、任务拆分和代码 diff 能否互相追溯？
-
这个模块过去有没有踩过类似坑？经验沉淀在哪里？
-
如果 AI 这次犯错，如何确保下次不再犯同类错误？
这些问题如果靠一次聊天解决，必然会漂移；如果靠人工口头提醒，必然会漏；如果靠模型自己搜索，必然不稳定。因此，我们需要一个框架，把这些问题变成可读取、可校验、可复用的工程结构。
4.2 业务复杂度拆解：四类约束必须进入框架
我们最终把业务复杂度拆成四类约束，并分别落到 Harness Engineering 的具体结构里。
| 业务约束 | 具体问题 | Harness Engineering 的技术落点 |
|---|---|---|
| 流程约束 | 需求、设计、开发、交付之间容易跳步 | 五阶段主流程 + 四道门禁 + main-process-numbering.md |
| 拓扑约束 | AI 不知道服务之间真实依赖 | .service-matrix/dependencies.yaml+ 影响面分析 |
| 契约约束 | IDL 字段兼容性和分支一致性容易被忽略 | 三仓联动 + idl_required + 服务仓库检查门禁 |
| 知识约束 | 团队规范和历史经验不在模型上下文里 | context/team/、context/harness-framework/、context/project/ 三层知识 |
| 演进约束 | AI 错误修完就丢，下次继续犯 | Self-Refinement + experience/*.md 版本化沉淀 |
注意，这里每一类约束都不是“提示词写得更详细”就能解决的。提示词可以提醒模型，但无法保证长期一致；聊天记录可以解释当下任务，但无法成为团队资产；单个工具可以提升效率，但无法替团队定义流程和审计口径。
4.3 为什么一定要自研：通用产品无法替我们定义业务语义
我们并不是因为“不喜欢现成工具”才自研。事实上，Harness Engineering 明确复用 Claude Code、Gemini CLI、Codex CLI、Continue、CodeBuddy 等执行层能力。真正需要自研的是它们上方这层业务语义和工程治理。我们有自己的微服务治理规范，有自己单独的一套CI/CD Devops 流程。调研了司内和业界的一些开源方案，发现适配度成本很高。最终选择复用开源方案的能力，站在巨人的肩膀上，搭建自己的Harness Engineering框架。
通用产品很难替我们定义下面这些内容：
1. 服务矩阵语义
哪些服务属于同一业务域，哪个服务依赖哪个服务，哪个模块需要 IDL，仓库路径如何解析，是否存在多级 repo_path，这些都是业务团队自己的拓扑知识。它们必须由团队维护在 .service-matrix/dependencies.yaml 中，而不能依赖模型临场搜索。
2. 需求生命周期语义
我们的需求不是“一句话任务”，而是有阶段、有门禁、有产物、有追溯关系的生命周期对象。什么时候算完成需求定义？什么时候可以进入开发？设计评审不过能不能继续写代码？这些规则必须写进 context/harness-framework/main-process-numbering.md，并被 Agent Skill Command 共同遵循。
3. IDL 契约语义
对业务系统来说，IDL 不是普通文本。它代表服务边界、兼容性和上下游契约。通用 AI 工具可以修改 IDL 文件，却不知道哪些字段冻结、哪些变更需要同步业务仓、哪些场景必须先建三仓同名分支。因此我们把 IDL 契约纳入三仓联动和阶段门禁。
4. 团队经验语义
模型知道通用 Go 最佳实践，但不知道某个服务过去因为分页无上限打爆过下游，也不知道某个 goroutine 泄漏问题在本模块出现过两次。团队经验必须写成 AI 可消费的知识文件，进入 context/project/{project}/{module}/experience/。
5. 工具解耦语义
今天团队可能用 Claude Code，明天可能换 Gemini CLI，内部也可能接入 CodeBuddy。我们不希望流程和知识被任何一个运行时锁定，所以把规范保存在 .codebuddy/ 和 context/，再渲染到不同 CLI 的本地目录。
4.4 自研不是重造 IDE，而是补齐 L5 工程治理层
一个容易误解的点是：自研 Harness Engineering 并不意味着我们要重造 Cursor、CodeBuddy 或 Claude Code。我们不做补全，不做编辑器，不做模型网关，不做通用 Agent 运行时。
我们只补齐一层：L5 工程治理层。
┌──────────────────────────────────────────────────────────────┐
│ L5 Harness Engineering：团队拥有的工程治理层 │
│ - 五阶段流程 │
│ - 四道门禁 │
│ - 三层知识体系 │
│ - 服务矩阵 │
│ - Self-Refinement │
│ - 多运行时适配 │
├──────────────────────────────────────────────────────────────┤
│ L3/L4 执行层： │
│ - 代码阅读 │
│ - 文件编辑 │
│ - 命令执行 │
│ - 测试修复 │
├──────────────────────────────────────────────────────────────┤
│ L1/L2 体验层：IDE、补全、对话、diff 可视化 │
└──────────────────────────────────────────────────────────────┘换句话说，Harness Engineering 的边界非常清晰：不替代执行工具，只定义执行工具必须遵守的工程上下文和协作协议。
4.5 技术路线：把业务约束编码成 AI 可执行的工程制品
从技术实现上看，Harness Engineering 的核心不是某个复杂服务，而是一组被版本化管理的工程制品：
| 工程制品 | 作用 | 为什么重要 |
|---|---|---|
AGENTS.md | 全局协作规范和硬规则入口 | 给所有 AI 运行时一个共同的行为基线 |
.codebuddy/skills/ | 可复用能力单元 | 把复杂任务拆成可委派、可 review 的 Skill |
.codebuddy/agents/ | 专家角色定义 | 让需求评审、设计评审、追溯检查等角色专业化 |
.codebuddy/commands/ | 标准化入口 | 把“我想做需求”变成稳定命令，而不是自由聊天 |
context/team/ | 团队级规范 | Git、日志、错误码、安全等规范 |
context/harness-framework/ | 框架工程规范 | 定义 Harness 自身流程、门禁、模板和校验规则 |
context/project/ | 服务级知识 | 每个模块的架构、经验、约束和历史坑 |
.service-matrix/dependencies.yaml | 服务拓扑与仓库路径 | 让 AI 不再猜服务关系和路径 |
requirements/ | 需求生命周期产物 | 让需求、设计、任务、门禁和代码形成追溯链 |
scripts/install.sh | 多运行时渲染 | 让同一份规范适配不同 AI CLI |
这些文件全部在仓库里，意味着它们可以被 code review、可以被 diff、可以被回滚、可以被持续演进。对 AI 来说，它们是上下文；对团队来说，它们是资产；对工程管理来说，它们是审计线索。
4.6 典型链路：一个需求如何被 Harness 接住
以一个跨服务需求为例，Harness Engineering 的运行方式不是“用户随口说一句，AI 直接改代码”，而是逐步收敛上下文：
-
需求进入：通过 /requirement:new 创建标准目录和需求骨架，需求不再散落在聊天记录里。
-
需求定义：AI 根据模板补齐背景、目标、非目标、验收标准，并触发需求评审门禁。
-
影响面分析：从 .service-matrix/dependencies.yaml 读取服务依赖，识别可能涉及的业务仓和 IDL 仓。
-
设计阶段：生成详细设计，建立“需求条目 → 设计决策 → 开发任务”的追溯关系。
-
设计门禁：由专门 Agent 检查方案完整性、服务边界、IDL 风险和追溯链质量。
-
开发准备：检查三仓分支是否一致，确认服务仓库是否就位，避免进入错误分支或错误路径。
-
编码执行：调用底层 CLI / IDE 的 AI 能力完成代码修改、测试和修复。
-
交付沉淀：将踩坑经验、规则修正和框架改进写入对应知识目录，进入下一轮复用。
这个链路的关键，是让 AI 每一步都在“被约束的上下文”里工作。它仍然可以很快，但快的方向被限定在正确轨道上。
4.7 用工程视角重新定义“AI 编程效率”
如果只统计“从一句话到生成 diff 的时间”，Superpower 类方案非常强。但在生产环境里，真正的效率不是生成速度，而是端到端交付效率：
-
需求是否被正确理解；
-
影响面是否漏掉；
-
设计是否覆盖关键约束；
-
代码是否能追溯到需求；
-
契约变更是否安全；
-
问题是否能在更便宜的阶段被发现；
-
经验是否能进入下一次任务。
Harness Engineering 对效率的定义更接近软件工程的总成本：少返工、少漏改、少口径漂移、少重复踩坑、少工具迁移成本。这也是我们选择自研的根本原因：我们不是要让 AI “看起来更聪明”，而是要让 AI 在真实业务系统里“长期更可靠”。
4.8 小结：从业务出发，再回到技术
因此，自研 Harness Engineering 的逻辑链条是：
真实业务复杂度
→ 单个 AI 助手无法稳定覆盖跨服务、跨仓、跨阶段协作
→ 需要把流程、拓扑、契约、知识、经验显式化
→ 显式化后的工程资产必须可版本化、可审计、可迁移
→ 形成 L5 Harness Engineering 治理层
→ 复用 Superpower 类工具作为执行层，而不是被执行层绑定这条路线看起来比“直接买一个更强的 AI 编程工具”慢，但它解决的是不同层级的问题：Superpower 提升个人战斗力，Harness Engineering 建设团队作战体系。
05
Harness Engineering 总览
5.1 一张图
┌─────────────────────────────────────────────────────────────────────┐
│ Harness Engineering 仓（脑） │
│ │
│ context/ .codebuddy/ requirements/ │
│ ├─ team/ ├─ agents/ (24) └─ {project}/ │
│ ├─ harness-framework ├─ skills/ (34) └─ {req-id}/ │
│ └─ project/ ├─ commands/(35) │
│ └─ hooks/ │
│ │
│ .service-matrix/dependencies.yaml │
│ (xx services, 3 teams, 单一真相源) │
└─────────────────────────────────────────────────────────────────────┘
│
┌───────┼───────┐
▼ ▼ ▼
┌──────┐ ┌──────┐ ┌──────┐
│ 业务仓│ │业务仓│ │ IDL │
│ (手) │ │ (手) │ │ (神经)│
└──────┘ └──────┘ └──────┘
xx+ 微服务，三仓分支联动，一条 TAPD 单 → 三个仓的同名分支5.2 六句话讲清楚
-
Harness 仓 = 大脑：只放规范、知识、需求状态、工具链，不放任何业务代码
-
业务仓 = 手脚：代码和测试，路径由 .service-matrix/dependencies.yaml 的 repo_path 声明
-
IDL 契约仓 = 神经：跨服务协议（.jce 等），路径由同一个文件的 idl_repo 字段派生
-
三仓联动：每个需求在三个仓里使用完全相同的分支名feature/{devops-name}/{tapd-id}，这是跨仓协同的基础约束
-
五阶段 + 四门禁：初始化 → 需求定义⭐ → 设计⭐ → 开发⭐⭐ → 交付
-
全部可版本化：规范是文件、知识是文件、需求状态也是文件，任何改动都可 diff 可审计 可 rollback
5.3 四个差异化亮点
接下来四节分别展开：
-
亮点一：五阶段 + 四门禁 —— 流程与质量的”骨架”
-
亮点二：三层知识体系 + 三仓联动 —— 单仓多服务下的上下文治理
-
亮点三：Skill Agent Command 三件套 —— 能力原子化与意图委派
-
亮点四：Self-Refinement —— 让 AI 从错误中沉淀经验
06
五阶段 + 四门禁 —— 让错误死在最便宜的地方
传统 SDLC 的大阶段，在 AI 协作语境里往往被随意跳过 —— 比如”需求一句话、设计嘴上说、AI 直接上代码”。代价是等到 MR 阶段才发现需求理解错了、接口契约和下游不兼容、数据迁移没想过回滚。
Harness Engineering 把主流程收敛成五阶段 + 四道强制门禁：
┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ 阶段 1 │ │ 阶段 2 ⭐ │ │ 阶段 3 ⭐ │
│ 初始化 │───▶│ 需求定义 │───▶│ 设计 │
│ │ │ │ │ │
│ 目录骨架 │ │ 撰写 → 评审⭐│ │ 预研 │
│ │ │ │ │ 设计 │
│ │ │ │ │ 评审+追溯⭐ │
└──────────┘ └──────────────┘ └──────────────┘
│
┌──────────────────────────────────────┘
▼
┌─────────────────────────────────┐ ┌─────────────┐
│ 阶段 4 ⭐⭐ │ │ 阶段 5 │
│ 开发 │───▶│ 交付 │──▶ Done
│ │ │ │
│ 4.1 任务拆分 │ │ 测试验收 │
│ 4.2 Dev 进入门禁 ⭐ │ │ 收尾 │
│ 4.3 服务仓库检查 ⭐ │ │ │
│ 4.4 编码循环 │ │ │
│ 选择→上下文→编码→审查→提交 │ │ │
└─────────────────────────────────┘ └─────────────┘
⭐ = 强制门禁（共 4 个，不可跳过）核心理念：错误越早被拦住，代价越低。
┌───────────────────────────────────────────────────────────┐
│ 错误代价递增曲线 │
│ │
│ 代价 ╱ │
│ ▲ ╱ │
│ │ ╱ │
│ │ ⭐ 需求门禁（2.2） ⭐ 服务门禁 │ │
│ │ │ （4.3） │ │
│ │ │ ⭐ 设计门禁 │ │ │
│ │ │ （3.3） ⭐ Dev │ │ │
│ │ │ │ 门禁（4.2） │ │
│ │ │ │ │ │ ▼ │
│ │ ▼ ▼ ▼ ▼ 代码/IDL 已写 │
│ │ 数据迁移已做 │
│ │ ◎ 改几行 ◎ 改设计 ◎ 改任务 ◎ 重切分支 │
│ │ 文档 文档 拆分 改环境 │
│ │ │
│ └─────────────────────────────────────────────────▶阶段 │
│ 阶段 2 阶段 3 阶段 4.1 阶段 4.3 阶段 4.4 │
│ │
│ ⭐ 正是设在"代价最低的拐点上" │
└───────────────────────────────────────────────────────────┘6.1 门禁总览（单一真相源）
| 门禁 | 位置 | 阻塞条件 |
|---|---|---|
| 需求评审门禁 | 阶段 2.2 | 需求文档不合格 / 评审未通过 |
| 设计门禁 | 阶段 3.3 | 设计评审未通过 / 追溯链不达标 |
| Dev 进入门禁 | 阶段 4.2 | tasks/features.json缺失或不合法 |
| 服务仓库检查门禁 | 阶段 4.3 | 三仓分支不一致 / 服务仓库未就位 |
门禁口径收拢在 context/harness-framework/main-process-numbering.md 这一份文档 —— 这是整条流程语义的唯一真相源。AGENTS.md、每一个 Skill、每一个 Command 都围绕它保持一致。这个”真相源”的意义在于：一次更新，全仓生效，避免规范口径散落多处并逐渐漂移。
6.2 为什么门禁要”尽量少、尽量靠前”
门禁是摩擦。加多了，研发绕开；加少了，错误漏出去。我们的平衡点是：
-
需求评审门禁（2.2）—— 拦住”需求没理解对”
-
设计门禁（3.3）—— 拦住”方案漏了关键约束 / 没追溯到需求”
-
Dev 门禁（4.2）—— 拦住”feature 拆分不合规，开发起点不对”
-
服务仓库检查（4.3）—— 拦住”三仓分支漂移 / IDL 契约仓未就位”
这 4 个点，分别对应”意图、方案、任务、环境”四个最容易出大错、改动代价又最低的节点。一旦过了 4.4 编码循环再回退，代价就从”改几行文档”升到”回滚代码 + 回滚 IDL + 回滚数据迁移”。
6.3 门禁是”机读”的，不是”口头的”
每个门禁都有对应的 Agent / Skill 和 markdown 检查规范，例如：
-
requirement-quality-reviewer Agent（需求评审门禁）
-
detail-design-quality-reviewer Agent（设计门禁）
-
traceability-gate-checker Skill（追溯链校验）
-
managing-requirement-lifecycle/gates/service-repo-check.md（服务仓库检查门禁）
门禁结论需要写入文件，并采用固定格式，确保可读、可审计。这条规范避免了”AI 口头说通过，但没有任何可追溯记录”的情况。
07
三层知识体系 + 三仓联动 —— 单仓多服务下的上下文治理
7.1 三层知识架构
| 层级 | 位置 | 范围 | 典型内容 |
|---|---|---|---|
| 团队级 | context/team/ | 所有项目必须遵循 | Git 规范、错误码空间、日志规范 |
| 框架工程级 | context/harness-framework/ | 所有需求研发必须遵循 | 五阶段流程、门禁规则、文档模板 |
| 服务级 | context/project/{project-name}/{module-name}/{service-name}/ | 特定服务 | 架构图、API、运维手册、踩坑经验 |
三层知识的可视化：
┌──────────────────────┐
│ 团队级 (最稳定) │
│ context/team/ │
│ ├─ Git 规范 │
│ ├─ 错误码空间 │
│ └─ 日志规范 │
└──────────┬───────────┘
│ 被所有项目继承
▼
┌────────────────────────────┐
│ 框架工程级 (中频更新) │
│ context/harness-framework/│
│ ├─ 五阶段流程 │
│ ├─ 门禁规则 │
│ ├─ 文档模板 │
│ └─ 上下文收集规范 │
└────────────┬───────────────┘
│ 被所有需求研发继承
▼
┌───────────────────────────────┐
│ 服务级 (高频演进、量最大) │
│ context/project/ │
│ └─ music_commercial_go_proj/│
│ ├─ vip/ │
│ │ ├─ INDEX.md │
│ │ ├─ architecture.md │
│ │ ├─ sop/ │
│ │ └─ experience/ │
│ ├─ assetcard/ │
│ └─ campaign/ │
└───────────────────────────────┘
AI 按"团队 → 项目 → 模块 → 服务"逐层缩小范围，O(1) 命中每一层都有 INDEX.md 作为入口，检索成本 O(1)。AI 不需要遍历整个仓库，只需要按 团队 → 项目 → 模块 → 服务 的路径逐层缩小范围。这是”渐进式披露”的物理实现。
7.2 .service-matrix/dependencies.yaml —— 单一真相源
workspace: ".."
business_repo: "music_commercial_go_proj"
idl_repo: "qqmusicjce"
default_team: "music-commercial"
teams:
music-commercial:
business_repo: "music_commercial_go_proj"
idl_repo: "qqmusicjce"
modules:
vip:
team: music-commercial
name: 会员核心域
services:
vipapi:
module: vip
repo_path: "{business-repo}/vipapi"
idl_required: true
assetcardmallcgi:
module: assetcard
repo_path: "{business-repo}/assetcard/mall/assetcardmallcgi"特点：
路径从不硬编码：用 {business-repo} / {idl-repo} 占位符，跨机器、跨账号无缝迁移
多团队共用同一 Harness 仓：teams: 块让不同业务团队有各自的业务仓 + IDL 仓
Active Team 三级解析：$HARNESS_TEAM > .harness/local.yaml > default_team，既支持会话级临时切换也支持仓库级默认
校验脚本：scripts/validate-service-matrix.js 会在每次 CI 跑过，保证占位符能正确解析、没有幽灵依赖
目前仓内实际管理 57 个服务，路径深度分布非常真实：
服务路径深度分布（57 个服务）
1 级 ┃████████████████████████ 21 (vipapi、VipSale …)
2 级 ┃██████████████████████████████████████ 32 (assetcard/mall/*、supplier/*)
3 级 ┃████ 4 (musicvip/viptab/*)
└─────────────────────────────────────────── 服务数
超过一半的服务含"子域"层 → 框架不能对深度作过强假设
解决方案：一切走 repo_path 真相源，由它自身决定深度整个框架没有对路径深度做出过强假设，一切走 repo_path 真相源 —— 这是在真实业务拓扑里被反复打磨出来的设计。
7.3 三仓联动：同一条 TAPD 单的三个分支
这是 Harness Engineering 很有特色的一个工程实践：每个需求，在三个仓里用完全相同的分支名。
┌──────────────────────────┐
│ 一条 TAPD 单 T12345 │
└─────────────┬────────────┘
│
┌──────────────────────┼──────────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌────────────────┐ ┌───────────────┐
│ Harness 仓 │ │ 业务代码仓 │ │ IDL 契约仓 │
│ (脑) │ │ (手脚) │ │ (神经) │
│ │ │ │ │ │
│ feature/Base/ │ │ feature/Base/ │ │ feature/Base/ │
│ T12345 ✓ │ │ T12345 ✓ │ │ T12345 ✓ │
│ │ │ │ │ (仅当涉及 │
│ 需求文档/ │ │ 代码/测试 │ │ IDL 变更) │
│ 设计/门禁/ │ │ │ │ │
│ 知识/状态 │ │ │ │ .jce 契约 │
└───────┬───────┘ └────────┬───────┘ └───────┬───────┘
│ │ │
└──────────────────────┼──────────────────────┘
│
┌─────────────▼────────────┐
│ 阶段 4.3 门禁强制校验 │
│ 三仓分支名必须完全一致 │
│ 任何漂移 → 阻塞进入 4.4 │
└──────────────────────────┘为什么这么做：
-
一条 TAPD 单 ID → 三仓分支名一对一，追溯链整洁
-
阶段 4.3 服务仓库检查门禁会自动校验三仓分支一致性，不一致直接阻塞
-
CR 时可以快速对齐三个仓的改动
-
回滚时三个仓同步处理，避免出现”代码回了、IDL 没回”的不一致状态
这条基础约束，是所有跨仓协调的锚点。
7.4 占位符词典（唯一真相源）
全仓只允许使用下列占位符：
| 占位符 | 语义 | 举例 |
|---|---|---|
{business-repo} | 业务代码仓根的磁盘路径（绝对） | /data/workspace/music_commercial_go_proj |
{business-repo-name} | 业务代码仓根的目录名 | music_commercial_go_proj |
{idl-repo}/ {idl-repo-name} | IDL 契约仓 | 对称 |
{project-name} | 逻辑项目名，用于知识库 / 需求目录归属 | music_commercial_go_proj |
{requirement-id} | 需求 ID | minimal-requirement-practice |
{module-name}/ {service-name} | 业务模块 / 服务 | vip/ vipapi |
写路径 vs 写归属两个语境绝不混用。这种”纪律性的枯燥”，换来的是一份可扫描、可 sed、可自动生成的结构化规范。
08
Skill Agent Command 三件套
8.1 三种能力原子的分工
| 类型 | 定位 | 数量 | 调用方式 |
|---|---|---|---|
| Skill | 可复用的工作流 规范 最佳实践 | 34 | 主对话按需 load，或被 Agent 调用 |
| Agent | 自主子任务执行者（可调工具、可调 Skill） | 24 | 主对话 Task 委派，或命令触发 |
| Slash Command | 固定入口 + 标准化参数 | 35 | 用户输入 /xxx:yyy |
这三类能力都是版本化 markdown 文件（.codebuddy/skills/*/SKILL.md、.codebuddy/agents/*/*.md、.codebuddy/commands/*/*.md），任何一次修改都能 code review、都能 diff、都能 rollback —— 这就是 Knowledge as Code 的物理实现。
8.2 按阶段组织的 Agent 体系
.codebuddy/agents/
├── Init/ 项目初始化
│ ├── project-bootstrapper
│ └── repo-ops-runner
├── RequirementManagement/ 需求管理
│ └── universal-context-collector
├── Startup/ 阶段 1
│ └── requirement-bootstrapper
├── Definition/ 阶段 2
│ ├── requirement-input-normalizer
│ └── requirement-quality-reviewer
├── TechResearch/ 阶段 3.1
│ └── tech-feasibility-assessor
├── OutlineDesign/ 阶段 3.2
│ └── outline-design-quality-reviewer
├── DetailDesign/ 阶段 3.2
│ └── detail-design-quality-reviewer
├── Implementation/ 阶段 4.4
│ ├── auxiliary-checker
│ ├── code-review-preparer
│ ├── complexity-checker
│ ├── concurrency-checker
│ ├── design-checker
│ ├── error-checker
│ ├── security-checker
│ └── traceability-consistency-checker
├── Acceptance/ 阶段 5
│ └── test-runner
└── KnowledgeMaintenance/ 知识沉淀亮点：阶段 4.4 的代码审查被拆成 8 个维度的独立 Agent 并行执行：
┌─────────────────────────────┐
│ code-review-preparer Agent │
│ （收集 diff + 上下文） │
└──────────────┬──────────────┘
│ 分发
┌───────┬───────┬──────┼──────┬───────┬────────┬────────┐
▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼
┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│设计 │ │复杂 │ │并发 │ │ 错误 │ │安全 │ │ 契约 │ │追溯 │ │辅助 │
│一致 │ │度 │ │安全 │ │ 处理 │ │漏洞 │ │ 一致 │ │性 │ │检查 │
└──┬──┘ └──┬──┘ └──┬──┘ └──┬──┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘
│ │ │ │ │ │ │ │
└───────┴───────┴───────┼──────┴────────┴────────┴────────┘
│ 聚合
▼
┌─────────────────────────────┐
│ code-review-report Skill │
│ （结论写入 reviews/*.md） │
└─────────────────────────────┘这是典型的多视角审查，效果远好于单次”AI 通读 + 写意见”。
8.3 Skill 全景
34 个 Skill，按功能归类：
| 类别 | 代表 Skill |
|---|---|
| 需求生命周期 | managing-requirement-lifecycle、feature-lifecycle-manager、requirement-session-restorer |
| 文档撰写 | requirement-doc-writer、outline-design-doc-writer、detail-design-doc-writer |
| 代码审查 | code-review-report、traceability-gate-checker、api-contract-consistency-validator |
| 服务治理 | service-dependency-analyzer、load-domain、load-service |
| 知识沉淀 | managing-knowledge、self-refinement |
| 工程工具 | dev-ocs、git-commit-message-generator、devops-cli、gongfeng |
| 规范查询 | engineering-spec-query、docs-index-updater、context-index-updater |
managing-requirement-lifecycle 是整个框架的”中央调度”。需求工作通过它推进，以保证阶段、门禁和上下文口径一致。它负责：意图识别、阶段检查、门禁验证、债务检查和计划更新。
8.4 Slash Command：标准化入口
/requirement:new # 新建需求
/requirement:continue # 恢复上下文
/requirement:next # 进入下一阶段
/requirement:gate-check # 门禁自检
/req-task:list / start / context / done # 功能点级别的任务流转
/agentic:code-review # 多维度代码审查
/agentic:load-service # 加载服务并生成技术总结
/agentic:note # 记录需求过程信息
/service:deps # 查看依赖
/service:onboard # 零配置接入外部服务
/service:load-domain # 域级跨服务沉淀
/knowledge:extract-experience # 提取经验
/knowledge:generate-sop # 生成 SOP35 个 Command 构成口径统一的交互表面：同一个命令，对应同一套流程，无论用 Claude Code Gemini CLI Codex CLI / Continue，体验都一致。
09
Self-Refinement —— 让 AI 从错误中沉淀经验
LLM 没有跨会话记忆。但团队的每一个”纠正”，都是一次宝贵的信号。
Harness Engineering 里有一个专门的 Skill 叫 self-refinement，外加 AGENTS.md 的认知模式第 5 条：
当遇到新模式或教训时：主动提议更新到
context/（Self-Refinement）
9.1 闭环怎么跑
┌──────────────────────────────┐
│ ① 用户纠正 AI 某个错误 │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ ② AI 识别：这是"模式性教训" │
│ 还是"一次性 diff"？ │
└──────────────┬───────────────┘
│ 模式性
▼
┌──────────────────────────────────┐
│ ③ AI 主动提议沉淀层级 │
│ ┌──────────────────────────┐ │
│ │ 团队级 → context/team/ │ │
│ │ 框架工程级 → harness- │ │
│ │ framework/ │ │
│ │ 服务级 → context/ │ │
│ │ project/{...} │ │
│ └──────────────────────────┘ │
└──────────────┬───────────────────┘
│ 用户确认
▼
┌──────────────────────────────┐
│ ④ 生成 experience 文档 / │
│ 更新 Skill / 修订规范 │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ ⑤ 下次同类场景，AI 主动引用 │
│ ↓ │
│ 新会话 / 新模型 / 新人也受益 │
└──────────────────────────────┘
📌 错误不再"走一次算一次"，而是成为团队资产9.2 具体产物示例
-
context/project/music_commercial_go_proj/campaign/DEPENDENCY_ANALYSIS.md —— 子域依赖影响分析的真实记录
-
context/project/music_commercial_go_proj/{module}/experience/*.md —— 踩坑经验（分页必须有上限、goroutine 泄漏、🔒字段约束 …）
-
context/project/{project}/sop/*.md —— 从经验提炼出的标准操作规程
这种”知识驻留在仓库里”的设计，让新人 新模型 新会话都能复用团队的集体经验，而不是从零开始理解业务约束。
9.3 一个微型 meta 案例
写这篇文章的过程本身就是一次 Self-Refinement：
-
最早的文档里 {project-root}{business-repo}{project-name} 三个占位符分工模糊
-
有人在 IDE 里选中一行问”这个定义清楚吗？”
-
于是发起了 MR !49：把占位符词典写进 AGENTS.md 作为唯一真相源，废弃 {project-root} 别名
-
再后续的 MR（→ 51）修正了 rollback 文档里的路径错误（项目名套两遍、没覆盖子域层）
-
这些修正本身都是 Self-Refinement 的直接产物
框架自身的演进，就是 Self-Refinement 的活样本。
10
与 Claude Code Cursor Cline 的关系
简答：Harness Engineering 不是这类工具的替代品，而是它们上层的治理层协议。
我们把 AI 编程工具分成两类能力来看：
| 类型 | 代表 | 角色 |
|---|---|---|
| Claude Code Cursor Cline Gemini CLI Codex CLI / Continue | 执行层 | 提供 AI 能力、代码理解、文件编辑、命令执行、测试修复 |
| Harness Engineering | 治理层 | 定义流程、门禁、知识体系、服务矩阵、三仓联动和经验沉淀 |
执行层工具越强，越需要治理层把它们接入正确轨道。否则 AI 生成速度越快，错误扩散也越快；工具自主性越强，越需要明确它可以做什么、什么时候做、做到什么程度算通过。
Harness 仓的 .codebuddy/skills/agents/commands/ 是真相源；scripts/install.sh 会把它们渲染到各 CLI 的本地目录：
.claude/ ← Claude Code 读这个
.gemini/ ← Gemini CLI 读这个
.codex/ ← Codex CLI 读这个
.continue/ ← Continue 读这个这些是 gitignored 的镜像目录。修改规范时只改 .codebuddy/，不同 CLI 自动受益。
因此，Harness Engineering 和 Superpower 类工具的关系可以概括为三句话：
-
执行交给工具：读代码、改代码、跑测试、修复报错，交给更强的 AI IDE / CLI。
-
规则留在仓库：流程、门禁、服务拓扑、团队知识和经验沉淀，保留为可 review 的工程资产。
-
协议连接两者：Skill Agent Command 把团队规范翻译成执行层工具可消费的上下文。
一句话：工程规范与 AI 工具解耦。今天用 Claude Code，明天换 Superpower 类新工具，流程和知识都不丢。
11
结语：工程化不是慢，是稳
回到导语那句话：AI 让写代码变快了，但快不等于对。
Harness Engineering 把 AI 协作从”聊天式”改成”工程化”的方式，不是给研发加负担，而是让 AI 每一次发力都落在正确的位置上：
-
在最便宜的地方拦住错误 —— 需求和设计门禁
-
在最重要的地方注入上下文 —— 三层知识体系 + 服务矩阵
-
在最可复用的地方沉淀经验 —— Knowledge as Code + Self-Refinement
-
在最容易漂移的地方收敛口径 —— 单一真相源 + 占位符词典
最后一句话
Context Engineering + Spec-First + Knowledge as Code，构成了可验证、可演进的 AI 协作工程基线。
如果你的团队正卡在”AI 写得快但对不对”的纠结里，不妨把 Harness Engineering 当作一面工程镜子 —— 对照看看流程是否完整、门禁是否可机读、知识是否已沉淀、跨服务协调是否已显式化。
-End-
原创作者｜黄欣欣
感谢你读到这里，不如关注一下？👇
📢📢来抢开发者限席名额！点击下方图片直达👇
你对本文内容有哪些看法？同意、反对、困惑的地方是？欢迎留言，我们将邀请作者针对性回复你的评论，欢迎评论留言补充。我们将选取1则优质的评论，送出腾讯云定制文件袋套装1个（见下图）。5月28日中午12点开奖。
扫码领取腾讯云开发者专属服务器代金券！
Original 黄欣欣 腾讯云开发者
内容效果不满意？点此反馈