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中的文字描述转化为可运行的代码。这带来了几个显著优势确定性高由于输入规格是明确且固定的输出的代码质量非常稳定减少了“跑偏”的可能。上下文完整执行者可以访问整个项目文件夹的上下文结合prd.md它能精准理解代码应该放在哪里、如何与现有模块集成。自动化程度高在这个阶段你可以放心启用“自动运行”等工具让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中自定义模式的“上下文”设置里一定要选择“完整文件夹上下文”。如果只选择“打开的文件”执行者将无法全面了解项目结构导致生成的代码集成度差。另外两个模式的快捷键如CmdShift1/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人格。操作步骤在你的用户目录$HOME/.config/或项目根目录创建AGENTS.md文件。将prompts/planner.md和prompts/executor.md的全部内容分别粘贴到以/Planner和/Executor开头的区块下。在聊天时只需输入/Planner或/ExecutorAmp 就会加载对应的长篇指令集进入该模式。这种方式的优缺点优点极度灵活不依赖特定工具的功能理论上在任何支持长上下文和自定义指令的AI工具中都能实现。缺点模式不是“持久化”的。每次新开一个聊天线程Thread或者进行了一段与模式无关的对话后你需要重新输入/Planner或/Executor来唤醒对应人格。这需要一点额外的操作纪律。3.4 GitHub Copilot 配置在生态内无缝衔接对于深度集成在 VSCode 和 GitHub 生态中的开发者使用 Copilot Chat 的自定义模式也是一个好选择。配置方式类似于 Cursor将提示词内容填入对应的模式描述文件中即可。一个关键细节在 Copilot 的模式配置中你可以为不同模式指定不同的底层模型如为规划师用 GPT-5为执行者用 Claude Sonnet。这充分利用了微软提供的多模型后端让你可以根据任务特性选择最佳“大脑”。4. 从理论到实践一个完整的功能开发案例让我们通过一个具体的例子看看这套工作流如何落地。假设我们正在开发一个简单的博客系统现在需要增加“文章草稿自动保存”功能。第1步启动规划师在 Cursor 中按下CmdShift1切换到“☂ Planner”模式。第2步描述需求我对AI说“我们需要为博客文章编辑器添加自动保存草稿的功能。用户在编辑文章时系统应该定期比如每30秒或在检测到用户暂停输入时比如停止输入后2秒自动将当前内容保存为草稿。草稿应与文章关联用户下次进入编辑时可以恢复。请帮我规划这个功能。”第3步交互式规划规划师开始提问并引导触发机制你希望是纯时间间隔30秒还是防抖Debounce模式或是两者结合数据存储草稿是保存在前端如LocalStorage作为临时缓存还是必须持久化到后端数据库如果存后端是新建一个drafts表还是在现有的posts表中增加一个draft_content字段用户体验如何向用户提示‘已自动保存’需要显示上次保存时间吗如果网络失败导致保存失败如何处理技术实现前端使用什么技术是原生的setInterval和oninput事件还是使用像 RxJS 这样的响应式库后端API接口如何设计PUT /api/posts/:id/draft冲突处理如果用户在多个标签页编辑同一篇文章自动保存的草稿如何处理冲突经过几轮问答规划师生成了一份docs/specs/auto-save-draft/prd.md。我审查了这份文档特别关注了它提出的“采用防抖模式停止输入2秒后保存为主结合心跳检测每60秒强制保存一次为辅”的方案以及将草稿作为posts表的一个jsonb类型字段draft_data的设计。我觉得合理于是“批准”了这个计划。第4步切换执行者按下CmdShift2切换到“✈ Executor”模式。我甚至不需要再给任何指令。第5步自动执行执行者自动读取了刚批准的prd.md。它开始工作首先它分析了现有的prisma/schema.prisma文件然后生成并运行了向Post模型添加draft_data Json?字段的迁移命令。接着它在app/api/posts/[id]/draft/route.ts中创建了新的API路由实现了GET获取草稿和PUT更新草稿的逻辑。然后它转到前端的文章编辑器组件使用useEffect和setTimeout实现了防抖逻辑并集成了调用新API的saveDraft函数。最后它在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提升工程效能的关键一步。我的体会是初期投入时间熟悉和定制这套流程会在后续无数个功能开发中以复利的形式回报你。