AI编程双阶段工作流：规划与执行分离提升开发效率

1. 项目概述：基于规格驱动的双阶段AI编码工作流

如果你和我一样，每天都在和AI编程助手打交道，那你肯定也经历过这种循环：给AI一个需求，它写出一堆代码，你发现逻辑不对或者架构有问题，然后开始漫长的“提示词迭代”——来回修改、补充细节、纠正方向，直到AI终于“理解”了你的意图。这个过程不仅耗时，而且在不同会话间切换时，上下文丢失更是让人头疼。今天要聊的这个项目，nicksp/ai-coding-workflow，就是为了彻底终结这种低效循环而生的。它不是什么新奇的框架，而是一套经过实战打磨的、基于“规格驱动开发”理念的双阶段工作流，核心思想是把“想”和“做”彻底分开，让AI各司其职。

简单来说，它定义了两种AI“人格模式”：规划师和执行者。规划师负责和你一起，把模糊的需求变成一份滴水不漏的技术规格说明书；执行者则像一位严谨的工程师，只认这份说明书，埋头把代码实现出来。这套方法最大的魅力在于，它把最耗时的“需求对齐”和“架构设计”过程固化成了一个可复用、可协作的文档资产，而不是消散在聊天记录里的碎片信息。无论你是独立开发者，还是团队协作，这套工作流都能显著提升AI编码的确定性、代码质量，并让你在不同AI工具间无缝切换时，依然保持上下文连贯。

2. 核心工作流拆解：为什么“先规划，后执行”如此有效

2.1 规划阶段：与AI架构师共创蓝图

规划阶段的核心产出物是一份名为prd.md的规格文档。这个阶段，你启用的AI是“规划师”模式。它的角色不是直接写代码，而是扮演一个经验丰富的技术负责人或系统架构师，引导你完成一次结构化的需求分析和技术设计。

这个过程的精妙之处在于交互性。规划师不会让你一次性扔给它所有需求。相反，它会通过一系列问题来引导你，比如：

• 核心功能：这个功能到底要解决用户的什么问题？最核心的交互流程是什么？
• 用户故事：从用户视角看，完成这个功能需要哪些步骤？
• 技术约束：需要兼容哪些现有API？有性能或安全方面的特殊要求吗？
• 数据模型：涉及哪些新的数据结构？与现有数据库表如何关联？
• 接口设计：需要新增或修改哪些API端点？请求和响应的格式是什么？
• 边界情况：错误处理逻辑是怎样的？输入验证的规则是什么？

通过这一问一答，规划师会逐步将你的想法具象化，并生成一份结构清晰的prd.md。这份文档通常位于docs/specs/{feature-name}/目录下，内容会包括功能概述、用户流程、API规范、数据库变更、甚至测试要点。关键在于，在最终“批准”这份规划之前，你有充分的机会进行审查和修改。这相当于在写第一行代码之前，就完成了一次详细的设计评审，从根本上避免了后续返工。

实操心得：在规划阶段，不要怕“啰嗦”。把你能想到的所有细节、顾虑甚至“愚蠢的问题”都抛出来。规划师的价值就在于帮你把这些模糊地带理清。一个常见的技巧是，在描述需求时，可以附带一两个你期望的代码片段示例或伪代码，这能极大帮助AI理解你的技术偏好和项目风格。

2.2 执行阶段：让AI工程师严格按图施工

一旦prd.md被批准，你的工作就切换到了“执行者”模式。此时，AI的角色转变为一位一丝不苟的工程师。它的首要任务是读取并理解那份已批准的规格文档，然后开始实现。

执行者模式的核心原则是“唯规格论”。它不会再去质疑或重新设计架构，它的目标就是以最高效、最准确的方式，将prd.md中的文字描述转化为可运行的代码。这带来了几个显著优势：

1. 确定性高：由于输入（规格）是明确且固定的，输出的代码质量非常稳定，减少了“跑偏”的可能。
2. 上下文完整：执行者可以访问整个项目文件夹的上下文，结合prd.md，它能精准理解代码应该放在哪里、如何与现有模块集成。
3. 自动化程度高：在这个阶段，你可以放心启用“自动运行”等工具，让AI自主地创建文件、编写代码、运行测试命令，你只需要做最后的代码审查。

这种清晰的职责分离，模仿了现实中高效的软件工程团队：产品经理/架构师定方案，工程师负责实现。AI在这两个角色上都表现出色，但混在一起用就会产生混乱。

3. 主流工具配置详解与避坑指南

项目提供了对 Cursor、Kilo Code、Amp 和 GitHub Copilot 的详细配置方法。这里我结合自己的使用经验，深入解析其中关键配置点的考量与常见陷阱。

3.1 Cursor 配置：追求极致的工作流集成

Cursor 因其深度集成 VSCode 和对 AI 工作流的原生支持，成为实践这套方法的首选工具之一。

规划师模式配置要点：

• 模型选择：推荐使用Gemini 2.5 Pro或GPT-5这类顶级模型。原因在于规划阶段需要强大的推理、分解和创造性思维能力，模型的能力上限直接决定了规格书的质量。小模型可能无法胜任复杂系统的设计。
• 工具权限：只需开启“搜索”和“编辑（仅限重新应用）”即可。“编辑并重新应用”这个选项很重要，它允许AI生成prd.md的草稿，然后由你审核后一次性应用，而不是边聊边改，保持了文档的完整性。
• 自动化关闭：务必禁用“自动应用编辑”和“自动运行命令”。在规划阶段，我们需要的是思考和讨论，任何自动化的代码修改都是干扰，且可能破坏现有项目。

执行者模式配置要点：

• 模型选择：Claude Sonnet 4.5是绝佳选择。它在代码生成、遵循指令和长上下文处理上表现优异，且速度较快，性价比高，适合高强度的实现工作。
• 工具权限：可以开启所有可用工具，包括运行命令、终端操作等。这是执行者能够“自主”工作的基础。
• 自动化策略：可以启用“自动运行命令”。例如，AI在实现一个函数后，可以自动运行相关的单元测试来验证。这能形成一个快速的反馈闭环。

避坑指南：在Cursor中，自定义模式的“上下文”设置里，一定要选择“完整文件夹上下文”。如果只选择“打开的文件”，执行者将无法全面了解项目结构，导致生成的代码集成度差。另外，两个模式的快捷键（如Cmd+Shift+1/2）一定要设置成顺手的，这是流畅切换的关键。

3.2 Kilo Code 配置：精细化的权限控制

Kilo Code 提供了更细粒度的工具权限控制，这对于安全性和专注度要求高的场景非常有用。

规划师模式的核心配置在于其group配置中的文件类型限制：

groups: - read - - edit - fileRegex: \.md$ description: Markdown files only - browser

这段配置的意思是：规划师模式只能编辑.md结尾的Markdown文件。这是一个极其聪明的安全措施。它强制规划师只能产出文档（prd.md），从根本上杜绝了它不小心（或在你未授权时）去修改源代码的可能，确保了职责的纯粹性。

执行者模式则相反，应该赋予其完整的文件编辑、命令运行等权限，让它有能力去执行任何必要的实现任务。

3.3 Amp 配置：通过提示词工程实现模式切换

Amp 的设计哲学不同，它没有内置的“模式”概念。但我们可以通过一个名为AGENTS.md的配置文件来“模拟”出不同的AI人格。

操作步骤：

1. 在你的用户目录（$HOME/.config/）或项目根目录创建AGENTS.md文件。
2. 将prompts/planner.md和prompts/executor.md的全部内容分别粘贴到以/Planner和/Executor开头的区块下。
3. 在聊天时，只需输入/Planner或/Executor，Amp 就会加载对应的长篇指令集，进入该模式。

这种方式的优缺点：

• 优点：极度灵活，不依赖特定工具的功能，理论上在任何支持长上下文和自定义指令的AI工具中都能实现。
• 缺点：模式不是“持久化”的。每次新开一个聊天线程（Thread），或者进行了一段与模式无关的对话后，你需要重新输入/Planner或/Executor来唤醒对应人格。这需要一点额外的操作纪律。

3.4 GitHub Copilot 配置：在生态内无缝衔接

对于深度集成在 VSCode 和 GitHub 生态中的开发者，使用 Copilot Chat 的自定义模式也是一个好选择。配置方式类似于 Cursor，将提示词内容填入对应的模式描述文件中即可。

一个关键细节：在 Copilot 的模式配置中，你可以为不同模式指定不同的底层模型（如为规划师用 GPT-5，为执行者用 Claude Sonnet）。这充分利用了微软提供的多模型后端，让你可以根据任务特性选择最佳“大脑”。

4. 从理论到实践：一个完整的功能开发案例

让我们通过一个具体的例子，看看这套工作流如何落地。假设我们正在开发一个简单的博客系统，现在需要增加“文章草稿自动保存”功能。

第1步：启动规划师在 Cursor 中按下Cmd+Shift+1，切换到“☂ Planner”模式。

第2步：描述需求我对AI说：“我们需要为博客文章编辑器添加自动保存草稿的功能。用户在编辑文章时，系统应该定期（比如每30秒）或在检测到用户暂停输入时（比如停止输入后2秒），自动将当前内容保存为草稿。草稿应与文章关联，用户下次进入编辑时可以恢复。请帮我规划这个功能。”

第3步：交互式规划规划师开始提问并引导：

1. 触发机制：你希望是纯时间间隔（30秒），还是防抖（Debounce）模式，或是两者结合？
2. 数据存储：草稿是保存在前端（如LocalStorage）作为临时缓存，还是必须持久化到后端数据库？如果存后端，是新建一个drafts表，还是在现有的posts表中增加一个draft_content字段？
3. 用户体验：如何向用户提示‘已自动保存’？需要显示上次保存时间吗？如果网络失败导致保存失败，如何处理？
4. 技术实现：前端使用什么技术？是原生的setInterval和oninput事件，还是使用像 RxJS 这样的响应式库？后端API接口如何设计？（PUT /api/posts/:id/draft？）
5. 冲突处理：如果用户在多个标签页编辑同一篇文章，自动保存的草稿如何处理冲突？

经过几轮问答，规划师生成了一份docs/specs/auto-save-draft/prd.md。我审查了这份文档，特别关注了它提出的“采用防抖模式（停止输入2秒后保存）为主，结合心跳检测（每60秒强制保存一次）为辅”的方案，以及将草稿作为posts表的一个jsonb类型字段draft_data的设计。我觉得合理，于是“批准”了这个计划。

第4步：切换执行者按下Cmd+Shift+2，切换到“✈ Executor”模式。我甚至不需要再给任何指令。

第5步：自动执行执行者自动读取了刚批准的prd.md。它开始工作：

1. 首先，它分析了现有的prisma/schema.prisma文件，然后生成并运行了向Post模型添加draft_data Json?字段的迁移命令。
2. 接着，它在app/api/posts/[id]/draft/route.ts中创建了新的API路由，实现了GET（获取草稿）和PUT（更新草稿）的逻辑。
3. 然后，它转到前端的文章编辑器组件，使用useEffect和setTimeout实现了防抖逻辑，并集成了调用新API的saveDraft函数。
4. 最后，它在UI上添加了一个小小的“已自动保存于 XX:XX”的状态提示。

整个过程，我几乎不需要干预。执行者严格遵循规格书，遇到不确定的地方（比如某个工具函数的具体位置），它会主动搜索代码库来确认。我只需要在它完成每个逻辑块后，浏览一下代码，检查是否有明显的错误。

5. 高级技巧与个性化定制

5.1 提示词的精髓：角色、规则与约束

这套工作流的核心资产是planner.md和executor.md这两个提示词文件。它们之所以有效，是因为其严谨的结构：

• 明确的角色定义：开篇就用<persona>标签（或在非Kilo Code工具中用强语气）定义AI的“人设”，例如“你是一位资深软件架构师”、“你是一名严谨的软件工程师”。这为后续所有行为设定了基调。
• 清晰的工作流程：一步一步告诉AI该做什么。对规划师是“引导用户、提问、生成文档、等待批准”；对执行者是“读取规格、理解上下文、分步实现、报告进度”。
• 严格的输出格式约束：要求规划师必须将输出组织成特定的Markdown标题结构（如“## 概述”、“## API规范”），这保证了生成的prd.md格式统一，便于执行者解析，也便于人类阅读。
• 工具使用规范：明确告诉AI在什么阶段使用什么工具。例如，要求执行者在修改数据库前必须运行git diff确认更改，在运行命令前解释其目的。

个性化定制建议：你可以且应该根据自己团队的技术栈和规范修改这两个提示词。例如，如果你的团队使用 Jira，可以在规划师提示词中加入“请将需求拆解为符合INVEST原则的用户故事，并输出到Jira导入格式”。如果你的项目有特定的代码风格检查工具（如 ESLint, Prettier），可以在执行者提示词末尾加上“所有生成的代码在提交前必须通过npm run lint和npm run format”。

5.2 规格文档作为团队协作的单一事实源

prd.md的价值远不止于驱动AI。它成为了项目的活文档。

• 新成员 onboarding：新人可以通过阅读docs/specs/目录下的文件，快速理解每个功能的来龙去脉和技术决策。
• 代码审查：审查者可以对照prd.md来检查代码是否完全实现了设计，审查效率更高。
• 回溯与维护：半年后当这个功能出现Bug时，开发者可以快速找到当初的设计文档，理解当时的意图和边界条件，而不是去猜测“这段代码为什么这么写”。

你可以将生成prd.md的流程纳入团队的Git工作流，要求每个新功能分支都必须包含对应的规格文档，并在合并请求中作为必须审查的内容。

5.3 与其他AI编码范式的结合

这套“规划-执行”范式并不排他，它可以与其它优秀实践结合：

• 与“测试驱动开发”结合：在规划阶段，就让规划师一并输出关键功能的测试用例描述。在执行阶段，执行者可以先写测试（红），再实现功能（绿），最后重构。
• 与“逐步提示”结合：对于极其复杂的模块，可以在执行阶段手动介入，将大任务分解为几个子任务，分多次让执行者完成，每次只关注一个子规格。
• 作为“AI编码规范”的载体：你可以将项目的编码规范、架构原则等写入规划师的提示词背景中，这样它产出的规格自然会符合团队规范，进而指导执行者产出风格一致的代码。

6. 常见问题与实战排坑记录

在实际使用中，你可能会遇到以下问题。这里是我踩过坑后的解决方案：

问题1：规划师提出的技术方案过于理想化或不切实际。

• 现象：AI基于通用知识设计了一个很“漂亮”的方案，但忽略了项目历史包袱或团队技术债。
• 解决方案：在启动规划师前，用几句话简要说明项目的技术约束。例如：“注意，我们当前的前端状态管理使用的是Zustand，而非Redux；后端ORM是Prisma，数据库是PostgreSQL。”更有效的方法是，在规划师的提示词中预设这些上下文。或者，在交互过程中，当AI提出一个方案时，直接指出“这与我们现有的X模式冲突，请考虑基于Y来实现”。

问题2：执行者错误理解了规格文档的某一部分。

• 现象：生成的代码逻辑与prd.md中的描述有偏差。
• 解决方案：首先，检查prd.md本身是否描述清晰、无二义性。AI是按字面意思理解的。其次，在执行者开始工作前，可以给它一个明确的指令：“请先复述你对规格文档中‘冲突解决策略’部分的理解，确认无误后再开始编码。”这相当于一次需求澄清。最后，如果错误发生，不要直接修改代码，而是应该回到规划阶段，修正prd.md，然后重新批准，再让执行者基于新规格重做或修正。这保持了工作流的纯洁性。

问题3：在大型项目中，执行者因上下文长度限制，忽略了关键代码。

• 现象：项目文件众多，AI的上下文窗口无法装入所有相关代码，导致它实现新功能时没有正确引用已有的工具函数或组件。
• 解决方案：利用好“搜索”工具。在执行者的提示词中，可以强调“在实现过程中，如果对现有代码结构不确定，请主动使用搜索工具查找相关函数、组件或接口定义”。此外，可以在prd.md中明确列出关键依赖文件的路径，引导AI优先关注这些文件。

问题4：不同AI工具间切换时，提示词格式不兼容。

• 现象：为 Cursor 写的提示词，直接复制到 Copilot 中可能因为工具指令集不同而报错或失效。
• 解决方案：维护一个“提示词核心版”。剥离掉工具特定的指令（如 Cursor 的@workspace或特定工具调用语法），只保留通用的角色定义、工作流程和输出格式要求。然后为每个工具（Cursor, Kilo Code, Copilot）分别创建一个“适配层”文件，将核心提示词与工具特定的指令拼接起来。这样更新核心逻辑时，所有工具的配置都能同步更新。

问题5：自动运行命令导致意外系统更改或破坏。

• 现象：执行者模式开启了“自动运行”，它在运行数据库迁移或安装依赖时，不小心破坏了环境。
• 解决方案：这是风险最高的部分。务必在执行者模式中，对“运行命令”工具保持审慎。一种策略是，对于高风险操作（如docker-compose down,rm -rf, 生产数据库迁移），在提示词中明确禁止AI自动运行，必须等待用户确认。另一种策略是，在安全的开发分支或容器化环境中进行AI驱动的开发，即使出错也能快速重置。

这套nicksp/ai-coding-workflow本质上是一种元方法，它教会我们的不是某个具体的编程技巧，而是如何高效地“管理”AI这个强大的、但有时方向感不佳的合作伙伴。通过将开发过程标准化、文档化，我们不仅获得了更好的代码和更快的速度，更重要的是，我们获得了可预测性和控制感。在AI辅助编程逐渐成为主流的今天，建立这样一套严谨的工作流，可能是区分随意使用AI和真正利用AI提升工程效能的关键一步。我的体会是，初期投入时间熟悉和定制这套流程，会在后续无数个功能开发中，以复利的形式回报你。