AI 写代码总翻车？我用 Harness:developer 把它管成“右侧打工人”

先说一个真实场景。

你让 AI 改个功能，本来想要“10 分钟提效”，结果最后变成“2 小时排雷”：

• 一会儿改了不该改的文件；
• 一会儿说“已完成”但没有验证证据；
• 你回头想复盘，发现没有计划、没有过程、没有日志；
• 最终你和同事围着屏幕沉默三分钟，谁都不敢点合并。

我后来发现，问题不在“模型笨”，而在“流程野”。

于是我设计了一个任务编排skill：Harness:developer， 干的事很直接：

把 AI 开发变成一条有门禁的流水线。主会话只负责编排，右侧 pane 才能写业务代码。你可以理解成让 AI 去右边工位打卡上班，左边主管只盯流程，不准亲自抡键盘抢活。

这篇文章不讲玄学，直接讲它到底怎么工作。看完你就能按步骤跑，尤其适合刚上手 AI 协作开发的同学。

先记住一句总规则

从 Step 2 开始，到 Step 6 结束：主会话禁止业务编码。

是的，禁止。不是“尽量不要”，是“违规就 fail”。

为什么这么绝对？因为大多数事故都发生在“差不多就行”的灰色地带。主会话一旦开始手改业务代码，你后面就很难分清：到底是编排成功，还是救火成功。

整条流程长什么样

Harness:developer 固定是 9 个阶段：

1. Step 0：Preflight：环境预检
2. Step 1：需求理解与计划落盘：prd/在线原型/原型源码三路并行分析
3. Step 2：编排锁建立：claudecode使用agent team分析需求并执行计划，codex使用subagents分析需求并执行计划
4. Step 3：启动指令生成
5. Step 4：启动右侧编码会话
6. Step 5：任务下发 + ACK 校验
7. Step 6：tmux+smux右侧创建pane，执行编码（主会话只监控，开发过程实时记录进度）
8. Step 7：强制调用 /Harness:verify 验证编码结果
9. Step 8：日志归档 + 规则合规报告

你可以把它看成“开发版过安检”。每一步都要验票，没票就别进下一站。

开始流程

终端执行tmux -> codex --yolo 或者 claude --dangerously-skip-permissions -> 输入提示词

# claudecode
/Harness:developer "完成 @docs/产品文档/v1.0/产品文档/交易中心_分账订单PRD.md" "codex" "http://localhost:3000/#/payment-orders/transfers"

# codex
$Harness:developer "完成 @docs/产品文档/v1.0/产品文档/交易中心_分账订单PRD.md" "codex" "http://localhost:3000/#/payment-orders/transfers"

Step 0：先查体检，再谈开工

这一阶段主要确认“你现在是不是在能跑流程的环境里”。

要检查的核心点：

• tmux 是否可用，主 pane 能不能探测到
• smux/tmux-bridge 是否可用
• 当前会话识别为 codex 还是 claude
• 关键 skill 是否具备：/prototype-reader、/Harness:progress、/Harness:verify

这一步最常见的翻车是：根本不在 tmux 里，或者 pane 信息都拿不到，还硬着头皮继续。后面自然是连锁崩。

一句话总结：Step 0 不是形式主义，它是“这趟车能不能发车”的决定点。

Step 1：三路并行分析，不再盲改

这里是我认为最值钱的一步。Harness:developer 要求并行跑 3 个分析单元：

• prd-analyst：看需求
• prototype-explorer：看原型
• source-analyst：看现有代码

注意，原型分析必须给硬证据，不接受“我看过了”的口头保证。至少要有：

• 页面开闭记录
• 3 张及以上截图（列表页、详情/弹窗、配置页）
• 浏览器已清理标记
• 主会话逐项验证截图文件存在

这一步完成后，会把计划文档和进度文档落盘。也就是说，从这一刻开始，你不再是“脑内计划”，而是“可追踪计划”。

很多人跳过这一步，理由是“我急着写代码”。结果往往是后面改三轮，最后总耗时更长。

Step 2：上锁，正式进入“只编排模式”

Step 2 是整条链路的硬门禁。

这里要做几件关键事：

• 校验 Step 1 产物存在（计划、进度、分析单元已回收）
• 输出固定强提醒：Step2-6 主会话仅编排，违规即 fail
• 识别并记录 MAIN_PANE_ID
• 清理多余子 pane
• 建立 ORCHESTRATION_LOCK=on 并写锁文件

这把锁的意义非常现实：防止流程运行中途“主会话忍不住下场改代码”。

你可以把它当作“防手痒机制”。听起来有点好笑，但真有用。

Step 3：生成启动命令，做一次防串改

这一步会生成 READY_TOKEN 和 START_CMD，并做可执行校验。

关键要求是：START_CMD 必须包含 ready:{READY_TOKEN}。

如果只是裸 ready，后面不认。因为裸 ready 很容易误判来源，token 化回执才能明确“这是这次任务、这个 pane、这条链路的回执”。

此外还会记录 START_CMD_SHA1，防止命令被串改或发错版本。

Step 4：拉起右侧 pane，确认“打工人已就位”

动作看起来简单：

• 新建右侧 pane
• 拿到 TARGET_PANE_ID
• 确认它不等于 MAIN_PANE_ID
• 通过协议发送启动命令
• 等待 ready:{READY_TOKEN}
• 校验 pane 当前进程必须是 codex|claude

真正难的不是“会不会 split-window”，而是“会不会做来源校验”。

我见过最经典的事故是：ready 回执出现在主 pane，但大家没注意，还继续推进。最后你以为右侧在写代码，实际右侧压根没起来。

这就是为什么它要求 token、要求来源、要求进程在位校验。不是麻烦，是防事故。

Step 5：下发任务，必须拿到 ACK 才算派工成功

这一步的核心是“发送任务 + 验收回执”。

合规 ACK 形态主要是：task_received:{MODULE_NAME}。

如果走 fallback，也不是随便说一句“我收到了”就行，还要补齐工作态证据，比如已经进入工作、已返回空闲等。

还有个细节很关键：ACK 必须来自目标 pane。主 pane 出现对应 ACK，直接判误发。

你可以理解成工单系统里的“签收回执”：没签收，不算派单成功。

Step 6：右侧执行编码，主会话只监控

这是最考验耐心的一段。

主会话此时允许做的事只有三类：

• 监控目标 pane 输出
• 定时记进度（通常每 3 分钟一次）
• 必要时发“继续开发”

不允许做的事就一条，但非常重要：主会话不能接管业务编码。

并且完成回执有顺序要求：

1. verify_done:{MODULE_NAME}
2. done_ack:{MODULE_NAME}

顺序错了不行，缺一个也不行。

另外，流程把“等待态”和“故障态”分得很清楚：

• timeout、task_blocked:*：属于等待态，继续等
• 429/50x：才算故障态，可进入恢复策略

这条规则能显著减少“焦虑型误操作”：看着不动就 kill pane，结果把正常执行链路硬切断。

定时更新进度的效果图：

Step 7：必须走 /Harness:verify，不能口头毕业

到了这步，很多人会说“我自己跑了 lint/typecheck 就好了吧”。

不行。

Harness:developer 要求必须调用 /Harness:verify，并保留可核验回执。原因很简单：统一口径、统一证据、统一复盘入口。否则每个人都说“我测过了”，但没人说得清“你到底怎么测的”。

Step 8：归档日志，让这次开发可追溯

最后一步是很多团队最容易忽略的，但长期价值最大：

• 写自检日志到固定目录
• 记录计划执行、验证结果、规则检查、问题修复
• 输出 Rule Compliance Report（改动文件 -> 对应规则）

这一步做得好，后面查问题就不是“靠记忆猜”，而是“按记录查”。

这套流程到底值不值得

如果你只看“第一次上手成本”，它确实比一句 prompt 重。

但如果你看“总交付成本”，它通常更省：

• 需求理解更早收敛，少返工
• 过程责任更清晰，少扯皮
• 验证证据更统一，少争议
• 归档更完整，少失忆

说白了，这是一套“把 AI 开发从表演赛变成联赛”的方法。

给小白的落地建议

如果你今天就想试，照这个顺序来：

1. 先完整跑一遍，不要私自删 Step
2. 严格执行 Step 2 的锁，不要觉得自己能自律
3. 把 Step 1 的原型证据当硬指标，不要口头化
4. Step 7 一定走 /Harness:verify，别手动替代
5. Step 8 认真写日志，给未来的自己省时间

你会发现，流程不是束缚，而是“降低犯错自由度”。这在多人协作里，几乎总是好事。

结尾

Harness:developer 最厉害的地方，不是让 AI 写得更快，而是让你知道“它到底有没有按规范写”。

快不快是一时的，稳不稳是长期的。

把 AI 放到右侧 pane 去打工，把主会话留给编排和审计。你会明显感觉到：项目开始像项目了，不再像临场 improvisation。