Harness 概念架构与 Coding 工程实践

方向定位：把 Harness 的「概念定义—架构分层—Coding 落地杠杆—Meta 抽象」打通成一条贯穿线。第一章解答「Harness 是什么、由哪些层/原语构成」；第二章解答「在 Coding Agent 上具体做什么、按什么顺序、用什么杠杆、怎么扩展到组织」；第三章解答「在框架之上还有什么稳定抽象，AgentOS 是什么」。不涵盖：Anti-pattern 与反馈机制细节（→ Harness 失效模式与反馈机制）；未来形态预测与减重趋势（→ Harness 演化与未来形态）；通用 Agent 工程化（→ Agent工程实践与工具生态）。当前版本：v1.0（合并版）合并日期：2026-05-20 来源数：12 篇

第一章 Harness 概念体系

1.1 公式：Agent = Model + Harness

定义：Agent 由两部分组成——Model 提供原始智力（"文本进文本出"的概率函数），Harness 提供把这种智力变成可稳定交付的整套外部基础设施。

等价表述：

"如果你不是模型，你就是框架/Harness。"（Vtrivedy10）
"模型是 CPU，Harness 是操作系统。CPU 再强，OS 拉胯也白搭。"
"大模型是发动机，Harness 是线束，使用者是驾驶员。"（汤道生）

关键含义：

评估一个 Agent 效果，真正评估的是 model + harness 的组合，不能孤立看模型分数
Harness 是团队/产品的战略级资产，不是一段 prompt
"你做的事情永远不是在给系统编码，你是在设计并控制这个系统。"

Harness 的精确定义：让模型能够作为 Agent 行动起来的外循环系统——决定何时启动模型推理、给它什么上下文、如何验证输出、何时回退、何时停止。

Harness 不是什么（三个常见误区）：

Harness ≠ Prompt：Prompt 是点菜，Harness 是后厨整个运营体系
Harness ≠ 某个工具：接一个搜索工具只是工具层的一部分
Harness ≠ Framework：LangChain 是框架，Harness 是工程实践（类似 DevOps 不是工具是文化）

本文讨论的 agent harness（运行时外循环），与机器学习社区的 evaluation harness（评测流水线） 是两个不同概念。

1.2 三层工程演进（Prompt → Context → Harness）

AI 工程方法论经历了三次范式跃迁，三层之间不是替代关系，而是嵌套包含——后一层把前一层装进自己内部。

工程层	时间	核心问题	工作对象	隐喻（汤道生）
Prompt Engineering	2022.11-2024	怎么和模型说？	单次对话的输出质量	给驾驶员一张地图
Context Engineering	2024-2025	给模型看什么？	上下文窗口的内容编排	给驾驶员一套导航系统
Harness Engineering	2026-	给 Agent 造一个什么世界？	长任务/复杂场景的稳定自主运行	给驾驶员造一辆完整的车

嵌套关系：

Prompt Engineering  ⊂  Context Engineering  ⊂  Harness Engineering
单次调用如何问           每一步喂什么信息           整条流水线怎么运转

与五幕演化的关系：从 ChatGPT 到 2026，AI 工程经历五幕：生成 → 连接 → 推理 → 行动 → 治理。Harness Engineering 是"治理时代"的工程产物——前四幕的每一条教训都是下一幕的前提。

术语进入主流的时间线：

2026.02.05 Mitchell Hashimoto《My AI Adoption Journey》写下 "Engineer the Harness"——术语进入主流的起点。其实践要点：每当 Agent 犯错，就工程化一个解决方案，让它永远不再犯同样的错误
2026.02.11 OpenAI《Harness Engineering: Leveraging Codex in an Agent-First World》
2026.03 Anthropic《Harness Design for Long-Running Application Development》——把二角色升级为 Planner/Generator/Evaluator 三角色
2026.04 Thoughtworks / Martin Fowler 抽象出 2×2 控制矩阵（Guides × Sensors × Computational × Inferential）

1.3 发动机—线束—驾驶员三角

汤道生用机械工程的隐喻把 Agent 系统的三个角色解耦：

角色	在 Agent 系统中对应	价值定位
发动机	大模型	原始动力来源，能力天花板
线束（Harness）	模型之外的一切基础设施	把动力转化为可控可用
驾驶员	使用者（人）	决定方向、判断质量、定义"完成"

为什么是三角不是二元：模型越强，对驾驶员的能力要求不是降低而是提高——自动驾驶悖论：监督自动驾驶比自己开车要求更高。驾驶员的稀缺能力是"品味"——判断什么是好的、什么是对的、什么是值得做的。

隐喻演进暗示 Harness 地位提升：

第一代（马具、缰绳）—— Harness 是约束物
第二代（线束、电缆）—— Harness 是连接物
第三代（操作系统、AgentOS 用户态）—— Harness 是基础设施
第四代（大脑—手）—— Harness 是身体本身

1.4 七大技术原语（按依赖关系自底向上）

把"业务层级"换成"实现原语"，回答**"具体要做哪些东西"**：

原语	解决的问题	核心机制
文件系统	持久存储、信息卸载、跨会话状态	文件读写 + Git 版本控制
Bash + 代码执行	避免工具集上限卡死能力	让模型自己写代码解决问题
沙箱	安全执行 + 横向扩展	隔离环境，按需创建/销毁
记忆与搜索	跨会话知识 + 训练截止后信息	AGENTS.md 记忆文件 + Web 搜索 + MCP
上下文管理	对抗上下文衰减	压缩机制 + 工具输出卸载 + 技能渐进式披露
长期自主执行	过早停止、跨窗口不一致	Ralph 循环 + 规划文件 + 自我验证
编排逻辑	复杂任务分解与并行	子代理生成、任务交接、模型路由

关键论断："文件系统不只是存储，它实际上是后面所有能力的地基。" 跨会话持久化、多智能体协作、Git 版本控制全部建立在文件系统之上。

1.5 六层架构（Harness 业务分层）

把七大原语按"业务问题分类"组织，得到 Harness 的六层架构：

层级	名称	解决什么问题	关键设计
L1	信息边界层	Agent 该知道/不该知道什么	定义角色与目标，裁剪无关信息，结构化任务状态
L2	工具系统层	Agent 怎么跟外部世界交互	工具选拔、调用时机、结果提炼；少即是多
L3	执行编排层	多步骤任务怎么串起来	Loop（Observe → Decide → Act → Verify → Repeat）
L4	记忆与状态层	长任务中间结果怎么管	独立管理任务状态、中间产物和长期记忆
L5	评估与观测层	Agent 怎么知道自己做对了没有	建立独立于生成过程的验证机制
L6	约束、校验与恢复层	出错了怎么办	预设规则拦截错误，失败时提供重试或回滚

优先级建议：一开始不要搭齐六层。投入产出比最高的是 L1（信息边界）和 L6（约束与恢复）——L1 决定 Agent 知道该干什么，L6 决定搞砸了能不能拉回来。

多版本分层模型对照：业界至少有 5 套主流分层方案（06 六层 / 07 七大原语 / 18 三层 / 22 六大构件 / 26 六大组件 / 30 Meta-Harness 三层），它们使用不同的命名和粒度，但深层都包含「信息边界 + 工具 + 编排 + 状态 + 验证 + 约束」六个面向。差异不在面向是否存在，而在粒度（三层 vs 七层）和主张（哪个面向应该独立成构件）。

选型建议：早期用三层做沟通工具，工程化阶段用六层做架构清单，规模化阶段用六大构件做改进焦点，平台化阶段用 Meta-Harness 做接口设计（→ 1.7、第三章）。

1.6 对话式 → Agentic 的本质拐点

对话式 AI vs Agentic AI 的本质差异不在技术能力，而在「谁做决策」：

阶段	工具代表	交互模式	人的角色
对话式 1.0	ChatGPT	问答 + 复制粘贴	指挥者 + 执行者
对话式 2.0	Cursor	编辑器内交互	指挥者
Agentic	Claude Code	目标描述→自主执行	把关者

转向 Agentic 的三个思维转变（缺一不可）：

从"怎么做"到"要什么"：好的 prompt 不是写得长，是目标写得清楚
学会定义验证标准："优化性能"太模糊，"首屏加载从 3.2s 降到 1.5s"Agent 能自己干
精力放到 Agent 做不好的事上：架构决策、产品判断、用户洞察

Agent 能力边界：擅长有客观对错标准的任务（测试通过/不通过）；不擅长无客观标准、需要人类判断的决策。

与 Harness 的关系：Agentic 模式可行的前提是 Harness 提供了 Verification 层（L5）——客观标准是 Agent 自主迭代的承重墙。真正切换到 Agentic 模式的开发者可能不到 10%——技术早就到位，差距在"人还没学会怎么用它"。

1.7 标志性案例（同模型 ×10 差距）

案例	变量	结果	启发
Can.ac 编辑接口实验	固定模型，只改文件编辑接口	编码基准 6.7% → 68.3%（约 10x）	瓶颈是基础设施而非模型智能
LangChain Terminal Bench 2.0	只优化运行环境	52.8% → 66.5%，排名 30 外 → Top 5	模型趋同时，决定成败的是 Harness 质量
Nate B Jones 实验	同模型只换 Harness	编程成功率 42% → 78%	模型能力天花板在模型外面
Anthropic 游戏开发	同 prompt 不同壳	简单方式 9 美元无效 vs 完整 Harness 200 美元可用	成本 22 倍换"完全无效→真正可用"
Claude Code vs Claude Web	同模型不同壳	Web 一问一答反复报错 vs Code 一次闭环	用户体验到的"AI 强不强"是 Harness 质量
某顶级工业级 Agent 源码	1,900 文件 / 512K 行 TS	模型调用代码 < 5%，其余 95% 是 Harness	`query()` 主循环 16 步只有 1 步调 API

核心判断：在模型边际放缓的窗口期，Harness 的工程努力比等下一代模型的回报率更高；但模型一旦跨过新的能力阈值，会把今天的 Harness 复杂度部分"吸收"掉。

第二章 Coding Agent 工程实践

2.1 Coding Agent 的统一循环与 Context 稀缺性

统一循环：当前主流 coding agents（Claude Code、Cursor、Codex）虽然产品形态不同，内部都共享同一个循环：

Read → Plan → Code → Validate → Iterate

循环的每一步都消耗同一份有限资源：context window。上下文利用率达到约 60% 之后，继续塞信息反而让 agent 表现变差。

Context window 的六类消耗项：

消耗项	典型膨胀点
System prompt / custom rules	每轮都注入，若不相关就是长期浪费
Tool definitions	每接一个 MCP server 增加 schema 占用
Conversation history	线性累积
Tool results	文件内容、终端输出、API 返回可能非常长
Agent output	模型自己写的代码与解释
长链迭代堆积	每多一次循环窗口进一步膨胀

关键转向：很多团队以为自己在优化 prompt，实际上更该优化的是"哪些信息不该一直存在上下文里"。

"第一天入职的天才新人"：AI Agent 是入职第一天的天才新人——能力强、反应快，对代码库、规范、架构几乎一无所知。Context engineering 不是"优化 prompt"，而是像组织 onboarding 一样系统性提供环境、规则、流程、工具和监督。

2.2 四大工程杠杆（功能分工）

四大杠杆解决完全不同的问题，不是同一类东西。混淆它们的边界会导致选型错位。

杠杆	解决的问题	注入时机	ROI
Custom Rules	规则约束（怎么写、怎么命名）	每轮自动注入	最低门槛、最高 ROI
MCP	外部能力接入（查库、调 API、读 Figma）	工具调用时	让 agent 从"只懂仓库"升级到"懂组织"
Skills	按需加载的知识 + 可执行脚本 + 可组合行为	简短描述常驻，完整内容按需注入	最强单元（兼具知识与可执行性）
SDD	任务输入质量（功能、边界、验收、测试计划）	写代码前	最彻底，但流程改变最难

前后端协同结构：

前端（校准方向）                    后端（收紧结果）
Custom Rules ─┐                 ┌─ Tests
MCP ──────────┼─ Agent 工作 ──┼─ Lint / Type check
Skills ───────┤                 ├─ Build scripts
SDD ──────────┘                 ├─ Review Agent
                                  └─ Hooks

只有两端同时存在，agent 才能从 demo 走向规模化生产。Feedback Loop 比单纯加杠杆更重要——没有 pass/fail 信号，所有杠杆都只是"建议"。

Skills 的特殊地位：

只有简短描述常驻上下文，完整内容按需注入
可封装模板、示例输出、参考文档、执行脚本
可以在独立 subagent 中运行，避免主上下文被重任务污染
真正价值不是"多一份说明书"，而是把高密度上下文从 always-on 区域迁移到 on-demand 区域
产品化范例（OMC）：用户级 ~/.omc/skills/ + 项目级 .omc/skills/ 两层 YAML（含 name/description/trigger/inject_to/content 字段），按触发条件自动注入对应 Agent——把 Skill 从"prompt 模板"升级为"可版本化、可触发、可定向注入"的产品形态

Agent Hooks 把软约束升级为硬约束：把验证逻辑挂到 Stop hook，Agent 完成任务前必须通过这些检查。"建议你去跑一下测试" → "必须先过门槛"。

2.3 P0/P1/P2 行动清单

不要一开始搭齐六层。按 ROI 排序：先做"能立竿见影"的，后做"投入大但收益慢"的。

P0：立即可做，效果最显著

行动	为什么	参考实践
创建 AGENTS.md 并持续维护	Agent 每次启动自动加载，犯错就更新	Hashimoto：每一行对应一个历史失败案例
构建自定义 Linter + 修复指令	错误消息直接告诉 Agent 怎么改	OpenAI：Linter 报错自带修复方法
把团队知识放进仓库	写在 Slack/Wiki 的知识对 Agent 等于不存在	OpenAI：仓库为唯一事实源

P1：P0 完成后考虑

行动	为什么	参考实践
分层管理上下文	渐进式披露，不要一次性塞满	OpenAI AGENTS.md 当目录
建立进度文件和功能列表	JSON 格式追踪功能状态	Anthropic 两阶段 Agent
给 Agent 端到端验证能力	浏览器自动化让 Agent 能像用户一样验证	Anthropic 用 Playwright/Puppeteer MCP
控制上下文利用率	尽量不超过 40-60%，增量执行	Smart/Dumb Zone

P2：有余力再考虑

行动	为什么	参考实践
Agent 专业化分工	每个 Agent 携带更少无关信息	OMC 19 Agent × 5 泳道极端化范例
定期垃圾回收	确保清理速度跟得上生成速度	OpenAI 后台清理 Agent
可观测性集成	把"性能优化"从玄学变成可度量	OpenAI 接入 Chrome DevTools

2.4 AGENTS.md 设计的"地图模式"

AGENTS.md 不是百科全书，是地图。

为什么巨型 AGENTS.md 必败：

失败原因	机理
Context 是稀缺资源	臃肿文件挤掉任务空间
指导过多反而失效	"一切都重要 = 没有重点"
文档快速腐烂	旧规则无人更新
单文件无法机械验证	linter 检查不到内容偏差

OpenAI 的解法：AGENTS.md 收缩到 ~100 行，只做"地图"指向 docs/ 分类文档；linter / CI 验证链接完整性；跑 "doc-gardening" 智能体定期扫描过时文档。

Hashimoto 的解法：AGENTS.md 的每一行对应一个历史失败案例，单 Agent 路线适合中小规模项目，六步进阶——积累失败 → 抽象规则 → 更新 AGENTS.md → 形成持续反馈循环。

适合放进去的内容：技术栈与架构模式、命名规范与代码风格、测试哲学、代码库中常见坑点、已多次观察到的 agent 反模式。

不适合放进去的内容：完整 API 文档、空泛废话（如"写干净代码"）、互相冲突的指令。

实操建议：保持在 500 行以内；按主题模块化拆分；少量 few-shot example 提升可执行性；不要把所有规则都做成 always-on。

关键认知：Custom Rules 不是一次性文档，而是随着 agent 犯错不断迭代的"行为调优资产"。

2.5 三种实战路线对比

维度	Hashimoto	OpenAI	Anthropic
Agent 数量	单 Agent	多 Agent + 后台清理	三角色（Planner/Generator/Evaluator）
约束方式	AGENTS.md 文本规则	自定义 Linter 机械规则	Sprint Contract + Evaluator
适用规模	个人 / 小团队	中等规模工程团队	长任务 / 高复杂度
投入成本	最低	中	最高（Solo 的 20x）

OpenAI 路线——机械约束 + 分层架构：3 人 5 个月 100 万行代码、1500 PR。五大方法论：

地图式文档（AGENTS.md 只当目录）
机械化约束（Linter 报错自带修复方法）
可观测性接入（Chrome DevTools + LogQL / PromQL）
熵管理（后台 Agent 做垃圾回收，清理速度 > 生成速度）
仓库即事实源（Slack / Wiki 对 Agent 不可见）

架构约束：严格分层 Types → Config → Repo → Service → Runtime → UI，违反 PR 自动拦截。关键洞察：架构约束在传统公司要等团队扩到数百人才引入，但对编码 Agent 来说是早期先决条件——没有约束，速度越快，架构漂移越严重。

Anthropic 路线——三角色分离 + Sprint Contract：

角色	职责	设计要点
Planner	一两句描述 → 完整 product spec + 分步 feature list	只聚焦产品上下文，不规定技术细节
Generator	逐 feature 落地	每个 Sprint 前谈"契约"（单 Sprint 27 条验收标准）
Evaluator	独立验收	Playwright 真正跑页面、点按钮；标记 pass/fail

关键实践：Initializer agent 创建 init.sh / claude-progress.txt；把高层需求展开成 200+ feature 全部初始 failing；agent 只能改 feature passes 状态，不能修改测试定义本身。Context Reset 策略：长任务中定期清空上下文窗口，启动全新 agent，通过结构化交接文档恢复——类似"重启进程解决内存泄漏"。

Hashimoto 路线——单 Agent + 失败案例驱动：启动单个 Agent + 极简 AGENTS.md → 观察 Agent 犯错 → 把根因抽象为规则 → 加入 AGENTS.md → 形成持续反馈循环。AGENTS.md 的每一行 = 一次历史失败案例。

2.6 组织级 Rollout：MercadoLibre

规模数据：近 20,000 名开发者；覆盖数千个代码仓库；SDD 已获约 4,000 名开发者采用；维护 9+ 技术栈 标准化规则。

关键实践：

组织维护标准化 rules 覆盖 9+ 技术栈
团队在标准化基础上叠加仓库级规则
自建内部 MCP，对接内部云平台、SDK、RAG 业务知识和应用文档
独立 Code Review Agent 接入 CI，对所有 PR（人写 + AI 写）做自动分析

Code Review Agent 的组织收益：人类 reviewer 更聚焦高层设计；更早发现 bug；review 周期更快；质量控制能力随 PR 数量扩展，而非依赖 reviewer 人数扩展。

关键认知：大规模 AI coding agent 不是"工具部署问题"，而是"工程制度升级问题"——规则如何分层治理、工具如何合规接入、反馈如何自动执行、不同技术栈如何建立最低统一标准、组织知识如何通过 MCP/Skill 进入 agent 回路。

40% 边际效益陷阱：SDD 覆盖率 20%（4000/20000）。工程化方案做得再好，没有强制机制（CI 拦截、Hooks 阻塞），就是自然天花板。

2.7 典型失败案例与减法实证

需求过粗导致"错得合理"：用户说"做一个后台新增商品功能"，缺失技术栈、API 合约、幂等性、角色权限等信息。Agent 实现一个看似可工作的 MVP，但再次点击按钮重复插入。根因不是 Agent 不会写代码，而是初始输入未说明隐含业务约束——SDD 解的正是这个问题。

Vercel 工具精简：可用工具从 15 个砍到 2 个，准确率 80% → 100%，Token 消耗减少 37%，速度提升 3.5 倍。在 Tool System 层做减法的 ROI 远高于做加法。

OpenAI Linter 报错自带修复：Linter 不只是"指出错误"，是"教 Agent 怎么改"——"禁止 X" 不如 "把 X 改成 Y"，前者要求 Agent 自己悟出修复方法，后者是 in-context learning 的高质量例子。

混合检索基础设施：Coding Agent 同时需要语义查询（"产品对用户会话的设计原则"）和精确匹配（"哪些文档提到 validateToken"）。Milvus 2.6 Sparse-BM25 同时生成 dense embedding + TF 编码稀疏向量，Reciprocal Rank Fusion 融合排序，BEIR 上吞吐量比 ES 高 3-4x。

OMC（oh-my-claudecode）多智能体范例：Claude Code 之上的多智能体编排框架（28.3k Stars）。5 泳道 × 19 Agent（规划/执行/验证/修复/维护）、Team 模式调度（Orchestrator + 最多 6 个 tmux worker）、两层 Skill 系统、OpenClaw 钩子。声称综合节省 30-50% token（未独立验证）。证明 Skill 可做成"用户级 + 项目级"两层 YAML 触发条件的产品组件，也是 P2"Agent 专业化分工"的极端化形态。

2.8 CLI Agent 性能与 Tool 接口工程

启动性能 7 项清单（某顶级工业级项目用 7 项技术叠加实现 12ms 的 --version）：

技术	节省时间	实施要点
Fast Path 入口分发	~100ms	`--version` / `-v` 在加载任何模块前直接输出退出
并行预取	~65ms	模块评估阶段并行 spawn MDM 子进程 + Keychain + GrowthBook
延迟加载	~1.1MB	OTel + gRPC + 大型命令模块按需 import
编译时 DCE	整个代码块	`feature()` 特性开关 + bundler 剥离非激活代码
memoize 单例	重复调用	`init()` / `getCommands()` / `getUserContext()` 只算一次
API 预连接	~50ms	init 阶段建立 TLS 握手但不发请求
工具列表分区排序	真金白银	内建/MCP 分别排序保 prompt cache 命中

Tool 接口 Fail-Closed 工厂模式：所有工具必须经过 buildTool() 创建，工厂提供"全部偏向最受限"的默认值：

python

TOOL_DEFAULTS = {
    "is_enabled": lambda: True,
    "is_concurrency_safe": lambda _: False,  # 假设不安全
    "is_read_only": lambda _: False,          # 假设会写入
    "is_destructive": lambda _: False,
    "check_permissions": lambda inp: {"behavior": "allow", "updatedInput": inp},
}

Fail-Closed 原则：忘了设置字段 → 走最受限路径。遗漏不是漏洞。配套设计：每个工具动态声明 is_concurrency_safe(input)（FileRead 总安全，Bash 看命令）；StreamingToolExecutor 强制并发规则（并发安全工具可彼此并行；非并发工具独占执行）。

内建 / MCP 工具分区排序保 prompt cache 稳定性：API 端 prompt cache 的缓存断点放在最后一个内建工具处。如果混合排序，添加/删除任何一个 MCP 工具都会让所有下游缓存失效——直接表现为 Token 成本上升。

第三章 Meta-Harness 与 AgentOS

3.1 Meta-Harness 三层架构（Anthropic）

Anthropic 在 Claude Managed Agents 中给出的极简抽象，强调不固化补丁、只承诺接口：

应用层：Agent 业务逻辑
    ↓
Session（执行事实流） ← append-only 不可变事件日志
Harness（调度脑干）   ← 无状态、可热替换、标准接口
Sandbox（可插拔执行） ← 大脑与手解耦，独立、可共享、懒加载
    ↓
基础设施层：工具 / MCP 服务 / Vault

核心承诺：

不承诺 harness 具体长什么样
只承诺几类长期稳定的接口
Session 不是 context window（是事实流，不是消息列表）
安全不依赖"模型不作恶"假设，依赖系统级凭证隔离

与其它模型的差异：Meta-Harness 是唯一把"调度逻辑"无状态化的方案，也是唯一把模型暂时缺陷与系统架构显式分离的方案——前提是相信模型会持续进化，今天的最优实现会变成明天的技术债。

3.2 从"业务层抽象"到"基础设施层抽象"

早期分层（06、05、18）侧重业务问题分类：循环、工具、记忆、验证。后期分层（22、30）侧重基础设施稳定性：把"调度"剥离成无状态层、把"状态"从消息列表升级为事实流。

这一转变与软件工程史上 OSI 七层 → TCP/IP 四层、Monolith → 微服务的转变同构。

实用启示：你的 Harness 是否在做"补丁固化"——把"模型当前能力缺陷"硬编码成永久架构？

3.3 Harness vs AgentOS 的层级关系

Harness 是 AgentOS 的用户态层（shell/daemon）
AgentOS 是内核（调度、隔离、资源管理）
两者是上下层关系，不是竞争关系

实用启示：当一家公司宣称"我们做 AgentOS"时，要追问它是替代 Harness 还是承载 Harness——这决定了选型逻辑。

3.4 三大编程范式与历史定位

三大编程范式按问题复杂度分层：

维度	Vibe Coding	Spec Coding	Harness Engineer
年份	2024	2025	2026
核心逻辑	跟着感觉走，AI 猜猜猜	先写清楚需求，AI 照着做	设计 AI 工作的环境和约束
比喻	理发店	装修队	F1 赛道设计师
质量	抽奖	合同约束	系统工程
角色	用户	需求方	系统设计者

核心能力转移：从"怎么写代码"变成"怎么设计让 AI 可靠工作的系统"。能用 Vibe Coding 解决的不要上 Spec，能用 Spec 解决的不要上 Harness——但能用 Harness 解决的不要停留在 Spec。

30 年软件工程驾驭复杂性的延续：

年代	代表作	驾驭的对象
1994	GOF《Design Patterns》	对象
2002	Fowler《企业应用架构模式》+ Evans《DDD》	企业架构
2010	微服务	分布式通信
2017	Kleppmann《DDIA》	数据系统
2026	Harness Engineering	智能体（不确定性系统）

Agent 时代的独特之处：Agent 是历史上第一次需要驾驭概率机器——你给它输入，不一定按你的预期输出。过去的工程经验（DAG、状态机、确定性流程）只能部分迁移，必须引入新原语：自我修正、外部验证、约束与回退、熵控。

关键洞察

跨多源融合后提炼的、超越任一单篇来源的发现。

"模型决定上限 vs Harness 决定上限"的表述张力：理论上限视角下模型决定一个任务可达到的最高分；实际可达上限视角下当前模型能力区间内可观察到的性能差异主要来自 Harness。在模型边际提升放缓的窗口期，Harness 的工程努力比等下一代模型回报率更高；但模型一旦跨过新的能力阈值，会把今天的 Harness 复杂度部分"吸收"掉。
Harness 分层模型的"骨架同构"现象：7 套主流分层方案虽然命名各异，但深层都包含「信息边界 + 工具 + 编排 + 状态 + 验证 + 约束」六个面向。选型不在于争论"哪套分层最对"，而是按团队成熟度选粒度。
三种实战路线的"团队规模 × 任务复杂度"决定论：Hashimoto 适合个人/小团队，OpenAI 适合中等规模工程团队，Anthropic 适合长任务/高复杂度。选型不是"哪个更对"，而是匹配你的规模和复杂度——20x 成本的三角色架构对小项目是浪费。
Custom Rules 是基础投入，不是高级技巧：即使没有 MCP、没有 Skills、没有 SDD，光把 AGENTS.md 做好（地图模式 + 失败案例驱动）就能解决大部分问题。投入 Harness 从来不是"先平台后规则"，而是"先规则再平台"。
机械约束 vs 文本规则的"硬度差"：文本规则"请遵守命名规范"→ Agent 可能遵守也可能不；Linter 规则机械检查 → Agent 必须遵守；Hooks 执行拦截 → Agent 没办法绕过。把"团队的口头规范"变成 Linter 规则是 P0 中最容易被忽视的高价值动作。
三角色架构的真正价值不在分工而在"独立性"：核心不是"把任务拆三段"，而是 Evaluator 必须独立于 Generator（GAN 思路）——让一个 Agent 既写代码又评价代码会自评虚高。同样适用于其他场景：写 PRD 的人不能验收、做需求的人不能写 acceptance criteria。
决策权让渡是对话式 → Agentic 的本质拐点：三阶段工作流的演化本质不是"AI 更强了"，而是"人愿意把决策权让渡多少"。Agentic 落地失败的项目，往往不是技术不行，而是团队没完成"指挥者→把关者"的角色切换。
"95% 代码是 Harness"的实证：某顶级工业级 CLI Coding Agent 公开源码（~1,900 文件 / 512K 行 TS）显示模型调用代码 < 5%。query() 主循环 16 步只有第 8 步调 API，其余 15 步全是验证、压缩、注入、修复、Hook、预算检查——评估自己/他人 Agent 项目时，模型调用相关代码远高于 5% 说明 Harness 不够厚。
组织级 rollout 的"40% 边际效益陷阱"：MercadoLibre SDD 只覆盖 20% 开发者。工程化方案做得再好，没有强制机制（CI 拦截、Hooks 阻塞）就是自然天花板——"上工具就能改变行为"是过于乐观的假设。
"Harness 是长出来的，不是设计出来的"：没有团队从一张完美架构图开始；都是从第一个犯错开始补，从第一条规则开始写。不要追求"完整六层 Harness 一次到位"，要建立"错误 → 新规则"的反馈循环。

待探索问题

棕地项目的 Harness 形态：所有公开案例（OpenAI、Anthropic、Stripe、Hashimoto）全是绿地项目；存量代码库的 Harness 怎么分层？哪些层不能照搬？
AGENTS.md 的腐烂速度怎么测量："500 行开始腐烂"是经验值，有没有可量化的"AGENTS.md 健康度"指标？
Skills 的复用边界：SkillHub 这样的 Skills 流通平台能成立吗？跨团队 / 跨公司 Skills 复用的实际障碍是什么？
Code Review Agent 的失效模式：Agent 评 Agent 的代码会不会陷入"互相说服没事"的死锁？
多 Agent 编排的"成本临界点"：20x 成本是任意场景都值得的吗？什么样的任务规模、容错要求下，多 Agent 是必要的而不是奢侈的？
三层工程演进之后：如果 Harness 是 2026 的范式，2028 的范式会是什么？社会化协作工程？多 Agent 治理？
Harness vs Framework 的边界：LangGraph、LlamaIndex Workflows 是 Harness 的实现还是 Harness 的子集？

来源索引

#	标题	来源标识	收录日期	贡献章节
1	05-Harness-Engineering-AI-Agent架构方法论	已归档-05-...-2026-04-13.md	2026-05-12	第一章 1.1/1.2/1.5；第二章 2.3
2	06-Agent-Harness六层架构-交付时代	已归档-06-...-2026-04-03.md	2026-05-12	第一章 1.1/1.5/1.7
3	07-Agent-Harness技术原语拆解	已归档-07-...-2026-04-03.md	2026-05-12	第一章 1.4
4	12-Harness-Engineering实战-百万行代码	已归档-12-...-2026-04-03.md	2026-05-12	第二章 2.4/2.5/2.7
5	16-Coding-Agent-Harness-四大杠杆与反馈闭环	已归档-16-...-2026-04-10.md	2026-05-12	第二章 2.1/2.2/2.6
6	17-汤道生-发动机线束驾驶员三角框架	已归档-17-...-2026-04-13.md	2026-05-12	第一章 1.2/1.3
7	18-Harness三层结构-知识约束反馈	已归档-18-...-2026-04-03.md	2026-05-12	第一章 1.5；第二章 2.5
8	22-HarnessEngineering深度解析-Agent治理时代	已归档-22-...-2026-04-13.md	2026-05-12	第一章 1.2；第三章 3.3
9	26-Agent等于Model加Harness-30年软件工程演进	已归档-26-...-2026-04-14.md	2026-05-12	第一章 1.1；第三章 3.4
10	30-Anthropic-AgentOS-Meta-Harness三层架构	已归档-30-...-2026-04-16.md	2026-05-12	第三章 3.1/3.2
11	AI 时代程序员三大流派	公众号	2026-04-13	第三章 3.4
12	聊天框时代结束-对话式到 Agentic 范式转移	公众号	2026-04-03	第一章 1.6
13	产品经理 Vibe Coding 30 个核心概念全景	公众号	2026-04-03	第一章 1.7
14	oh-my-claudecode 多智能体编排框架深度分析	产品案例研究	2026-05-18	第二章 2.2/2.7
15	工业级 CLI Coding Agent 源码解析（charrli）	源码分析	2026-05-19	第一章 1.7；第二章 2.8

演进记录

日期	版本	变更摘要
2026-05-12	v0.1（原概念篇）	由 8 篇 Harness 主题源文件批量合成。建立"概念—框架—案例—洞察"完整骨架。提出 7 套分层模型的统一对照视图。提炼"模型决定上限 vs Harness 决定上限"的张力调和、Harness 分层骨架同构、隐喻演进暗示地位提升三个跨源洞察。
2026-05-12	v0.1（原工程实践篇）	由 6 篇源文件批量合成。建立四大杠杆 + Feedback Loop 框架、P0/P1/P2 行动清单、AGENTS.md 地图模式、三种实战路线对比和组织级 rollout 方法论。提炼"机械约束 vs 文本规则的硬度差"、"40% 边际效益陷阱"、"三角色架构的真正价值不在分工而在独立性"等跨源洞察。
2026-05-15	v0.2（原概念篇）	由 /route-knowledge 路由触发：吸收 3 篇综述笔记。新增三大编程范式演进、对话式→Agentic 范式转移、上下文工程是 PM 最大杠杆等概念与案例。
2026-05-18	v0.2（原工程实践篇）	由 /route-knowledge 路由分析触发，纳入 OMC 多智能体编排框架案例：补充 Skills 产品化范例和 P2 极端化范例。
2026-05-19	v0.3（两篇均更新）	工业级 CLI Coding Agent 源码解析：第一章新增"95% 代码是 Harness"实证；第二章新增 CLI 启动性能 7 项清单、Tool 接口 Fail-Closed 工厂模式、工具列表分区排序保 prompt cache 三个工程实践。
2026-05-20	v1.0	合并《Harness 概念与架构体系》与《Coding Agent Harness 工程实践》为单一文档。三章结构：第一章概念体系（公式、三层演进、三角隐喻、七大原语、六层架构、Agentic 拐点、标志性案例）；第二章 Coding 工程实践（统一循环、四大杠杆、P0/P1/P2、AGENTS.md 地图模式、三路线对比、组织级 rollout、Tool 工程）；第三章 Meta-Harness 与 AgentOS（Anthropic 三层抽象、范式跃迁、AgentOS 关系、三大流派与 30 年软件工程史定位）。去重 Agent=Model+Harness 公式、Skills 描述、Harness 分层多版本对照表。

思维模型

认知方法论

学科模型

职场与成长

05-AI与Agent

00-基础学科

01-Agent核心

02-Harness工程

03-RAG系统

04-成本与效能

05-AI安全

06-战略与前沿

Harness 概念架构与 Coding 工程实践

第一章 Harness 概念体系

1.1 公式：Agent = Model + Harness

1.2 三层工程演进（Prompt → Context → Harness）

1.3 发动机—线束—驾驶员三角

1.4 七大技术原语（按依赖关系自底向上）

1.5 六层架构（Harness 业务分层）

1.6 对话式 → Agentic 的本质拐点

1.7 标志性案例（同模型 ×10 差距）

第二章 Coding Agent 工程实践

2.1 Coding Agent 的统一循环与 Context 稀缺性

2.2 四大工程杠杆（功能分工）

2.3 P0/P1/P2 行动清单

2.4 AGENTS.md 设计的"地图模式"

2.5 三种实战路线对比

2.6 组织级 Rollout：MercadoLibre

2.7 典型失败案例与减法实证

2.8 CLI Agent 性能与 Tool 接口工程

第三章 Meta-Harness 与 AgentOS

3.1 Meta-Harness 三层架构（Anthropic）

3.2 从"业务层抽象"到"基础设施层抽象"

3.3 Harness vs AgentOS 的层级关系

3.4 三大编程范式与历史定位

关键洞察

待探索问题

来源索引

演进记录

认知方法论

学科模型

职场与成长

00-基础学科

01-Agent核心

02-Harness工程

03-RAG系统

04-成本与效能

05-AI安全

06-战略与前沿

Harness 概念架构与 Coding 工程实践 ​

第一章 Harness 概念体系 ​

1.1 公式：Agent = Model + Harness ​

1.2 三层工程演进（Prompt → Context → Harness） ​

1.3 发动机—线束—驾驶员三角 ​

1.4 七大技术原语（按依赖关系自底向上） ​

1.5 六层架构（Harness 业务分层） ​

1.6 对话式 → Agentic 的本质拐点 ​

1.7 标志性案例（同模型 ×10 差距） ​

第二章 Coding Agent 工程实践 ​

2.1 Coding Agent 的统一循环与 Context 稀缺性 ​

2.2 四大工程杠杆（功能分工） ​

2.3 P0/P1/P2 行动清单 ​

2.4 AGENTS.md 设计的"地图模式" ​

2.5 三种实战路线对比 ​

2.6 组织级 Rollout：MercadoLibre ​

2.7 典型失败案例与减法实证 ​

2.8 CLI Agent 性能与 Tool 接口工程 ​

第三章 Meta-Harness 与 AgentOS ​

3.1 Meta-Harness 三层架构（Anthropic） ​

3.2 从"业务层抽象"到"基础设施层抽象" ​

3.3 Harness vs AgentOS 的层级关系 ​

3.4 三大编程范式与历史定位 ​

关键洞察 ​

待探索问题 ​

来源索引 ​

演进记录 ​

Harness 概念架构与 Coding 工程实践

第一章 Harness 概念体系

1.1 公式：Agent = Model + Harness

1.2 三层工程演进（Prompt → Context → Harness）

1.3 发动机—线束—驾驶员三角

1.4 七大技术原语（按依赖关系自底向上）

1.5 六层架构（Harness 业务分层）

1.6 对话式 → Agentic 的本质拐点

1.7 标志性案例（同模型 ×10 差距）

第二章 Coding Agent 工程实践

2.1 Coding Agent 的统一循环与 Context 稀缺性

2.2 四大工程杠杆（功能分工）

2.3 P0/P1/P2 行动清单

2.4 AGENTS.md 设计的"地图模式"

2.5 三种实战路线对比

2.6 组织级 Rollout：MercadoLibre

2.7 典型失败案例与减法实证

2.8 CLI Agent 性能与 Tool 接口工程

第三章 Meta-Harness 与 AgentOS

3.1 Meta-Harness 三层架构（Anthropic）

3.2 从"业务层抽象"到"基础设施层抽象"

3.3 Harness vs AgentOS 的层级关系

3.4 三大编程范式与历史定位

关键洞察

待探索问题

来源索引

演进记录