这是一篇由原始材料转换而来的阅读页，保留了源文件的主要结构，并补充了可追溯的来源说明与链接。

Harness Engineering 是控制论：把 Anthropic 与 OpenAI 的工程实践合在一起看

参考框架：George（@odysseus0z）在 X 文章 《Harness Engineering Is Cybernetics》 中提出，harness engineering 的本质不是“更会写 prompt”，而是把软件工程重新组织为一个可观测、可调节、可纠偏的控制系统。
文章链接：https://x.com/odysseus0z/article/2030416758138634583

主要参考：
- Anthropic Engineering: Effective harnesses for long-running agents
https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
- OpenAI: Harness engineering: leveraging Codex in an agent-first world
https://openai.com/index/harness-engineering/ / https://openai.com/zh-Hans-CN/index/harness-engineering/

TL;DR

如果把软件开发看作一个控制系统，那么：

• Anthropic 重点解决的是：智能体如何在跨会话、跨 context window 的情况下持续推进，不失忆、不烂尾、不提前宣布完成。
• OpenAI 重点解决的是：当智能体成为主力执行者后，如何把整个代码仓库、文档系统、测试系统、观测系统、约束系统改造成一个agent-first 的工程环境。
• George 那篇 X 文章 给了一个很强的总框架：这不是单纯的自动化，也不只是 prompt engineering，而是控制论（cybernetics）在软件工程层面的落地。

一句话概括：

人不再主要“拧阀门”，而是负责设计阀门、传感器、控制器、报警器与验收标准；智能体在这套系统里持续执行、验证、修正与交付。

因此，真正值得提炼的，不是某个 CLI flag，不是某个模型名字，也不是某个“神 prompt”，而是一套完整的方法论：

1. 把隐性知识外显化：让仓库成为事实源。
2. 把任务拆成可验证的小步：不要 one-shot。
3. 把反馈环做实：测试、UI、日志、metrics、traces 都要可供 agent 读取。
4. 把质量要求机械化：lint、CI、结构测试、脚本化 runbook。
5. 把经验沉淀为工件：plans、progress、feature list、docs、golden rules。
6. 把清理和治理常态化：doc gardening、cleanup、refactor、drift control。

后面的最大篇幅，我会把所有能想到的工程规范、模式、方法和实施细则尽量展开，作为一个偏“agentic engineering 作业规范大全”的草案。

一、先讲核心思想：为什么说 Harness Engineering 是“控制论”

1.1 George 的框架：从蒸汽机调速器到 Kubernetes，再到智能体工程

George 那篇文章里最有穿透力的比喻，不是 AI，而是三段历史：

1. 瓦特调速器（centrifugal governor）
   工人不再手动拧阀门，而是设计一个会根据转速自动调节阀门的机构。

2. Kubernetes controller
   工程师不再盯着每个服务手动重启，而是定义 desired state，由 controller 持续观测 actual state 并自动 reconcile。

3. Harness engineering
   工程师不再主要逐行写代码，而是设计环境、约束、反馈回路和知识结构，让 agent 去持续地产出代码、测试、文档和修复。

这三者共享一个共同模式：

• 有一个目标状态（desired state / spec / completion criteria）
• 有一套传感器（tests / logs / metrics / screenshots / lint / CI）
• 有一套执行器（agent 对代码、文档、配置、脚本的修改能力）
• 有一个控制器（harness / controller / rules / plans / policies）
• 有一套校准机制（人工 judgment、golden rules、architecture invariants、review）

所谓 harness engineering，本质上就是：

在“软件工程”这一层，第一次出现了足够强的传感器 + 执行器组合，使得高层工程决策也能进入闭环控制。

1.2 为什么代码仓库以前是“控制闭环的盲区”

George 的一个关键判断是：

• 编译器管语法
• 测试管行为
• linter 管风格

这些当然也是反馈回路，但它们的控制层级比较低。它们只能检查“可机械验证”的性质：

• 编不编得过
• 测试过不过
• 格式对不对

而在这些之上的问题——比如：

• 这次改动是否符合架构方向？
• 这个抽象会不会让系统未来更难维护？
• 这个模块边界是不是会漂移？
• 这个实现是否符合团队长期的 engineering taste？

过去缺乏合适的 sensor 与 actuator，所以只能靠人脑来判断，也只能靠人手来修。

LLM 的意义不只是“会写代码”，而是：

• 它能在一定程度上感知这些更高层的问题；
• 它也能直接实施修复。

于是，软件工程第一次有可能在更高抽象层面形成真正的闭环。

但注意：

闭环能形成，不等于闭环会稳定。

调速器要调参，controller 要对 spec 敏感，agent 也必须被校准。

而 Anthropic 与 OpenAI 的文章，本质上都在讨论“如何做这种校准”。

1.3 Anthropic 和 OpenAI 分别校准了什么

Anthropic：校准“跨会话连续性”

Anthropic 的切入点更像是在说：

如果一个 agent 每次 context window 切完都像换了个失忆工程师，那你先别谈宏大系统设计，先把“交接班制度”建立起来。

所以它强调： - initializer 与 coding agent 分工 - init.sh - progress.md - feature_list.json - 每次只做一个小功能项 - 会话结束必须留下干净状态

这是一套“长跑接力制”的校准方法。

OpenAI：校准“整个仓库作为 agent-first 操作系统”

OpenAI 的切入点则更宏观：

如果你真的让 agent 来主导仓库，那么仓库本身就得变成它的世界、它的地图、它的工具箱、它的约束系统和它的反馈控制面板。

所以它强调： - AGENTS.md 要短，只做地图 - 真正知识在 docs/ - 复杂任务写进 plans/ - 架构边界、命名、日志、文件大小等都要机械化 - UI、logs、metrics、traces 都要让 agent 直接读 - doc gardening、cleanup、golden principles 要常态化

这是一套“仓库即控制系统”的校准方法。

合起来看

因此可以这么理解：

• Anthropic 给出了长任务 agent 的最小可行接力协议。
• OpenAI 给出了 agent-first 工程组织的完整操作系统蓝图。
• George 则指出：它们其实是在同一个控制论框架下工作。

二、统一提炼：Harness Engineering 的八条核心原则

原则 1：仓库必须成为事实源（Repo as source of truth）

对 agent 来说，它运行时上下文里看不到的东西，几乎就等于不存在。

所以： - Slack 讨论 - 口头共识 - 会议纪要 - Google Docs - 人脑中的“默认常识”

如果没有进入 repo，就不会被稳定继承。

落地要求

• 架构原则写到 docs/architecture/
• 产品行为写到 docs/product/
• 启动与排障方法写到 docs/runbooks/
• 执行计划写到 plans/
• 关键 taste / golden rules 写到仓库中并最好被 lint / CI 执行

原则 2：AGENTS.md 应该是地图，而不是百科全书

OpenAI 这一点非常重要，George 的框架也支持这一点。

一个巨大的 AGENTS.md 往往会： - 挤占上下文 - 淹没真正重要的信息 - 很快腐烂 - 很难做 freshness / ownership / cross-link 检查

所以更好的做法是： - AGENTS.md：短、稳、像目录 - docs/index.md：知识总入口 - 具体规则：拆到细分文档中

原则 3：复杂任务必须工件化（Plans as first-class artifacts）

复杂任务不能只存在于聊天上下文中。

一个可持续的 agent 工作流，必须把以下内容写成文件： - 目标 - 范围 / 非目标 - 假设 - 约束 - 执行步骤 - 验证方法 - 回滚路径 - 决策日志 - 当前状态

这使得 agent 的工作不是“重新理解一遍上下文”，而是“继续执行一个版本化计划”。

原则 4：一步一验收，绝不 one-shot

Anthropic 最强的经验之一就是：

不要让 agent 一次尝试做完整系统。

真正稳定的方法是： - 把工作拆成小的、可验证的增量 - 每次只推进一个 coherent increment - 每一步都可恢复、可回滚、可交接

原则 5：测试不是附属品，而是传感器

没有测试、UI 验证、logs、metrics、traces，agent 只能“猜”。

而 harness engineering 的目标，不是让 agent 更大胆，而是让 agent 更可验证。

因此，所有反馈源都应被视为传感器： - 单元测试 - 集成测试 - 端到端测试 - 浏览器自动化 - DOM snapshot - screenshot / video - structured logs - metrics / traces - CI 输出 - lint 错误消息

原则 6：重要规则必须机械化

“请注意架构分层”没有太大价值； “违反分层就 CI fail”才有价值。

同理： - “最好加结构化日志” < “没有结构化日志 lint fail” - “尽量别写超大文件” < “超过阈值 fail” - “不要猜 payload 结构” < “边界不 parse/validate 就 fail”

原则 7：经验要沉淀成可复用控制面

如果每次 agent 出错，人类只是手工修一次，那系统没有变强。

只有当问题被沉淀成以下形式，系统才真正升级： - 文档补充 - 计划模板 - linter 规则 - CI 检查 - 复现脚本 - regression test - runbook - cleanup 任务 - golden principles

原则 8：治理要常驻，不能只靠大扫除

OpenAI 文中“每周五拿 20% 时间清 AI slop”这个细节非常说明问题。

AI 产出速度越高： - 偏差扩散越快 - 错误模式复制越快 - 人工补救越不可能规模化

因此必须常驻： - doc gardening - cleanup/refactor runs - invariant scans - quality scoring - drift detection - targeted auto-fix PRs

三、Anthropic 与 OpenAI 的实践如何互补

3.1 Anthropic 解决的是“接力”问题

Anthropic 提供的是一套非常像“值班制度”的东西：

• 第一个 agent 负责建骨架
• 后续 agent 负责逐步推进
• 用 init.sh 降低启动成本
• 用 progress 降低交接损耗
• 用 feature_list.json 降低“误判完成”的概率
• 用 git commit 形成可恢复记忆

它特别适合： - 跨 context window 的长任务 - 需要多次会话接续的项目 - 先把系统从“容易断片”拉到“能稳定接力”

3.2 OpenAI 解决的是“规模化主导”问题

OpenAI 的重点不是单一任务，而是整个仓库如何支持 agent 高频运转：

• 地图式 AGENTS
• docs/ 系统化知识库
• 计划体系
• worktree 隔离运行
• 可被 agent 查询的观测栈
• lint / CI / 结构测试机械执行约束
• 后台治理 agent

它特别适合： - agent 已经是主力执行者 - 任务吞吐量很高 - 代码库和团队开始变大 - 人的瓶颈从 coding 变成 QA / judgment / architecture

3.3 最优组合：先接力，再系统化

一个现实可行的落地顺序通常是：

阶段 1：先补 Anthropic 式最小骨架

• init.sh
• progress.md
• feature_list.json
• clean commit discipline

阶段 2：补 OpenAI 式知识与计划结构

• AGENTS.md 做地图
• docs/index.md
• docs/architecture/
• docs/runbooks/
• plans/active/
• plans/done/

阶段 3：机械化工程约束

• lint
• CI
• structural tests
• custom checks
• parseable logs / errors

阶段 4：常驻治理与高吞吐运转

• doc gardening
• cleanup agents
• drift detection
• short-lived PRs
• targeted auto-fix

四、工程规范、模式、方法和实施细则大全

下面进入最大篇幅部分。这里不追求“优雅”，而追求“尽可能全”。你可以把它当成一个 agent-first 软件工程的操作规范草案。

4.1 知识架构规范（Knowledge Architecture）

4.1.1 AGENTS.md 规范

目标： 给 agent 一个稳定入口，而不是塞满所有规则。

建议： - 控制长度，尽量短 - 内容只包含：核心理念、仓库入口、会话流程、关键约束、去哪看更多信息 - 不要把大量细枝末节都塞进去 - 必须包含 docs 和 plans 的入口 - 必须包含启动与验证的主路径

不建议： - 把所有风格细节写在 AGENTS.md - 把所有 runbook 内容也写进去 - 把会变化很频繁的知识都放进去

4.1.2 docs/ 目录规范

建议至少划分： - docs/index.md：总入口 - docs/architecture/：系统分层、边界、域模型、依赖方向 - docs/product/：功能需求、用户旅程、验收标准 - docs/runbooks/：本地启动、调试、部署、回滚、排障 - docs/quality/：测试策略、lint 规则、review 原则 - docs/debt/：技术债、重构计划、质量评分

4.1.3 文档元信息规范

建议在重要文档上带： - last reviewed date - owner / maintainer - verification status - related paths / related plans - deprecated / active status

4.1.4 决策记录规范

关键决策要能追溯： - 为什么这么设计 - 有哪些备选方案 - 取舍是什么 - 什么时候复审

可使用： - ADR（Architecture Decision Record） - plan 的 decisions log - docs/architecture 下的 decision 文档

4.1.5 术语和命名规范

如果产品/系统有专有概念，必须有术语表： - 领域实体命名统一 - 避免同义词漂移 - 让 agent 不会在不同目录中看到多个说法

4.2 会话交接与长任务规范（Continuity / Handoff）

4.2.1 progress 日志规范

每次会话结束必须记录： - 目标 - 做了什么 - 修改了哪些文件 - 跑了哪些命令 - 结果如何 - 剩余风险 / 未完成点 - 下一步建议 - 对应 commit

4.2.2 feature list 规范

适合用 JSON，而不是 Markdown。

每个功能项应包括： - 唯一 id - category - priority - description - steps（端到端操作步骤） - verification notes - passes: true/false

重要约束： - 后续 coding agent 原则上只改 passes - 如果必须扩 scope，应追加条目，不要静默改写已有需求

4.2.3 init.sh / bootstrap 规范

作用： - 快速确认环境是否健康 - 降低新会话理解成本 - 给 agent 一个固定的“先验收基线”入口

应尽量做到： - 可重复运行 - 失败有清晰退出码 - 输出适合 agent 解析 - 包含最小 smoke test - 必要时启动本地依赖

4.2.4 clean state 规范

每次会话结束时： - git status 尽量干净 - 有清晰 commit - 中间态要么写明原因，要么清理掉 - 不把仓库留在“半可运行状态”

4.2.5 一次只做一个 coherent increment

要求： - 一个功能点 - 一个缺陷修复 - 一个明确的小改造

不要： - 同时修很多无关问题 - 一边重构一边改需求一边补文档，导致交接成本变大

4.3 计划体系规范（Planning as Artifact）

4.3.1 什么时候必须写 plan

以下场景建议必须有 plan： - 跨多个子系统 - 需要几小时以上工作 - 涉及数据库 / schema / migration - 涉及 UI + backend 联动 - 回滚复杂 - 验证链条长 - 可能跨多次会话

4.3.2 plan 最少字段

• objective
• scope / non-goals
• assumptions
• constraints
• relevant docs / code
• execution steps
• verification plan
• rollback plan
• decisions log
• status log
• exit criteria

4.3.3 plan 更新纪律

计划不是一次写完就不动。 每次有关键进展都应更新： - 当前状态 - 新发现风险 - 决策变化 - 实测结果 - 下一步

4.3.4 小任务 vs 大任务

• 小任务：可在 progress.md 里轻量记录
• 大任务：必须升格为 plan 文件

4.4 测试与验证规范（Feedback Loops / Sensors）

4.4.1 验证分层

建议按层组织： 1. static checks / lint 2. unit tests 3. integration tests 4. smoke tests 5. e2e / browser tests 6. runtime verification via logs/metrics/traces

4.4.2 “已完成”的定义

一个功能被标记为完成，至少应满足： - 不破坏基线 smoke - 功能行为可复现地通过 - 关键边界条件已验证 - 有记录说明如何验证

4.4.3 浏览器自动化规范

对于 web app，尽量让 agent 能： - 打开页面 - 读取 DOM snapshot - 截图 - 导航与点击 - 输入与提交 - 录制复现路径

因为很多问题代码层面看不出来，但 UI 层会暴露。

4.4.4 截图 / 视频 / DOM 作为工件

建议保留在： - bug reproduction artifacts - regression proof - feature verification evidence

4.4.5 parseable CI / test 输出

CI 输出尽量： - 格式稳定 - 机器可读 - 错误可定位 - 最好带 remediation hints

4.4.6 错误信息设计

如果你有自定义检查器或 lint，错误信息不要只说“错了”，要说： - 错在哪里 - 期望什么 - 推荐修法是什么

对 agent 这非常重要，因为错误信息本身就是 prompt 的一部分。

4.5 观测性规范（Logs / Metrics / Traces）

4.5.1 结构化日志

关键路径必须有 structured logging： - request id / trace id - domain context - event name - error class - timing

4.5.2 指标规范

对于 agent 可修复的问题，最好暴露： - latency - error rate - throughput - startup duration - queue depth - retry count

4.5.3 traces 规范

对于复杂用户旅程或多服务链路： - 每个关键 span 应命名稳定 - 能定位性能瓶颈 - 能配合 user journey 做验收

4.5.4 让 agent 直接查询观测数据

最佳状态是： - logs 可被本地查询 - metrics 可被查询 - traces 可被检索 - worktree / task 对应隔离环境

这能让 agent 从“猜 bug”升级到“闭环 debug”。

4.5.5 每个任务最好有临时、隔离的运行实例

OpenAI 提到的 worktree 思路很关键。 建议： - 每个任务有隔离环境 - 对应独立 logs / metrics - 用完即清理 - 避免不同任务污染彼此的状态

4.6 架构与边界规范（Architecture Invariants）

4.6.1 分层必须明确

例如： - Types → Config → Repo → Service → Runtime → UI

关键不在于具体层名，而在于： - 依赖方向清晰 - 允许边有限 - 违规时能被工具发现

4.6.2 跨域访问必须有显式接口

不要让任意模块随意穿透调用。 最好： - 通过 provider / facade / service boundary - 便于 agent 理解什么是允许路径

4.6.3 边界解析而不是 YOLO 式探测

对外部输入： - parse - validate - 显式 schema - typed SDK 优先

不要： - 靠猜字段 - 靠 ad hoc probe - 让 agent 在不确定结构上继续搭代码

4.6.4 文件大小与模块复杂度限制

建议： - 文件大小阈值 - 函数长度阈值 - 导出项数量阈值 - 圈复杂度阈值

原因不是形式主义，而是： - 提高 agent 可读性 - 降低 drift - 降低未来 refactor 成本

4.6.5 命名约束

包括： - schema 命名 - type 命名 - handler / service / repo 命名 - test 文件命名 - event 名称规范

4.6.6 共享工具优先于复制 helper

OpenAI 的“golden principles”很值得学。 如果某类逻辑是 invariant carrier，就应收敛到共享工具，而不是各处手写小 helper。

4.7 脚本化与工具入口规范（Operable by Agent）

4.7.1 高频操作必须脚本化

凡是经常发生的，都应该给 agent 一个固定入口： - 启动环境 - 健康检查 - 跑 smoke - 复现 bug - 收集日志 - 执行回归 - 生成报告 - 清理临时资源

4.7.2 不要让关键流程依赖“记得怎么敲命令”

如果一个流程只存在于人类的 muscle memory 里，它就不适合 agent-first 团队。

4.7.3 本地脚本优先于 prompt 里写一大段 shell

如果一个命令序列会重复发生，应该提升为脚本 / runbook / make target。

4.7.4 脚本必须可组合

脚本最好： - 参数明确 - 输出稳定 - 可用于 CI - 可被 agent 反复调用

4.8 Review、PR 与合并规范

4.8.1 短生命周期 PR

高吞吐 agent 环境里，大 PR 往往会拖慢系统。 建议： - PR 小而明确 - 一个主题一个 PR - 让 review 成本稳定

4.8.2 review 要求结构化

review 最好围绕： - correctness - architecture fit - verification sufficiency - risk / rollback - missing docs / tests

4.8.3 agent-to-agent review 可以成为主力，但需要同一套工件协议

无论 reviewer 是人还是 agent，都应共享： - plans - docs - logs - feature list - progress

4.8.4 merge gates 不宜过重，但边界必须清晰

OpenAI 提到高吞吐环境下： - corrections are cheap - waiting is expensive

这不意味着不要 gate，而是： - gate 应聚焦于高价值不变量 - 不要让低价值阻塞堆积 - flaky 问题要靠治理，不要无限拖住主流程

4.9 文档治理规范（Doc Gardening）

4.9.1 文档也需要生命周期管理

每份文档都应该能回答： - 还有效吗？ - 被谁维护？ - 是否与当前代码一致？ - 是否应归档？

4.9.2 doc gardening 应定期运行

建议周期性执行： - 检查 stale docs - 修复 broken links - 标记 deprecated docs - 发现高频修改区域缺少 runbook / architecture note

4.9.3 文档健康度可量化

比如： - 交叉链接覆盖率 - 最近 review 时间 - 与代码变更频率的偏差 - 高频触达模块是否有文档

4.9.4 过时文档比没有文档更危险

没有文档时，agent 至少知道自己不知道； 错误文档会直接让 agent 朝错误方向高效奔跑。

4.10 Cleanup、Refactor 与 Drift Control

4.10.1 AI slop 必须承认其存在

agent 大量产出后，必然会出现： - 重复抽象 - 命名不一致 - 风格漂移 - 边界松动 - 局部最优但全局不协调

4.10.2 需要后台清理任务

建议常驻： - duplicate pattern scan - shared util extraction - naming normalization - file size cleanup - architecture drift repair - stale TODO sweep

4.10.3 技术债要持续偿还

不要等“大重构周”。 更好的方式是： - 每天小额偿还 - 把 debt item 版本化 - 用 agent 扫描和发起小 PR

4.10.4 质量评分可以有用

可按模块维护： - 文档质量 - 测试质量 - 可观测性质量 - 架构一致性 - agent legibility

4.11 Multi-Agent 角色模式

4.11.1 initializer

负责搭骨架： - init.sh - progress.md - feature_list.json - docs skeleton - initial plan scaffolding

4.11.2 builder / coding agent

负责一个增量的实现与验证。

4.11.3 reviewer

负责： - diff 检查 - 风险提示 - 验证链审查 - 文档 / plan 缺失检查

4.11.4 debugger

专注： - 复现 bug - 收集日志 / metrics / traces - 缩小问题范围

4.11.5 gardener

专注： - docs 更新 - broken links - stale rules - knowledge map 整理

4.11.6 janitor / cleanup agent

专注： - drift repair - duplicate extraction - style normalization - boring but compounding hygiene work

4.11.7 角色再多，也必须共享同一套仓库工件

角色分化不是让系统更乱，而是让大家对同一个控制面分工操作。

4.12 Bug Factory 模式

适用： - issue 驱动维护 - 高频线上问题 - UI/性能/集成问题多

规范： - 每个 bug 有 repro steps - 尽量脚本化复现 - 收集 screenshot / logs / traces / failing tests - 修复后增加 regression guard - 文档记录 root cause

关键原则： - 没有可复现路径的 bug，很难高质量交给 agent 持续处理

4.13 Agent-First 产品开发模式

适用： - 绿地项目 - 要求快速试错 - 团队愿意把“写代码”外包给 agent

规范： - 人定义产品方向与 acceptance criteria - agent 生成 scaffold、功能、测试、文档 - 人判断优先级与 tradeoff - 所有长期知识都沉淀回 repo

额外要求： - 比普通项目更重视 architecture invariants - 更重视 docs freshness - 更重视观测性

4.14 安全与权限规范

4.14.1 最小权限原则

agent 拥有什么权限，应与任务匹配： - 只读分析 - workspace write - network access - external side effects

4.14.2 对外副作用要更谨慎

比如： - 发消息 - 发邮件 - 改线上配置 - 发 PR 到外部仓库 - 访问生产环境

这些最好： - 需要明确审批 - 有操作审计 - 有回滚路径

4.14.3 secrets 绝不靠“默认知道”

• secrets 不写入 docs / repo
• 用明确的密钥管理
• 用受控环境注入
• runbook 只写如何获取，不直接写密钥值

4.14.4 网络访问是能力，不是默认福利

因为联网会引入 prompt injection、供应链风险、环境污染。 应： - 明确允许范围 - 尽量最小化 - 在需要时开启，而不是默认全开

4.15 人类角色的再定义

4.15.1 人的主要工作从“写”变成“设定”

人类越来越负责： - 目标拆解 - acceptance criteria - architecture boundaries - quality bar - rollback policy - priorities - escalation judgment

4.15.2 人最稀缺的不是 typing，而是 attention 和 judgment

这点 OpenAI 说得很透。 工程系统应围绕“节省人类注意力”设计，而不是围绕“让 agent 看起来很聪明”设计。

4.15.3 最有杠杆的工作，是把 judgment 编码进去

例如： - review 评论抽象成 lint - 常见 bug 转成 regression test - 经验写成 runbook - 审美偏好写成 naming / layering / file-size invariants

4.16 反模式清单（Anti-Patterns）

反模式 1：巨型 AGENTS.md

结果： - 上下文拥堵 - 规则腐烂 - agent 不知道什么最重要

反模式 2：只给高层 prompt，不给工件

结果： - 每次都从零理解 - 容易 one-shot - 容易误判完成

反模式 3：没有固定启动路径

结果： - 每个 agent 都在猜怎么启动项目 - 大量浪费在环境摩擦上

反模式 4：没有 progress / handoff

结果： - 上下班之间信息断裂 - 重复劳动 - broken state 无人负责

反模式 5：没有 feature list / completion definition

结果： - agent 看到一半进展就宣布 done - scope silently drifts

反模式 6：测试只靠 unit test，不做 e2e / UI 验证

结果： - 代码看起来对，实际体验坏了

反模式 7：依赖人脑里的架构共识

结果： - agent 永远学不会 - 新 agent 与新员工一样不断踩坑

反模式 8：人工周会大扫除，而没有后台治理机制

结果： - AI slop 持续复利 - 人被清洁劳动吞噬

反模式 9：用“再试一次更强模型”代替修 harness

结果： - 短期似乎有效 - 长期系统性问题还在

反模式 10：过度管 style，反而忽视 architecture 和 verification

agent 时代，真正需要被严控的是： - correctness - boundaries - reproducibility - observability - maintainability

而不是把所有精力都花在低价值风格争执上。

4.17 建设顺序建议（Implementation Roadmap）

如果一个团队现在几乎没有 harness，可以这样起步：

第 0 阶段：先别追求“全自动”

先建立可读、可验、可恢复的基础设施。

第 1 阶段：补最小接力工件

• AGENTS.md
• init.sh
• progress.md
• feature_list.json

第 2 阶段：补知识地图

• docs/index.md
• docs/architecture/
• docs/runbooks/
• docs/product/

第 3 阶段：补计划体系

• plans/active/
• plans/done/
• plans/templates/

第 4 阶段：补机械化约束

• lint
• CI
• structural tests
• file size / naming / layering / boundary parsing checks

第 5 阶段：补观测与 UI 闭环

• browser automation
• screenshots / videos
• logs / metrics / traces
• repro scripts

第 6 阶段：补后台治理

• doc gardening
• cleanup agents
• drift scans
• quality scoring

4.18 一份可执行的检查清单（Checklist）

仓库入口

• [ ] AGENTS.md 是否短且稳定？
• [ ] docs/index.md 是否存在并指向关键知识？
• [ ] 关键启动路径是否清晰？

连续性

• [ ] 是否有 progress.md？
• [ ] 是否有 feature_list.json？
• [ ] 是否有 init.sh？
• [ ] 是否要求每次 clean commit？

知识系统

• [ ] 架构原则是否入库？
• [ ] 产品行为是否入库？
• [ ] runbook 是否存在？
• [ ] 关键决策是否可追溯？

计划体系

• [ ] 复杂任务是否有 plan？
• [ ] plan 是否有 verification 和 rollback？
• [ ] active / done plans 是否区分？

验证闭环

• [ ] smoke test 是否稳定？
• [ ] e2e 是否覆盖关键旅程？
• [ ] UI 是否可被 agent 检查？
• [ ] CI 输出是否机器可读？

观测性

• [ ] 是否有 structured logs？
• [ ] 是否有关键 metrics？
• [ ] 是否有 traces / correlation id？
• [ ] agent 是否能读取这些信息？

约束系统

• [ ] layering 是否可被检查？
• [ ] boundary parsing 是否可被检查？
• [ ] file size / naming / schema rules 是否明确？
• [ ] lint 错误是否包含 remediation hints？

治理

• [ ] 是否定期做 doc gardening？
• [ ] 是否有 cleanup / refactor agent？
• [ ] 是否有 drift detection？
• [ ] 是否持续偿还技术债？

五、最后再收束一次：核心思想到底是什么

如果只让我把这三篇内容——Anthropic、OpenAI、George——压缩成一句话，那就是：

Harness engineering = 把软件工程从“人工直接操作对象”升级成“人设计控制系统、agent 在系统中闭环执行”的工程范式。

Anthropic 告诉我们： - 智能体要能接力，必须有外置记忆与明确交接协议。

OpenAI 告诉我们： - 智能体要能规模化地产出，必须让仓库、文档、测试、观测与约束都变成 agent 可读、可执行、可验证的控制面。

George 告诉我们： - 这其实不是孤立技巧，而是控制论在软件工程中的一次上移： - 以前人手动拧阀门， - 现在人设计调速器； - 以前人手动运维服务， - 现在人定义 desired state 和 controller； - 以前人逐行写代码， - 现在人设计 harness，agent 在其中写、测、修、验、清理。

所以，未来真正稀缺的能力，不只是会用模型，也不是会背几个 CLI 参数，而是：

• 会不会设计知识地图
• 会不会定义验收标准
• 会不会构建反馈回路
• 会不会把工程 taste 编码成约束
• 会不会让系统持续可恢复、可治理、可扩展

换句话说：

智能体时代最值钱的工程能力，不是 prompt engineering，而是 harness engineering。