Add Zhihu note: QQ音乐Harness Engineering实践
This commit is contained in:
Zane
785
InBox/zhihu_QQ音乐HarnessEngineering实践.md
Normal file
785
InBox/zhihu_QQ音乐HarnessEngineering实践.md
Normal file
@@ -0,0 +1,785 @@
|
|||||||
|
---
|
||||||
|
title: "QQ音乐Harness Engineering实践"
|
||||||
|
source: "知乎 - 鹅厂架构师"
|
||||||
|
url: "https://zhuanlan.zhihu.com/p/2041178181210748380"
|
||||||
|
date: 2026-06-09
|
||||||
|
tags: [zhihu, harness-engineering, ai-coding, vibe-coding, qq-music]
|
||||||
|
type: article
|
||||||
|
---
|
||||||
|
|
||||||
|
# QQ音乐Harness Engineering实践
|
||||||
|
|
||||||
|
> 作者：腾讯工程师 koka
|
||||||
|
|
||||||
|
导语当 AI 开始快速生成大量代码，真正的瓶颈就不再是"写不出来"，而是"看不完、想不清、管不住"。 本文基于一个落地在大仓多服务（Monorepo Microservices）场景中的开源工程框架，回答一个核心问题：如何把 AI 协作从对话式编码，升级为可控、可审计、可复用的工程过程？
|
||||||
|
作者：腾讯工程师 koka
|
||||||
|
1. 从 "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 在正确的轨道上尽量高效地生成"。自由和高效并不矛盾 —— 真正的高效，恰恰来自正确的约束。
|
||||||
|
|
||||||
|
2. 核心公式：代码产出 = 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 闭环，让每次纠错都沉淀为团队资产
|
||||||
|
|
||||||
|
这就是为什么核心公式的乘号如此重要 —— 提升上下文质量，是比提升模型能力更高效的杠杆。因为模型能力的提升依赖外部厂商，而上下文质量的提升，完全掌握在团队自己手中。
|
||||||
|
|
||||||
|
3. 什么是 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
|
||||||
|
3.3 QQ音乐 Harness Engineering
|
||||||
|
|
||||||
|
但真实的企业级研发场景里，一个需求从开始到上线要经历多个 Agent、多个工具、多个服务、多个仓库的协同。这一层业界留白了：
|
||||||
|
|
||||||
|
┌───────────────────────────────────┐
|
||||||
|
│ │
|
||||||
|
│ ▼ │
|
||||||
|
│ Harness Engineering 接管的范围 │
|
||||||
|
│ ┌───────────────────────────┐ │
|
||||||
|
│ │ Team Agent Governance │ │
|
||||||
|
│ │ = Multi-Agent × Multi-Service × Multi-Lifecycle │ │
|
||||||
|
│ │ （让团队的 AI 协作跨会话、跨工具、跨服务可治理） │ │
|
||||||
|
│ └───────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
└───────────────────────────────────┘
|
||||||
|
4. 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框架。
|
||||||
|
|
||||||
|
通用产品很难替我们定义下面这些内容：
|
||||||
|
|
||||||
|
服务矩阵语义
|
||||||
|
|
||||||
|
哪些服务属于同一业务域，哪个服务依赖哪个服务，哪个模块需要 IDL，仓库路径如何解析，是否存在多级 repo_path，这些都是业务团队自己的拓扑知识。它们必须由团队维护在 .service-matrix/dependencies.yaml 中，而不能依赖模型临场搜索。
|
||||||
|
|
||||||
|
需求生命周期语义
|
||||||
|
|
||||||
|
我们的需求不是“一句话任务”，而是有阶段、有门禁、有产物、有追溯关系的生命周期对象。什么时候算完成需求定义？什么时候可以进入开发？设计评审不过能不能继续写代码？这些规则必须写进 context/harness-framework/main-process-numbering.md，并被 Agent Skill Command 共同遵循。
|
||||||
|
|
||||||
|
IDL 契约语义
|
||||||
|
|
||||||
|
对业务系统来说，IDL 不是普通文本。它代表服务边界、兼容性和上下游契约。通用 AI 工具可以修改 IDL 文件，却不知道哪些字段冻结、哪些变更需要同步业务仓、哪些场景必须先建三仓同名分支。因此我们把 IDL 契约纳入三仓联动和阶段门禁。
|
||||||
|
|
||||||
|
团队经验语义
|
||||||
|
|
||||||
|
模型知道通用 Go 最佳实践，但不知道某个服务过去因为分页无上限打爆过下游，也不知道某个 goroutine 泄漏问题在本模块出现过两次。团队经验必须写成 AI 可消费的知识文件，进入 context/project/{project}/{module}/experience/。
|
||||||
|
|
||||||
|
工具解耦语义
|
||||||
|
|
||||||
|
今天团队可能用 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 建设团队作战体系。
|
||||||
|
|
||||||
|
5. 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 从错误中沉淀经验
|
||||||
|
6. 五阶段 + 四门禁 —— 让错误死在最便宜的地方
|
||||||
|
|
||||||
|
传统 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 口头说通过，但没有任何可追溯记录"的情况。
|
||||||
|
|
||||||
|
7. 三层知识体系 + 三仓联动 —— 单仓多服务下的上下文治理
|
||||||
|
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 个服务，路径深度分布非常真实：
|
||||||
|
|
||||||
|
整个框架没有对路径深度做出过强假设，一切走 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、可自动生成的结构化规范。
|
||||||
|
|
||||||
|
8. 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 # 生成 SOP
|
||||||
|
|
||||||
|
35 个 Command 构成口径统一的交互表面：同一个命令，对应同一套流程，无论用 Claude Code Gemini CLI Codex CLI / Continue，体验都一致。
|
||||||
|
|
||||||
|
9. Self-Refinement —— 让 AI 从错误中沉淀经验
|
||||||
|
|
||||||
|
LLM 没有跨会话记忆。但团队的每一个"纠正"，都是一次宝贵的信号。
|
||||||
|
|
||||||
|
Harness Engineering 里有一个专门的 Skill 叫 self-refinement，外加 AGENTS.md 的认知模式第 5 条：
|
||||||
|
|
||||||
|
当遇到新模式或教训时：主动提议更新到 context/（Self-Refinement）
|
||||||
|
┌──────────────────────────────┐
|
||||||
|
│ ① 用户纠正 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 类新工具，流程和知识都不丢。
|
||||||
|
|
||||||
|
结语：工程化不是慢，是稳
|
||||||
|
|
||||||
|
回到导语那句话：AI 让写代码变快了，但快不等于对。
|
||||||
|
|
||||||
|
Harness Engineering 把 AI 协作从"聊天式"改成"工程化"的方式，不是给研发加负担，而是让 AI 每一次发力都落在正确的位置上：
|
||||||
|
|
||||||
|
在最便宜的地方拦住错误 —— 需求和设计门禁
|
||||||
|
在最重要的地方注入上下文 —— 三层知识体系 + 服务矩阵
|
||||||
|
在最可复用的地方沉淀经验 —— Knowledge as Code + Self-Refinement
|
||||||
|
在最容易漂移的地方收敛口径 —— 单一真相源 + 占位符词典
|
||||||
|
最后一句话
|
||||||
|
|
||||||
|
Context Engineering + Spec-First + Knowledge as Code，构成了可验证、可演进的 AI 协作工程基线。
|
||||||
|
|
||||||
|
如果你的团队正卡在"AI 写得快但对不对"的纠结里，不妨把 Harness Engineering 当作一面工程镜子 —— 对照看看流程是否完整、门禁是否可机读、知识是否已沉淀、跨服务协调是否已显式化。
|
||||||
Reference in New Issue
Block a user