8.7 综合最佳实践：从想法到交付¶

这一章把前面的内容压成一套可执行流程。你可以把它当成日常开发的默认操作系统。

这里不再解释 Prompt / Context / Harness 的概念，也不展开框架选型。概念看 2. Prompt / Context / Harness 三层工程方法，harness 落地看 6. Harness Engineering，最终项目模板看 9.4 最小项目模板。

总流程¶

flowchart TD
  A[想法 / 问题] --> B[网页对话澄清]
  B --> C[任务工件化]
  C --> D[本地 Agent 只读探索]
  D --> E[计划与验收标准]
  E --> F[实现]
  F --> G[自动验证]
  G --> H[只读 review]
  H --> I[人工 diff 审查]
  I --> J[合并 / 发布]
  J --> K[复盘沉淀]
  K --> L[更新 docs / AGENTS / skills]

核心思想：越靠近生产代码，越要从“聊天”变成“证据”。

1. 网页对话只做前置澄清¶

网页 GPT / Claude / Gemini 适合做：

解释概念。
比较方案。
整理需求。
生成第一版 PRD。
查漏补缺。
做第二意见。

不适合做：

直接改真实仓库。
判断未读取过的项目约定。
替你确认测试已通过。
在没有 diff 的情况下做最终 review。

推荐做法：

先在网页端把想法变成任务卡。
再把任务卡交给本地 Agent。
不要把网页端生成的代码直接粘进项目。

2. 每个任务先有完成标准¶

任务开始前先写清楚：

目标是什么。
不做什么。
涉及哪些模块。
可能有哪些风险。
如何验证。
什么时候必须停手问人。

如果你只写“帮我优化一下”，Agent 会替你发明标准。

3. 先让 Agent 读，不要先让它改¶

复杂任务第一轮应该是只读探索：

请先只读分析，不要修改文件。
输出：
1. 相关文件和调用链。
2. 现有实现模式。
3. 可能方案。
4. 风险和需要确认的问题。
5. 建议验证命令。

这一步会显著减少跑偏。它也能暴露 Agent 是否真的理解项目，而不是直接套模板。

4. Prompt 用四段式¶

Goal:
  我想达成什么结果，以及为什么。

Context:
  相关文件、需求、错误日志、设计约束、已有约定。

Constraints:
  不要做什么、必须遵守什么、权限和范围在哪里。

Done When:
  通过哪些检查，交付哪些证据。

这比长篇叙事更稳定，也更适合 Claude Code / Codex / OpenCode。

5. Context 用分层文件，而不是堆进聊天¶

推荐分层：

根目录规则：AGENTS.md / CLAUDE.md / GEMINI.md。
项目知识：docs/architecture.md、docs/domain.md、docs/testing.md。
当前任务：tasks/<slug>/prd.md、plan.md、journal.md。
复盘沉淀：docs/pitfalls.md、skills/、retrospectives/。

原则：

高频规则放入口文件。
长知识放 docs。
临时上下文放 task。
重复流程放 skill。

6. MCP 先只读，skills 先小而准¶

MCP 默认顺序：

文档检索。
代码搜索。
浏览器/Playwright。
GitHub/issue/PR 读取。
日志/监控读取。
外部系统写入。

第 6 类要非常谨慎。初学者先不要把生产写权限交给 Agent。

skills 默认顺序：

bug-fix。
pre-review。
task-to-plan。
frontend-review。
ci-fix。

不要让 skills 变成收藏夹。一个 skill 如果一个月没有实际减少返工，就删掉或重写。

7. 实现和评审要分离¶

不要让同一个 Agent 既当运动员又当裁判。

推荐流程：

flowchart LR
  A[Implementer Agent] --> B[Diff]
  B --> C[Verifier<br/>tests/build]
  B --> D[Reviewer Agent<br/>read-only]
  C --> E[Human]
  D --> E
  E --> F[Accept / revise / reject]

最小做法：

实现 Agent 可以改代码。
review Agent 只读。
人类最终看 diff。

8. 多 Agent 前先划清写入范围¶

多 Agent 适合：

A 做后端，B 做前端。
A 修 bug，B 补测试。
A 探索方案，B 实现推荐方案。
A 实现，B 只读 review。

不适合：

两个 Agent 同时改同一批文件。
需求还不清楚就并行。
没有 worktree 或分支隔离。
没有最终合并人。

分工提示：

你负责 <模块/目录>。
不要修改 <其他模块/目录>。
如果发现需要跨边界修改，先停止并报告。
完成后输出变更摘要、验证结果、未解决风险。

9. 每次完成都要有证据包¶

完成摘要应该包含：

改了什么。
为什么这样改。
运行了哪些检查。
检查结果是什么。
没有运行什么，原因是什么。
剩余风险。
建议人工 review 的重点。

不要接受只有“已完成”的回复。

10. 失败时不要继续堆 prompt¶

Agent 跑偏时，优先做四件事：

停止继续修改。
查看 git diff。
回到任务目标和验收标准。
决定是修正、回滚部分改动，还是新开会话。

典型止损信号：

Agent 第三次修同一个错误仍失败。
Agent 开始修改无关文件。
Agent 无法解释当前 diff。
Agent 为了通过测试而删除测试或绕过校验。
上下文里出现互相矛盾的要求。

11. 复盘要进入系统¶

每次任务结束后问：

哪条规则应该写进 AGENTS/CLAUDE？
哪个坑应该写进 docs/pitfalls？
哪个重复流程应该写成 skill？
哪个检查应该自动化？
哪个 MCP 能减少复制粘贴？
哪个上下文过期了？

如果复盘只停留在聊天里，下次还是会犯同样错误。

12. 一周节奏¶

个人可以按这个节奏维护系统：

每天：任务结束后补 verification 和 handoff。
每两三天：整理重复 prompt，判断是否写成 skill。
每周：清理过期 docs，更新 AGENTS/CLAUDE。
每周：回看失败任务，补测试或规则。
每月：检查 MCP 和 skills 权限，删除不用的扩展。

收束原则¶

让 AI 多做执行。
让文档承载上下文。
让工具提供事实。
让测试提供证据。
让 review 保持独立。
让人类保留判断。

这就是 Vibe Coding 从“会用 AI 写代码”走向“能独立用 AI 开发”的分界线。