2.6 方案先行实现为后——让 AI 代码质量翻倍的核心技巧模块二：AI 协作方法论

模块二：AI 协作方法论 | 第06讲：方案先行实现为后——让 AI 代码质量翻倍的核心技巧

项目：VibeNote 智能笔记
本讲只讲一件事：先让模型把思路写成「可审查的工件」，再让它写代码。

一、开场：为什么「一步到位」最容易翻车

reference/practice/vibe-coding-methodology.md 把这条方法论写得很透：直接生成代码时，模型在「边想边写」，容易出现逻辑断层与前后不一致；先输出实现方案，再基于方案写代码，方案文本会成为后续生成的锚点。这和思维链（CoT）是同一类技巧：把复杂任务拆成「先想清楚再动手」，稳定性会明显提升。

我想补一个工程视角：方案先行不是拖延，是把返工前移。你在文档里否决一个错误方向，成本是一次对话；你在代码里否决，成本是一次合并与一次回滚。

flowchart TD
  Req[需求] --> Plan[技术方案]
  Plan --> Rev[人审/修订]
  Rev --> Impl[分模块实现]
  Impl --> Test[逐步验证]
  Test --> Ship[合并交付]

flowchart LR
  Bad[边想边写] --> Drift[前后不一致]
  Good[先方案后代码] --> Anchor[方案锚点]
  Anchor --> Stable[更稳定实现]

二、方案先行到底是什么：不是写 PRD 作文

「方案」最低应包含：

模块边界：哪些文件/目录会动，哪些绝不碰
数据流：输入从哪来，状态放哪，持久化怎么走
接口契约：请求/响应类型、错误语义
风险与非目标：最容易翻车的点、本期不做的事
验证计划：命令 + 手工路径 + 边界用例

满足这五条，才配叫「可实施方案」。否则只是愿望清单。

三、人审方案：审什么、怎么审

建议用「删、砍、加」三字诀：

删：过度设计、无关抽象、顺便重构
砍：范围蔓延、隐式需求
加：遗漏的边界、错误处理、观测点（日志/指标）

参考方法论也提醒：AI 会堆设计模式；审查阶段就要砍。

四、分模块实现：自上而下设计，自底向上落地

参考文章给出的节奏仍然成立：先蓝图，再基础模块，再功能模块，最后集成。映射到 VibeNote：

数据与类型（Note 模型、校验）
服务端读写（Route Handler / Server Action）
编辑器 UI（textarea + 预览）
AI 能力（摘要/扩写/改写）
端到端验证与文档同步

flowchart TB
  B[蓝图/契约] --> D[数据层]
  D --> A[API 层]
  A --> U[UI 层]
  U --> AI[AI 集成]
  AI --> E2E[端到端验证]

五、每一步都要验证：小步慢跑不是口号

每完成一个模块，立刻跑：

pnpm lint
pnpm build（关键节点）
手工路径（创建/编辑/刷新）

参考作者强调：单测与细粒度测试在 vibe coding 里更重要，因为 bug 堆积后在长上下文里爆炸。

六、文档驱动开发（DDD 不是领域驱动那个 DDD）

这里的 DDD 指 Document-Driven Development：方案、接口、目录 README、决策记录（ADR）与代码同步演进。分形文档结构（第03讲）是落地工具。

七、可运行示例：用 TypeScript 记录「方案评审结论」

把评审结构化，避免口头说了就算：

// scripts/design-review.ts
// npx tsx scripts/design-review.ts

type Review = {
  feature: string;
  approved: boolean;
  changes: string[];
  blockers: string[];
};

const r: Review = {
  feature: "VibeNote Markdown 分栏预览",
  approved: true,
  changes: ["预览使用 debounce 300ms", "禁止引入新编辑器依赖"],
  blockers: [],
};

console.log(JSON.stringify(r, null, 2));

八、完整工作流示例（你可以复制当 checklist）

需求：一句话 + 非目标
让 AI 输出方案（含文件清单/风险）
你修订方案并写 docs/adr/xxx.md（可选）
分模块让 AI 实现，每模块后验证
合并前更新目录 README
复盘：哪些假设错了，规则文件要不要补

九、与 Prompt / Workflow / 规则文件的关系

第01讲：单次指令质量
第02讲：流程与检查点
第03讲：上下文调度
第04讲：被动规则
第05讲：调试工序
本讲：把「设计」变成显式锚点——它们是乘法关系。

十、思考题

你最近一次「先写代码后补方案」的返工成本是多少？
你会把「方案必须包含文件清单」写进团队规范吗？
你如何防止方案审完却没人更新文档？

十一、下讲预告

下一讲项目实战：VibeNote V2.0，Markdown 分栏预览 + AI 写作助手，把模块二所有方法一次性落地。

参考阅读：reference/practice/vibe-coding-methodology.md（方案先行、小步验证、文档记忆）。

十二、方案模板（VibeNote 可直接复制）

背景与目标

用户故事：
成功标准（可验证）：

非目标（本期不做）

模块与文件清单（预测）

path — 职责一句

数据流

输入 / 状态 / 持久化

API 与类型契约

请求 / 响应 / 错误语义

风险与缓解

验证计划

命令 / 手工路径 / 边界用例

十三、方案评审「红灯问题」清单

失败时用户看到什么？
幂等吗？重复点击会怎样？
需要迁移吗？如何回滚？
性能与安全边界是什么？

十四、分模块颗粒度：不大不小

一个 PR 一个可演示竖切
单 PR 文件数设软上限
每模块结束可 build

十五、方案 v0 → v1：追问就是审查

第一轮输出方案 v0，用红灯清单追问得 v1，再批准实现。

十六、方案阶段就列验收用例

用 Given/When/Then 描述 3～5 条，哪怕先手工执行。

十七、何时写 ADR

新依赖、数据模型变化、安全策略变化、关键业务规则变化——满足任一就写。

十八、方案批准后仍漂移怎么办

新需求新开工单，不混进同一实现线程。

十九、VibeNote V2 方案里必须先锁的四件事

textarea 是否保留、AI 是否仅服务端、流式状态机、失败时是否仍可保存。

二十、可运行示例：模块队列 JSON

// scripts/module-queue.ts
import { writeFileSync } from "node:fs";

const q = {
  feature: "v2-markdown-ai",
  modules: [
    { id: "types", tasks: ["NoteDraft 类型", "zod schema"] },
    { id: "api", tasks: ["/api/ai/writing route"] },
    { id: "ui", tasks: ["MarkdownEditor 分栏", "toolbar"] },
    { id: "verify", tasks: ["lint", "build", "manual"] },
  ],
};

writeFileSync("docs/module-queue.json", JSON.stringify(q, null, 2));
console.log("written docs/module-queue.json");

二十一、团队阻力：用数据说话

统计两周返工 issue 里「范围/契约不清」占比，用数字推动方案先行。

二十二、时间盒：方案 45 分钟必须出 v0

没有 v0 就不允许改代码。v0 可以丑，但不能没有文件清单与风险。

二十三、与调试的接口

方案写清契约，调试时结构化工单会更短。

二十四、与规则文件的接口

反复出现的方案约束应下沉到 AGENTS.md。

二十五、本讲第二小结

锚点、颗粒度、红灯清单、文档同步，四件事一起做，AI 生成会从「快而飘」变成「快且稳」。

二十六、补充思考题

你愿意把「无方案不编码」写进规则吗？
你如何衡量方案先行是否真的省时间？

二十七、收束

方案先行实现为后，本质是把思考外置成可审查工件。

二十八、把方案当作合同初稿

对方案苛刻一点，未来合并冲突会少一点；对方案宽容一点，未来加班会多一点。

二十九、给 Tech Lead 的三问

本周多少 PR 缺影响面说明？多少改动没更新目录 README？多少 AI 改动引入未解释依赖？

三十、给 solo 的三问

三句话说清竖切价值吗？知道哪些文件不能动吗？写得出验证命令吗？

三十一、结语

把方法用进下一讲 VibeNote V2.0 实战：你会看到锚点如何减少返工。

参考阅读：`reference/practice/vibe-coding-methodology.md`（方案先行、小步验证、文档记忆）。

三十二、方案与原型

原型验证需求，方案锁定实现。别用方案写一堆幻想，原型负责把幻想落地成选择。

三十三、方案与估时

方案阶段给出区间估时：实现/测试/文档各占多少。没有估时的方案往往会在实现阶段偷偷膨胀。

三十四、方案与依赖

把依赖新增单列一节：为什么需要、替代方案、体积影响、维护成本。

三十五、方案与可观测性

从方案里指定日志字段与错误码，不要等上线再补。

三十六、方案与国际化

若 VibeNote 未来要多语言，方案里先写文案策略，避免后面全局替换。

三十七、方案与性能

首屏、列表、编辑器输入延迟，至少点三项给预算。

三十八、方案与安全

AI 功能写清提示注入防护、输出过滤、密钥管理。

三十九、方案与可访问性

编辑器工具栏要键盘可达；方案里写一句就够，别靠自觉。

四十、方案与移动端

textarea 分栏是否在窄屏改为上下堆叠？方案里决定，别交给模型临场发挥。

四十一、方案评审记录

评审结论要落盘：谁批准、改了什么、为什么。

四十二、方案与测试数据

准备三类测试笔记：空、极大、含代码块与表格。

四十三、方案与回滚

说明如何关闭 AI 功能开关（feature flag）。

四十四、方案与文档同步

列出必须更新的 README 路径。

四十五、方案与发布

是否需要迁移、是否需要双写、是否需要灰度。

四十六、从方案到任务拆解

把方案文件清单映射为 issue 列表，一项一项合并。

四十七、避免方案中的「顺便」

任何顺便都要单独立项，否则范围必炸。

四十八、方案写作的语言

用短句、用列表、少用形容词；模型更容易遵守。

四十九、让 AI 参与评审而不是替你做决定

可以让 AI 对方案做挑战清单，但最终拍板在人。

五十、结语

方案先行不是官僚，是你在高速生成时代保留掌控感的抓手。

五十一、把方案当作「类型系统」：越早约束越便宜

在 TypeScript 里，类型错在编译期比在运行期便宜。方案就是需求层的类型：边界错在方案阶段比在上线后便宜。你不会在业务代码里回避类型，也不应该在真实项目里回避方案。尤其对 VibeNote 这种涉及用户数据的产品，方案里的安全与权限段落不是可选项。

五十二、方案与协作：让评审可异步

把方案贴进 PR 或 issue，同事用评论逐条质疑。你再把结论合并回方案正文。异步评审比会议更高效，也更适合分布式团队。AI 可以帮你生成「评审问题清单」，但别让它替同事签字。

五十三、方案与工具：不要被工具带跑

无论你用 Cursor、Claude Code 还是其他代理，方案先行的纪律不变。工具只会改变你写方案的速度，不应改变你是否写方案。把纪律写进规则文件（第04讲），工具升级时你也不会失守。

五十四、方案与债务：识别「隐性债务句」

方案里如果出现「先简单做」「以后再优化」「临时处理」，你要高亮它们：它们往往是债务种子。不是不能写，但必须配到期条件：什么时候还、谁来还、怎么验收还清。

五十五、最终收束

方案先行实现为后，是一条让你越用越省的路。你开始会慢，后来会稳；稳到一定程度，速度会回来，而且是高质量的速度。下一讲我们用 VibeNote V2.0 把这条路走完整。

五十六、方案里的「数据模型」段落怎么写

先写实体字段与约束，再写读写路径。对笔记产品，至少覆盖：标题、正文、标签、更新时间、删除软删与否。字段越具体，AI 生成 DAO/Server Action 越不容易漏校验。

五十七、方案里的「状态管理」段落怎么写

说明哪些状态是 URL 驱动，哪些是本地 UI 状态，哪些是服务端真相。编辑器里常见坑是把草稿状态同时放多处，最后不同步。方案里用一句话定「单一数据源」。

五十八、方案里的「错误处理」段落怎么写

列出可预期错误：网络失败、模型失败、校验失败、权限失败。每种错误对应 UI 与可重试策略。没有这张表，AI 很容易只写 happy path。

五十九、方案里的「流式输出」段落怎么写

写清取消策略、卸载清理、loading 与 partial 文本展示规则。流式是体验利器也是 bug 源，方案不写清就会死在边界上。

六十、方案里的「性能」段落怎么写

Markdown 预览 debounce 多大、是否需要 web worker、长文输入是否分块渲染。给预算而不是给形容词。

六十一、方案里的「安全」段落再强调

用户笔记内容可能包含恶意提示词，方案要写「系统提示与用户材料分离」与「输出不可执行」原则。

六十二、方案评审的参与者

至少包含实现者与审查者；涉及数据要有业务方；涉及合规要有负责人。不是形式，是风险共担。

六十三、方案更新策略

实现中发现方案不适用，先改方案再改代码。代码先行改方案后补，是最常见的漂移来源。

六十四、与第02讲 Workflow 的对齐

方案票→审查票→实现票→验证票，四张票把本讲落到日常。

六十五、与第05讲调试的对齐

方案写清契约，调试更少猜。契约越像 OpenAPI，越利于结构化调试。

六十六、练习：给 VibeNote V2 写一页方案

不用完美，但必须包含文件清单与风险。写完再对照红灯清单自检。

六十七、练习：让 AI 挑战你的方案

要求 AI 输出「十个可能翻车的点」，你再逐条标注接受/拒绝/延后。

六十八、别用方案逃避交付

方案时间盒结束就必须进入实现。方案不是拖延许可证。

六十九、方案与里程碑

把里程碑定义成可演示节点，而不是「完成 80%」。可演示才是硬标准。

七十、最后一句话

先想清楚再动手，不是慢，是把慢挪到最便宜的地方。

延展1、方案先行与组织文化

组织如果奖励「立刻出活」而不奖励「把边界写清」，方案先行会被阳奉阴违。你要用制度对齐：把方案审查作为合并门槛之一，把返工率纳入复盘。个人可以自律，团队要靠机制。VibeNote 作为课程项目，你现在是自己的 Tech Lead，请对自己狠一点：没有文件清单就不写代码。坚持两周，你会感到合并冲突减少、对话变短、AI 输出更一致。方案不是写给老板的，是写给未来自己的。未来你会感谢现在多写的半页纸。

延展2、方案先行与组织文化

延展3、方案先行与组织文化

延展4、方案先行与组织文化

延展5、方案先行与组织文化

延展6、方案先行与组织文化

五十六、把「方案评审」变成团队仪式

每周固定 30 分钟，只评审方案不写代码。每个人带一个一页纸方案，互相用红灯问题挑战。你会看到方案质量整体上升，而会议时间反而下降。

五十七、与个人知识库联动

把成功方案与失败方案都放进你的笔记系统（例如 VibeNote 自己）。标签用「方案模板」「返工案例」「红线清单」。这是在给未来的自己留上下文。

五十八、收束重申

方案先行实现为后，不是慢，是把错误提前到最便宜阶段。你掌握它，AI 才是杠杆；否则 AI 只是放大器。

五十九、与下一讲的桥

下一讲项目实战会把方案先行落实成 VibeNote V2.0 的文件清单与 PR 分段。你会看到「锚点」在真实仓库里长什么样。

六十、最后一句话

先设计后写代码，不是迂腐，是专业。专业的人不是不写快，而是知道哪里该慢。

六十一、练习：给自己设一条硬规则

本周只允许自己在「方案一页纸」存在的情况下让 AI 改超过两个文件。违反就复盘为什么想跳过。你会很快看清自己的侥幸心理。

六十二、再补一段

当你把方案先行练成习惯，你会发现 Prompt 变短了，因为大量约束已经提前写进方案与规则文件。这才是「少写提示词」的正道。

六十三、结语

把本讲打印成一页「红灯清单 + 方案模板」，贴在你显示器旁边。它比收藏一百篇 AI 文章更有用。

六十四、真·收束

方案先行实现为后，是模块二的总纲。你掌握它，前面五讲才有落点；你忽略它，前面五讲只是散点技巧。

六十五、下一讲预告（再强调）

下一讲是 VibeNote V2.0 实战：你会把方案模板填成真实文件清单，把 PR 分段变成真实合并记录。别只看不做。

去做。别光读。读一百遍不如做一遍。做一遍胜过收藏十次。收藏不会帮你交付。交付才重要。坚持下去你会看到复利。复利比短期爽更重要。记住这句话。真的。去吧。走。好。行。

2.6 方案先行实现为后——让 AI 代码质量翻倍的核心技巧