AI 不缺智商缺纪律:一场 Harness 工程化实践


引言

本文核心观点:AI Coding 的瓶颈正从「模型能力」转移到「流程工程」——模型已经足够聪明,但不稳定,而稳定性必须由外部框架供给。

读完你能带走:一套可抄的 harness 分层结构、一个「把流程当被测对象」的评测方法、4 条用代价换来的踩坑教训,以及一个能迁移到任何 AI 工作流的工程化模式。

我曾经用一个不断膨胀的 CLAUDE.md 解决 AI “不守纪律”的问题——把所有规矩写进去:先写单测、部署前评审、提交前合 master。它确实管用了三天。 然后问题以更严重的形式回来了:规则多到“撑爆”上下文,模型读完规则就没“脑容量”读代码,于是它开始遗忘、串味、自我矛盾。

那一刻我意识到:对付 AI 的不确定性,堆 prompt 是负债,做框架才是资产。 这篇文章就是这套框架(harness)两个月的演进复盘。

01
harness 是什么,它到底解决什么

harness = 把「AI 该怎么干活」固化成可执行、可约束、可评测的工程框架。 它和“写更好的 prompt”有本质区别:prompt 是一次性的说服,harness 是结构性的约束。模型供给智商,harness 供给纪律。

用过 AI 编码的人大概率遇到过这三个痛点:

这些痛点不是因为个人运气差,它们存在结构性的技术根因。VILA-Lab 对 Claude Code 的逆向工程揭示:Claude Code 的记忆完全基于文件系统(CLAUDE.md + JSONL 日志),没有向量数据库、没有 Embedding。上下文管理靠一条 5 层渐进式压缩管线——从裁剪低优先级提示、截断工具输出,一直到最后手段的全量模型摘要(Auto-Compact),流程状态细节恰恰会在这一层被丢失。

Devin 的 CPO 在 Latent Space 播客中坦言:当记忆达到数千条时,如何在正确的时机检索到正确的记忆——“尚未解决”。

Agent 「遗忘」不是 bug,是当前架构的必然代价。 遗忘有三重根因:压缩丢失(Auto-Compact 省略“看似不重要”的流程步骤)、检索失败(记忆文件在但没被加载进上下文)、指令遵循失败(信息都在但模型仍然跳步)。

harness 的三层设计(规则外置、状态持久化、门禁阻断)恰好对应这三个根因,逐一堵漏。

02
搭建:我的 harness 长什么样

这是全文重点。我的 ~/.claude 不是一堆零散配置,而是一个三层加载模型,核心设计思想只有一句:把上下文当预算来管理。

判断:主会话的上下文是最贵的资源,不是免费的草稿纸。 所以分层的唯一标准不是"按功能分类",而是"按何时被读取"——常驻的极小,深的按需加载。

下面逐层讲清楚:每层放什么、解决什么、付出什么代价。

2.1 常驻入口层:CLAUDE.md + CLAUDE.local.md

放角色、代码偏好、流程触发规则、G1–G8 门禁速查。关键设计是 CLAUDE.local.md 自包含、不依赖全局 @import:新项目接入只需拷一份模版进去就能独立运作。

  • 解决:每个项目的流程规范彼此隔离、互不串味。

  • 效果:主会话常驻上下文压到 ≤8K,把宝贵窗口留给真正的代码。

2.2 原子规则层:rules/(7 个)

每个规则单一职责、可被按需引用。它们的本质,是把踩过的坑固化成强制约束:

每条规则都是一次事故的墓志铭。 坑只踩一次,之后由规则兜底——这是 harness 最朴素也最值钱的复利。

2.3 角色 Agent 层:agents/

这是全套框架的发动机,把一个“全能主会话”拆成一条职责清晰的流水线:

  • 流程调度:dispatcher 读 state.json + workflow.yaml,决定下一步该调谁——交通警察,只管路由不管业务。

  • 评审合成:orchestrator 读三角色写入 phases/*.md 的观点,合成结论并向用户确认——会议秘书,只管合成不管调度。

  • 三角色评审:requirement-analyst(业务)/ tech-architect(技术)/ quality-guardian(质量),各写各的观点段,互不污染。

  • 流程执行:plan-generator → developer → verifier → deployer → tester,从方案到验收一步一岗。

判断:主会话应该退化成一个「什么都不想、只执行 dispatcher 指令」的纯执行器。 这是反直觉的——我们本能地想让主模型更全能;但全能恰恰是污染之源。主会话不是能力不足,而是职责收窄,像微服务里的 thin controller,不是它不行,是它不该管。这个思路并非独创,Devin 从第一天就做了“脑机分离”:推理(“大脑”)在沙箱外执行,执行环境(“机器”)无权访问大脑状态。Cognition 的评价是“更好的架构”,代价是状态管理更复杂。

我的 harness 走了一条更轻量的路:不隔离进程,转而通过 agent 职责隔离 + 文件交接达到类似效果。

按照用途分为以下四类:

真正需要警惕的不是「agent 多」,是「agent 间耦合多」。 输入输出是清晰的文件/JSON、不需要会话协商,数量就不是问题。

这套“薄主会话”靠三条铁律落地:

1. 主会话只听 dispatcher:dispatcher 读 state.json 返回"下一步调谁",主会话照做,禁止自己 Read phases/*.md / evidence.json2. 职责隔离:dispatcher 只管路由、orchestrator 只管合成、developer 只管编码、verifier 只管检查,每个 agent 的可用工具严格受限3. 上下文 ≤8K:主会话只加载 CLAUDE.md + 触发规则 + 最近一条 dispatcher 指令

它的代价必须诚实讲清,详见下方表格。

2.4 按需上下文层:context/(10 个)

完整流程详情、Pre-Mortem 模板、对抗辩论模板、证据链规范、TDD/ATDD 指南、记忆进化机制全放这层,只在进入对应阶段时才被 Read。常驻层因此始终精简,深度内容像弹药一样“打仗时才搬上来”。

这不是凭感觉。LLM 注意力呈 U 型分布,中部信息准确率显著下降(Stanford "Lost in the Middle", TACL 2024);声称支持 32K+ 的模型仅半数能在该长度保持可靠性能(NVIDIA RULER)。

设计原则:上下文不是越大越好的「免费缓冲区」,是需要精心管理的稀缺资源。 每份 context 只含该阶段所需最小集,用完即释放,不占后续窗口。代价是依赖元数据质量——context 文件描述写得模糊就会在该加载时漏加载,对策是 orchestrator 按阶段维护强制 Read 清单。

2.5 执行支撑层:skills/(22 个)+ commands/(12 个)+ evals/

  • skills/(22 个):把内部 CLI 和研发工具链封装成 AI 可调用的能力。最核心的是 ubase 全家桶:一句“帮我看下 wrate 最近半小时的日志”就能自动拼 SLS 查询、做时间窗口换算、把命中结果聚类成异常摘要,而不是把原始日志全量灌回上下文。还有 dev1-5 需求开发全链路、hsf-workflow 接口测试流程、setup-change-env 一键建变更等。

  • commands/(12 个):slash 命令入口。/init-harness 一键接入新项目、/harness-audit 体检当前配置健康度、/learn 把踩坑经验沉淀成规则。

  • 经验三级进化(auto-learn 规则驱动):这是 harness “越用越聪明”的核心机制。以 mvn -am 卡死 为例——第一次踩坑写成 lesson(单次记录);第二次在不同项目又遇到,归纳为 pattern(“Mac + system-scope 依赖 = 禁用 -am”);第三次验证后晋升 instinct,自动注入所有新项目的 build.md 规则。每一级晋升都需人工确认,防止错误经验扩散。

2.6 稳定性支点:eval 检测 + hook 拦截

以上五层定义了「该怎么做」,但如果没人检查「有没有做到」,一切约束都是纸上谈兵。因此,让 harness 真正稳定的不是规则本身,是验证机制。

这一判断有最新研究支撑,arxiv 2605.29682 的核心发现指出,原始 token 消耗和工具调用仅解释 agent 成功率方差的 R²=0.33~0.42,而验证反馈质量(Effective Feedback Compute)达到 R²=0.94~0.99。换句话说:决定 AI 干活靠不靠谱的并非「给它多少预算」,而是「检查做得多好」。

我的 harness 里,这一“检查层”由两个机制撑起:

  • G1–G8 门禁墙(eval 式硬校验):每个门禁是确定性的 Python 函数,检查产物存不存在、编译过不过、单测通没通。verifier agent 跑完后写 phases/verification.json,任一 gate FAIL 则流程退回 DEVELOPING——**不是"建议",是"阻断"。

  • hook 拦截(运行时硬约束):Claude Code 的 hook 机制在工具调用执行前拦截。我用它做两件事:① 状态文件写操作只允许编排层 agent 触发(其他绕过直接 reject);② 危险操作(git push --force、rm -rf)弹确认。hook 不是事后审计,是实时围栏。

这套「门禁外置」的思路正在成为业界共识。sd0x-dev-flow 将其总结为四个关键词:**"hook-enforced dual review, state-machine gates that survive context compaction, and fail-closed safety"**——注意"survive context compaction"这个措辞,它直接针对的就是 Claude Code Auto-Compact 阶段丢失流程状态的问题。Apache Burr(已进入 Apache 基金会)则把这个模式做成了通用框架:每个 Agent 决策表达为状态机节点 + 可插拔持久化 + 实时追踪 UI。

核心原则:流程强制执行必须从 LLM 推理中外置到确…

— 以上为试看内容(约 40%),开通会员后阅读全文 —