# 我花了一天，给 AI Coding Agent 搭了一个 Mini Harness

最近在折腾 AI Coding AgentClaude Code / Cursor / 自定义 Agent时我发现一个很常见的问题**模型会写代码但不一定会“按流程工作”。**它可能- 需求还没对齐直接开始改代码- 改着改着 scope creep顺手改了别的模块- 一次改 8 个文件最后根本不知道哪一步坏了- 自己说“完成了”但没有可验证的状态- 长会话后上下文压缩开始“假装记得自己干过什么”我慢慢意识到问题不是模型不会写代码而是 **缺一个 Harness约束层**。于是我尝试给 AI Agent 搭了一个 **Mini Harness**。它不负责生成代码而是负责 把 Agent 约束在一个可恢复、可审计、可推进的轨道里运行。---# 什么是 Harness很多人第一次听到 Harness会想到- Test Harness- Browser Harness- Runtime Harness但在 AI Agent 里我更喜欢把它理解成 Harness Agent 的运行约束层Execution Constraint Layer它不是模型本身。而是**限制模型什么时候能做事、能做什么、做完怎么验证。**一句话**Prompt 负责思考Harness 负责约束。**---# 为什么 Prompt 不够一开始我也尝试过直接写超长 Prompt。比如- 不允许跳步骤- 每次只能改一个任务- 不能改计划外文件- 高风险任务必须暂停- 做完要验证- 要记录状态结果很快发现问题。Prompt 再长本质还是**soft rule软约束**模型可以“知道”但不一定“遵守”。尤其长会话后上下文压缩、任务切换、状态漂移问题会越来越明显。所以我开始拆**Prompt ≠ Harness**---# 我设计的 Mini Harness核心结构很简单textHARNESS.md # 协议说明specstate.yaml # 全局状态机ledger.yaml # 任务队列audit.log # 审计日志git commits # checkpoint它本质是一个**Stateful Checkpointed Agent Harness**---# 第一层状态机FSM我先把 Agent 强制放进状态机里。textNONE↓RESTATE↓PLAN↓EXECUTE↓DONE外加textBYPASS用于小改动逃逸。---## RESTATE需求对齐禁止 Agent 直接干活。先复述- 需求是什么- 范围内是什么- 范围外是什么- 隐性假设- 验收标准目的防止 AI 一上来 scope creep。---## PLAN拆任务写入ledger.yamlyamltasks:- id: T1title: Refactor auth middlewarefiles:- src/auth.tsrisk: mediumstatus: proposed每个任务- 有 DoD- 有文件范围- 有依赖- 有风险等级Agent 不能跳过。---## EXECUTE一次一个任务只允许处理yamlstatus: in_progress那一条。防止Agent 一次乱改一堆文件。这其实是**single-flight execution**---# 第二层RALPH MODE自动串行执行后来我发现每个 task 都让用户回复 next 很烦。于是加了 auto mode。textPLAN↓ok auto↓EXECUTE(auto)Agent 自动循环textload taskeditverifycommitadvancerepeat直到- DoD 失败- 风险高- 越界- 文件超白名单- 用户 stop这部分开始有点像真正的 Coding Agent。---# 第三层Scope Guard这是我觉得最关键的一层。Agent 最大问题不是写错代码。而是**写太多。**所以我加yamlfiles:- src/auth.ts任务执行时只能改这些文件。超出直接 Boundary Intercept。本质**filesystem scope isolation**---# 第四层Checkpoint每个任务通过 DoD 后bashgit add -Agit commit -m harness: T2 update auth为什么一定要 commit因为它解决三个问题## 1. 可回滚坏了直接回退。## 2. 可恢复新 session 看 git log 就知道做到哪。## 3. 可审计一个 task 一个 commit。---# 第五层State RehydrationLLM 最大的问题之一长会话后会“假装记得”。所以我禁止 Agent 依赖纯会话历史。每次任务开始必须重读textstate.yamlledger.yamlgit log重新恢复状态。这叫**state rehydration**---# 我后来发现最大的坑其实不是 Agent而是 Token一开始我把整个 HARNESS.md 塞进 Prompt。很快发现太胖了。因为混了- protocol- examples- docs- rationale- runtime于是我拆成三层。---# 正确的 Harness 结构重 Spec轻 Runtime## Layer 1Spec长文档HARNESS.md负责协议说明。不是每轮都喂模型。---## Layer 2State磁盘yamlcurrent_stage: EXECUTEactive_task_id: T2execution_mode: auto只存真实状态。---## Layer 3Runtime最小注入每轮只注入yamlstage: EXECUTEtask: T2rules:- only modify task.files- DoD must pass- high risk stop- emit state diff控制在几百 token。而不是几千 token。---# 它算真正的 Harness 吗我的答案是**算。**但更准确说它不是 Runtime Harness。也不是 Test Harness。它是 Stateful Checkpointed Agent Harness一个轻量级 AI Coding Agent orchestration layer。---# 下一步怎么升级如果继续做 v1我会补## 1. Verifier检查- schema 是否合法- 是否只有一个 in_progress- state 是否脏---## 2. File Sandbox自动 diffbashgit diff --name-only验证是否越界。---## 3. Transactional Commit先 commit 成功再推进 state。避免 split-brain。---## 4. Watchdog限制 auto loop 次数。防止死循环。---# 最后我原本以为自己在写 Prompt。后来发现我其实在写一个 Agent Harness。Prompt 在教 AI 思考。Harness 在约束 AI 行为。而真正稳定的 Agent往往两者都需要。