Harness工程与AGENTS-md实践

“Agent = Model + Harness”的约束工程——与本库自身的 AGENTS.md 宪法互为印证。

Harness 三问

Harness（系统提示词+工具+文件系统+沙箱+编排+检查机制）回答：AI 在哪干活/用什么干活/怎么知道干得对不对。Mitchell Hashimoto 定义：Agent 每犯一个错，就设计一个机制让它永不再犯同类错。

关键实证数据

指令遵从率：CLAUDE.md 约 20% vs PreToolUse Hook 100%（wow-harness 实测）——能自动化的检查 > 写在 AGENTS.md > 口头约定；审查 Agent 的工具 schema 直接删除 Edit/Write（物理不可写）；
OpenAI Codex 百万行实践：3 工程师 5 个月零手写；AGENTS.md 精简到约 100 行只做”目录”细节入 docs/（OpenAI 自家仓库有 88 个 AGENTS.md）；专设 doc-gardening Agent 定期修过时文档；花数小时重写 Linter 报错信息使其面向 AI 可读；
Anthropic 生成/评估分离：评估器实际操作页面按四维打分 5-15 轮；成本对比：单 AI 20 分钟 $9 产出不可用 vs 完整 Harness 6 小时$ 200 交付可玩产品；
上下文衰减：即使标称 1M token，性能衰减约在 25.6 万 token 处开始；
AGENTS.md 标准史：2025-05 AMP 提 AGENT.md → OpenAI 买下 agents.md 域名定复数 → Linux Foundation 托管，2026 初 GitHub 6 万+项目采用；各工具对照（CLAUDE.md/.cursorrules/copilot-instructions/GEMINI.md/.clinerules），ln -s AGENTS.md CLAUDE.md 兼容。

编写原则（Map not Manual）

≤200 行；只直写”不知道就会写错代码”的必要信息和硬性规则，其余放 docs/ 放链接；bad case 驱动迭代；
curl 验证规范（防 shell 兼容问题）：每个 curl 独立执行禁串联；输出写 /tmp 临时文件再由 python3 独立解析；
lint 错误信息三段式：WHAT（违了什么）+WHY（为什么禁）+HOW（怎么修），AI 可直接按 HOW 自修；
闭源组件用 git submodule 引源码（“源码永不过时，就是最准确的文档”）+ ref-*.md 架构地图。

渐进式 Spec 三铁律

No Spec No Code / Spec is Truth / Reverse Sync（先修文档再修代码）；70% 需求 ≤5 人日不走全流程；编排层（强模型决策）+执行层（廉价模型编码）两层；HARD-GATE：spec+tasks 确认前禁止编码；每个 task 必须展示编译/测试输出证据；对话轮次 20→3-5 轮。

人机协作自由度曲线

调研=中（自由探索但须给证据）、方案设计=高、规划=低（精确到文件路径+函数签名）、执行=零（Plan 是合同 AI 是打印机）、验收=中。三大错误：讨论与命令混谈、阶段产出搞混、自由度给反。

架构治理三层防线（按确定性分配工具）

import-linter 管依赖方向（100% 确定，12% 检查项）→ Semgrep 管 AST 模式（>95%，29%）→ AI Review 管语义（~80%，58%）；组合 ~8h 投入、$0.03/PR、覆盖 95%；AI 的 Blocker 不直接阻塞需人工确认；每月把 AI 高频判断下沉为 Semgrep 规则（“从 AI 每次判断变成机器自动拦截”）。

增补：AGENTS.md 里的模型分工规则（#795，2026-10-04）

双速 Agent（Codex 深思 + Jev 快断）的关键一步不是”能调用 Jev”，而是把分工规则写进 AGENTS.md，让 Agent 知道什么时候该调用。可直接抄的规则结构：

Prefer Jev for: yes/no 检查、已知列表里选一项、测试 pass/fail 判断、命令风险分级、工具选择、retry/continue/stop 决策、置信度打分、校验门禁；
Use Codex directly for: 写代码、解释概念、复杂 debug、架构设计、生成文档、多步推理任务；
Escalation: Jev 不确定或返回升级信号时，转回 Codex 推理继续任务。

配套判断框架：“什么任务根本不值得动用一次复杂推理”——Agent 浪费能力的典型方式是让会思考的模型反复做不需要思考的事（老板自己收快递）。命令风险 Gate 三档分流是安全闸门样板：低风险自动执行 / 中风险询问用户 / 高风险阻止。演进叙事：Prompt Engineering → Context Engineering → Harness Engineering。

增补：HelixHarness——企业级 Harness 开源样本（#832，2026-11-02）

滴滴金融 2026-10-29 开源（github.com/didi/helixharness，前身内部 OpenHarness，已在滴滴 10 余部门、上百业务模块推广）。定位：在现有 Coding Agent 之上搭工程化基础设施，解决 AI Coding 从个人提效走向团队规模化落地的四大痛点：工程化支撑不足（AI 难掌握项目架构/业务逻辑/团队规范）、过程数据不可观测（工具调用/代码修改/返工路径无全链路记录）、框架迭代缺统一评测、团队适配成本高。

与本章既有知识的对应：

四层结构化工程上下文：Knowledge（业务知识与技术架构）/ Harness（工程约束与资源索引）/ Specs（需求规格与验收标准）/ Hooks（自动化质量检查）——与本页”渐进式 Spec”及 AGENTS.md 实践同源，区别是它把隐性知识”与业务代码共同维护”为团队资产（标准化目录结构）；
可观测-评测-自进化闭环：全链路过程观测积累数据 → 形成优化假设 → 候选修改统一评测+风险验证 → 受控落地——“框架的每一次优化都有数据依据，避免纯经验判断”，与 AGENTS.md 的”每月把 AI 高频判断下沉为机器规则”同一思想的平台化版本；
标准化端到端工作流（项目初始化→方案设计→开发执行→结果归档，统一命令驱动）。

原始素材（重点篇目）

Harness 三问
AGENTS.md 方法
wow-harness 数据
渐进式 Spec
三层防线
#795 双速 Agent 与 AGENTS.md 分工规则
#832 HelixHarness 开源
Harness 设计 UI 测试

沉淀园

探索