1. 项目概述基于规格驱动的AI编码双阶段工作流如果你和我一样每天都在和Cursor、Claude、GitHub Copilot这些AI编码助手打交道那你肯定也经历过这种循环给AI一个需求它写出一堆代码你发现不对再解释它再改来回拉扯好几轮最后出来的东西可能还是和你的架构设想有偏差。时间都花在了沟通和修正上而不是真正的创造性工作上。我最近在实践一个来自开源项目nicksp/ai-coding-workflow的方法论它彻底改变了我和AI协作的方式。这套方法的核心我称之为“规格驱动的双阶段工作流”它把AI编码从一个模糊的对话过程变成了一个清晰、可重复、高质量的工程化流程。简单来说它引入了两个明确的角色规划师和执行者。规划师负责和你一起把模糊的想法变成一份详尽、无歧义的技术规格说明书执行者则是一个严格的“施工队”只认这份说明书负责把它精准地实现成代码。这听起来像是增加了步骤但实际上它通过前置的、结构化的思考极大地减少了后续的返工和迭代。我实践了几周后发现对于中等复杂度的功能整体交付时间缩短了至少30%而且代码质量显著提升因为执行阶段的AI不会自作主张地“发挥”而是严格遵循我们共同制定的蓝图。这个方法特别适合需要长期维护的项目、团队协作的场景或者当你需要中途暂停一个任务过几天再回来接着做时。它通过一个中心化的prd.md文件把“需求-设计-实现”的链路固化下来成为了项目知识的一部分而不仅仅是某次AI聊天会话里的临时记忆。接下来我会详细拆解这套工作流的设计思路、在不同工具中的具体配置方法以及我在实操中积累的一系列能让你事半功倍的心得和避坑指南。2. 核心工作流设计思路拆解2.1 为什么需要“规划”与“执行”分离在传统的AI编码对话中我们往往让同一个AI模型身兼数职既要理解业务又要设计架构还要编写代码。这就像让一位建筑师同时去工地砌砖角色冲突必然导致效率低下。AI模型在单次对话中的“上下文”是有限的并且存在注意力漂移的问题。当你要求它为一个复杂功能编写代码时它可能在前半段还记着架构约束写到后半段就只专注于实现某个局部逻辑从而忽略了整体的设计一致性。“规划与执行分离”正是为了解决这个根本矛盾。其背后的逻辑借鉴了软件工程中经典的“设计-实现”瀑布模型思想但通过AI工具实现了快速迭代。规划阶段的核心目标是产出一份“机器可读”的规格说明书。这里的“机器”既指AI执行者也指未来的开发者包括几天后的你自己。这份文档需要清晰定义接口、数据结构、关键算法、边界条件以及非功能性需求如性能、安全性。执行阶段则变成一个相对“机械”的翻译过程将规格说明书转化为等价的、可运行的代码。由于目标单一执行AI可以更专注、更少出错。从我个人的体验来看这种分离带来了几个关键好处。首先它强制了前置思考。在规划阶段你必须和AI一起厘清所有模糊点这本身就是一个极佳的架构梳理过程能提前发现很多潜在的设计缺陷。其次它实现了关注点分离。作为人类开发者你在规划阶段是“产品经理架构师”专注于“做什么”和“怎么做”在执行阶段则转变为“代码审查员”专注于“做得对不对”。最后它带来了确定性和可复现性。一份好的prd.md就像一份合同是评估执行结果好坏的唯一标准这使得协作和验收变得异常清晰。2.2 规格说明书连接两个阶段的唯一真理源整个工作流能够运转的核心在于那份被称为“唯一真理源”的规格说明书通常是一个名为prd.md的Markdown文件。它绝不是一份随便写写的需求文档而是一份具备足够工程细节、能够直接指导编码的蓝图。一份合格的prd.md应该包含哪些内容根据项目提供的提示词模板和我自己的实践它通常包括以下几个部分功能概述用一两句话清晰说明这个功能是什么解决什么问题。用户故事/验收标准以“作为[角色]我希望[目标]以便[价值]”的格式描述并列出具体的、可测试的验收条件。技术设计这是最核心的部分。需要定义新的API端点包括URL、方法、请求/响应体结构、数据库表结构变更、核心函数或类的接口定义、关键算法步骤的伪代码、以及状态流转图。依赖与约束明确列出该功能依赖的现有模块、第三方库以及必须遵守的技术约束如响应时间100ms。测试策略指出需要进行的测试类型单元测试、集成测试以及需要覆盖的关键场景。部署与运维考量是否需要新的环境变量、配置变更或监控指标。注意在规划阶段你应该引导AI规划师主动向你提问以完善这些部分。例如如果它只给出了一个函数名你应该要求它明确参数类型、返回值类型和可能抛出的异常。这份文档的详尽程度直接决定了执行阶段的质量和顺畅度。这个文件通常会被放在一个固定的目录下例如docs/specs/feature-auth/。这种组织方式不仅便于查找更重要的是为AI执行者提供了明确的上下文路径。当切换到执行者模式时AI会首先去读取这个目录下的prd.md确保它的所有工作都基于这份已批准的规划。3. 核心工具配置与实操要点原项目提供了在Cursor、Kilo Code、Amp和GitHub Copilot等主流工具中的配置方法。我将结合自己的使用经验为你解析其中的关键配置项和容易踩坑的地方。3.1 Cursor中的深度配置解析Cursor因其强大的代码理解和编辑能力是实践这套工作流的绝佳平台。其“自定义模式”功能让我们可以精确地塑造AI的行为。规划师模式配置要点模型选择推荐使用Gemini 2.5 Pro或GPT-5。这不是炫技而是有实际考量。规划工作需要强大的推理、分解和结构化思维能力这些模型在复杂问题拆解和文档生成上表现更优。如果使用能力较弱的模型生成的规格书可能漏洞百出导致后续执行阶段不断返工。上下文务必开启“完整文件夹上下文”。规划师需要了解你的整个项目结构、现有的代码风格和技术栈才能做出合理且一致的设计。工具权限重点开启“搜索”和“编辑 - 编辑与重新应用”。搜索让它能探索现有代码库“编辑与重新应用”是生成prd.md文件的关键。最关键的一步是务必关闭“自动应用编辑”和“自动运行”。在规划阶段你需要仔细审核AI生成的每一版设计文档手动确认后再让它保存。如果自动应用一个不成熟的设计被直接写入文件可能会干扰你的思路。执行者模式配置要点模型选择推荐Claude Sonnet 4.5。执行阶段更看重代码生成的准确性、对项目上下文的快速理解以及执行速度。Sonnet 4.5在这些方面表现非常均衡且高效性价比高。工具权限可以开启所有工具包括搜索、编辑、运行命令等。执行者需要全方位的权限来完成编码、运行测试、安装依赖等任务。自动化这里与规划师相反可以开启“自动运行”对于简单的、确认安全的命令但建议保持“自动应用编辑”为关闭。这样AI可以自主运行一些npm install或go test这样的命令来验证代码但在修改核心代码文件时仍会征求你的同意给你最后把关的机会。实操心得我为两个模式设置了不同的快捷键CmdShift1 和 CmdShift2并在模式名称前加了图标☂ 和 ✈这样在Cursor的聊天窗口下拉菜单中能快速识别和切换。视觉和肌肉记忆的双重提示能让工作流切换变得非常流畅。3.2 在无模式工具中的变通方案以Amp为例像Amp这样的工具其设计哲学是“一个智能体走天下”没有官方的模式切换功能。但这难不倒我们我们可以利用其AGENTS.md的机制来“模拟”出不同的模式。具体操作如下在你的用户根目录~/.config/或项目根目录创建一个名为AGENTS.md的文件。将prompts/planner.md的全部内容复制到/Planner标题下将prompts/executor.md的全部内容复制到/Executor标题下。在Amp聊天中当你需要启动规划师时只需输入/Planner然后换行输入你的需求。Amp会加载对应的提示词并在此后的对话中保持这个“人格”。要切换回执行者或普通模式需要开启一个新的聊天线程或者明确告诉Amp“请退出当前模式回到普通对话”。这种方式的局限性状态隔离不完美Amp的上下文是连续的即使切换了“模式”之前的对话历史可能仍会产生微妙影响。严格来说不如Cursor那种真正的模式隔离干净。需要手动重置容易忘记切换模式导致用执行者的口吻去做规划或者反过来。我的建议如果主要使用Amp可以将这个工作流作为辅助。对于极其重要或复杂的任务还是建议在Cursor中完成规划和核心执行再利用Amp的强项如深度代码分析进行局部优化或审查。3.3 提示词工程理解两个角色的核心指令项目的精髓在于那两个提示词文件planner.md和executor.md。理解它们如何塑造AI行为比单纯复制粘贴更重要。规划师提示词的核心指令角色定位明确告诉AI它是“高级软件架构师”任务是引导用户创建无歧义的技术规格。交互流程它被设计成会主动提问例如“这个功能的成功标准是什么”“需要考虑哪些错误边界”“现有的User模型需要扩展字段吗” 它不会直接开始写文档而是先通过对话厘清一切。输出物格式它被严格要求将最终输出物生成到docs/specs/{feature-name}/prd.md路径下并遵循固定的Markdown模板。这保证了产出的一致性。停止条件只有在用户明确说“批准”或“确认”后它才会最终生成并保存文档。这给了用户绝对的控制权。执行者提示词的核心指令角色定位它是“一丝不苟的软件工程师”唯一目标是实现已批准的规格。输入依赖它被指示首先去查找并阅读docs/specs/目录下的prd.md文件。如果找不到它会拒绝行动并提醒用户先进行规划。行为准则它必须严格遵守规格书不得擅自添加未指定的功能或改变设计。如果发现规格书与现有代码库存在无法调和的冲突它应该暂停并询问而不是自作主张。工作方式它被鼓励采取小步快跑的方式一次只修改或创建一个文件然后运行相关的测试来确保没有破坏现有功能之后再继续下一步。避坑指南不要直接使用项目提供的原始提示词而不做任何调整。你应该根据自己项目的技术栈是ReactNode.js还是Go抑或是Python数据管道和团队规范对提示词进行微调。例如在规划师提示词中可以加入“请遵循本项目采用的REST API设计规范”或“数据库迁移请使用Liquibase格式”。在执行者提示词中可以指定“单元测试使用Jest框架并达到90%分支覆盖率”。这种定制化能让AI的输出更贴合你的实际环境。4. 完整工作流实操过程与核心环节理论说再多不如看一次完整的实战。假设我要在一个任务管理Web应用类似简化的Jira中新增一个“任务依赖关系”功能任务A完成后才能开始任务B。4.1 第一阶段与规划师共创蓝图启动与需求输入在Cursor中我切换到“☂ Planner”模式在聊天框输入“我们需要为任务管理应用添加任务依赖功能。一个任务可以阻塞多个其他任务也可以被多个任务阻塞。需要能在创建和编辑任务时设置依赖并在任务列表或详情页直观看到依赖状态。”交互式澄清规划师不会立刻开始写文档。它可能会反问我“依赖关系是单向的A阻塞B还是需要支持双向约束A和B互斥” - 我回答“只需单向阻塞。”“前端如何展示是在甘特图上连线还是在任务卡片上用一个标签列表” - 我回答“在任务卡片上用一个‘等待’和‘阻塞’的列表展示即可初期不做甘特图。”“后端如何存储新建一个task_dependencies联结表还是在tasks表里加一个blocked_by_ids的JSON数组字段” - 我引导它“分析一下两种方案的优劣并考虑我们现有tasks表的结构PostgreSQL。” 它会分析并建议使用联结表以保持数据范式化和便于复杂查询。“核心业务逻辑是什么比如当任务A完成时是否自动检查并更新被它阻塞的任务B的状态” - 我确认“是的这是一个关键点。需要有一个服务在任务状态变更为‘完成’时触发检查将所有仅被此任务阻塞的任务状态自动更新为‘待开始’。”生成与审核规格书经过几轮问答规划师认为信息已充分它会生成一份完整的prd.md草案并展示给我看。我会仔细检查API设计POST /api/tasks/:id/dependencies的请求体格式是否正确数据库迁移它生成的CREATE TABLE task_dependencies的SQL语句索引设置是否合理(task_id, blocks_task_id)的联合唯一索引核心服务方法TaskService.updateDependencies和TaskService.checkAndUnblockTasks的方法签名是否清晰伪代码逻辑有无循环依赖或死锁风险前端组件它提议的新组件TaskDependencyList.vue的Props接口定义是否完备批准与固化确认无误后我输入“批准”。规划师便会将这份最终的prd.md写入到docs/specs/task-dependency/目录下。至此蓝图创建完毕。4.2 第二阶段让执行者精准施工切换模式与启动我切换到“✈ Executor”模式。神奇的是我甚至不需要再输入任何指令。执行者模式下的AI被预设了行为它会自动去扫描docs/specs/目录寻找最新的或未实现的规格书。读取规格与制定计划执行者读取到刚生成的prd.md后会在聊天框输出它的理解“我将实现‘任务依赖关系’功能。根据规格书我将按以下顺序进行1. 创建数据库迁移文件2. 更新Task模型层3. 实现TaskService中的两个核心方法4. 添加新的API路由和控制器5. 创建前端Vue组件并集成到任务卡片中。现在开始第一步。”分步执行与验证第一步它生成一个YYYYMMDDHHMMSS_create_task_dependencies_table.sql迁移文件内容完全符合规格书中的SQL定义并询问是否运行迁移。我确认后它执行npm run db:migrate命令。第二步它修改models/Task.js文件添加blockedBy()和blocks()的Sequelize关联关系。然后它运行现有的模型单元测试确保没有语法错误或关联冲突。第三步它创建services/taskDependencyService.js实现规格书中描述的两个核心方法。这里它非常“听话”没有引入任何规格书之外的“炫技”代码逻辑清晰简洁。接着它为此服务创建了对应的单元测试文件并生成了测试用例。第四步它修改routes/tasks.js添加新的路由并创建对应的控制器函数。之后它用curl命令或测试工具对新API进行快速冒烟测试。第五步它创建components/TaskDependencyList.vue并修改TaskCard.vue来引入这个新组件。完成后它可能会启动开发服务器 (npm run dev) 并告诉我“前端组件已集成请在浏览器中查看任务详情页以验证UI。”交付与收尾所有步骤完成后执行者会做一个总结“任务依赖功能已全部实现。共创建/修改了8个文件涵盖了数据库、后端服务、API和前端组件。所有现有测试通过新服务的单元测试已添加。请进行最终的功能验收。”整个过程中我作为开发者角色从“设计师监工”转变为了“质检员产品经理”。我不再需要反复解释“这里应该用数组还是对象”而是专注于审核执行者每一步的产出是否严格符合我们之前共同制定的蓝图。这种心流体验效率提升是实实在在的。5. 常见问题、排查技巧与进阶心得5.1 规划阶段常见问题问题1规划师提出的问题过于宽泛或肤浅无法引导出深层设计。排查检查使用的AI模型是否足够强大如GPT-5。能力较弱的模型可能不擅长深度追问。解决在你的初始需求描述中就预先加入一些约束和思考方向。例如不说“加个搜索功能”而说“加一个基于Elasticsearch的全文搜索功能需要支持对title和description字段的高亮显示并考虑分页和搜索结果缓存策略”。给AI一个更高的起点。我的技巧我会扮演“挑剔的客户”主动向规划师提出它可能忽略的极端情况。比如“如果两个任务互相设置为依赖形成循环怎么办我们的系统应该如何检测和防止这种情况” 这能激发规划师思考更健壮的方案。问题2生成的prd.md技术细节不足比如只说了“要一个API”但没有定义具体的请求/响应格式。解决在规划师生成草案后不要急于批准。直接对它说“请为POST /api/tasks/:id/dependencies这个端点补充详细的OpenAPI/Swagger格式定义包括请求体示例和所有可能的HTTP状态码及响应体。” 规划师会据此完善文档。5.2 执行阶段常见问题问题1执行者找不到prd.md文件或读取了错误的旧文件。排查首先确认docs/specs/{feature-name}/目录结构是否正确文件是否存在。然后检查执行者模式的提示词中关于查找规格书的路径指令是否准确。解决可以手动为执行者提供上下文。在执行者模式下直接输入“请阅读docs/specs/task-dependency/prd.md文件并基于此开始实施。” 这能绕过自动查找逻辑。问题2执行者理解了规格但在实现时与现有代码库的编码风格或架构模式冲突。现象例如你的项目使用Repository模式但AI生成了直接调用ORM的Service代码。解决这是提示词需要定制化的典型场景。在执行者提示词的开头部分明确加入你项目的编码规范。例如“在实现时请严格遵守本项目架构数据访问必须通过UserRepository接口不要直接使用UserModel.find()。服务层应放在src/services/目录且类名采用PascalCase。”我的技巧在项目根目录维护一个ARCHITECTURE_GUIDE.md文件并在提示词中要求执行者在动手前先阅读此文件。这样能极大提升代码的一致性。5.3 工作流适配与进阶心得1. 如何应对需求变更这是规格驱动开发的最大优势之一。当需求中途变化时你不需要和AI在混乱的代码上下文里争论。只需回到规划师模式打开原来的prd.md文件说“基于这份规格我们现在需要增加一个需求允许用户为依赖关系设置预期延迟时间。请更新规格书。” 规划师会分析现有设计提出修改方案例如在task_dependencies表加一个delay_hours字段并生成更新后的规格。然后你再让执行者基于新版本规格书去实施变更所有修改都有迹可循。2. 在团队中如何协作prd.md文件是绝佳的协作工具。团队成员A可以用规划师模式起草一个功能的初版设计将生成的prd.md提交到Git分支。团队成员B可以Review这个Markdown文件直接在文件评论区提出建议“这个API是否应该考虑版本化”。讨论达成一致后再由任何人可以是A或C切换执行者模式来完成编码。这完美分离了设计讨论和实现工作。3. 处理非常规或探索性任务不是所有任务都适合严格的“规划-执行”。对于一些探索性、研究性的任务比如“用Three.js尝试画一个旋转的立方体”直接让AI自由发挥可能更快。这套工作流最适合的是那些需求相对明确、结果可以规格化的开发任务比如实现一个CRUD接口、添加一个表单验证、集成一个第三方支付SDK等。4. 模型不是万能的人的判断至关重要无论规划师还是执行者它们都是强大的辅助而非替代品。规划师提出的设计方案需要你用专业经验去评估可行性执行者生成的代码你必须仔细进行代码审查特别是安全性和性能关键部分。我习惯把AI生成的代码看作一个“超级高效且不知疲倦的初级工程师”的产出而我作为高级工程师负责提供设计方向和进行最终的质量把关。这种“人机协同”的定位让整个过程既高效又可靠。经过一段时间的实践这套基于规格驱动的双阶段AI编码工作流已经成为了我日常开发中不可或缺的一部分。它带来的最大价值并非仅仅是代码生成速度的提升而是一种确定性和秩序感。它将原本充满随机性的AI对话变成了一条可预测、可管理、可重复的生产线。对于追求工程质量和团队效率的开发者来说花一点时间搭建并适应这套流程是一项回报率极高的投资。