PDPI Spec：规格驱动开发协议，让AI编程告别“氛围编码”

1. 项目概述从“感觉对了”到“规格对了”在软件开发的江湖里我们可能都经历过这样的场景产品经理丢过来一个模糊的需求开发同学凭着一腔热血和“感觉对了”的直觉一头扎进代码里。几周后功能上线了但问题也接踵而至——代码像意大利面条一样纠缠不清一个小小的改动就能引发一连串的Bug新来的同事看着代码库一脸茫然重构更是无从谈起。这种“Vibe Coding”氛围编码模式在个人小项目或快速原型阶段或许能行得通但一旦项目规模扩大、团队协作加深它就成了项目失控、技术债堆积的罪魁祸首。我最近深度研究并实践了一个名为PDPI Spec的开源项目它提出了一套名为Spec-Driven Development (SDD)的规格驱动开发协议。这套协议的核心就是要把软件开发从一个依赖个人“感觉”和“氛围”的艺术活转变为一套严谨、可重复、可协作的工程化流程。它强制要求团队在写第一行代码之前必须依次完成需求Requirements、设计Design、计划Plan、实现Implementation这四个阶段的文档化工作。简单来说它的核心理念就是“谋定而后动”。这套方法特别适合与当前主流的AI编程助手如 Cursor、Claude Code、通义灵码等协同工作。AI不再是那个只会根据模糊指令生成不确定代码的“黑盒”而是被塑造成一个严格遵守流程、在不同阶段扮演不同专业角色如产品经理、架构师、项目经理的“SDD编排者”。这对于希望提升代码质量、保证项目可预测性、并希望将AI深度融入开发流程的团队和个人开发者来说无疑提供了一条极具价值的实践路径。2. 核心理念与PDPI流水线深度解析PDPI Spec 不仅仅是一套文档模板它是一套完整的开发哲学和强制执行的工作流。理解其背后的“为什么”比记住步骤更重要。2.1 为什么是“谋定而后动”在快节奏的互联网行业“快”常常被误解为“跳过思考直接动手”。但无数项目教训告诉我们前期节省的思考时间往往会在后期以数倍、甚至数十倍的调试、返工和沟通成本偿还回来。SDD 倡导的“慢”是一种战略性的“慢”——通过在前期的需求、设计和计划阶段投入足够精力来换取实现阶段的“平滑”与“快速”。这就像盖房子。你不会在图纸都没画好的情况下就让工人开始砌墙。需求文档是你的“用地规划许可证”设计文档是详细的“建筑蓝图”实施计划是“施工组织设计”。PDPI 就是确保你按这个顺序来避免盖到一半发现承重墙位置不对或者忘了留水管。2.2 PDPI 五阶段流水线详解PDPI 将开发流程拆解为五个环环相扣的阶段每个阶段都有明确的目标、产出和负责的“角色”。第 0 阶段准备工作 (Prework) - 扮演“上下文侦探”这个阶段常被忽略但却至关重要。它的目标是理解你即将工作的“土壤”——现有的代码库。你需要像侦探一样梳理出项目的核心架构项目基因、关键模块的依赖关系、现有的技术栈和约束条件。产出是一份“上下文工件”这能确保你后续的设计不会与现有系统格格不入避免“空中楼阁”式的设计。第 1 阶段需求定义 (Requirements) - 扮演“技术产品经理”这里要解决“为什么做”和“做什么”的问题。SDD 推荐使用Jobs to be Done (JTBD)理论来框定问题并用Gherkin风格的“Given-When-Then”句式编写用户故事。例如“Given 用户已登录When 用户点击‘创建报告’按钮Then 系统应弹出报告参数配置表单并允许用户选择时间范围。” 这种格式无歧义、可测试是后续所有工作的基石。产出是requirements.md。第 2 阶段系统设计 (Design) - 扮演“首席软件架构师”这是从“做什么”到“怎么做”的飞跃。你需要设计系统架构、定义模块接口、规划数据模型、评估技术选型及权衡Trade-offs。SDD 鼓励使用Mermaid图表来可视化这些设计如流程图、序列图、类图、ER图等。一份好的design.md应该让另一个资深的工程师看了之后能大致想象出代码的组织结构而不需要询问任何细节。第 3 阶段实施计划 (Plan) - 扮演“高级工程经理”设计是宏观的“怎么做”计划则是微观的“一步步怎么做”。这个阶段要求将设计拆解成一系列原子的、可验证的任务步骤。每个步骤应该足够小小到可以在一个较短的工作单元如2-4小时内完成并且有明确的验证标准例如写完这个函数需要通过哪些单元测试。产出是plan.md它本质上是一个给“实现者”可能是你自己也可能是AI的详细工单。第 4 阶段代码实现 (Implementation) - 扮演“初级开发/实现专员”终于可以写代码了但这里的写代码是在严格遵循测试驱动开发 (TDD)和计划的前提下进行的。实现者尤其是AI的角色被“降级”为执行者它不需要再思考宏观设计只需要严格按照plan.md中的步骤一步步地实现代码并通过预先定义的测试来验证每一步的正确性。这极大地降低了AI生成代码的随机性和错误率。注意这五个角色不一定对应五个人。在个人或小团队项目中你可能需要扮演所有角色。但关键在于当你切换到每个角色时你的思维模式和工作产出必须符合该角色的要求。与AI协作时你通过指令明确告知AI它当前扮演的角色。3. 项目结构与实操配置指南理解了理念我们来看看如何将一个项目“PDPI化”。PDPI Spec 提供了一套清晰的文件结构和规则我们需要将其落地到自己的项目中。3.1 核心目录结构搭建首先你需要在项目的根目录下引入PDPI的规则库。有两种方式作为子模块引入git submodule add https://github.com/zgs225/PDPI-spec.git .spec-rules直接复制规则文件将.spec-rules/目录及其所有内容复制到你的项目根目录。你的项目结构最终会看起来像这样my-software-project/ ├── .spec-rules/ # 【核心】PDPI协议规则库 │ ├── PREWORK.md │ ├── REQUIREMENTS.md │ ├── DESIGN.md │ ├── PLAN.md │ ├── IMPLEMENTATION.md │ ├── PREWORK-QA.md # 各阶段的质量检查清单 │ ├── REQUIREMENTS-QA.md │ └── templates/ # 各阶段文档模板 ├── specs/ # 【核心】你的所有规格文档存放处 │ └── user-authentication/ # 示例一个“用户认证”模块 │ ├── STATUS.json # 状态跟踪文件 │ ├── PREWORK.md │ ├── requirements.md │ ├── design.md │ └── plan.md ├── src/ # 你的项目源代码 └── tests/ # 你的项目测试代码关键点解析.spec-rules/是“宪法”定义了每个阶段该做什么、怎么做、产出什么格式。它应该是相对稳定、跨项目共享的。specs/是“法律文书”里面存放每个具体功能模块的规格文档。每个模块一个文件夹隔离清晰。STATUS.json是“案件进度表”是AI智能体理解当前进度的唯一依据必须由AI维护。3.2 STATUS.json项目状态的“唯一真理源”这是PDPI流程中最具巧思也最关键的一环。STATUS.json不是一个给人看的报告而是一个给AI智能体Agent读取和更新的机器可读的状态文件。它确保了即使对话中断、上下文丢失AI也能在下次对话时准确“接盘”。一个典型的STATUS.json内容如下{ currentPhase: DESIGN, phaseHistory: [ { phase: PREWORK, startedAt: 2023-10-27T10:00:00Z, completedAt: 2023-10-27T11:30:00Z, artifactPath: specs/user-auth/PREWORK.md, qaStatus: PASSED }, { phase: REQUIREMENTS, startedAt: 2023-10-27T13:00:00Z, completedAt: 2023-10-27T15:00:00Z, artifactPath: specs/user-auth/requirements.md, qaStatus: PASSED } ], currentArtifactPath: specs/user-auth/design.md, nextPhase: PLAN, blockers: [] }实操心得必须由AI管理你应该通过指令要求AI来创建和更新这个文件。例如“请根据我们刚才完成的讨论更新STATUS.json将当前阶段推进到DESIGN并记录设计文档路径。”QA状态是闸门只有当前阶段的qaStatus标记为PASSEDAI才被允许进入下一阶段。这强制了质量检查。blockers字段用于记录当前阻碍进展的问题如“等待第三方API文档”、“某个技术方案需要评审”等有助于风险可视化。4. 与AI智能体协作的实战流程PDPI Spec 的真正威力在于与AI编程助手的结合。下面我以开发一个“用户评论模块”为例演示如何与AI例如Claude或Cursor的AI一步步协作。4.1 阶段0准备工作 – 引导AI成为“侦探”首先在项目根目录初始化好PDPI结构。然后打开与AI的对话。你的指令 “我们现在要开始开发一个新的功能模块user-comment。请扮演PDPI SDD流程中的‘上下文侦探’角色。请先阅读.spec-rules/PREWORK.md中的规则然后为我分析当前项目根目录下的代码结构特别是与用户、帖子相关的现有模块生成一份specs/user-comment/PREWORK.md文档并创建和初始化specs/user-comment/STATUS.json文件。”AI的行动与产出AI会去读取.spec-rules/PREWORK.md理解它在这个阶段的任务是分析代码上下文。AI扫描你的src/目录可能发现已有的user.model.js、post.service.ts等文件。AI生成PREWORK.md内容可能包括项目技术栈Node.js Express MongoDB。相关模块用户模块路径、核心API、帖子模块数据结构、服务层。架构模式遵循MVC数据访问层已抽象。潜在约束数据库已有一个users集合评论可能需要引用user_id和post_id。AI创建STATUS.json设置currentPhase: PREWORK,qaStatus: IN_PROGRESS。你人类的工作审查PREWORK.md确保AI理解正确。运行.spec-rules/PREWORK-QA.md中的检查项例如“是否识别了所有关键依赖模块”。确认无误后指示AI“PREWORK阶段已完成并通过QA请更新STATUS.json将qaStatus改为PASSED并将currentPhase更新为REQUIREMENTS。”4.2 阶段1需求定义 – 与AI共同扮演“产品经理”你的指令 “现在进入REQUIREMENTS阶段。请切换角色为‘技术产品经理’并阅读.spec-rules/REQUIREMENTS.md。我们将基于‘用户希望在帖子下发表和查看评论’这个核心目标共同撰写需求文档。请先提出一些关键的JTBD问题来澄清范围。”协作过程AI根据规则会引导你讨论JTBD“当用户读完一篇帖子主要的‘任务’是什么是快速表达观点还是进行深度讨论”“评论需要支持回复吗即楼中楼功能。”“评论的审核机制是什么是否需要敏感词过滤或人工审核”你们一起将这些讨论转化为Gherkin场景场景: 用户发布一条顶级评论 假设 用户张三已登录 并且 位于帖子如何学习SDD的详情页 当 他在评论框输入这篇指南非常实用并点击“提交” 那么 评论应立即显示在评论列表顶部 并且 评论内容旁应显示他的头像和昵称 并且 他应该能看到“删除”按钮 场景: 用户回复一条评论 假设 用户李四已登录 并且 他看到了张三的上述评论 当 他点击该评论下的“回复”按钮输入“同意特别是实操部分”并提交 那么 一条新的回复应嵌套在张三的评论下方 并且 回复内容前应有“回复 张三”的标识AI将这些内容整理到specs/user-comment/requirements.md中并遵循模板结构概述、JTBD、用户故事、非功能性需求等。注意事项避免模糊词汇将“好用”、“快速”转化为可衡量的指标如“评论提交后前端显示延迟应小于200ms”。穷举边缘情况和AI一起思考空评论怎么办评论超长怎么办用户频繁刷评论怎么办这些都要写在需求里。4.3 阶段2 3设计与计划 – AI作为“架构师”和“经理”设计阶段指令 “需求已确认。请现在切换角色为‘首席软件架构师’阅读.spec-rules/DESIGN.md为‘用户评论模块’进行系统设计。请重点设计1. 评论的数据模型MongoDB Schema。2. 核心API接口RESTful端点。3. 评论列表的嵌套查询逻辑。请使用Mermaid图来展示数据模型和核心交互序列。”AI的产出 (design.md)会包含数据模型设计// Comment Schema { _id: ObjectId, postId: ObjectId, // 关联的帖子ID userId: ObjectId, // 评论者ID parentId: ObjectId? // 父评论ID用于实现嵌套。null表示顶级评论。 content: String, isDeleted: { type: Boolean, default: false }, // 软删除标志 createdAt: Date, updatedAt: Date }API设计GET /api/posts/:postId/comments,POST /api/comments,DELETE /api/comments/:id等。Mermaid序列图展示从用户提交评论到存入数据库、再推送到前端的完整流程。权衡分析例如讨论是使用数据库的递归查询还是应用层拼装树形结构并给出选择建议。计划阶段指令 “设计文档已评审通过。请切换角色为‘高级工程经理’阅读.spec-rules/PLAN.md将上述设计拆解为具体的、原子的实现步骤生成plan.md。每个步骤必须包含1. 步骤编号和描述。2. 具体的代码变更位置文件路径。3. 验证方式例如需要编写的测试用例描述。”AI的产出 (plan.md)会是这样的任务清单## 实施计划 1. 【后端】创建评论数据模型文件 - 文件src/models/Comment.js - 操作定义Mongoose Schema包含上述字段。 - 验证编写单元测试验证Schema定义正确索引已创建。 2. 【后端】实现评论创建服务函数 - 文件src/services/commentService.js - 操作实现 createComment(postId, userId, content, parentId) 函数处理父子评论逻辑。 - 验证编写单元测试测试正常创建、创建回复、参数错误等情况。 3. 【后端】添加评论路由和控制器 - 文件src/routes/commentRoutes.js, src/controllers/commentController.js - 操作实现POST /api/comments 端点调用service层。 - 验证使用Supertest编写集成测试模拟HTTP请求。 4. 【后端】实现按帖子获取评论列表的接口 - 文件src/services/commentService.js (新增函数), src/controllers/commentController.js - 操作实现 getCommentsByPostId(postId) 函数支持平铺或树形返回需设计查询逻辑。 - 验证编写单元测试和集成测试验证查询正确性和性能。 5. 【前端】创建评论UI组件... ...4.4 阶段4实现 – AI作为高效的“执行者”这是最“轻松”但也最需要严格监督的阶段。你不再需要向AI描述复杂的逻辑只需要“派单”。你的指令 “所有前置规格都已就绪。请切换角色为‘初级开发/实现专员’阅读.spec-rules/IMPLEMENTATION.md。现在请严格按specs/user-comment/plan.md中的步骤1开始执行。请采用TDD方式先写出步骤1中要求的Comment模型的单元测试然后再实现该模型。”AI的行动它会先去读IMPLEMENTATION.md知道自己的职责是严格按计划编码和写测试。它读取plan.md中的步骤1。先写测试在test/models/Comment.test.js中生成测试代码断言Schema的各个字段类型正确。再实现代码在src/models/Comment.js中编写Mongoose Schema定义。运行测试并反馈AI可能会模拟运行测试并告诉你是否通过。如果项目有测试运行命令它甚至会建议你运行npm test来验证。你的工作监督AI是否严格遵循计划。运行测试确认功能正确。完成一个步骤后指示AI“步骤1已完成并通过测试。请更新STATUS.json中的进度如果有子状态并继续执行步骤2。”5. 常见问题、挑战与应对策略在实践中完全遵循PDPI会遇到一些挑战。以下是我总结的常见问题及解决办法。5.1 挑战一感觉流程“太重”拖慢进度问题每个功能都要写四份文档是不是太官僚了一个小功能也要这样吗应对策略区分功能粒度对于“修改按钮颜色”这类纯样式改动可以直接走简化流程或跳过PDPI。PDPI适用于“用户评论模块”、“支付集成”、“数据导出服务”这类有独立逻辑、影响多个层级的功能模块。文档适度精简模板是指导不是八股文。PREWORK如果上下文简单可以几句话说清。DESIGN对于简单CRUD可能就是一个Schema和几个API描述。核心是思考过程被记录和验证文档篇幅可以灵活调整。利用AI加速写文档本身是思考的过程。用AI辅助如“根据以上对话请帮我整理成规范的requirements.md初稿”可以极大提升文档产出速度。思考的时间无法省略但书写的时间可以压缩。5.2 挑战二AI不听话总想直接写代码问题即使给了指令AI有时还是会迫不及待地给出代码片段或者跳过某些步骤。应对策略强化角色指令在每次对话开始时明确重申“你当前的角色是[角色名]请严格遵守.spec-rules/[阶段].md中的协议。在未收到明确指令前不得进行下一阶段或编写代码。”使用检查清单在每个阶段结束时主动要求AI或自己根据*-QA.md文件进行逐项检查。例如“请根据REQUIREMENTS-QA.md清单检查我们刚完成的需求文档并列出任何不满足项。”状态文件驱动始终坚持让AI来读写STATUS.json。你可以反问AI“请查看当前的STATUS.json我们下一步应该进行哪个阶段根据规则我们现在可以开始写代码吗” 让规则文件来“约束”AI的行为。5.3 挑战三设计或计划考虑不周实现时才发现问题问题设计时觉得没问题实现时遇到技术难题或者计划步骤不合理。应对策略拥抱迭代PDPI不是瀑布模型。如果在IMPLEMENTATION阶段发现DESIGN有致命缺陷完全可以也应该回流。流程是1. 暂停实现。2. 更新STATUS.json记录阻塞原因。3. 回到DESIGN阶段修改设计文档。4. 同步更新PLAN。5. 继续实现。STATUS.json中的phaseHistory会记录这次回流这是正常的学习和优化过程而不是失败。计划预留缓冲在PLAN阶段可以加入“风险评估”或“缓冲步骤”。例如在计划中写明“步骤6实现嵌套评论查询。此步骤可能涉及复杂的聚合管道如果性能不达标则回退到方案B应用层递归组装。”同行评审对于核心模块的设计和计划邀请同事进行简短的评审。多一双眼睛能提前发现很多问题。5.4 挑战四与现有团队流程的融合问题团队已有Git分支策略、代码评审、CI/CD流程PDPI如何融入应对策略文档即PRD将requirements.md和design.md作为技术评审Tech Review的必须材料。创建功能分支前必须先完成这些文档并通过评审。计划即任务卡将plan.md中的原子步骤直接拆分成GitHub Issues或Jira子任务。实现过程就是逐个关闭这些任务。状态文件纳入版本控制STATUS.json和所有规格文档都应提交到Git。这为项目提供了完整的、可追溯的决策记录。你可以看到任何一个功能是如何从一句话需求一步步演化成代码的。6. 个人实践心得与进阶技巧经过多个项目的实践我发现PDPI Spec不仅规范了开发更深层次地改变了我和AI协作的思维模式。心得一从“提示词工程”到“流程工程”过去与AI协作精力耗费在精心构思“提示词”上希望一次生成完美的代码。现在我的精力转向设计清晰的“流程”。我不再需要写出完美的、一步到位的指令我只需要确保AI在正确的流程节点上扮演正确的角色。流程本身会引导产出高质量的结果。这降低了单次交互的认知负荷。心得二规格文档是最好的“上下文”在与AI的长期对话中上下文丢失是个大问题。PDPI创建的specs/目录成为了一个永不丢失的、结构化的“项目记忆”。新加入的成员或者隔了几天再回来的我只要阅读这些文档就能立刻理解功能的来龙去脉。对于AI来说在开始实现前让它先“阅读”相关的需求、设计和计划文档相当于进行了一次深度的上下文预热生成的代码针对性极强。心得三培养“可测试性”的前置思维因为PLAN阶段要求每个步骤都有验证方式这强迫我在设计时就必须思考“这个功能该如何测试”。TDD不再是口号而是流程强制的自然结果。设计出的接口会更清晰模块耦合度会更低因为高耦合的代码难以进行原子化的测试。进阶技巧定制化你的.spec-rulesPDPI Spec 提供的规则是通用的起点。你可以且应该根据自己团队的技术栈和偏好进行定制。修改模板在.spec-rules/templates/中为你常用的技术栈如React前端、Go后端添加更具体的示例。增强QA清单在*-QA.md中加入你们团队特有的检查项。例如在DESIGN-QA.md中加入“是否考虑了接口的向后兼容性”、“数据库索引设计是否经过评审”。集成自动化工具可以编写简单的脚本在STATUS.json的currentPhase变更时自动在项目管理工具中创建对应的任务列表。PDPI Spec 像是一副严谨的脚手架它限制了“胡乱搭建”的自由却换来了建筑整体的稳固与高效。它可能不适合每一个五分钟就能写完的脚本但对于任何你希望其长期存活、易于维护、团队协作的项目而言投入时间建立这样的规格驱动开发习惯无疑是一笔回报丰厚的投资。它让AI从一名偶尔发挥超常但也时常出错的“天才实习生”变成了一位遵守纪律、流程清晰、产出稳定的“专业工程师”。