我的 Spec 编程实践：从 PRD、TDD、Plan 到 AI 原生开发规范

最近在使用 Codex、Trae、Qoder 等 AI Coding 工具进行开发时我越来越明显地感受到一个问题AI Coding 真正难的可能已经不是“让 AI 写代码”而是让不同的 Agent 始终理解同一个项目。尤其是一个项目在开发过程中需求会变化设计会调整Plan 会不断修改同时我又可能在不同 IDE 之间切换。这让我开始重新思考一个问题AI 原生开发到底需要什么样的开发规范我最近对 Spec ProgrammingSpec 编程的实践也正是从这个问题开始的。一、我原来的开发方式PRD → TDD → Plan → Coding以前我的开发流程比较简单Brainstorming ↓ PRD ↓ TDD ↓ Plan ↓ Coding ↓ Test这个流程本身没有什么问题。PRD 解决我要做什么TDD / 技术设计解决技术上怎么做Plan 解决这一次具体改哪些东西然后交给 Coding Agent 执行。对于小项目这套方式已经足够好用。但是随着 AI Coding 的深入我发现一个新的问题PRD、TDD、Plan 之间缺少一个稳定的“行为事实层”。二、为什么开始关注 Spec Programming传统开发中我们通常比较关注需求文档技术设计代码测试而 AI Agent 加入之后出现了一个新的核心问题Agent 如何知道“什么才算正确”比如我的一个 AI Visibility 项目中有这样的业务规则Experiment Comparison 只有在以下条件全部一致时才能进行Anchor Query Version Search Mode Model Version Prompt Version Temperature只要其中一个不同就不能进行 Comparison。这其实已经不是简单的“需求描述”。它更像是一份行为规范 / Correctness Contract也就是 Spec。因此我逐渐形成了一个认识PRD 描述“我要什么”Spec 描述“什么情况下才算正确”。三、PRD、SPEC、PLAN到底有什么区别我现在比较倾向于这样理解文档解决的问题PRD为什么做、做什么SPEC什么必须成立PLAN这一次准备怎么做Code实际怎么实现Verify有没有真的做到可以把它理解成PRD ↓ 我要解决什么问题 ↓ SPEC ↓ 什么行为才算正确 ↓ PLAN ↓ 这一次怎么实现 ↓ CODE ↓ 实际实现 ↓ VERIFY ↓ 用证据证明它正确这比单纯的PRD → TDD → Coding多了一层非常重要的东西正确性的定义。四、我发现一个 PRD 对应一个 SPEC进一步实践之后我逐渐形成了一个比较简单的关系一个需求 ↓ 一个 PRD ↓ 一个 SPEC ↓ 多个 PLAN也就是One Requirement → One PRD → One SPEC → N Plans为什么不是一个 PRD 对应一个 Plan因为一个需求往往不会一次开发完成。例如PRDAI Visibility Agent SPEC ├── Query 生成规则 ├── Query Version 固化规则 ├── Experiment 运行规则 ├── Comparison 规则 └── Report 生成规则 PLAN-01 实现 Query Agent PLAN-02 实现 Experiment PLAN-03 实现 Comparison PLAN-04 优化 Report因此SPEC 是相对稳定的行为定义PLAN 是不断变化的执行过程。五、但现实开发并不是瀑布模型很快我又发现一个问题。真实开发中需求本身也会变化。一开始可能认为这个功能应该这样做。开发以后才发现用户真正需要的是另外一种行为。这时候不能说“PRD 已经写完了不能改。”当然可以改。因此我现在更认可一种持续收敛而不是一次性冻结。整个过程实际上更像PRD ↓ SPEC ↓ PLAN ↓ Coding ↓ Verify ↓ 发现问题 ↓ 调整 PLAN / SPEC / PRD ↓ 再次 PLAN ↓ Coding ↓ Verify ↓ ……这才符合真实的软件开发。六、什么时候修改 PRD、SPEC、PLAN这里我认为需要一个非常简单的判断原则。1. 实现方式变化 → 修改 PLAN例如原计划使用 Redis 做缓存后来发现项目规模很小直接使用 MySQL这只是技术实现变化。不需要修改 PRD。也不一定需要修改 SPEC。只修改 PLAN 即可。2. 业务行为变化 → 修改 SPEC例如原来的规则Comparison 只需要 Model Version 一致开发以后确认Model Version Prompt Version Temperature Anchor Query Version Search Mode 必须全部一致这是业务规则发生变化。因此应该修改 SPEC。3. 产品目标变化 → 修改 PRD例如原来做一个内部 AI Visibility 检测工具。后来变成做一个客户可以直接使用的 AI Visibility Agent。这已经不是实现细节变化而是产品目标变化。因此应该修改 PRD。七、所以文档不是“开发前一次性写完”这是我实践 Spec 编程以后比较重要的一个认识。以前很容易把文档理解成先写文档 ↓ 文档冻结 ↓ 开始开发 ↓ 代码实现文档但 AI 原生开发更像认知 ↓ 文档 ↓ 实现 ↓ 反馈 ↓ 新的认知 ↓ 更新文档 ↓ 再次实现因此文档不是开发前一次性写完的而是随着认知变化持续更新的。这也意味着Spec 不一定在第一次 Coding 之前就是完美的。特别是在探索型项目中Spec 本身也可以逐步收敛。八、我的两个 Spec 模式目前我把需求大致分成两类。模式一需求非常明确例如用户点击“删除项目”系统必须删除项目及其关联数据并提示成功。这种情况下可以直接PRD ↓ SPEC ↓ PLAN ↓ Coding ↓ VerifySpec 可以在 Coding 前基本确定。模式二需求基本明确但细节未知例如我要做一个 AI Visibility Agent。目标很明确。但是很多细节并不确定Query 怎么生成Query 怎么分类Experiment 怎么设计SOV 怎么计算Competitor 怎么确定Report 应该展示什么这种情况下如果要求一开始就写出完整 Spec反而会增加负担。更合理的是PRD ↓ Draft SPEC ↓ Exploration PLAN ↓ Coding / Experiment ↓ 发现新问题 ↓ 调整 SPEC ↓ 新的 PLAN ↓ Coding ↓ Verify也就是说Spec 可以从 Draft 逐步收敛到 Stable。九、一个 SPEC 可以对应多个 PLAN这一点对 AI Coding 尤其重要。例如SPEC-001Experiment Comparison PLAN-001 实现基础 Comparison PLAN-002 增加参数一致性校验 PLAN-003 增加 mismatch reason PLAN-004 增加前端 Comparison UI PLAN-005 增加 Regression Test这些 Plan 都服务于同一个 SPEC。所以SPEC ≠ Task ListSPEC 是系统必须满足什么。PLAN 是现在准备做什么。这两个概念不能混在一起。十、那历史版本怎么办这是我最近觉得非常重要的一步。既然 PRD、SPEC 都会变化那么是不是应该保存PRD-v1 PRD-v2 PRD-v3 SPEC-v1 SPEC-v2 SPEC-v3我的答案是通常没有必要。我更倾向于文档保存当前状态Git 保存演化历史。也就是docs/ ├── PRD.md └── SPEC.md plans/ └── current.md文档永远保持当前项目真实状态。而历史交给 Git。例如commit A PRDAI可见度检测工具 ↓ commit B PRD升级为 AI Visibility Agent ↓ commit C SPEC增加 Query Version ↓ commit D SPEC增加 Comparison 一致性规则需要查看历史的时候gitloggitdiffgitshow即可。十一、为什么我认为“文档 Git”是一个很好的组合因为它把两个问题分开了。文档解决现在是什么Git解决以前是什么为什么变成现在这样因此当前事实 ↑ │ PRD / SPEC / PLAN │ ↓ Git │ ┌────────┼────────┐ ↓ ↓ ↓ 历史1 历史2 历史3这比在文档里面人为维护大量版本号简单很多。而且 Agent 最需要的其实就是当前事实。如果项目目录里面同时存在PRD-v1.md PRD-v2.md PRD-final.md PRD-final-2.md PRD-new.md对于人来说已经够混乱。对于 Agent 来说更容易产生上下文冲突。因此一个事实最好只有一个权威来源。十二、这也解决了跨 IDE 开发的问题这是我实践过程中另外一个非常现实的问题。我现在会使用不同的 AI Coding 工具Codex Trae Qoder ……如果把项目上下文绑定在某一个 IDE 中就会出现Codex 知道这些 Trae 不知道 Qoder 又不知道但如果把核心项目事实放到 Git 仓库Project │ ├── AGENTS.md ├── docs/ │ ├── PRD.md │ └── SPEC.md ├── plans/ │ └── current.md └── src/那么 IDE 可以变化。Agent 可以变化。模型可以变化。但是项目本身没有变化。十三、AGENTS.md 应该放在哪里在这个过程中我也重新理解了AGENTS.md的作用。它不是 PRD。也不是 SPEC。它更像这个项目应该如何与 Agent 协作。例如AGENTS.md Project 项目是什么 Architecture 项目基本架构 Development Rules 开发规则 Workflow Agent应该如何工作 Verification 如何验证 Documentation PRD / SPEC / Architecture在哪里例如1. 先理解任务 2. 阅读相关 PRD / SPEC 3. 检查现有代码 4. 必要时制定 PLAN 5. 实现 6. 测试 7. Verify 8. 汇报结果这样 Agent 每次进入项目都可以快速建立上下文。十四、AIDF我最终形成的轻量开发规范到这里我发现自己其实并不需要再造一个复杂的 Agent Framework。Codex 有自己的 Agent。Trae 有自己的 Agent。Qoder 也有自己的 Agent。它们都有AgentPlanMemoryMCPSkillsSubagentsBrowserCheckpointsVerification这些能力应该让 IDE 自己负责。我真正需要标准化的是项目自己的事实和协作规则。因此我把目前的思路暂时称为AIDFAI Development Framework / AI Development Convention但我更倾向把它理解成一种AI 原生开发约定而不是一个庞大的软件框架。十五、AIDF 的最小目录对于普通小项目我认为甚至不需要复杂结构project/ │ ├── AGENTS.md │ ├── docs/ │ ├── PRD.md │ └── SPEC.md │ ├── plans/ │ └── current.md │ └── src/这已经足够。如果项目变大再逐步演化project/ │ ├── AGENTS.md │ ├── docs/ │ ├── requirements/ │ │ ├── PRD-001.md │ │ └── PRD-002.md │ │ │ ├── specs/ │ │ ├── SPEC-001.md │ │ └── SPEC-002.md │ │ │ └── architecture.md │ ├── plans/ │ ├── PLAN-001.md │ └── PLAN-002.md │ └── src/也就是说先简单复杂度随着项目增长。而不是一开始就建立几十个目录和模板。十六、AIDF 的核心关系到现在我认为可以把整个体系压缩成一张图一个需求 │ ↓ ┌─────┐ │ PRD │ └──┬──┘ │ 当前需求/目标 │ ↓ ┌──────┐ │ SPEC │ └──┬───┘ │ 当前行为/正确性 │ ┌─────────┼─────────┐ ↓ ↓ ↓ PLAN-01 PLAN-02 PLAN-03 │ │ │ └─────────┼─────────┘ ↓ Code ↓ Verify │ ↓ 发现新的认知 │ ┌─────────┼─────────┐ ↓ ↓ ↓ PRD SPEC PLAN │ │ │ └─────────┼─────────┘ ↓ 持续收敛 │ ↓ Git │ 保存全部历史这不是严格的瀑布流程。而是一个持续反馈、持续收敛的 AI 原生开发循环。十七、我现在对 Spec 编程的理解经过这段实践我对 Spec Programming 的理解也发生了一些变化。我以前容易把 Spec 理解成“在写代码之前把需求写得非常详细。”现在我更倾向于理解为让 Agent 在写代码之前、过程中和之后始终有一份明确的“什么才算正确”的共同依据。因此 Spec 编程真正解决的并不只是怎么写代码。而是人、Agent、代码、需求之间如何保持一致。十八、我认为最重要的不是 Spec而是“事实的唯一来源”整个实践最后让我形成了一个更简单的原则One Fact → One Source of Truth例如产品目标PRD业务行为SPEC当前实现任务PLANAgent 协作规则AGENTS.md代码src/历史Git不要让同一个事实散落在PRD TDD README Plan Agent Memory 聊天记录 代码注释多个地方。否则最终一定会出现到底哪个是真的而这恰恰是 AI Coding 最容易出现的问题之一。十九、我的最终方案足够简单就好因此我现在并不打算构建一个复杂的 Spec Framework。我的方案非常简单AGENTS.md ↓ 项目如何与 Agent 协作 PRD ↓ 为什么做 / 做什么 SPEC ↓ 什么必须成立 PLAN ↓ 这次准备怎么做 CODE ↓ 实际实现 VERIFY ↓ 证明是否正确 GIT ↓ 记录全部演化历史一句话总结文档负责当前状态Git 负责历史状态PRD 负责目标SPEC 负责正确性PLAN 负责行动Agent 负责执行。这可能就是我目前理解的、比较适合个人开发者和小团队的 Spec 编程实践。二十、写在最后AI Coding 让软件开发发生了一个很大的变化。过去我们主要解决人如何写代码。现在越来越需要解决人如何让 AI 正确地理解项目并持续地参与项目。因此未来的开发规范可能不会越来越重反而可能越来越轻。不是建立更多文档。不是建立更多流程。而是找到最少的一组约定让人 ↓ PRD ↓ SPEC ↓ PLAN ↓ Agent ↓ Code ↓ Verify ↓ Git始终保持一致。我现在对 Spec 编程最大的体会就是Spec 不是为了限制开发而是为了让人和 Agent 对“什么是正确的”形成共同认知。而一个好的 AI 原生开发规范也许并不需要重新发明 Agent。只需要把项目事实管理好。