让 Agent 写代码之前，先让它把想法写在纸上：一套经过验证的 AI 编程工作流

目标读者：经常使用 AI 辅助编程的开发者、技术 Leader 或对 AI 提效感兴趣的工程师。
核心价值：获得一套能彻底解决 AI 编写复杂代码时“架构跑偏”和“静默错误”的实操工作流。
阅读时间：6 分钟

AI 写代码最大的灾难不是语法报错，而是架构崩塌；把 AI 从执行者变成被审阅的作者，才是真正的提效解法。

为什么你越用 AI 写代码，技术债越多？

每当看着项目中那个能跑通却完全绕过了统一错误处理中间件、自己 try-catch 了一套野路子逻辑的 AI 生成模块，你是不是也感到一阵无力？

在 AI 辅助编程领域，大多数人的姿势是这样的：抛出需求 -> AI 生成 -> 报错再修 -> 循环往复。这种“无尽的生成-修复死循环”在写简单脚本时很爽，但在复杂业务逻辑面前，通常会以系统崩塌告终。

经过不断的摸索与试错，许多高阶开发者逐渐形成了一套共识：在 AI 动手写代码之前，必须先让它把想法完整地“写在纸上”。

静默错误：AI 生成代码的致命陷阱

AI 最大的失败往往不是写出带有明显语法错误的代码。编译器或解释器能轻易抓住那些明显的错误。

真正致命的，是那些在局部能够完美运行，却把整个系统架构搞坏的代码。

例如：

• 一个绕过了现有消息队列、直接同步调用下游服务的订单处理模块。
• 一个无视项目统一鉴权中间件、自己重写了一套 Token 校验逻辑的接口。
• 一个与现有日志采集管道完全脱节、到处散落 console.log 的监控组件。

这类错误安静、隐蔽，不仅难以排查，还会成为未来系统的巨额技术债。解决这个问题的核心，就是阻止 AI 的冲动，强迫它“三思而后行”。

核心方法论：把 AI 变成“被审稿的作者”

真正的价值不是 AI 的生成能力，而是我们与 AI 之间的“对齐”。 代码写错了有报错拦截，但架构方向错了，只有人类能察觉。

我们可以通过以下三个步骤，将 AI 从一个鲁莽的“执行者”，训练成一个需要不断被审阅和批注的“作者”。

第一步：深度调研（Research）—— 在纸面上消灭认知偏差

不要让 AI 在对话框里口头告诉你它的理解，而是要求它将对现有代码库的理解，正式地写入一个单独的文档（例如 research.md）。

在这个阶段，你的 Prompt 应该密集出现“深入”、“现有架构”、“边界条件”等词汇。告诉 AI：别走马观花，去挖掘系统的复杂性。

示例指令：”请深入阅读 src/order/ 目录下的所有文件，梳理当前订单状态流转和支付回调的完整链路。将理解写入 docs/research.md。在这个阶段，绝对不要写任何实现代码。”

这份文档的受众是你自己。你需要通过阅读它，验证 AI 是否真的吃透了系统现状。任何误解都必须在这一步被无情消灭，绝不能存活到编码阶段。

第二步：规划与批注循环 —— 注入人类的隐性知识

在验证了 AI 的理解后，进入规划阶段。要求 AI 生成详细的实施计划文档（例如 plan.md）。当 AI 生成计划后，最核心的工作流来了：不要在对话框里纠正它，而是直接在 plan.md 中添加你的批注。

示例场景：
AI 在计划中写道：”新增一个 NotificationHelper 工具类来发送站内信和邮件。”
你在文档中直接批注：”[人类批注：项目已有 MessageBus 统一推送通道，禁止新建发送入口，必须复用现有通道。]”

把带有批注的文档扔回给 AI，并附上那句最关键的指令：“按注释更新计划文档。注意：先不要写代码！”

这个循环可能需要重复两到六次。AI 懂得写优美的算法，但它不知道产品优先级和历史包袱。批注循环，正是将人类脑海中的隐性知识转化为明确指令的过程。

第三步：无聊的执行 —— 照单全收与持续追踪

当 plan.md 被打磨得无懈可击，并且附带了清晰的待办清单时，创造性的脑力劳动其实已经结束了。接下来的执行阶段，你应该期望它变得极度“无聊”和机械。

示例指令：“严格按照 plan.md 的步骤实现。每完成一项，就在计划文档中打个勾（[x]）。不到所有任务完成不要停。”

在这个阶段，你的纠错可以变得极其简短：

• “你漏掉了 plan.md 中要求的 retryWithBackoff 重试机制。”
• “表单校验的错误提示文案不对，参照设计稿改一下。”

因为上下文极度清晰，一两句话就足以让 AI 拨乱反正。**如果遇到大面积的逻辑崩盘，最佳策略是直接 Git 回滚，缩小任务范围后重来。**缩小范围重做，永远比在烂摊子上修修补补要高效得多。

为什么这种方法最有效？

1. 抵抗上下文退化：随着对话深入，AI 表现会退化。但 plan.md 作为物理文件，是系统状态的“锚点”，随时可以重新指向它。
2. 化解静默错误：不写计划直接写代码，绕过消息队列直接同步调用的错误难以察觉。但在计划阶段，这种架构错误在纸面上无所遁形。
3. 激发深层推理：强迫 AI 写文档，实际上是在激发其更深层次的推理能力（Chain of Thought），显著提升最终代码质量。

结语：理清思路，再谈生成

这套工作流没有用到任何魔法 Prompt。它的本质极其朴素：**在动手之前，把思路逼到纸面上，反复修改直到满意为止。**写作的秘密从来不是下笔如神，而是改稿改到吐；AI 辅助编程同样如此。

这套流程也戳破了一个幻觉：AI 并不能替你思考。让 AI 先把想法写在纸上，不仅是在审阅机器，也是在倒逼我们自己理清思路。