3.5 规格驱动开发与 OpenSpec：先明确行为，再安排实现

定做书柜时，只说“容量大一点”不够，还需要确定宽高、层板间距、承重与安装位置。规格说明也是这样：把希望软件具备的行为写成能够讨论、实现和验收的要求。

Spec 是 specification 的简称，可以译为规格说明。规格驱动开发强调先澄清目标和约束，再据此实现与验证。它能减少来回猜测，但不会让 AI 自动做到分毫不差。

为什么一段聊天记录还不够

假设要增加点赞功能，至少需要确定：谁能点赞、能否重复点赞、取消后数量怎样变化、刷新后是否保留。若这些问题没有说明，前端临时加一和数据库永久保存都可能被当作“已实现”。

聊天适合讨论；确定的规则适合写入项目。规格应说明系统应该怎样表现，设计说明解释如何实现，任务清单安排具体工作，测试则检查是否达到要求。

文档	回答的问题	点赞功能示例
需求或规格	用户能够做什么	登录用户可以点赞与取消
设计说明	用什么方式实现	如何存储用户与文章的关系
任务清单	还有哪些工作	接口、页面和测试分别完成到哪里
验收记录	做出的结果是否符合要求	重复请求没有增加重复点赞

用 OpenSpec 组织一次变更

OpenSpec为 AI 辅助开发提供规格与变更组织方式。使用前按照官方要求准备 Node.js，再安装并初始化。初始化会生成项目文件，应在准备使用它的项目目录执行。

npm install -g @fission-ai/openspec@latest
openspec --version
openspec init

初始化时选择自己使用的工具，按输出确认生成的技能或命令入口。不同客户端的调用写法可能不同，不要假定所有地方都支持同一个斜杠命令。

目录中的两类内容

下面展示常见组织方式，实际文件由版本与工作流决定：

openspec/
├── specs/
│   └── article-likes/
│       └── spec.md          # 已确认的现行行为
└── changes/
    └── add-article-likes/
        ├── proposal.md      # 为什么修改、影响什么
        ├── design.md        # 实现方案与取舍
        ├── tasks.md         # 实现和验证清单
        └── specs/
            └── article-likes/
                └── spec.md  # 本次增加或改变的要求

specs 记录当前约定，changes 记录一次变更及其过程。变更完成后再按工作流归档与同步，使后续任务能找到现行规则，而不是在一堆历史讨论中猜测。

一份可以验收的功能规格

下面是普通 Markdown 规格示例；若使用 OpenSpec，应由相应工作流转换为它要求的需求与场景结构。

# 文章点赞

## 目标与范围
登录用户可以给文章点赞或取消点赞。
本次只处理点赞，不增加收藏、消息通知或排行榜。

## 行为规则
- 同一个用户对同一篇文章最多保留一条有效点赞记录。
- 用户重复提交点赞请求时，不重复增加数量。
- 取消未点赞的文章时，最终仍为未点赞状态。
- 点赞状态与数量在刷新页面后保持一致。
- 未登录用户不能通过直接请求接口绕过限制。

## 异常处理
- 文章不存在时返回明确的未找到提示。
- 请求失败时，页面不应把未确认的状态显示为已成功保存。

## 验收场景
- 用户首次点赞后，状态变为已点赞，数量增加 1。
- 同一用户再次提交点赞请求，数量不增加。
- 用户取消点赞后，状态与数量恢复。
- 两个不同用户分别点赞，数量增加 2。
- 未登录请求被拒绝，数据库没有新增记录。

这份规格没有强迫你选择某个数据库，却明确了必须达到的行为。具体怎样约束重复记录，可以在设计阶段结合现有项目决定。

场景为什么比形容词更有效

“点赞稳定可靠”无法直接测试。“同一用户重复提交不增加数量”则能构造输入并核对结果。如果请求超时，还应考虑服务端可能已经成功写入，客户端重试后是否会重复计数。

验收场景最好同时覆盖正常情况、边界情况和失败情况。不要只写“全部测试通过”，因为测试本身尚未说明需要检查什么。

实现过程中发现需求不对怎么办

规格不是不能修改的合同文本。若实现时发现“用户重复点击”实际上应该切换点赞状态，就需要先确认交互意图，再更新相关规格和测试。不要让代码采用新规则，而文档继续写旧规则。

也不是所有错别字或局部修复都需要完整提案。影响范围越小，记录越可以简短；涉及多处行为或多人协作时，再保留更完整的设计与变更过程。

怎样确认 OpenSpec 使用正确

创建变更后，先检查生成文档是否真实反映需求；实现后，核对任务清单与实际文件；归档前，检查验证结果与遗留事项。可以用 openspec --help 查当前命令，再按官方命令说明进行校验。

文档格式校验通过，只说明文件结构符合工具要求，不代表功能已经正确实现。反过来，功能暂时能运行，文档没同步，也会让下一次修改失去可靠依据。

其他带规格或任务模式的工具也可以采用同样思路，例如 Qoder。无论使用哪种产品，重点都是把目标、约束、实现和验收对应起来。