大家好，和你们很多人一样，我的团队也在全力投入基于 AI 的开发。不过，随着我们不断开发新功能、修复 bug、用 Cursor 发布版本……代码库开始变得像个丛林。虽然一切都能运行，测试也都通过了，但决策的背景信息却逐渐丢失，智能体（有时候是人类）会重复实现已有功能，或者做出不符合现有模式的东西。我觉得这种情况在高度依赖 AI 开发的团队中越来越常见，所以想分享一下我们目前的做法。
过去几个月里，我们制定了自己的规范驱动开发（SDD）流程，觉得相比其他方法有一些优势。特别是，我们采用了结构化的执行流程，并且把智能体的工作结果也纳入其中。下面我会介绍它的具体运作方式、实际发生了哪些变化，以及其他人如何采纳这种方法。
什么是 Spec-Driven Development
简而言之：你先设计文档/规范，然后用它们作为实现的输入。接着，把实现过程中发生的事情（调研、代理讨论、评审等）记录下来，作为输出规范，供以后参考。整个流程是：
- Input specs: product brief, technical brief, user stories, task requirements.
输入规范：产品简介、技术简介、用户故事、任务需求。 - Workflow: research → plan → code → review → revisions.
工作流程：调研 → 规划 → 编码 → 评审 → 修订。 - Output specs: research logs, coding plan, code notes, review results, findings.
输出规范：调研日志、编码计划、代码备注、评审结果、发现内容。
通过将文档（包括输入和输出）作为一等公民的产物，你会强制团队去理解并实现可追溯性。目标不是制造一堆文档，而是建立足够的结构，让你的决策可以被追溯，并且让代理在下一个功能迭代时有足够的上下文。
为什么这对我们的团队有帮助
- Better reuse + less duplication: Since we maintain research logs, findings and precious specs, it becomes easier to identify code or patterns we’ve “solved” already, and reuse them rather than reinvent.
更好的复用 + 更少的重复：由于我们维护了研究日志、发现和宝贵的规范，所以更容易识别已经“解决”的代码或模式，并加以复用，而不是重新发明。 - Less context loss: We commit specs to git, so next time someone works on that feature, they (and the agents) see what was done, what failed, what decisions were made. It became easier to trace “why this changed”, “why we skipped feature X because risk Y”, etc.
更少的上下文丢失：我们把规范提交到 git，下次有人在这个功能上工作时，他们（以及代理）可以看到之前做了什么、哪里失败了、做了哪些决策。追溯“为什么这里改了”、“为什么我们因为风险 Y 跳过了功能 X”等问题变得更容易了。 - Faster onboarding: New engineers hit the ground with clear specs (what to build + how to build) and what’s been done before. Less ramp-ing.
更快的入职流程：新工程师一上手就有清晰的规范（要构建什么 + 如何构建），还能了解之前做过什么。减少适应期。
我们是如何一步步实现的
首先值得一提的是，这种方法其实只适用于体量较大的功能。修复 bug、小调整或清理工作，简单解释一下就可以让 AI 自己处理了。
对于你的大型项目/功能，下面是一个最简版流程：
- 定义你的
prd.md**：** 功能目标、用户流程、基本需求。 - 定义你的
tech_brief.md：高层架构、约束条件、技术栈、定义。 - 针对每个功能/用户故事，编写一个
requirements.md文件：说明故事内容、验收标准、依赖关系。 - 针对故事下的每个任务，编写一个
instructions.md：详细的任务说明（需要做哪些调研、涉及哪些代码区域、测试指南）。这应该大致相当于一个典型的 PR 规模。不要包含代码级细节，这些最好留给 agent 在实现时处理。 - 开始实施时，为每个任务创建一组自定义命令，执行以下操作：
- 为该任务创建一个
research.md：你对代码库、现有模式、坑点的了解。 - 创建一个
plan.md：你打算如何实现。 - 代码完成后，创建
code.md：你实际做了什么，有哪些变更，哪些内容被跳过。 - 然后
review.md：反馈，改进。 - 最后
findings.md：反思、注意事项、下一步行动。
- 为该任务创建一个
- 把这些 spec 文件和代码一起提交，这样以后的人（无论是 AI 还是人类）都能了解完整的上下文。
- 使用文件夹命名规范：比如
project/story/task/requirements.md、…/instructions.md等，这样更直观。 - 为每种规范类型创建模板，使其轻量化，并在各个任务中保持标准化。
- 选择两到三个功能做试点，然后在全面推行前完善你的文档模板、文件夹规范和规范命名。
一些经验教训
- 让规范模板保持简单。如果太复杂，大家会跳过填写或阅读规范。
- 能自动化的就自动化：如果你创建了一个任务，就自动生成空的 spec 文件。如果可能的话，把这个流程接入你的系统。
- 定期回顾 specs：每两周问一次：“我们忽略了哪些输出结果？”这样可以暴露技术债务。
- 对于 agent 驱动的工作流：确保你的 agent 能访问 spec 文件夹，并且有使用说明。没有这些结构化输入，价值会迅速下降。
最后的想法
如果你一直在快速上线功能，虽然它们能用，但感觉自己正在失去对代码库的掌控，希望这个 SDD 工作流能帮到你。
额外福利：如果你想要一个自动化这种工作流的工具，而不是自己手动搞（比如输入 specs 创建、任务管理、输出 specs），我正在开发一个叫 Devplan 的工具，可能会对你有帮助。
如果你尝试过类似的方法，欢迎分享哪些有效、哪些没用。