Vibe Coding 心得：让 AI 协作从「盯盘」变成「放手跑」

我以前用 AI 写代码，经常会需要看它跑完了吗，出什么问题没？

真正能把 AI 协作拉到一个新档位的，是把盯盘改造成放手跑的工作流：让 Agent 在你不在线的时候也能持续推进，并且在遇到不确定性时不会瞎猜，遇到错误时会自我校验，遇到风险时会主动收敛到可控范围。虽然现在已经用类似于在云上跑的 coding agent 了，但是目前来说，在本地使用 claude code 更可控，也更方便 agent 之间协作，比如使用 git worktree。

这篇文章只讲一件事：把这一套并行开发的方法自动化在任何代码上。

总结：瓶颈在于验证

现在模型足够强，开发的瓶颈从写代码转移到了验证与回滚。你可以让 Agent 快速改出一个版本，但如果你无法快速验证、无法安全回滚，那么你就会用更频繁的微管理去抵消风险，整体效率就上不去了。

我总结的工作流

我把一次可放手的协作任务拆成 5 个阶段。每个阶段的目标不同，自动化程度也不同：

1. 上下文初始化（Context Initialization）
   • 新到手一个仓库，扫描仓库 / 指定文件夹结构
   • 建立并对齐：项目结构、运行方式、改动边界（Scope）、关键约束
2. 规划（Planning）
   • 把目标拆成子任务
   • 对关键决策点输出 ≥2 个方案 + 取舍依据 + 验收标准（DoD）
   • 主动提出必要澄清问题（不能猜）
3. 执行（Execution）
   • 严格按已确认的 Plan 做增量改动
   • 只在 scope 内动手；必要时先打最小补丁拿到信号
4. 迭代（Iterate）
   • 执行 → 验证 → 修复 → 再验证，直到满足 DoD
   • 卡住时回到决策点，改规则/约束，不要盲目扩大改动面
5. 审查与收敛（Review & Refactor）
   • 给出检查清单（冗余、副作用、边界污染、可维护性），让人类来 review
   • 输出最终变更摘要与回滚/验证说明，在 scalability, reliability 上给出建议，以及对现在代码质量和架构的评价。使用 AWS Well Architected Framework, Operation Excellence, Security, Reliability, Performance Efficiency, Cost Optimization, Sustainability.

这里最关键的是：规划阶段必须产出 DoD。没有 DoD，Agent 很难知道什么时候算完成，会在模糊处停下来问你，或者交付半成品就收工。

并行开发：写完 spec，发一句话

上面讲的是工作流的结构，但具体落地的方式，我希望是：写好下一版本的 spec，然后只对某一个 agent 说一句"开始并行开发"，它就会自己遵循一份文档推进，不需要你手工分工、手工盯盘、手工开多个 worktree。

我总结的关键是使用 Skills.md 运行脚本和按阶段推进，并且让每一段都有固定输入和固定产出。你只需要 review 产出物。

1) 开发前：固化重复问题

这里需要把 Agent 会反复问你的问题，或者是你经常问 Agent 的问题，提前固化成文档与脚本，让它可以在没有人类反馈时继续推进。

最小文档集（我个人会放在 docs/agent/ 或 .agent/）：

• SPEC.md：下一版本 spec（用户故事/边界/验收标准）
• SCOPE.md：允许改哪些目录/禁止改哪些目录（以及原因）
• RUNBOOK.md：一条命令启动完整环境 + 常见故障定位入口（日志、健康检查）
• TESTING.md：测试分层（单测/集成/e2e）+ 最小 smoke 流程
• PARALLEL_DEV.md：并行开发执行说明（Agent 的操作手册）
• PRDOD.md（或 TASK_CONTRACT.md 模板）：DoD 合同（Agent 不能在合同未满足时结束）
• DECISIONS.md：架构决策记录（ADR 简化版），避免重复讨论
• SECURITY.md：最小权限与危险操作红线（迁移/删库/生产配置等）

一个可直接复用的 docs/agent/PARALLEL_DEV.md 最小模板（你写好一次，之后每个版本只改 SPEC.md）：

一个可复用的 docs/agent/PRDOD.md 合同模板（让完成可验收）：

本地启动开发服务器的指令集，让 Agent 不用猜：

• 唯一入口命令：make dev / pnpm dev / ./scripts/dev-all.sh（启动后自动跑 healthcheck）
• 唯一测试命令：make test / pnpm test / pytest（失败要给可定位日志）
• 日志可归因：每个服务有前缀或独立日志文件（能定位谁报错）
• 环境声明：.env.example + 缺失时明确报错（不要静默失败）

你要给 Agent 的启动口令，应该指向这些固定文件，而不是临时口头解释。推荐写成仓库级约束（例如 CLAUDE.md/AGENTS.md）：

• "开始任何实现前，必须先读 docs/agent/SPEC.md、docs/agent/SCOPE.md、docs/agent/PRDOD.md。"
• "不允许在 scope 外改动；需要改动必须先提出方案并等待确认。"
• "每个子任务结束必须更新合同清单并提供验证证据放在文档中（测试结果/截图/日志段）。"

对照 Claude Code 作者 Boris 的并行 setup

Boris 的方法没有太多复杂的框架，他做的是把并行拆成一组可组合的模块，然后让每条 session 都能独立完成一个闭环。

开发前（把规则、命令、权限变成共享资产）

• 团队共享 `CLAUDE.md` 并持续更新：看到 Claude 做错事就补一条规则，让下一次自动避坑（规则是防重复犯错的最短路径）。
• 把高频流程写成 slash commands：放在 .claude/commands/，例如一个 /commit-push-pr 把 git status 等信息预计算好，减少来回沟通。
• 用 hooks 做最后 10% 的确定性：例如 PostToolUse 自动格式化，避免 CI 因格式失败。
• 用 `/permissions` 预授权常用安全命令：不要用 --dangerously-skip-permissions，而是在你信任的环境里提前 allowlist。（我个人会直接 --dangerously-skip-permissions）
• 共享 settings 与工具配置：.claude/settings.json、.mcp.json 这类配置文件进 git，团队一致性会直接提升并行质量。

开发中（让每条 session 都能自证正确）

• Plan mode 起步 + 计划通过后再自动执行：先把计划打磨到你满意，再切到 auto-accept edits，让它一口气跑完。
• 并行跑多条 session：本地终端 + web + 手机都可；关键是让它们各自有明确任务边界与 DoD，而不是同时做同一件事互相污染。
• 把验证做成内循环：Boris 的经验是最重要的是给 Claude 一条反馈回路。验证可以是测试命令、浏览器 UI 检查、截图对比。
• 长任务的 stop hook / 背景验证：让做完后自检成为强制步骤，而不是靠你想起来再去验收。

开发后（把结果回填到系统里，下一次更省心）

• 在 code review 里用 bot 追加规则/补文档：例如在 PR 里 tag @.claude 让它把经验写回 CLAUDE.md 或 runbook。
• 用 subagents 做收尾自动化：比如 code-simplifier（简化代码）、verify-app（端到端测试），把 review 前的整理制度化。

把这些模块和上面的文档 + worktree + 合同（DoD）合起来，就得到一个更贴近现实的并行系统：

• Boris 这边的基础设施是多 session、commands、hooks、permissions、subagents。
• 我补的是并行闭环的合同结构（SPEC/SCOPE/RUNBOOK/PRDOD + worktree 隔离 + 结束条件）。

两者叠加之后，你才能真正做到：写完 spec → 发一句"开始并行开发" → 你只在最后做 review 与回填。

2) 开发中：在独立工作区里循环直到 DoD

让 Agent 自己把计划→执行→验证→修复→再验证跑成闭环，你不需要做任务拆分，只需要在开始前给出 spec 和合同模板。

并行开发的默认工作单位是一个任务一个分支/一个 worktree，解决两个问题：

• 让 Agent 在跑偏时可以直接丢弃工作区，不污染主工作区。
• 让你 review 时能把变更压缩成一个 PR，而不是散落在本地状态里。

git worktree 是最轻量的做法（Claude Code 的作者也曾在推特里强调过这种多工作区并行的工作方式）。示例命令：

执行期，你需要约束的是它如何结束任务。推荐把运行闭环写成合同条目（每条都要可验证）：

• 计划：输出任务拆分 + 关键决策点的 A/B 方案 + 选择依据
• 实现：每次提交都附上做了什么/为什么/影响面
• 验证：跑测试（或最小 smoke）并贴结果；前端给截图/录屏/可复现步骤
• 回滚：给出可撤销策略（feature flag、回滚提交、迁移回滚）
• 交付：PR 描述里包含 DoD 清单（全部勾选才算结束）

如果你希望尽量放手，有三类选项能显著减少你被打断的次数：

• 澄清问题的异步出口：约定澄清问题统一写到 docs/agent/questions.md 并按优先级排序，避免 Agent 反复卡住。
• 决策点的默认策略：例如遇到引入新依赖/改数据模型/改公开 API，必须停下来出 A/B 方案；其他小改动默认采用最小变更。
• 中间产物的强制记录：例如每次失败都把错误摘要 + 复现步骤 + 下一步写进 docs/agent/trace.md，让你回来能快速定位它为什么卡住。

3) 开发后：review 和回填

你把系统搭起来之后，Claude Code 可以做到自己澄清→并行开发→自验收→交付 PR，但它只会在你提供的文档与反馈回路允许的范围内自主推进。缺口一旦触碰到需求取舍 / 风险红线 / 外部权限，它就应该停下来，把问题写出来等你确认。

我倾向于把交给 Agent 的东西理解成一份可执行合同：输入、边界、验证方式、结束条件都写清楚，Agent 的职责是把合同跑到全勾。

建议的 review 清单（按顺序）：

• 合同是否完成：DoD 清单是否全部勾选；证据是否可复现（测试/截图/日志）
• 改动边界：是否严格在 SCOPE.md 允许范围内；是否出现顺手重构
• 风险点：是否触碰了数据迁移、权限、生产配置等红线；是否有回滚路径
• 可观测性：失败时能否通过日志快速定位；是否补齐关键日志/健康检查
• 可维护性：是否引入隐性耦合；是否把关键决策写进 DECISIONS.md

做完 merge 之后，还有一步：回填系统。

• 把这次 Agent 反复问的问题，写进 RUNBOOK.md/TESTING.md/SCOPE.md
• 把这次跑偏的决策点，写成一条规则（下次直接禁止/或要求先出方案）
• 把这次有效的执行配方，沉淀成一个可复用的 SKILL.md（输入/输出固定）

人类验收

验收不用逐行看代码，按合同 + 风险控制走就够了，每一步都能在 10 分钟内完成或明确卡点：

1) 先看 PRDOD 合同是否全勾

• DoD 是否全部勾选
• 每一条 DoD 是否都有证据（测试输出/截图/日志段/复现步骤）

2) 复现一次最小验证（不要只信截图或粘贴结果）

• 按 RUNBOOK.md 启动
• 按 TESTING.md 跑 smoke 或关键测试
• 前端按复现步骤走一遍关键路径

3) 看变更边界与风险

• 是否严格在 SCOPE.md 内改动（有没有顺手重构）
• 是否触碰红线（数据迁移、权限、生产配置、删除/清空操作）
• 是否提供回滚路径（feature flag / revert commit / 迁移回滚）

4) 看可维护性信号，而不是挑剔实现细节

• 日志/健康检查是否更容易定位问题
• 决策点是否写入 DECISIONS.md（避免下次重复争论）
• runbook 是否被更新（避免下次还要你口述）

5) 合并前最后一句话检查

• "如果今天线上出问题，我是否能在 5 分钟内：定位 → 回滚 → 恢复？"

如果你想把这套验收变成每次都能照单执行的流程，建议把上面的 5 步写成 docs/agent/HUMAN_ACCEPTANCE.md 的勾选清单，并在 PARALLEL_DEV.md 里要求 Agent 在 PR 描述中引用它（例如：Human Acceptance: docs/agent/HUMAN_ACCEPTANCE.md）。

6 条工程纪律

下面 6 条是针对典型失败模式总结出来的约束：

1. 少即是多（对抗上下文膨胀）：越多插件/记忆系统/超长规则，越容易把无关信息塞进实现阶段，Agent 更容易跑偏。
2. 研究与实现分离（对抗方案污染）：先做 research（列方案/取舍），再用干净上下文的实现任务落地选定方案。
3. 中立提示（对抗讨好/幻觉）：少用"找 bug""证明 X"这种偏置指令，改用"逐模块走读并汇报发现"。
4. 压缩后的再对齐（对抗断片）：每次 /compact 之后，强制重读 plan + 关键文件，避免在信息缺口处自己补全。
5. 明确终止条件（对抗半成品收工）：把完成写成合同（测试/截图/手动验证清单），否则 Agent 只知道怎么开始，不知道怎么结束。
6. 规则与技能（对抗偏好漂移）：规则固化禁区/偏好，技能固化可重复配方；规则变多互相打架时，要定期合并清理。

可执行输入

盯盘的一个根源是输入不可执行：Agent 需要在执行中不断向你索取关键事实。要让它独立推进，需要把输入写成它能直接执行的格式，而不是一段散文。

推荐固定一个任务输入模板（尽量短，但必须完整）：

• 目标：一句话说明要的结果（用户可感知的变化）
• 约束：必须遵守的边界（可改/不可改、不能引入依赖、性能/安全要求）
• 证据：链接/截图/日志片段/复现步骤（越像证据，越能避免误解）
• 验收标准（DoD）：怎么验证确实改对了（测试、日志、行为）
• 不做什么（Non-goals）：不要顺手重构、不要改 UI 主题、不要动 API
• 回滚策略：出问题怎么退（开关、分支、备份点、恢复步骤）

协作规约：不要把你的解法塞给 Agent

先给 Agent 一个你认定的解法会导致两个后果：

1. 它把你的解法当作约束，跳过方案空间探索（你失去了纠偏机会）。
2. 当解法错了，你分不清是缺 context 还是它判断错。

更高效的做法是：你只给目标 + 约束 + 证据，先让 Agent 提供 2-3 个可行方案，再由你选。

规划：关键决策点输出 ≥2 个方案

只给一个方案时，你无法区分它是真正正确，还是只是先想到这个。多方案输出能把推理显性化，纠偏成本更低。

建议输出格式（每个决策点一块）：

• 决策点：要不要引入新依赖 / 要不要重构 / 要不要改 API 合约
• 方案 A（推荐）：做法 + 优点 + 风险 + 前置条件
• 方案 B：做法 + 优点 + 风险 + 前置条件
• 选择依据：为什么选 A（与目标/约束对齐）
• 验收标准（DoD）：怎么验证（测试/日志/行为）

前端为什么更难

Spec-driven 对后端/纯逻辑更顺，是因为输入输出边界天然明确：请求、响应、类型、错误码、性能指标都能被测试捕捉。

前端的难点通常有三个：

1. 需求的真相是视觉与交互细节，难以从口头描述完整还原。
2. 上下文分散：路由、布局、状态、样式、组件层级、feature flag，任何一个缺失都会导致看起来改了，但不是你想要的。
3. 验收不可自动化：没有截图对比/Playwright/VRT，Agent 很难自证改对了。

前端要走得顺，输入必须更像证据：截图、路径、元素定位、复现步骤、验收标准。

前端修改：指令模板

把前端指令固定成一张表（不需要很长，但必须可执行）：

• 目标：一句话说明你要的结果（用户可感知的变化）
• 页面/路由：/pricing、/settings/billing
• 文件定位：src/web/app/pricing/page.tsx（至少到 page.tsx 或组件文件）
• 证据：截图（before/after 或标注要改的区域）；如果无法给图，给 DOM 文本/选择器/组件名
• 复现步骤：1) 打开… 2) 点击… 3) 观察…
• 验收标准（DoD）：可观察、可测试（例如按钮文案从 A→B；hover 样式保持不变；移动端不换行）
• 不做什么（Non-goals）：不要顺手重构、不要改 UI 主题、不要改 API
• 验证方式（可选）：Playwright 用例 / 截图对比（VRT）/ 手动检查清单

多服务启动与日志

能跑起来只是基础，真正要的是启动后 Agent 能自己定位问题。关键差异在于：日志是否可归因（哪个服务）、是否可检索（能抓到错误段）、是否可复现（同一条命令可重跑）。

方案 A：一键脚本 + 带前缀的聚合日志（适合本地开发）

• 提供 scripts/dev-all.(sh|ps1)：统一启动各服务
• 每个服务输出加前缀（[web] [api] [worker]）并聚合到同一个终端/文件
• Agent 只需要跑一次命令 + 读一个日志文件就能定位问题

优点：可 hot reload，迭代快；风险：不同 OS/终端适配要做一点工程。

方案 B：docker compose up + docker compose logs -f（适合稳定复现）

• 用 docker-compose.yml 声明依赖（db、queue、api、web）
• 用 docker compose up -d 启动，用 docker compose logs -f --tail=200 <service> 精准看某个服务

优点：环境一致，适合 CI/复现；风险：前端 hot reload 可能变慢（取决于挂载与构建策略）。

任务边界与 /compact

/compact 做的事是：当上下文变长或变乱时，把当前状态压缩成下一步还能执行的最小信息包。

建议触发条件：

• 你发现 Agent 开始重复、发散、或持续误解同一约束
• 一个阶段结束（完成 Context / Planning / Execution / Iterate / Review 任一阶段）
• 已产生大量中间产物（日志、临时脚本、试验分支）需要收敛成结论

任务边界（一个可放手跑的任务应满足）：

• 目标可一句话定义，且有可验证的 DoD
• 输入依赖明确（文件路径/环境/账号/数据）
• 不需要在执行过程中频繁向人类索取新的关键事实

估时里程碑

估时的用处是把不确定性拆成可管理的块：每块都有产出物、验证方式、最坏情况与降级方案。

本仓库已新增一个可复用模板：skills/估时里程碑/SKILL.md，把估时输出固定为：

• 假设（每天可投入时间、熟悉度、依赖可用性）
• 里程碑（按日/按半天切块）
• 每个里程碑的交付物与验收方式
• 风险与降级（砍功能顺序）

关于 levelsio 那条线程

levelsio 那条线程真正说透的一件事是：当模型足够强时，开发效率的瓶颈从写代码转移到验证与回滚。他让 Agent 在生产跑，是在用生产环境作为最快的反馈回路，但这个做法成立的前提是他已经把风险管控做好了。

可复用的控制面（按重要性排序）：

• 可回滚性优先：备份、快照、可恢复演练（原文里明确提到"lots of backups"）。
• 验证前置：哪怕不写自动化测试，也要有人类在线验收的固定流程（原文是"browser open and test live"）。
• 权限最小化：先不要把 bug board 直接连到执行链路；用只读 GitHub 权限生成 PR，由人类 accept/reject。
• 输入可信度治理：把 bug board 当作外部输入面，默认存在 prompt injection 风险；需要净化/白名单/隔离策略。
• 异步澄清：把必要澄清问题丢到 Telegram/通知系统，避免 Agent 因信息缺口停摆或误跑。

直接跑起来

如果想把上面这套流程直接用在自己的仓库上，可以拉取我做的 skills/parallel-development。

这个 Skill 包含三部分：

文档模板集（assets/templates/docs/agent/）放在 docs/agent/ 下，包括 SPEC、SCOPE、PRDOD、RUNBOOK、TESTING、DECISIONS、SECURITY、questions、trace 和 HUMAN_ACCEPTANCE，每个文件对应一个明确的角色，Agent 按文档推进，不靠猜。

三个 PowerShell 脚本负责把易出错的步骤变成确定性操作：pd_init.ps1 把模板安装到目标仓库，pd_worktree.ps1 创建隔离的 git worktree 和分支，pd_kickoff.ps1 把前两步合并成一条命令一次完成。

References 目录里有 interview 问题框架、workflow 细节、Claude Code 并行模块对照，以及估时里程碑模板，按需读取，不强制加载到上下文。

用法是：把仓库路径和 feature spec 传给脚本，跑完之后对 Agent 说一句"开始并行开发"，剩下的它自己跑。

参考

• <https://x.com/bcherny/status/2007179832300581177>
• <https://x.com/levelsio/status/2027566773814403448?s=48&t=un5pnX0HhInP-JQCj18LWw>
• <https://steipete.me/posts/2025/shipping-at-inference-speed>
• <https://x.com/shao__meng/status/2028833958230933729?s=46&t=86vuVwyeuTqpU6CbA9mldw>
• <https://github.com/obra/superpowers>