核心导读： SDD（规范驱动开发）的理念固然强大，但在真实的商业项目中，纯靠人类手动维护不断膨胀的 Spec 文档无异于刻舟求剑。本文将带你跳出“手工作坊”，深度对标行业两大主流 SDD 框架体系：主打本地化与极客精神的 OpenSpec，以及深度绑定 CI/CD 的工程化巨兽 Spec Kit。同时，我们还将首次揭秘如何通过
AGENTS.md协议，让 Cursor、Claude Code 与 Trae 等异构 AI 工具在同一个项目中实现丝滑的任务交接。
引言：当“手工作坊”遇到“规模化墙”
在实施 SDD 的第一个月，你的团队会感到前所未有的舒畅。每天早上，架构师写好 Markdown 规范，AI 执行编码，下班前自动更新文档，一切井井有条。
但到了第三个月，当系统模块增加到 50 个，当 10 个开发人员在 10 个不同的 Feature Branch（特性分支）上同时工作时，“规模化墙（Scale Wall）” 出现了：
- Spec 冲突地狱： 两个人同时修改了核心的
Database_Spec.md，Git 合并时不仅代码冲突，连 AI 赖以生存的上下文文档也冲突了。 - 上下文过载（Context Bloat）： 随着项目演进，全局 Spec 膨胀到了 2 万词。每次把全量文档喂给 Cursor，不仅极度消耗 Token（烧钱），还会导致 AI 因为信息过载而“变笨”。
- 流程倒退： 遇到紧急 Bug 时，程序员为了赶进度，又偷偷绕过 Spec 直接改了代码，导致**“代码现实”与“文档契约”脱节**。
为了打破这堵墙，业界诞生了专门的 SDD 框架生态。它们的作用就像 React 对于前端工程师、K8s 对于运维工程师一样——将设计模式固化为自动化工具链。 目前，赛道上最受瞩目的两套解决方案是：OpenSpec 与 Spec Kit。
第一章：OpenSpec —— 本地化、轻量级与“增量哲学”
OpenSpec 是由开源社区驱动的一套轻量级 SDD 规范与命令行工具库（CLI）。它的核心哲学是：“Markdown 是一切，本地是一切。” 它不需要你购买昂贵的企业级 SaaS，也不强制绑定特定的代码托管平台。
1.1 核心机制：主 Spec + Delta Spec 体系（解决上下文膨胀）
OpenSpec 最令人惊艳的设计，是它解决“全量文档过载”的 Main-Delta（主从增量）架构。
在复杂的项目中，它强制将规范分为两层：
- Main Spec（主规范）： 记录系统稳定的核心领域模型、数据库 Schema 和全局防腐策略。这部分高度压缩，轻易不改。
- Delta Spec（增量规范）： 每当拉取一个新分支开发新功能时，利用 CLI 自动生成一个
.delta/feature-A.spec.md。这个文档只记录本次修改的意图和任务清单。
graph TD
subgraph OpenSpec_Workflow[OpenSpec 工作流]
A["全局 Main Spec.md"] -->|"只读上下文"| B("当前分支: Delta_Spec_Login.md")
B -->|"指导 AI 编码"| C["代码库变更"]
C -->|"测试通过"| D["发起 PR"]
D -->|"合并入 Main 分支"| E{"自动化编译引擎 (LLM)"}
E -->|"自动提炼与归档"| A
E -->|"销毁"| B
end
style A fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
style B fill:#fff9c4,stroke:#fbc02d,stroke-width:2px
style E fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
图 1：OpenSpec 的 Main + Delta 演进模型
执行流转： 在编码时，Cursor 等工具只需读取全局 Main Spec（了解底线）+ 当前 Delta Spec（了解当前任务）。当 PR 被合并进主干后，OpenSpec 会触发一个后置的 AI Agent，自动将 Delta Spec 中的有效信息“浓缩”并合并到 Main Spec 中，然后删除 Delta 文件。 这不仅完美避开了 Git 冲突，还保持了架构文档的永远精简与新鲜。
1.2 OpenSpec 的优劣势
- ✅ 优势： 极度轻量，审计友好（所有意图变更都在 Git 历史中），不依赖特定 IDE（无论是 Cursor 还是 Neovim 都能用）。
- ❌ 劣势： 依赖开发者的自觉性，缺乏 CI/CD 层的强制阻断能力，不适合治理极其混乱的跨部门外包团队。
第二章：Spec Kit —— 工程治理巨兽与 GitHub 深度集成
与追求极客精神的 OpenSpec 不同，Spec Kit 是面向企业级（Enterprise）治理设计的工程化框架。它的核心哲学是：“不被 CI 拦截的规范，就等于没有规范。”
2.1 核心机制：CI/CD 自动化拦截与双向校验
Spec Kit 将 SDD 理念深度嵌入到了代码托管平台（如 GitHub Actions 或 GitLab CI）中。它引入了一个“冷酷无情”的 AI Reviewer。
当开发者提交一段代码时，Spec Kit 不仅会跑单元测试，还会执行 “代码与意图一致性校验（Intent-Code Alignment Check）”。
它在 CI/CD 中执行如下逻辑：
- 读取 PR 中的代码 Diff。
- 读取该分支关联的
Feature_Spec.md。 - 启动 LLM 裁判引擎，质问：“这段代码的实现，是否 100% 符合 Spec 中的契约？是否偷偷引入了不在架构图中的第三方库？”
如果在 Spec 中规定了“必须使用 Redis 做缓存”，但 AI Reviewer 发现开发者（或编码 AI）为了省事在代码里写了一个本地的 Map 缓存，PR 会被直接 Block（阻断），并附上详细的修正建议。
2.2 Spec Kit 的优劣势
- ✅ 优势： 强制力极强，真正做到了“契约防腐”；适合大规模、合规要求高（如金融、医疗）的业务线。
- ❌ 劣势： 配置繁琐，成本较高（CI 每次跑 LLM 校验都需要消耗大量 Token），且对开发者的灵活性是一种“降维打击”，容易引起抵触情绪。
第三章：决策树——如何选择最适合你的框架？
不盲从工具，而是让工具匹配你的组织形态。以下是为你准备的 SDD 框架选型决策图：
图 2：SDD 框架生态选型决策树
第四章：终极融合：通过 AGENTS.md 实现异构 AI 工具交接
如果你不想引入任何外部框架，有没有一种“零依赖”的最优雅解法？
有。那就是目前在北美顶尖 AI 研发团队中悄然兴起的 AGENTS.md 协议。
4.1 为什么需要多工具协同？
2026 年的今天，没有任何一个 AI 编程工具能够包揽一切：
- Cursor / Windsurf： 拥有无敌的 GUI 体验，适合用来处理前后端联调、写复杂的组件，但因为占用显存和内存大，不适合做长时间的后台自动化任务。
- Claude Code (CLI)： 原生集成在终端，没有华丽的界面，但执行脚本、跑端到端测试、分析日志的能力极其悍勇。
- Trae 等文档分析智能体： 擅长阅读长篇累牍的需求文档并转化为标准的 Spec 架构图。
在 SDD 高阶实践中，人类架构师就像是乐队的指挥，而这些 AI 工具就是不同声部的乐手。 我们需要一份乐谱，这就叫 AGENTS.md。
4.2 【拿走即用】AGENTS.md 实战模板
在项目的根目录创建一份 AGENTS.md 文件。当任何 AI 工具被唤醒时，它们的第一条指令就是：“请阅读 AGENTS.md，明确你自己的职责边界。”
# 🤖 异构 AI 智能体协作协议 (AGENTS.md)
## 全局原则
本项目采用 SDD (Spec-Driven Development)。所有代码变更必须先有 Spec。
不同 AI 工具请根据本协议，认领自己的工作流。
---
## 🎭 角色与职责划分
### 1. 架构智能体 (推荐工具: Trae / ChatGPT Web)
- **职责**: 负责与人类产品经理沟通，消化模糊需求。
- **输出**: 仅允许在 `/docs/specs/` 目录下生成或修改 `Feature_Spec.md` 文档。
- **禁忌**: 严禁直接修改 `src/` 目录下的任何业务代码。
### 2. 编码智能体 (推荐工具: Cursor / Windsurf)
- **职责**: 充当主力“代码搬运工”。读取 `Feature_Spec.md`，执行原子化编码任务。
- **工作流**:
1. 读取指定的 Spec 任务。
2. 实现具体逻辑 (只写代码，不跑长耗时测试)。
3. 将完成的任务在 Markdown 中打勾 `[x]`。
- **交接暗号**: 编码完成后，在终端输出 `[AGENT_HANDOVER: CODE_READY]`。
### 3. QA 与运维智能体 (推荐工具: Claude Code CLI)
- **职责**: 自动化测试与 CI 预检。
- **工作流**:
1. 拦截到 `[AGENT_HANDOVER: CODE_READY]` 信号。
2. 自动启动终端容器，运行 `npm run test:e2e`。
3. 若失败，自行分析 Error Log，并回调 Cursor 修正。
4. 若成功，自动执行 `git commit -m "feat(spec): implemented..."` 并推送。
4.3 协作的魔力
当你把这份文件放进项目后，奇妙的化学反应发生了： 你用 Trae 梳理完了一份长达 3 页的《支付重构规范》；然后你切到 Cursor，按下一个快捷键，Cursor 开始像缝纫机一样精准地修改 20 个文件；写完后，终端里的 Claude Code 突然苏醒，自动拉起 Docker 跑了 500 个测试用例，修复了 2 个类型报错，最终平滑地推送到远程仓库。
在这个过程中，没有任何相互踩踏，没有架构的越权，一切都在 SDD 规范的铁轨上高速运行。
结语：工具是载体，心智是引擎
无论是轻盈的 OpenSpec，还是重装的 Spec Kit，亦或是极客风的 AGENTS.md，它们本质上都是为了解决同一个问题：对抗 AI 带来的技术熵增，捍卫系统的概念完整性。
选择什么工具并不重要，重要的是你的团队是否已经建立了“先对齐、后编码”的 SDD 心智模型。如果人类架构师自己连一张清晰的领域模型图都画不出，再强大的 CI/CD 拦截网，也挡不住烂代码的洪流。
我们已经解决了“如何用工具规范单个人与 AI 的协作”。但未来的软件工程，注定是由多个不同职能的 AI 智能体（Agent）组成的虚拟公司。 在下一篇文章 《【进阶范式】多智能体协同：Superpowers 与子代理驱动开发》 中，我们将彻底打开思路，探讨为什么“多代理（Multi-Agent）”比单个超级大模型质量更高，并教你在规范中内置强制的 TDD（测试驱动开发）闭环。
敬请期待。
