本文作者杜学友引言本文核心观点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. 主会话只听 dispatcherdispatcher 读 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 推理中外置到确定性基础设施。不能依赖模型“记住”该执行哪个步骤——门禁必须是确定性代码独立于上下文窗口fail-closed默认拒绝只放行显式允许的操作。这回答了一个根本问题如果 AI 不听话了怎么办答案不是让它更聪明应该是不管听不听话越界就被拦住。贯穿五层的一条主线19 节点链 × G1–G8 门禁 × intent×risk 动态裁剪。完整的 19 节点是一条标准研发链路需求评审→需求确认→方案设计→方案确认→Pre-Mortem→实施计划→验收标准确认 →拉变更→建分支→建 worktree→开发→编译→单测→ATDD→证据链 →部署预发→接口测试→上线确认→验收报告但绝不是每个需求都走全 19 步——该走多重的流程由意图 × 风险动态裁剪决定外加一条最实用的硬规则——“改完必部署”只要检测到真实业务代码改动自动把部署预发、接口测试追加为必需节点堵死“改了代码、没验证就收工”。当前链路的边界诚实声明流程止步于预发部署 接口测试 验收报告onlineG8 生产上线节点不强制。原因是生产发布涉及灰度策略、流量切换、线上回归——目前这些动作的「出错成本」远高于让 AI 自主操作的「效率收益」所以由人兜底。下一步的明确目标AI 自主完成预发验证 → 触发生产发布 → 观测线上指标 → 产出线上验收报告把 G8 从「人工确认」进化为「AI 执行 人工兜底」。把这些拼起来一个 FEATURE/HIGH 需求在我的 harness 里实际是这样流转的主会话 → dispatcher(读 state.json返回下一步调谁)→ intent-classifier 判定意图×风险 → dispatcher → 三角色并行评审(业务/技术/质量)→ orchestrator 合成 → 我确认方案 → dispatcher →plan-generator 出实施计划 → dispatcher → developer 按 TDD 编码 → dispatcher → verifier 跑 G1–G8 门禁 → dispatcher → deployer 部署预发 → dispatcher → tester 接口测试 → 验收报告全程主会话没「思考」过任何业务细节它只是 dispatcher 指令的执行器每个 agent 从干净上下文启动、只装自己那一段的规则和输入。这就是「dispatcher 状态机 文件交接」在一次真实需求里的样子。03 打磨从「能用」到「好用」的关键几跳上面是成品。但它不是设计出来的是被现实一路逼出来的。回看整个演进过程是四个阶段、每一步都有一个“此路不通”的拐点第一阶段 · 拿来主义起点是开源。用 oh-my-claudecode、everything-claude-code 等社区项目的 OpenSpec 规范直接上手——别人总结好的 CLAUDE.md 模板、多 agent 示例、最佳实践合集。它帮我从「裸用 AI」跨进了「有章法地用 AI」但很快碰到天花板通用规范覆盖不了我的开发流程需求分析 技术方案 验收标准 开发 单元测试 项目环境预发流水线 自动化验证边界情况全靠临场补丁。触发词每次我要写的额外 prompt 比规范本身还长时就意味着该自己造了。第二阶段 · 重 prompt 约束于是我开始自建 harness。最初的思路极其朴素把所有流程规矩写进 CLAUDE.md让 AI 按步骤一步步走。需求分析怎么做、方案设计几步走、编码完必须跑单测、部署前必须合 master……全写成指令式 prompt。三天后崩了。 症状如下不听话——规则太多模型开始选择性遵守这次记得先写单测下次又跳过这次跑了编译验证下次忘了。上下文爆炸——所有规则常驻窗口留给实际代码的空间被挤压模型读完规则就没脑容量读代码。自我矛盾——规则间偶尔冲突比如快速修复走简化路径 vs “所有改动必须走评审”模型不知道听谁的开始编造折中方案。核心教训prompt 约束是说服不是强制。模型理解了规则不等于遵守了规则——你无法用更多的字来对抗概率性的遗忘。第三阶段 · 减负 分层加载至此问题的根因已经清晰我把「有状态的流程」硬塞进了「无状态的对话窗口」本质上是用错了工具。于是做了两件事给 harness “减负”把常驻 prompt 从“全流程指令手册”砍到只剩角色定义 触发规则压到 ≤8K。深度内容TDD 指南、Pre-Mortem 模板、对抗辩论规范全部移到 context/ 层只在进入对应阶段时才 Read 进来。整理三层加载链路常驻入口层 → 原子规则层 → 按需上下文层把上下文当预算管理而不是当草稿纸挥霍。这一步的效果立竿见影主会话不再被规则淹没模型终于有脑容量去理解代码了。但新问题在长程会话中暴露了——写了几百行代码、跑了几十次工具调用之后上下文被业务代码和工具输出逐渐填满规则虽然还在但已经被稀释到注意力衰减区。典型症状写完代码后忘记该走什么流程因为先跑单测再提交这条规则被几十屏代码输出挤到了模型看不见的位置。第四阶段 · Agent 调度编排最后一跳是认知上最大的转变不再约束模型你该怎么做而是让不同的 agent 各司其职、互相制衡。核心设计一个dispatcher流程驱动器作为大脑只负责算下一步该谁上场其他 agent 各管一段——三角色评审独立思考互不串味、developer 只管编码不管流程、verifier 只管检查不管实现。第二章描述的「笨主会话」原则在这里真正落地了。一次高强度全天重构验证了这个架构状态外置、决策收敛给 dispatcher即使单次会话崩了、上下文被压缩了状态不丢、流程能续。但 24 agent 也暴露了过度拆分的代价——每个 agent 的 system prompt 本身就是一个小型 CLAUDE.md规则指令占满上下文后留给实际任务的空间反而更少agent 间转交多、调试链路长、维护心智负担大。后续把 intent-classifier / debate-moderator / pre-mortem 等流程节点合并入主干 agent精简冗余的中间调度层在保留核心约束dispatcher 路由、职责隔离、状态外置、门禁阻断的前提下降低了协调成本和单 agent 规则密度。这就是第二章描述的当前架构。三条路我都走过为什么选文件交接而不是现成编排Claude Code 原生提供WorkflowJS 脚本编排和Agent Team消息驱动团队两种多 agent 机制我逐一试过后走了第三条路。核心原因harness 本质上是控制平面不是计算平面。Workflow 不行做控制平面——它的强项确实诱人确定性控制流循环/条件/扇出、高并行 pipeline() / parallel()、schema 强校验。乍一看和 SOP 工序链天然匹配。但实际跑通后暴露了三个硬伤①超时机制——Bash 命令默认 120s 超时最大 10 分钟Workflow 子 agent 本身也有执行时长上限一个 TDD 全循环写测试→编译→修复→重编译或 Maven 长构建经常被静默杀死而你在脚本层拿到的只是一个 null 返回无法区分任务失败还是超时被杀②无 askUser 交互原语——我的 19 节点链有 6 个人工确认点Workflow 脚本内无法暂停等待用户决策③跨 session 不可续——同 session 内可 resumeFromRunId 恢复但 HIGH 需求可能跨 2-3 天换 session 后状态接不上。它的确定性控制流适合单阶段、无人工交互、可在超时窗口内完成的计算任务如三角色并行评审但做不了需要跨天、有人工门禁、单步可能耗时数十分钟的控制平面。Agent Team 不行——松散协调无确定性工序保证成员 idle 后靠消息唤醒、状态散落在 TaskList 中无统一 state.json中断后恢复靠推断、SendMessage 是通知不是阻断无法做到 hook 级硬围栏。它适合多人并行改多模块不适合严格工序链。最终选择dispatcher 状态机 文件系统交接agent A 写 phases/05-design.mdagent B 读它。三个硬优势①天然持久化——进程崩了文件还在跨天需求 Read state.json 即续②可审计——每步产物都是人可读的 markdowngit diff 一眼看清谁在哪步写了什么③强一致性——state-keeper 单写者hook 拦截其他写者 ajv schema 校验前置从架构层面消除多 agent 写冲突。代价同样真实每次 agent 切换需 Read 上一步产物~2-5K tokens IO 开销、调试链路跨多个 agent 的 transcript、并行能力受限于文件交接的序列化特性。结论三种机制正交互补。 Workflow 管计算平面高并行单阶段Team 管协作平面多人独立任务dispatcher 文件交接管控制平面有状态工序链 人工门禁 跨天续跑。我当前的实验方向正是混合编排dispatcher 管控制流Workflow 加速三角色评审等纯计算环节。尾声 · 评测驱动当我开始频繁改规范一个问题让我夜不能寐我改完了到底变好了还是变坏了这种感觉说不清、道不明——焦虑的产物是下一章的评测平台。真正推动架构演进的从来不是「想要更好」是「现在的做法已经崩了」。 每一阶段的切换都并非优化而是止损。四个阶段的核心转变只有一句话从「用更多的字约束 AI」到「用更好的结构约束 AI」。这一路踩的坑每一个都已固化成规则或修复——它们是这篇文章里最贵的部分04 评测把流程作为被测对象第三跳的产物是一套把 harness 本身当成被测软件的评测平台。它的设计原点是一句反常识的定位核心理念评测平台是评估者不是执行者。 它只检测被试 claude 是否走完了 harness 的每个节点产物在不在、门禁过没过而绝不替它去执行部署或测试。一旦平台开始帮忙干活它就失去了客观裁判的资格。平台按「用 harness 的三种姿势」分成三条互不串联的轨道评分引擎是整套平台的灵魂。 它用 100% Python 确定性逻辑、零 LLM 调用、3 次跑分 hash 完全一致的方式从 7 个维度给 harness 的每次执行打分。七维评分评什么、怎么评、为什么这样评设计这套评分体系时我参考了四个来源SWE-bench用测试通过率验证代码改动、AgentBench用工具调用效率衡量 agent、Anthropic Eval Guide双评分器对抗偏差、CMMI流程域成熟度。最终融合成 7 个维度每个维度都可以用一句话解释在检查什么为什么是确定性评分不用 LLM 评委很多人第一反应是「LLM 打分更懂语义、更准」。我的判断恰恰相反宁要可复现的「粗糙分」不要会漂移的「精准分」。 评测的唯一目的是驱动迭代——只有 3 次跑分完全一致才能回答这次改规范到底变好还是变坏。一个偶尔波动 ±5 分的 LLM 评委再精准也会让 A/B 对比彻底失去意义。两个权重最高的维度流程完整性 22% 代码正确性 22%怎么保证评分准确流程完整性不靠「模型说做了」要靠「产物文件在不在」——文件系统不会说谎。同时按 intent×risk 裁剪必需节点QUERY 不要求任何产物满分、BUG_FIX/LOW 只查 5 个节点、FEATURE/HIGH 查满 19 个。代码正确性是防注水的硬核用 amaven jdk 真编译、真跑单测。还会对比 evidence.json 的自报结果和真实编译结果计算诚实度差距honesty gap——AI 声称 G3 通过但编译其实挂了这个差距就会暴露。这里踩过一个反直觉的坑最初图干净给评测配了空的隔离 Maven 仓库结果依赖全解析失败、恒为 0 分换回共享本地 6.9G 的 ~/.m2 缓存离线复用才跑通。评测环境越“干净”反而越不真实。评测平台到底解决了什么这个问题可以浓缩为一句话回答把「改 harness 凭感觉」变成「改完有分、好坏可对比、回退有据」。以下是三个实证自进化闭环有了确定性分数harness 的自进化闭环才能转起来创建AI 生成 / fork→ 评测对比7 维 × 多 case→ 激活基线留备份可回退→ 收集弱项维度再优化。我甚至让 AI 拿好配置去改待优化配置生成候选版本——用 AI 优化约束 AI 的规则再用确定性分数验证优化是否有效。05 还能怎么提升诚实的代价与边界判断这套系统最大的风险不在于「不够准」在于「假装它覆盖了一切」。 所以比起“吹效果”更该把“欠账”摆上台面。除了这些明确的欠账调研中看到的业界前沿方向也值得关注结构化记忆层当前 harness 的经验三级进化lesson→pattern→instinct是手动管理的。VikingMemVLDB 2026, ByteDance证明了一个反直觉的发现——更少的 Token 留存 更智能的组织 全量保留16.82% Token 留存得分 75.80朴素 RAG 100% 留存仅 63.81。Sverklo 的双时态记忆每条记忆绑定 valid_from_sha / valid_until_sha更新时插入新行而非覆盖可以让 harness 精确回答「在 commit X 时 Agent 知道什么」。代码知识图谱对大型 Maven 多模块项目Agent 每次理解代码关系都要逐文件读取消耗宝贵上下文。Codebase-Memory-MCP 通过多轮 AST 分析构建持久化知识图谱13 节点类型、18 边类型Agent 可通过图查询获取调用链、依赖关系无需逐文件扫描——虽然其声称的「99.2% Token 减少」在对抗验证中被证伪但架构模式本身对AI Coding场景有价值值得在单模块上试点。编排形态 A/B 对比目前正在做v-agentwf-nodecompagent 编排vs v-dynwfdynamic workflow——两种 harness 形态由评测分数决定优劣不靠拍脑袋而由数据说话。能「用实验回答架构之争」这件事本身就是评测平台最大的价值。06 结语一个可迁移的模式这两个月最大的收获并非某个 agent 或某条规则反而是一个可以搬到别处的思维模式任何「能力够强但输出不稳定、且过程可观测」的 AI 工作流都可以被这样工程化——给它分层的约束、外置的状态、确定性的评分让每一次改动都能被证明是进步还是退步。它的边界也很清楚这个模式依赖「过程可观测」。 如果一个 AI 任务的中间产物无法落盘、无法检测比如纯创意生成这套打法就会失效而它的价值也会随模型进化而衰减——当模型强到能自我保证流程纪律的那天harness 就该功成身退。但那一天还没来。在此之前我们这些工程师的主场依然清晰——模型负责聪明我们负责让它守纪律。参考资料[1] VILA-Lab 对 Claude Code 的逆向工程https://github.com/VILA-Lab/Dive-into-Claude-Code[2] Latent Space 播客https://www.latent.space/p/cognition[3] The Age of Async Agents — Cognition’s Walden Yan OpenInspect’s Cole Murrayhttps://www.latent.space/p/cognition?spmata.21736010.0.0.7d863401Hmvk0V[4] Lost in the Middle: How Language Models Use Long Contextshttps://arxiv.org/abs/2307.03172[5] RULER: What’s the Real Context Size of Your Long-Context Language Models?https://arxiv.org/abs/2404.06654[6] Scaling Laws for Agent Harnesses via Effective Feedback Computehttps://arxiv.org/abs/2605.29682[7] sd0x-dev-flowhttps://github.com/sd0xdev/sd0x-dev-flow[8] VikingMemVLDB 2026, ByteDancehttps://arxiv.org/html/2605.29640v1[9] Sverklohttps://github.com/sverklo/sverklo?spmata.21736010.0.0.7d863401Hmvk0V[10] Codebase-Memory-MCPhttps://github.com/DeusData/codebase-memory-mcp
