AI 协作范式：SDD 规范驱动工作流

背景

• 不知道需求边界，顺手改了不该改的代码；
• 不知道验收标准，写完一个“看起来差不多”的版本就停了；
• 不知道项目规范，命名、目录、接口风格都不统一；
• 新开会话后，之前解释过的业务背景又丢了。

SDD

• 它不是“先写文档再开发”这么简单，而是把文档变成 AI 可以持续读取、理解、执行的上下文。
• SDD 解决的不是“AI 不会写代码”，而是“AI 不知道该怎么写”，让AI少猜

基本思想：Specify → Plan → Tasks → Implement（Github Spec Kit）

Spec：定义“做什么”和“不做什么”

需求说明书 + 行为边界 + 验收标准

• 用户场景是什么；
• 功能边界在哪里；
• 哪些情况要处理；
• 哪些情况不处理；
• 验收标准是什么。

Design：定义“怎么做”

技术方案说明书

• 改哪些模块；
• 数据流怎么走；
• 接口怎么设计；
• 是否影响历史逻辑；
• 是否兼容旧数据；
• 哪些方案被放弃，为什么。

Tasks：定义“先做什么，做到什么程度”

执行拆分问题，把一个复杂需求拆成多个小任务

开源工具 OpenSpec

OpenSpec 不是 SDD 本身，而是一个承载 SDD 流程的工具。
specs/这里放的是项目已经确认下来的长期规则，是项目的“长期知识库”。

openspec/  
├── specs/  
│ └── <domain>/  
│ └── spec.md  
├── changes/  
│ └── <change-name>/  
│ ├── proposal.md  
│ ├── design.md  
│ ├── tasks.md  
│ └── specs/  
│ └── <domain>/  
│ └── spec.md  
└── config.yaml

changes/这里放的是某一次需求变更。比如你要做“新增导出功能”，就可以建一个 change，里面有：

• proposal.md：为什么要做；
• design.md：怎么做；
• tasks.md：拆成哪些任务；
• spec.md：这次需求会改变哪些行为。

等这个需求完成后，再归档，把有效内容合并进长期 Spec。

/opsx:propose

用于生成需求规格。

给 AI：

• 产品文档；
• 技术方案；
• 需求描述；
• 接口文档；
• 设计稿链接。

AI 帮你生成：

• proposal；
• design；
• tasks；
• spec delta。

/opsx:apply

用于根据 Spec 生成代码。

apply 不是万能的。即使 AI 理解了需求，也可能不符合团队代码习惯，所以还需要 Skills、AGENTS.md、Hooks 继续约束。

/opsx:sync

用于同步变化。

把开发过程中发生的变化同步回规格spec文档。

/opsx:archive

用于归档沉淀。“长期协作稳定性”

需求完成后，把这次开发中确认下来的东西沉淀到长期上下文里。

其他工具辅助

MCP

MCP 解决的是：AI 如何获取外部需求上下文

Skill

Skills 解决的是：AI 应该按照什么习惯工作。

底层 Skill：通用工作习惯

比如：

• 编码前先分析；
• 优先小改动；
• 不扩大改动范围；
• 修改后说明影响面；
• 不确定先确认；
• 不要乱删代码。

AI 的长期工作习惯。

上层 Skill：项目业务规则

比如：

• 当前项目的架构分层；
• 哪一层负责请求；
• 哪一层负责数据处理；
• 组件命名习惯；
• 业务专有名词；
• 历史坑；
• 禁止修改的目录。

AI 对这个项目的工作方式理解。

AGENTS.md

AI 进入项目后的入场说明书。

例如：

• 项目目录结构；
• 技术栈；
• 启动命令；
• 测试命令；
• 哪些目录不要随便改；
• 国际化规则；
• 命名规则；
• 提交前检查方式。

它和 Skills 的区别在于：Skills 是按需激活，比如你做前端组件开发，可能激活“前端组件开发 Skill”。做接口联调，可能激活“API 联调 Skill”。AGENTS.md 是进入项目默认生效

所以AGENTS.md 适合放：

最底层、最稳定、最默认的项目规则。

Hooks

Hooks 解决的是：软约束不可靠，必须加硬约束。

比如硬检查是否有中文编码

完整体系

MCP 提供上下文  
↓  
/opsx:propose 生成 Spec / Design / Tasks  
↓  
人 review 并修改规格  
↓  
AGENTS.md 提供项目基础规则  
↓  
Skills 提供通用/业务开发习惯  
↓  
/opsx:apply 让 AI 按规格写代码  
↓  
Hooks 执行硬校验  
↓  
人 review、验证页面和逻辑  
↓  
/opsx:sync 同步变更  
↓  
/opsx:archive 沉淀长期经验

什么时候适合用？

当需求复杂度足够高时，前期写规格的成本，会换来后期更少返工、更稳定协作、更低 review 成本。