AI 不缺智商缺纪律：我的 Harness 工程化实践

核心判断

AI Coding 的瓶颈正从"模型能力"转移到"流程工程"。模型已经足够聪明，但不稳定，稳定性必须由外部框架供给。prompt 是一次性的说服，harness 是结构性的约束——模型供给智商，harness 供给纪律。

作者曾用不断膨胀的 CLAUDE.md 解决 AI "不守纪律"的问题，把所有规矩写进去。管用了三天后，规则多到撑爆上下文，模型读完规则就没"脑容量"读代码，开始遗忘、串味、自我矛盾。结论：对付 AI 的不确定性，堆 prompt 是负债，做框架才是资产。

遗忘不是 bug，是架构的必然代价

Claude Code 的记忆完全基于文件系统（CLAUDE.md + JSONL 日志），没有向量数据库、没有 Embedding。上下文管理靠 5 层渐进式压缩管线，流程状态细节恰好在最后的 Auto-Compact 阶段被丢失。Devin CPO 也坦承：当记忆达到数千条时，如何在正确时机检索到正确记忆——"尚未解决"。

遗忘有三重根因：

• 压缩丢失：Auto-Compact 省略"看似不重要"的流程步骤
• 检索失败：记忆文件在但没被加载进上下文
• 指令遵循失败：信息都在但模型仍然跳步

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

harness 三层加载架构

核心设计思想：把上下文当预算来管理。分层的唯一标准不是"按功能分类"，而是"按何时被读取"——常驻的极小，深的按需加载。

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

放角色、代码偏好、流程触发规则、G1–G8 门禁速查。关键设计是 CLAUDE.local.md 自包含、不依赖全局 @import——新项目接入只需拷一份模版进去就能独立运作。主会话常驻上下文压到 ≤8K，把宝贵窗口留给真正的代码。

2.2 原子规则层：rules/（7 个）

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

• build.md：禁用 mvn -am，只编译单模块（-am 触发全量解析卡死）
• branch-hygiene.md：提预发前必须先合 master（多分支集成构建报"找不到符号"）
• code-search.md：禁 Grep 搜 Java 结构、禁 LSP，强制走 kbase（符号搜索误命中、上下文浪费）

每条规则都是一次事故的墓志铭。坑只踩一次，之后由规则兜底——这是 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 的"脑机分离"思路一致，但走了一条更轻量的路：不隔离进程，而是通过 agent 职责隔离 + 文件交接达到类似效果。

"薄主会话"靠三条铁律落地：

1. 主会话只听 dispatcher，禁止自己 Read phases/*.md / evidence.json
2. 职责隔离，每个 agent 的可用工具严格受限（developer 有 Edit/Bash，verifier 只有 Read/Bash）
3. 上下文 ≤8K，主会话只加载 CLAUDE.md + 触发规则 + 最近一条 dispatcher 指令

2.4 按需上下文层：context/（10 个）

完整流程详情、Pre-Mortem 模板、对抗辩论模板、证据链规范、TDD/ATDD 指南——只在进入对应阶段时才被 Read。LLM 注意力呈 U 型分布（"Lost in the Middle"），声称支持 32K+ 的模型仅半数能在该长度保持可靠性能。每份 context 只含该阶段所需最小集，用完即释放。

2.5 执行支撑层：skills/（22 个）+ commands/（12 个）+ evals/

• skills/ 封装内部 CLI 和研发工具链为 AI 可调用能力，最核心的是 ubase 全家桶
• commands/ 提供 slash 命令入口：/init-harness 一键接入新项目、/harness-audit 体检配置健康度、/learn 沉淀踩坑经验
• 经验三级进化：lesson（单次记录）→ pattern（归纳规则）→ instinct（自动注入所有新项目），每级晋升需人工确认

稳定性支点：门禁 + hook 拦截

让 harness 真正稳定的不是规则本身，而是验证机制。arxiv 研究发现：原始 token 消耗仅解释 agent 成功率方差的 R²=0.330.42，而验证反馈质量达到 R²=0.940.99——决定 AI 靠不靠谱的不是"给多少预算"，而是"检查做得多好"。

• G1–G8 门禁墙：确定性 Python 函数，检查产物存不存在、编译过不过、单测通没通。任一 gate FAIL 则流程退回——不是"建议"，是"阻断"
• hook 拦截：工具调用执行前实时拦截。状态文件写操作只允许编排层 agent 触发，危险操作弹确认

核心原则：流程强制执行必须从 LLM 推理中外置到确定性基础设施。不能依赖模型"记住"该执行哪个步骤——门禁必须是确定性代码，独立于上下文窗口，fail-closed。

19 节点链 × intent×risk 动态裁剪

完整研发链路 19 节点：需求评审→需求确认→方案设计→方案确认→Pre-Mortem→实施计划→验收标准确认→拉变更→建分支→建 worktree→开发→编译→单测→ATDD→证据链→部署预发→接口测试→上线确认→验收报告。

但不是每个需求都走全 19 步：

• QUERY/NA：0 个必需节点
• BUG_FIX/LOW：FAST_PATH，开发→编译→单测→证据→报告
• FEATURE/MEDIUM：加方案设计、对抗辩论、TDD
• FEATURE/HIGH：19 节点拉满 + ADR 架构决策记录

外加硬规则"改完必部署"：检测到真实业务代码改动，自动追加部署预发和接口测试节点。

演进四阶段：每一步都是止损

1. 拿来主义：用社区项目 OpenSpec 规范上手，通用规范覆盖不了定制流程
2. 重 prompt 约束：所有规矩写进 CLAUDE.md，三天后崩了——规则太多导致选择性遵守、上下文爆炸、自我矛盾。教训：prompt 约束是说服不是强制
3. 减负 + 分层加载：常驻 prompt 砍到 ≤8K，深度内容移到 context/ 层按需加载
4. Agent 调度编排：不再约束模型"该怎么做"，而是让不同 agent 各司其职、互相制衡。24 agent 曾暴露过度拆分的代价，后续精简冗余中间调度层

关于编排选型：Claude Code 原生 Workflow 适合计算平面（高并行单阶段），Agent Team 适合协作平面（多人独立任务），dispatcher 状态机 + 文件交接适合控制平面（有状态工序链 + 人工门禁 + 跨天续跑）。文件交接的硬优势：天然持久化、可审计、强一致性。

评测：把流程当被测对象

核心理念：评测平台是评估者，不是执行者——只检测 harness 每个节点是否走完，绝不替它执行。

七维评分体系（100% Python 确定性逻辑，零 LLM 调用）：

• 流程完整性 22%：产物文件是否存在 + 预设规则命中率
• 代码正确性 22%：真跑 mvn compile + mvn test，编译失败 = 0 分
• 接口验收 18%：真跑 ATDD 测试 + 检查接口测试证据
• 产物质量 15%：结构检查 + 反注水检测
• 效率 10%：耗时 + 成本 USD
• 安全合规 8%：扫描 transcript 是否违反 harness 规则
• 迭代能力 5%：检测 BUILD FAILURE → BUILD SUCCESS 的恢复链条

为什么不用 LLM 评委？宁要可复现的"粗糙分"，不要会漂移的"精准分"。只有 3 次跑分完全一致，才能回答"这次改规范到底变好还是变坏"。

诚实的代价与边界

明确欠账：

• 产物质量只做结构检查，判不了方案设计优劣（拟引 LLM 评委 + 多次投票取中位数）
• eval 跑批是单机单进程，需容器化部署 + 任务持久化
• 评测集仅 5 个 case，长尾覆盖不足

可迁移的模式

任何"能力够强但输出不稳定、且过程可观测"的 AI 工作流，都可以被这样工程化——分层约束、外置状态、确定性评分。边界在于依赖"过程可观测"：如果中间产物无法落盘检测（如纯创意生成），这套打法失效。价值也会随模型进化衰减——当模型强到能自我保证流程纪律的那天，harness 就该功成身退。

但那一天还没来。在此之前：模型负责聪明，我们负责让它守纪律。