翻译转载自：tech-lab.sios.jp/archives/50…
翻译转载自作者：サイオステクノロジーの吉永
本人非原作者，只是一名在东京从事RAG开发的技术负责人，看到本篇文章深有启发，故而转载翻译搬运。
前言
今年在参与生成式 AI 应用事业和 WEB 应用开发的过程中，我学到了许多关于与 AI 编码助手协作的经验。这次我想把在反复试验中总结出来的、今年开始流行的“规格驱动开发（SDD）”以及为实现它所需的工具谈一谈。
那么，使用 AI 编码助手（如 Claude Code、GitHub Copilot、Cursor 等）时，你有没有过这样的经历？
我说“帮我加上用户认证功能”，结果生成了 1000 行代码
我又改口说“不，不要 JWT，用会话认证……”，又生成了 1000 行代码
我再次更正说“本来不是用 React 而是用 Next.js……”，又生成了另外 1000 行代码…
这个无限循环地狱，实际上就是被称为“Vibe 编码”的现象。
什么是 Vibe 编码
“Vibe 编码”这个词是由 OpenAI 联合创始人 Andrej Karpathy 在 2025 年 2 月首次提出的概念。它指的是一种全新的开发风格，因 LLM（大规模语言模型）的性能飞跃提升而成为可能。
Vibe 编码的特点
Vibe 编程具有颠覆传统软件开发常识的特征。首先，它强调一种忘记代码存在、依靠直觉进行开发的方式。开发者无需理解代码细节，只要用自然语言向 AI 发出指示，功能就会被实现。
即使出现错误信息，也不会试图理解其含义，而是将其原封不动地复制粘贴给 AI，且不附任何注释。期望 AI 能提出某种修正建议。
更令人惊讶的是，**代码会超出开发者理解的范围而不断增长。**不知不觉中代码库可能扩展到数千行，且没有人能掌握其全貌。用语音输入向 AI 下达指示也很普遍，边散步边编程也成为可能。
遇到错误时，如果无法修复，就通过变通方法应对，或进行随机修改，反复尝试直到错误消失。这是一种与传统调试截然不同的方法。
乍一看似乎非常高效且具有创新性，但实际上这种方法潜藏着严重的问题。
四个根本的问题
Vibe 编码背后存在以下四个根本性问题。
1.模糊的需求规范 最大的问题是，“要做什么”并不明确。当开发者给出模糊的指示时，AI 会根据其训练数据进行推测性补全。例如说“添加用户认证”时，AI 可能会在 JWT 认证、会话认证、OAuth、Basic 认证等多种选项中自行判断并推进实现。
结果是，生成的实现与开发者原本意图的认证方式完全不同。为修正这个问题再次投喂提示时，又会生成另一种实现……就这样陷入无限循环。
2.缺乏上下文 项目中必然存在技术栈、编码规范、架构模式等特有的上下文信息。但如果这些信息没有传达给 AI，就会生成与现有代码库不兼容的代码。
例如，项目使用的是 Next.js 15 的 App Router，可 AI 却用 Pages Router 来实现。数据库访问用的是 Prisma，却被写成了原生 SQL。此类不一致经常发生。
3.非确定性输出 由于 LLM 的性质，即使是相同的提示每次也会返回不同的结果。这意味着缺乏再现性。昨天有效的方法今天可能行不通。即使你尝试同事成功的方法，也可能无法得到相同的结果。在这种情况下，团队协作会变得非常困难。
4.知识的散失 在与 AI 的对话中，重要的决策会被逐步确定。“这个 API 要按 RESTful 设计”“认证令牌要保存在 HTTP-only Cookie 中”“错误处理要由专用中间件负责”等等，项目的重要方针就这样被决定下来。
但是，这些决策会埋在聊天记录中，之后无法被检索重看。开始新会话或由其他开发者接手时，就得从头重复相同的讨论。
为了解决这些问题，社区尝试了各种方法。
为了解决 Vibe 编码的问题，最先出现的方法是 CLAUDE.md。
CLAUDE.md 的出现
CLAUDE.md 是放在项目根目录中用于指示 AI 的文档。它专门针对 Anthropic 公司的 Claude Code，记录项目的指南、最佳实践、约束事项等。
传统方法：CLAUDE.md/AGENTS.md
为此，试图解决前面提到的“缺乏上下文”问题。这样 AI 就能理解项目的技术栈、编码规范和架构模式。
# 项目概要
电商网站的后端开发
## 技術技术栈
- Node.js + TypeScript
- Express.js、PostgreSQL、Jest
## 代码规范
- 函数应遵循单一职责原则
- 必须进行错误处理
- 以测试优先的方式实现
## 实现时的注意事项
1. 包含 TypeScript 的类型定义
2. 将 API 设计为 RESTful
3. 认证使用 JWT Bearer token
CLAUDE.md 自 2025 年 6 月左右开始逐步演进。
CLAUDE.md 的演进
**第 1 阶段（2025 年 6 月左右）**时，它仅被用作简单的备忘单。提供项目的基本信息，列出常用命令，仅有如此程度的内容。在这一阶段，对开发者来说只能减少查看手册的麻烦，效果有限。
**第 2 阶段（2025 年 7 月〜9 月）**时，它演进为用于定义 AI 约束的工具。开始撰写详细的风格指南，包含用于自动化工作流的指示。此外，为了从过去的失败中学习，还添加了“不该做的事”清单。
为支持单一仓库管理多个项目（monorepo）的结构，也实现了层次化的设置管理。通过在根目录的 CLAUDE.md 中定义总体规则，各子项目的 CLAUDE.md 则可以覆盖各自的规则。
AGENTS.md 的出现
2025 年 8 月 19 日，OpenAI 将 AGENTS.md 作为开放格式公开发布。这是对 Anthropic 公司独有的 CLAUDE.md 进行更通用化的版本。
AGENTS.md 最大的特点是作为在多个 AI 工具之间共享的通用指示。Claude Code、GitHub Copilot、Cursor、Windsurf、Aider 等各种 AI 编程助手都可以复用相同的指示文档。
另外，推荐语言是英语。这是有明确理由的。AI 模型的训练数据中英语占绝大多数，技术术语用英语表达歧义更少。因此在国际化团队开发时，若以英语编写，任何人都能理解。
AGENTS.md 包含如下内容：
作为实现指南，记录代码规范（命名规则、文件结构、类型定义）、错误处理模式、安全检查清单、认证实现模式等。
作为工作流指示，定义了新功能开发流程（需求确认→实现→验证→提交）、缺陷修复流程、代码审查标准等。
因此，AI 不再只是简单地生成代码，而能够按照项目的工作流推进工作。
CLAUDE.md/AGENTS.md 的局限
不过，我们也发现 CLAUDE.md/AGENTS.md 存在局限性。尤其是随着项目的成长，以下问题开始显现。
1.规格（规范）管理变得困难 由于整个项目的说明都包含在一个文件中，会产生各种问题。
首先，所有功能的规格会混在一起。认证功能、支付功能、通知功能、管理后台……等各个功能的规格，都会写在同一个文件里。文件会变得臃肿，达到数千行也不罕见。
接着，过去的决策事项会被埋没在某处。“三个月前决定的认证方式的详细内容写在哪里来着？”即使去找，在海量文件中找到对应部分也很困难。
另外，目前也存在一个难以找到正在进行的工作内容的问题。当并行开发多个功能时，仅通过阅读文件无法判断哪些已经完成、哪些正在进行、哪些尚未开始。
更为严重的是，后加入的成员难以把握整体情况。新加入的工程师即便阅读数千行的 CLAUDE.md/AGENTS.md，也很难理解项目的历史沿革和当前状态。
2.无法追踪变更
CLAUDE.md/AGENTS.md 是由 Git 管理的，因此理论上可以追踪变更历史。然而实际上，很难弄清楚哪个功能在何时被添加。
查看整个文件的差异时，只能得到“在第 500 行新增 3 行，在第 800 行修改 5 行”之类的信息。仅凭差异无法判断那是认证功能的变更、支付功能的新增，还是编码规范的更新。
规格变更的历史没有留下也是一个问题。由于“为什么要将认证方式从 JWT 改为会话认证？”这类决策的背景没有被记录，同样的讨论就会被反复重复。
多人共同工作时，这个问题变得更严重。如果成员 A 更新了认证功能的规范，同时成员 B 在添加支付功能的规范，就会出现 Git 冲突。由于所有内容都集中在一个文件中，并行协作就变得非常困难。
此外，不同会话之间信息无法共享也是一个问题。在 Claude Code 中周一的工作内容不会在周二的新会话中被继承。未写入 CLAUDE.md 的隐含决定事项每次都会丢失。
3.缺乏可扩展性
最严重的是，项目一变大就会变得无法管理。
对于小型项目（1～2 人、几个月的开发周期），CLAUDE.md/AGENTS.md 已经足够用了。但是，一旦是 10 人以上的团队、开发周期超过 1 年，情况就完全不同了。
尤其是，修改现有功能（1→N）是困难的。若是从零创建新功能（0→1），只需在 CLAUDE.md/AGENTS.md 中添加新章节即可。然而，若要修改已有功能（1→N），则必须找到文件中相应的部分，并在保持一致性的前提下进行更新。
在大型项目中，各个文件夹中可能会散布着多个 CLAUDE.md/AGENTS.md。例如 frontend/CLAUDE.md、backend/CLAUDE.md、infra/CLAUDE.md 等。如果这些文件之间出现矛盾，AI 就无法判断应优先遵循哪一个，从而导致混乱。
结果是，很难把握整体情况。要了解项目的当前状态，需要全部阅读多个 CLAUDE.md/AGENTS.md，追踪 Git 历史记录，并进一步查看代码库。
为克服这些局限，迫切需要一种新方法。这就是规范驱动开发（SDD）。
规范驱动开发（SDD）的崛起
进入 2025 年后，一种名为**规格驱动开发（Spec-Driven Development，SDD）**的新方法迅速受到关注。
- Kiro（AWS）已发布预览版（2025 年 7 月 15 日）
强力推进“规范驱动开发”
- Spec Kit（GitHub）已发布（2025 年 9 月 2 日）
使用 GitHub Copilot 实现的开源工具
- 重新评估 CLAUDE.md/AGENTS.md 的作用
对规范明确化与共享重要性的关注增加
SDD 的本质
SDD 的本质可以一句话概括如下：
在写代码之前，先与 AI 就要做什么达成一致
这听起来可能很理所当然。然而，在 Vibe 编码的时代，这种“理所当然”却被遗忘了。
在传统软件开发中，需求定义→设计→实现的顺序是基本流程。然而，随着 AI 编码助理的出现，“先让 AI 写代码，运行不通再修正”的做法变得普遍。
SDD 是在 AI 编码时代也能让人重新认识到设计重要性的做法。
SDD 的关键概念
- 明确的规格定义旨在消除模糊性。不是说“添加用户认证”，而是定义具体规格，例如“添加基于 Google OAuth 的认证，会话有效期为 24 小时，并提供登出功能”。
- 人类与 AI 的共同理解强调拥有相同的认知。事先对规范进行对齐，以确保 AI 生成的代码与开发者的意图完全一致。通过这种方式，可以大幅减少“与预期不符”的问题。
- 可预测的实现意味着在实现之前就能看到结果。如果有详细的规格说明，就可以事先预测实现后的代码会是什么样子。这样可以将返工降到最低。
- 可追溯的变更能够明确何时、什么发生了变化。通过保留规格的变更历史，就能回答“为什么会这样”的疑问。
传统流程与 SDD 流程的区别
如果用图来表示这种差异，就非常清楚。 传统的 Vibe 编码流程呈现出如下的循环结构：
将想法转换为提示词，让 AI 生成代码。调试生成的代码，如果有问题就修复它。然而，即便修复了，又会出现另一个问题，挫败感随之累积。最终，又回到起点尝试另一种方法……陷入这种无尽循环。
另一方面，SDD 的开发流程是直线型且清晰的：
将创意以规格说明的形式文档化。由人类对该规格进行审查，并与 AI 达成一致。在达成一致后才开始实施。实施完成后，将规格归档并作为知识进行积累。其特点是每个步骤都明确，返工减到最低。
SDD 带来的 4 大价值
SDD 为开发流程带来以下 4 大价值。
-
可预测性，可以在实现之前预见结果。如果有详细的规范，就能事先知道“实现这个功能后，数据库模式会变成这样、需要新增这些 API 端点、前端组件会进行这样的变更”。由此可以防止意外的副作用。
-
可审计性，所有变更都可以被追踪。查看规格的变更历史后，可以明确知道“何时、谁因何原因进行了此变更”。在合规性和安全审计中，这种可追踪性非常重要。
-
可重用性，规格会作为知识得以积累。在过去项目中编写的认证功能规格可以在新项目中重复使用。这样就不必重复多次解决相同的问题。
-
团队协作，不同的 AI 工具也能共享相同的规格。即便成员 A 使用 Claude Code，成员 B 使用 Cursor，只要参考相同的规格，就能生成一致的代码。
当前的主要 SDD 工具（截至 2025 年 11 月）
实现 SDD 的工具在 2025 年接连出现：
- Kiro (AWS) – kiro.dev
- Spec Kit (GitHub) – github.com/github/spec…
- OpenSpec (Fission AI) – github.com/Fission-AI/…
- BMad Method (BMad Code) – github.com/bmad-code-o…
- cc-sdd（日本产开源工具）– github.com/gotalab/cc-…
每个工具都有其特点，本次以 OpenSpec 为中心介绍。
什么是 OpenSpec
OpenSpec 是由 Fission AI 开发的轻量级工作流管理工具，用于实现以规范驱动的开发（Specification-Driven Development）。
OpenSpec 解决的问题
OpenSpec 旨在直接解决前面提到的 CLAUDE.md/AGENTS.md 的局限性。
OpenSpec 最大的特点是针对现有项目进行了优化。它并非为从零开始的新项目设计，而是可以后期引入已经运行中的项目。可以在不影响现有代码库的情况下分阶段导入。
支持多种AI工具也是一个重要点。可用于 Claude Code、Cursor、GitHub Copilot、Aider 等各种 AI 编码助手。即便团队成员各自使用不同的工具，也能共享相同的规范。
轻量的结构使学习成本也很低。这一点也很吸引人。无需复杂的配置文件或构建工具，基本上只需编辑 Markdown 文件即可。如果已有现成的文档撰写技能，就能马上开始使用。
变更管理的明确化是 OpenSpec 的核心功能。就像 Git 的 pull request 一样，可以清晰管理规范的差异。一眼就能看出“添加了什么、修改了什么、删除了什么”。
OpenSpec 按以下四个步骤运行。
- 1.在Proposal（提案）阶段，会提出变更内容。以结构化的形式提出诸如“想要添加两因素认证”“想要在搜索功能中添加筛选”等变更。在此阶段，尚未生成代码。
- 2.在Review（审核）阶段，会对提案的规格进行确认和调整。由人类阅读规格，如有不明之处则与 AI 对话以进行细化。在这个阶段，实施方向会被确定。
- 3.Apply（适用）阶段根据达成一致的规范执行实现。AI 读取规范，并按照其生成代码。由于规范明确，AI 的输出也具有可预测性。
- 4.Archive（归档）阶段将已完成的变更作为知识进行积累。把提案时创建的变更差异整合到主规范中。通过此举，项目的规范始终保持最新状态。
OpenSpec 的核心概念：两个文件夹
OpenSpec 的结构出奇地简单。基本上，由两个文件夹构成。
AGENTS.md
openspec/
├── specs/ # 当前的规格
│ └── auth/
│ └── spec.md # 认证功能的规格
│
└── changes/ # 提案中的更改
└── add-profile-filters/
| ├── proposal.md # 变更内容
| ├── tasks.md # 任务清单
| ├── design.md # 技术规格
| └── specs/
| └── auth/
| └── spec.md # 规格差异
└── add-frontend-ui/
openspec/specs/ 文件夹用于管理当前的规格。这表示项目的“当前状态”。认证功能、支付功能、搜索功能等各个功能的规格作为独立文件进行管理。
openspec/changes 文件夹用于管理提出的变更。这表示项目的“未来状态”。每个变更提案作为独立目录进行管理，目录中包含提案内容、任务清单、技术规范、规范差异等。
通过这种结构，解决了 CLAUDE.md/AGENTS.md 中“所有内容混在一个文件里”的问题。同时，也便于并行推进多个变更。
变更差异的概念
OpenSpec 最强大的功能之一是类似于 Git pull request 的变更差异管理。
# 配置文件规格的变更差异
## 新增 要求
### 要求：角色过滤器
系统必须提供按用户角色进行过滤的功能
## 修改后的需求
### 要求：检索响应（更新版）
检索结果必须包含已应用筛选器的状态
## 已移除的需求
### 要求：全部表示
（废止：由于性能问题）
通过这种差分形式，审查时一眼就能看出发生了什么变化。
ADDED 部分记录了将要新添加的需求。在此示例中，可以看出将新增一项名为“ロールフィルター”的功能。
MODIFIED 部分记载了对现有需求的变更。可以看到，现有的“搜索响应”需求已被更新，包含了过滤器应用状态。
REMOVED 部分记载了将被废止的需求。可以看到，“全部显示”功能因性能问题而被废止。
这种差分形式对于习惯了 Git diff 或拉取请求的工程师来说，非常容易理解。就像代码审查一样，规范也可以被审查。
OpenSpec 的实际使用方法
让我们通过实际场景详细看看如何使用 OpenSpec。
场景：添加双因素认证（2FA）
考虑在现有的认证系统中添加 2FA（二要素认证）。目前仅通过电子邮件地址和密码进行认证，但为了提高安全性，想要添加通过短信或认证应用的 2FA。
第 1 步：提出变更建议
首先，创建变更提案。可以直接从命令行执行，也可以用自然语言向 AI 助手提出请求。
# 命令行，或请求 AI 助手
/openspec:proposal 添加两步验证
或者，用更自然的说法：
开发者： 「在个人资料搜索中添加按角色和团队的筛选功能
请创建一个 OpenSpec 更改提案来添加该功能」
AI： 「正在创建 OpenSpec 更改提案...」
**生成 openspec/changes/add-profile-filters/**
执行此命令后，AI 会自动生成以下文件结构：
openspec/changes/add-2fa/
├── proposal.md # 变更的意图和背景
├── tasks.md # 实现任务清单
├── design.md # 技术规格
└── specs/auth/
└── spec.md # 2FA 的规范（差异）
proposal.md 中记录了为何需要此变更、将提供何种价值等背景信息。例如会写明“为提升安全性，引入双因素认证（2FA）。由此可以大幅降低未授权访问的风险”等内容。
tasks.md 中列出了实现所需的任务。比如“在数据库模式中为 2FA 添加表”“实现短信发送功能”“实现与认证应用的联动功能”“在前端添加 2FA 设置界面”这样的具体任务。
design.md 中记载着技术设计内容。比如“2FA 的验证码为 6 位数字且有效期为 5 分钟”、“使用 Twilio API 发送短信”、“与身份验证应用的联动采用 TOTP 协议”等此类技术决策事项。
specs/auth/spec.md 中将记载认证功能规格的差异。这是最重要的文件，会清楚地示出相对于现有认证规格的变更点。
第 2 步：对规范进行审查和调整
确认生成的规格，并根据需要进行调整。在此阶段，将在与 AI 对话的过程中细化规格。 开发者：“添加角色和团队筛选的验收条件”
AI：「将更新规格差异…」
编辑 specs/profile/spec.md 和 tasks.md
例如，在这一阶段会与 AI 讨论诸如“2FA 的备份代码如何处理？”，“2FA 设置是可选还是必须？”，“如何迁移现有用户？”等疑问点。
如果不能接受 AI 提出的规格，可以反复请求修改。可以逐步添加具体要求，例如“生成 10 个备份代码，使用一次后即失效”“对现有用户在下次登录时提示设置 2FA，但不强制”等。
在这一阶段仍然完全不会生成任何代码。专注于把规格定下来。这就是回归软件开发基本原则：在写代码之前先把设计确定下来。
步骤 3：实施
一旦达成对规范的共识，就可以进入实现阶段了。
# 命令行，或向 AI 助手请求
/openspec:apply add-profile-filters
或者，用自然语言：
开发者：“规格看起来不错。我们来实现吧”
AI：“按顺序实现任务...”
任务 1.1 ✓ 数据库模式更新
任务 1.2 ✓ 添加 API 端点
任务 2.1 ✓ 前端组件创建
AI 会按 tasks.md 中列出的任务顺序依次执行。每当某个任务完成时，都会显示进度。
由于规格明确，AI 的输出也具有可预测性。在“数据库模式更新”任务中，正如预期会添加 user_2fa 表。在“添加 API 端点”任务中，将实现诸如 POST /api/auth/2fa/enable 、 POST /api/auth/2fa/verify 等端点。
即使发生问题，也能明确是哪个任务出了问题，因此调试变得容易。由于任务被拆分为小的单元，问题的定位也更为简单。
第 4 步：归档与知识积累
实现完成并通过测试后，将对更改进行归档。
# 命令行，或向 AI 助手请求
/openspec:archive add-profile-filters
或者，自然语言描述： 执行此命令后，会发生以下情况：
开发者：“将更改存档”
AI：“正在将更改存档……”
*openspec archive add-profile-filters --yes*
✓ 规格已更新
1.openspec/changes/add-2fa/specs/auth/spec.md （差分）将被合并到 openspec/specs/auth/spec.md （主规范）中
2.将删除目录 openspec/changes/add-2fa/
3.此更改将记录在 Git 历史中
结果是，openspec/specs/文件夹将始终保留最新的规范，而 openspec/changes/ 文件夹只保留正在进行的更改，从而保持一个整洁的状态。
与仅有 CLAUDE.md 的比较
在这里，我们将比较仅使用传统的 CLAUDE.md 与使用 OpenSpec 的情况。
仅有 CLAUDE.md 时的工作流程：
- 1.在编辑器中打开 CLAUDE.md
- 2.不知道应该把 2FA 的规范写在哪（认证部分？安全部分？新建一个部分？）
- 3.在合适的位置追加规范
- 4.给 AI 的提示：“添加 2FA”
- 5.AI 会生成大量代码（有时会超过 1000 行）
- 6.尝试审查生成的代码，但不知道做了哪些更改
- 7.对现有认证逻辑的影响范围不明
- 8.其他开发者更新了 CLAUDE.md，发生了 Git 冲突
- 9.解决冲突后，自己的修改和他人的修改混在一起，变得难以分辨
结果：
- × 规格被埋在 CLAUDE.md 中（之后很难找到）
- × 变更记录不会保留（为什么会成为这个规格不明）
- × 团队间共享困难（不知道谁修改了什么）
使用 OpenSpec 时的工作流程：
- 1.与 /openspec:proposal 二要素認証を追加 一起执行命令
- 2.一组结构化的文件将被自动生成
- 3.按顺序审查 proposal.md、tasks.md、design.md、spec 之间的差异
- 4.如有不明之处，可在与 AI 对话中进行细化
- 5.在达成规格一致后，使用 /openspec:apply 开始实现
- 6.可以按各任务查看进度
- 7.在现场即时审查各项任务的成果物
- 8.如有问题，仅修正相关任务
- 9.完成后以 /openspec:archive 作为知识进行积累
- 10.其他开发者可在不产生冲突的情况下并行进行不同的变更提案
结果： ✓ 变更内容明确（在专用目录中管理） ✓ 可以掌握影响范围（以差异形式显示） ✓ 团队内共享知识（在档案中积累） ✓ 支持并行工作（在 changes/ 下分离）
现有的 AGENTS.md/CLAUDE.md 不需要了吗？
这里会产生疑问。“有了 OpenSpec，AGENTS.md/CLAUDE.md 就不需要了吗？”
答案是**“不，不需要，建议并用”**
AGENTS.md/CLAUDE.md 和 OpenSpec 的角色是不同的。
AGENTS.md/CLAUDE.md 描述整体指示。定义跨项目规则，例如项目的编码规范（“变量名使用 camelCase”“文件名使用 kebab-case”等）、项目整体架构（“采用 MVC 模式”“使用依赖注入”等）、通用工作流程（“提交前必须运行 lint 和 test”等）。
OpenSpec 管理各个功能的规格。它管理诸如认证功能的详细规格、支付功能的 API 设计、搜索功能的算法等按功能划分的具体规格。
两者是互补关系。如果把 AGENTS.md/CLAUDE.md 看作 “项目的宪法”，那么 OpenSpec 就像 “各项具体法律”。
OpenSpec 提供了用于与 AGENTS.md/CLAUDE.md 集成的特殊块：
<!-- OPENSPEC:START -->
# OpenSpec 操作手顺
此手顺适用于在本项目中活动的 AI 助手。
在以下请求时请始终打开 `@/openspec/AGENTS.md`：
- 如果提及计划或提案（包含 proposal、spec、change、plan 等词）
- 有关引入新功能、不兼容更改、架构变更、大规模性能/安全性工作的内容
- 内容模糊、需在编码前准备正式规格说明书的情况
`@/openspec/AGENTS.md` 请学习以下内容：
- 变更提案的创建与应用方法
- 规格书的格式与规范
- 项目结构与指导方针
请保留此管理区块，以便通过“openspec update”来更新步骤。
<!-- OPENSPEC:END -->
将此块添加到 AGENTS.md 后，AI 助手将自动学习如何使用 OpenSpec。当用户说“想要添加新功能”时，AI 会自动生成修改 OpenSpec 的提案。上述块将在 OpenSpec init 运行时自动添加到 CLAUDE.md。
与其他工具的比较
在这里，我们来比较主要的 SDD 工具。除了 OpenSpec 之外，还有几款优秀的 SDD 工具。
Kiro（AWS）
Kiro 是由 AWS 开发的 SDD 工具。它为大型项目设计，特点是采用将项目方向与各个功能规格明确分离的两层结构。
.kiro/
├── steering/ # 项目方向性（变更频率：低）
│ ├── product.md # 产品愿景、目标、目标用户、主要功能
│ ├── tech.md # 技术栈、架构方针
│ └── structure.md # 目录结构、命名规则
└── specs/ # 功能规格（更改频率：高）
└── add-2fa/
├── requirements.md # 功能需求
├── design.md # 技术设计
└── tasks.md # 实现任务
项目结构：
steering/ 文件夹包含定义整个项目方向的内容。这些信息的变更频率较低。
product.md 包含产品的愿景、目标、目标用户、主要功能等构成项目核心的信息。例如，“该应用面向中小企业的财务人员，作为费用报销系统。主要功能为费用的申报、审批与结算”等内容。
tech.md 记录技术栈、架构方针、使用的库等信息。如“使用 Next.js 15 + NestJS + PostgreSQL”“采用微服务架构”“认证使用 Auth0”等技术决策事项。
structure.md 记载目录结构、命名规范、模块间的依赖关系等内容。例如“前端放在 /frontend ，后端放在 /backend ”“组件名使用 PascalCase 命名”等结构性规则。
另一方面， specs/ 文件夹定义各个功能的详细规格。这类信息变更频繁。
为每个功能创建一个目录，并在其中放置 requirements.md（功能需求）、design.md（技术设计）、tasks.md（实现任务）。
Kiro 的两层结构的优点：
通过这种两层结构，项目的宪法（ steering/ ）和各个单独的法律（ specs/ ）被明确分离。
对 steering/ 的修改应当谨慎进行。因为它会影响所有功能。另一方面， specs/ 会频繁更改。每当添加新功能或修改现有功能时，都需要更新它。
这种分离使得团队间的角色分工也变得清晰。产品经理或架构师负责管理 steering/ ，而各个开发者负责管理 specs/ ，这样的分工成为可能。
在大规模项目（数十人团队、数年开发）中，这种结构非常有效。
Spec Kit（GitHub）
Spec Kit 是 GitHub 开发的 SDD 工具。它针对从零开始创建新项目进行了优化，具有从项目启动到运维覆盖所有阶段的详尽文档结构，这是其特点。
项目结构：
specs/001-todo-app-git-oauth/
├── spec.md # 功能规格书
├── checklists/
│ └── requirements.md # 质量检查清单
├── plan.md # 实施计划（技术选型）
├── research.md # Phase 0: 技术调研
├── data-model.md # Phase 1: 数据模型
├── contract/
│ └── openapi.yaml # Phase 1: 阶段 1：API 约束
├── tasks.md # Phase 2: 阶段 2：实现任务
└── quickstart.md # 开发者指南
Spec Kit 的特点是将开发流程分为四个阶段。
第 0 阶段：规格制定
第 0 阶段：规格制定，定义要做什么。
spec.md 中记载了功能概述、用户故事、验收标准等内容。例如：“作为工程师，希望能够通过 Google OAuth 登录。登录成功后会重定向到仪表盘”。
research.md 中记载了技术调研结果。例如：“作为认证库将比较 NextAuth.js 与 Auth0 的结果，决定采用 NextAuth.js。理由是与 Next.js 的集成更容易，且免费额度更充足”等调研报告。
第 1 阶段：设计
Phase 1: 设计中，设计如何构建。
plan.md 中记载了实现计划。包括技术选型的详细理由、架构图、开发进度表、风险管理等。
data-model.md 中记载了数据模型。是诸如“User 表包含 id (UUID)、email (string)、name (string)、createdAt (timestamp)”这样的具体模式定义。
contract/openapi.yaml 中以 OpenAPI 格式定义 API 规范。由此可确保类型安全，并能自动生成 API 文档。
第 2 阶段：实施
第 2 阶段：在实现阶段，执行具体的实现步骤。
tasks.md 列出实现任务。例如“项目初始化”“数据库设置”“认证端点实现”“登录界面制作”等具体任务。
第 3 阶段：审查
阶段 3：在评审中，确认实现内容的运行情况。
quickstart.md 中记载着开发者指南。包含环境搭建步骤、启动开发服务器的方法、运行测试的方法、部署步骤等。新成员加入时，只要阅读这个 quickstart.md 就能立即开始开发。
此外，checklists/requirements.md 包含质量检查清单。功能需求、非功能需求、测试覆盖率、文档、代码质量等，各项需要确认的内容都被列在清单中。
Spec Kit 的强项：
Spec Kit 作为从零开始启动新项目的完整指南发挥作用。由于明确了该做什么、按什么顺序做以及需要确认的事项，即使是经验不足的团队也能启动高质量的项目。
此外，通过与 OpenAPI 的集成来确保类型安全性也是一个重要优势。如果 API 规范发生更改，类型定义会自动更新，从而防止前端与后端的不一致。
还考虑了与 GitHub Copilot 的集成，在 GitHub 上的项目中尤为有效。
3 个工具的比较表
将三种工具在表格中进行比较如下：
| 特点 | OpenSpec | Spec Kit | Kiro |
|---|---|---|---|
| 对象 | 已有项目 (1→N) | 新项目（0→1） | 全部项目 |
| 结构 | 2 个文件夹(specs规格 + change变更) ） | 4 阶段文件 | (steering引导 + specs规格） |
| 主要文件 | proposal.md、tasks.md、spec(差异) | spec.md + research.md、plan.md + data-model.md、tasks.md 、quickstart.md | product.md、tech.md、structure.md、requirements.md、design.md、tasks.md |
| 变更管理 | 差异 + 存档 | Git履历 | Git履历 |
| 価格 | 免费（仅需支付 AI 工具使用费） | 免费（仅需支付 AI 工具使用费） | 付费（每月有免费额度） |
应该选择哪一个
每个工具都有明确的使用区分。
OpenSpec 非常适合在现有项目中引入。它可以在已在运行的项目中后期导入，学习成本低，并且便于并行推进多个变更。
“想在现有项目中引入 SDD，但又想避免大的变动”“团队成员使用不同的 AI 工具”“多个功能在并行开发中”等这种情况下，OpenSpec 非常适合。
Spec Kit 非常适合新项目的启动。它会从零开始细致引导，文档详实，且配备完善的质量检查表。
“准备开始一个新项目”“团队成员中有很多经验不足的人”“想重视质量”“正在使用 GitHub Copilot”——在这些情况下，Spec Kit 非常适合。
Kiro 非常适合在需要稳健结构的大规模长期项目中使用。其由 steering 和 specs 两层构成，结构强大，能够清晰地将项目方向与各个功能模块分离。
“适合在几十人规模的团队中开发”“适合持续数年的项目”“适合希望明确产品经理与开发者职责分工”“有预算（可以引入付费工具）”等情形时，Kiro 适用。
AI 编码的进化
AI 编码在过去几年里发生了巨大的进步。
第 1 代：代码补全时代（约从 2021 年起），出现了 GitHub Copilot、TabNine 等工具。这些工具在你写出部分代码后，会预测并补全下一行代码。开发者的生产力有所提升，但这不过是“补全”而已，开发者进行设计和编写代码的基本工作并未改变。
第 2 代：对话式代码生成的时代（约自 2023 年起），出现了 ChatGPT、Claude、Cursor 等。当用自然语言指示“做一个用户认证功能”时，就能生成完整的代码。这是一次革命，但同时也带来了所谓的 Vibe 编码问题。
第 3 代：规范驱动开发的时代（2025 年〜），出现了 OpenSpec、Kiro、Spec Kit 等工具。在编写代码之前先定义规范并与 AI 达成一致的方式。由此实现了可预测、可审计、可复用的开发。
开发者角色的变化
随着规范驱动开发的出现，开发者的角色也在发生变化。
在第二代 AI 编码中，开发者的角色是**“在 AI 的辅助下编写代码”**。工作重心是审查、修正并整合 AI 生成的代码。
在第 3 代 AI 编码中，开发者的角色已转变为**“设计规范并驾驭 AI”**。大量的代码编写工作交由 AI 完成，开发者则专注于明确界定“应该构建什么”。
不过，以下几点不变：
- 阅读代码的能力、理解代码的能力仍然很重要。要判断 AI 生成的代码是否正确，就需要具备读懂代码的能力。
- 将编写代码的工作交给 AI将成为未来趋势。通过让 AI 处理单纯的 CRUD 操作、模板代码、测试代码等，可以提高效率。
- 因此，明确界定“应该做什么”的能力将变得更加重要。今后工程师需要具备撰写具体且清晰规范的能力，而不是给出模糊的指示。
团队开发的改进
SDD 将为团队开发带来重大改进。
-
可以实现知识的积累与共享。因为规范被以文档形式保留，“为什么会有这样的设计”“是出于怎样的缘由选择这项技术”都能够在事后被理解。即便有新成员加入，只要阅读规范就能迅速跟上进度。
-
也有望提高质量。通过可预测的输出，“与预期不符”的差距会减少。可审查的变更使得能够在规格层面进行审查。可追溯的历史使得在出现问题时更容易确定是哪一项变更引起的。
总结
将这一年的学习总结为三点。
1.规范是新的源代码
在与 AI 协作时，明确的规范最为重要。比起代码本身，定义“要做什么”的规范在这个时代更有价值。只要有了规范，AI 就能生成代码。相反，如果没有规范，AI 就会迷失方向。
2.与 AI 协作需要结构性
需要摆脱凭感觉编写代码（Vibe 编码），转向可预测的开发。与其凭直觉编写代码，不如通过结构化的流程与 AI 协同工作，这样才能在质量和生产力之间取得平衡。
3.从被 AI 支配的开发，转向驾驭 AI 的开发
通过规范驱动开发（SDD），可以更高效地构建更优的软件。AI 是强大的工具，但掌控它的是人类。通过定义明确的规范并恰当操纵 AI，才能实现真正的生产力提升。
最后
这次在不断试验和改进的过程中，我写了关于今年开始流行的“规格驱动开发（SDD）”及实现它所需工具的内容。我认为今年我在工作内外学到的生成式 AI 工具和 Azure 资源等广泛内容，已经通过博客发表出来。今后我也会继续发布与工作无关但自己学到的内容。
备注：转载原作者文地址：tech-lab.sios.jp/archives/50…
