搭个人 AI Coding harness：从能跑到能用，14 条踩坑清单
接上一篇《老炮经验沉淀 2.0》最后那一层——L3 harness 编排。那篇里我说 harness 是「把团队工作流编码成调度逻辑的那段代码」，但没展开。这篇展开。
过去一年我自己搭了一个 multi-coding-agent harness 跑团队任务。从最初一个 200 行的 Python 脚本跑串行任务，到现在能调度 4–6 个 agent 并行 + 自动 review + 跨模型路由，中间踩过的坑远比我预想的多。
把这些坑整理成 14 条清单，分成 4 组。每组都是 harness 从「能 demo」走到「能用」必须跨过的门槛。
一、经济性：你要先活下来才能讨论质量（3 条）
1. 多模型路由是必须，不是可选
团队经费有限的前提下，所有任务都打 Opus 是自杀。基本盘是：
- Haiku / 小模型：意图识别、JSON 解析、分类、tag 抽取
- Sonnet / 主力模型：主干代码生成、单步重构
- Opus / 大模型：跨文件 review、复杂 spec 拆分、debug 难案
一条经验：80% 的 token 应该花在 20% 的关键节点上。我们 harness 跑了三个月之后，把 70% 的调用迁到 Haiku / Sonnet，Opus 只在 reviewer 和 critical planner 节点上场——月账单从 $1800 砍到 $400，产出质量反而升了（因为关键节点没省）。
2. 单任务 token 有硬上限
任务太大，agent 自由发挥、跑偏概率飙升；任务太小，调度协调成本超过执行成本。
我观察到的甜点是 ~3000 input token / task。超过这个数，让 planner agent 先拆，每个子任务都压在阈值内。这一条直接决定了 harness 的输出稳定性——任务拆得对，输出就稳；任务一大，所有下游 review / 重试都救不回来。
3. 三级硬预算闸
单任务 / 单 session / 单日，三个层级各设 hard cap。
这条放在经济组的最后，是因为你不踩一次不会觉得它重要——直到某天 agent 进了个无限 retry loop，半夜烧光月度预算才会变成第一优先级。
我现在的设置：单任务 $0.5、单 session $5、单日 $30。超了直接 hard kill。比起预算被烧光，被 kill 几个低优任务便宜得多。
二、鲁棒性：不崩 / 不出事（4 条）
4. context 管理与 handoff
长 session 必崩。Agent 跑 30 分钟之后输出质量断崖式下跌——上下文塞满了之前的废输出，模型注意力分散。
解决方式不是加大 context window（治标），而是 auto compaction + 结构化 handoff：
- 每跑完一个阶段，planner 把状态压成结构化 brief
- 下一段 agent 拿到 brief + 当前任务，不需要看历史 raw 内容
- Brief 走 schema 化（JSON），不靠自然语言
没做这个，harness 跑半天就开始幻觉；做了之后理论上可以跑天级任务。
5. 失败重试要分三级
agent 报错别直接抛回人：
- 同模型 retry：网络抖动、临时限流，大多数失败这层就能消化
- 切模型 retry：当前模型卡 prompt 注入 / 上下文过载，换一个模型常常就过了
- 升级到人：连续两轮失败 + 错误信号一致，停手等人
多数「agent 不可用」其实是上下文塞太满或者温度过高，换个模型就跑通。没有三级链的 harness，会把大量本可自动消化的失败当成事故抛给人，把推动者磨垮。
6. 沙箱与权限分级
agent 能跑命令，但不能 rm -rf /；能改文件，但不能 push main；能读 DB，但不能 drop table。
按任务类型分配执行权限是 harness 设计的强制项，不是 nice-to-have。任何一个 agent 默认拿到 root，早晚出事。我的分级：
- 读文件 / 跑测试：默认开
- 写文件 / 跑 build：需要在白名单目录
- 跑数据库 / 调外部 API：sandbox 内 / 模拟环境
- 改 git 远端 / 部署生产：必须人工 confirm
7. 任务幂等性
agent 重试不能产生副作用。
否则你会遇到：一个发邮件的 agent 失败重试三次，用户收到三封一样的邮件；一个扣款的 agent 卡在网络层 timeout 重试，账被扣两次。
实现上：每个任务带 idempotency key，所有副作用调用都过这个 key 去重。这条听起来是支付系统的事，但 agent 时代任何 harness 都要装——因为重试是默认行为，不是异常路径。
三、质量：怎么把输出做到能用（3 条）
8. 复杂任务必须自我 review
简单任务追求速度，可以跳过 review；复杂任务（跨文件、跨服务、新模块）必须有 reviewer agent 兜底。
reviewer 不是"再问一遍"那么简单，要带 L2 sediment 里的 checklist：边界条件 / N+1 / error handling / 命名 / 测试覆盖。reviewer 跑完输出结构化 verdict（pass / fix / reject），harness 根据 verdict 决定是否回流 coder。
这条决定了 harness 的输出下限。没有 reviewer，harness 永远在「输出靠人审」的状态；有了 reviewer 且 checklist 不空，80% 的 PR 可以无人审直出。
9. agent 之间走结构化输出，不要走自然语言
planner → coder → reviewer → merger，每一段输出都是 JSON schema，下一段 agent 直接解析字段。
让 agent 用自然语言交付是初期最容易犯的偷懒。看起来「灵活」，实际上每两段之间都有 5–10% 的解析失败率，叠 4 层之后整体成功率塌到 60% 以下。
schema 化的另一个好处：输出可以被持久化、可被 diff、可被 replay。当你想知道「上周那个任务 reviewer 为什么 reject」，直接拉那条 JSON 看，不用回放整个 session。
10. 人在环（HITL）节点要事先设计，不是事后补
哪些节点必须 block 等人确认，哪些可以异步推到 inbox？这件事必须在 harness 设计阶段就定，不能等出事再补。
我的硬 block 节点：
- 生产部署 / 灰度切流
- 数据库 schema 变更
- 删数据 / 删用户
- 跨服务 breaking change
软推送节点（异步进 inbox，agent 继续走）：
- 新功能的命名 / UX 微调建议
- 非核心模块的 review
- 文档质量评分
这条做好了之后，人介入的总时间能砍 60% 以上——你只在真正不该错的地方花注意力。
四、扩展性：harness 怎么演进，不是一次性产物（4 条）
11. 跟标准协议走，别自己造轮子
~/.agents 规范现在除了 Claude Code 都已经收了，cc 大概率也会跟。harness 在 agent 角色定义、tool 调用、context 传递这些层面，能用标准协议绝不自定义。
我们 harness 现在双轨：一套标准 agents/ 目录，一套 .claude/ 镜像。等 cc 跟上之后合并。短期一点点 over-engineering，省下来的是长期换 agent 不用重写 harness 的灵活度。
12. 任务图谱是 DAG，不是线性 pipeline
线性 pipeline 是入门写法，能跑但浪费一半时间。真实任务有大量可并行段：
- frontend 和 backend 改动可并行，但都得等 spec agent 先跑完
- 测试 agent 和 review agent 可以并行跑（review 输出不依赖测试结果）
- 多个独立模块的 coder 完全并行
把任务编排成 DAG，明确依赖边，调度器自动并行。一个 4 小时的串行任务，DAG 化之后通常能压到 1–1.5 小时。
13. 可观测性是 harness 能不能迭代的关键
每个 agent 任务记结构化日志：耗时、token、模型、输出质量分、人工干预次数、retry 次数、最终 verdict。
没有这些数据，你不知道哪个 agent / 哪条 rule 在拖后腿，harness 永远停留在「能跑」，到不了「跑得好」。
我现在的最低基线：每个任务一条 JSON log + 周度 dashboard 看 7 个指标（成功率、平均耗时、平均 token、retry 率、人工介入率、单任务 cost、reviewer reject 率）。某个指标异常，下钻到对应的任务样本看原因。
14. cursorrules / spec / agent 定义全部进 git
harness 的所有配置——agent role 定义、cursorrules、spec 模板、reviewer checklist——必须在 git 里。
某天你调了一条 rule，三周后某类任务质量突然崩了，必须能 git bisect 找回来。没版本化的 harness 就是没维护，迟早一笔糊涂账。
附加好处：rules 可以走 PR review，团队多人协作不会互相覆盖；rollback 一次成本低，鼓励大胆改。
14 条的优先级
如果你刚开始搭 harness，不用一次做完。按依赖关系，有 4 条是地基——做错了后面全要返工：
- #1 多模型路由 —— 没这个，harness 跑不到第二个月就被账单劝退
- #9 结构化输出 —— 没这个，加 agent 越多解析失败率越高
- #14 版本化 —— 没这个，迭代越快崩得越快
- #13 可观测性 —— 没这个，你以为在优化其实在瞎调
剩下 10 条可以踩到了再补——但这 4 条踩到时已经晚了。
收尾
Harness 工程的本质是把团队工作流凝固成代码。代码不止是执行逻辑，更重要的是这套调度、回退、观测、预算的结构性约束——是你十年带团队的判断变成一段会跑的程序。
这件事的护城河，不在 prompt 的精巧，也不在模型选型——这两件事谁都能抄。真正没法抄的是你 harness 里那些「为什么这里要卡人、为什么那里能并行、为什么这条 retry 三次就停手」的判断。每一条都来自一次真实事故。
如果你是 TL：搭 harness 是 2026 年最值得做的一件事。不是为了节省人力——节省人力是副作用。本质是把你过去十年的判断从你脑子里搬出来，放进一个能 7×24 执行的东西里。当你哪天离开这个团队、转型、退场，harness 还在跑，那才是真正意义上的「经验沉淀」。
这 14 条不是终点，是入场券。能跑通这 14 条的 harness 才刚刚算「能用」。再往上还有 agent 自我演进、跨项目复用、多团队联邦——那是另一篇的事了。