总的来说，如果你想快速上手、灵活迭代，选 OpenSpec；如果你做大型项目、需要完整文档链，选 spec-kit。

官网：

https://github.com/github/spec-kit/：Spec Kit 是一个开源工具包，旨在通过规范驱动开发（Spec-Driven Development） 方法帮助开发者更快速地构建高质量软件。其核心思想是将规范（specifications）变为可执行的内容，直接生成可工作的实现，而非仅作为开发指导。

https://github.com/Fission-AI/openspec

背景：Ai Coding演进

整体来看，AI Coding 的演进遵循一条清晰的路线：人工干预越来越少，AI 自主性越来越高。

几个关键转折点值得关注：

从补全到理解（2021→2022）：早期 AI 只是”预测下一个 token”，本质是高级自动补全。ChatGPT 之后，AI 开始真正”理解”需求，可以解释代码逻辑、定位 bug、生成完整函数。

从片段到代码库（2022→2023）：Cursor 等工具引入了代码库感知能力，AI 不再只看当前文件，而是理解整个项目的结构与上下文，多文件重构成为可能。

从助手到 Agent（2023→2024）：这是最重要的跳跃。AI 从”回答问题”变成”自主行动”——能规划步骤、调用工具、运行命令、读取结果、再迭代。Devin、Claude Code 是代表。

Spec Coding 的出现（2025）：这是你之前问到的阶段。用户只需写规格（自然语言或结构化描述），AI 负责将其转化为可运行的代码，并自动测试和修复。人的角色从”写代码”转变为”定义 what”。

Spec（specification） 是一份描述软件应该”做什么”的文档，通常包括功能需求、接口定义、行为规则、数据格式等。开发者按照这份规格来实现代码，而不是边想边写。

当前行业争议主要集中在：AI 能否真正替代软件工程师的系统设计和模糊需求拆解能力，这也是全自主阶段尚未到来的核心障碍。

Vibe Coding VS Spec Coding

vibe coding：prd直接给agent，然后开干，生成代码，这个过程就是。（物料->炒菜）

spec coding：通过需求分析（prd分析出包含哪些功能点，人工查漏不全）、技术方案设计（基于这些功能点生成具体方案，人工再明确下，比如用到MQ，应该确认哪个选型）、代码生成（基于技术方进行生成）。（物料->生成菜谱（trd）->炒菜）。 Spec coding通过 human-in-loop来确认具体方案。

一、spec-kit VS openspec

两个都是 Spec-Driven Development（规格驱动开发） 框架，核心理念相同：先写规格、再生成代码，让 AI 编码更可预测。但定位和风格差异明显：

核心区别

维度	spec-kit（GitHub 官方）	OpenSpec（Fission-AI）
维护方	GitHub 官方出品	独立开源社区
Stars	68.8k ⭐	21.9k ⭐
安装方式	Python CLI（`uv` 安装）	npm 包（`npm install -g`）
工作流风格	阶段式、严格的 phase gates	流动式、迭代灵活
复杂度	较重，文档丰富，配置多	轻量，命令简洁
适用场景	企业级、大型项目、Greenfield	个人/团队、Brownfield 友好
命令风格	`/speckit.constitution` → `/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement`	`/opsx:new` → `/opsx:ff` → `/opsx:apply` → `/opsx:archive`

OpenSpec 自己的 README 里也有一句直接的比较：spec-kit 更彻底但也更重，有严格的阶段门控和大量 Markdown，需要 Python 环境；OpenSpec 更轻量，可以自由迭代。

二、open-spec

open-spec 命令流程解析

这四个命令构成了一条完整的 需求 → 开发 → 落地 → 归档 流水线。下面先逐个解释，再用一个完整例子串联。

命令说明

`/opsx:new` — 创建新规格

从一个需求描述出发，生成结构化的 spec 文档（功能描述、接口定义、边界条件等）。这是整个流程的起点，产出物是一份可供后续命令消费的 spec 文件。

`/opsx:ff` — Fast Forward（推演/完善）

对已有 spec 做 深化推演。自动补全遗漏的字段、识别潜在冲突、生成示例数据或测试用例。”ff” 取意 “fast forward”，让 spec 从粗糙变得可执行。

`/opsx:apply` — 应用规格到代码

将 spec 落地为实际代码/配置变更。读取当前 spec 内容，对目标代码库执行 diff/patch，产出可提交的代码改动。

`/opsx:archive` — 归档规格

将已完成的 spec 打上终态标记并归档，从活跃队列移入历史记录，便于后续溯源和审计。

完整示例：给用户服务新增「手机号登录」功能

需求：用户可以用手机号 + 短信验证码登录，原有邮箱登录保持不变

Step 1 — `/opsx:new`

/opsx:new "手机号短信验证码登录"

1	/opsx:new "手机号短信验证码登录"

产出： specs/phone-login.md（草稿）

title: 手机号短信验证码登录
status: draft
scope:
  - POST /auth/sms/send      # 发送验证码
  - POST /auth/sms/verify    # 校验并登录
constraints:
  - 验证码 6 位数字，5 分钟有效
  - 同一手机号 60 秒内限发 1 次
open_questions:
  - 验证码存储用 Redis 还是 DB？
  - 国际手机号是否需要支持？

title: 手机号短信验证码登录

status: draft

scope:

- POST /auth/sms/send # 发送验证码

- POST /auth/sms/verify # 校验并登录

constraints:

- 验证码 6 位数字，5 分钟有效

- 同一手机号 60 秒内限发 1 次

open_questions:

- 验证码存储用 Redis 还是 DB？

- 国际手机号是否需要支持？

Step 2 — `/opsx:ff`

/opsx:ff specs/phone-login.md

1	/opsx:ff specs/phone-login.md

产出： spec 被补全，open_questions 被决策掉

title: 手机号短信验证码登录
status: ready
scope:
  - POST /auth/sms/send
      request:  { phone: "string, E.164格式" }
      response: { request_id: "uuid", expires_in: 300 }
  - POST /auth/sms/verify
      request:  { phone: "string", code: "string", request_id: "uuid" }
      response: { token: "JWT", user_id: "string" }
decisions:
  - 验证码存 Redis，key = sms:{phone}，TTL = 300s
  - 暂不支持国际号，phone 必须 +86 开头
  - 限流用 Redis SETNX，key = sms:limit:{phone}，TTL = 60s
test_cases:
  - 正常发码 → 正常验证 → 返回 token ✅
  - 60s 内重复发码 → 429 Too Many Requests ✅
  - 验证码错误 3 次 → 锁定该 request_id ✅
  - 验证码过期 → 401 Expired ✅

title: 手机号短信验证码登录

status: ready

scope:

- POST /auth/sms/send

request: { phone: "string, E.164格式" }

response: { request_id: "uuid", expires_in: 300 }

- POST /auth/sms/verify

request: { phone: "string", code: "string", request_id: "uuid" }

response: { token: "JWT", user_id: "string" }

decisions:

- 验证码存 Redis，key = sms:{phone}，TTL = 300s

- 暂不支持国际号，phone 必须 +86 开头

- 限流用 Redis SETNX，key = sms:limit:{phone}，TTL = 60s

test_cases:

- 正常发码 → 正常验证 → 返回 token ✅

- 60s 内重复发码 → 429 Too Many Requests ✅

- 验证码错误 3 次 → 锁定该 request_id ✅

- 验证码过期 → 401 Expired ✅

Step 3 — `/opsx:apply`

/opsx:apply specs/phone-login.md --target ./src
```

**产出：** 实际代码变更
```
✅ 新增  src/routes/auth/sms.ts
✅ 新增  src/services/sms.service.ts
✅ 修改  src/routes/index.ts         # 注册新路由
✅ 修改  src/types/auth.d.ts         # 扩展登录类型
✅ 新增  tests/auth/sms.test.ts      # 按 test_cases 生成

/opsx:apply specs/phone-login.md --target ./src

```

**产出：** 实际代码变更

```

✅ 新增 src/routes/auth/sms.ts

✅ 新增 src/services/sms.service.ts

✅ 修改 src/routes/index.ts # 注册新路由

✅ 修改 src/types/auth.d.ts # 扩展登录类型

✅ 新增 tests/auth/sms.test.ts # 按 test_cases 生成

Step 4 — `/opsx:archive`

代码合并上线后：

/opsx:archive specs/phone-login.md --version v2.4.1

1	/opsx:archive specs/phone-login.md --version v2.4.1

产出： spec 状态变更并移入归档目录

specs/phone-login.md  →  archive/2026-03/phone-login@v2.4.1.md

status: archived
archived_at: 2026-03-18
shipped_version: v2.4.1

specs/phone-login.md → archive/2026-03/phone-login@v2.4.1.md

status: archived

archived_at: 2026-03-18

shipped_version: v2.4.1

流程总览

/opsx:new      →  生成草稿 spec（有 open questions）
    ↓
/opsx:ff       →  推演补全（决策 + 接口细化 + 测试用例）
    ↓
/opsx:apply    →  生成代码变更（可直接提 PR）
    ↓
/opsx:archive  →  归档终态 spec（可溯源）

/opsx:new → 生成草稿 spec（有 open questions）

↓

/opsx:ff → 推演补全（决策 + 接口细化 + 测试用例）

↓

/opsx:apply → 生成代码变更（可直接提 PR）

↓

/opsx:archive → 归档终态 spec（可溯源）

在 Claude Code 中使用 OpenSpec（推荐）

# 1. 安装
npm install -g @fission-ai/openspec@latest

# 2. 在项目目录初始化
cd your-project
openspec init

# 3. 打开 Claude Code，然后开始
```

在 Claude Code 中的流程：
```
# 新建一个 feature
/opsx:new add-user-auth

# 一键生成所有规划文档（proposal、specs、design、tasks）
/opsx:ff

# 执行实现
/opsx:apply

# 归档完成
/opsx:archive

# 1. 安装

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

# 2. 在项目目录初始化

cd your-project

openspec init

# 3. 打开 Claude Code，然后开始

```

在 Claude Code 中的流程：

```

# 新建一个 feature

/opsx:new add-user-auth

# 一键生成所有规划文档（proposal、specs、design、tasks）

/opsx:ff

# 执行实现

/opsx:apply

# 归档完成

/opsx:archive

三、speckit

speckit 命令流程解析

spec-kit 提供一套 /speckit.* 斜杠命令，让你在 Claude Code 里按结构化流程开发：

命令	功能
`/speckit.constitution`	创建项目原则/规范
`/speckit.specify`	描述要构建什么（需求）
`/speckit.plan`	生成技术实现方案
`/speckit.tasks`	拆解成可执行任务清单
`/speckit.implement`	执行所有任务、开始编码

这五个命令构成了 约束定义 → 需求规格 → 实现计划 → 任务拆解 → 代码落地 的完整研发流水线。

产品想法/需求
    ↓
┌─────────────────┐
│ /speckit.constitution│  → 创建项目原则/规范。前置
└─────────────────┘
    ↓
┌─────────────────┐
│ /speckit.specify│  → 产品规格文档 (WHAT)
└─────────────────┘
    ↓
┌─────────────────┐
│ /speckit.plan   │  → 技术方案 (HOW)
└─────────────────┘
    ↓
┌─────────────────┐
│ /speckit.tasks  │  → 拆任务 (DO)
└─────────────────┘
    ↓
┌─────────────────┐
│ /speckit.impletment  │  → 执行任务 (DO)
└─────────────────┘

产品想法/需求

↓

┌─────────────────┐

│ /speckit.constitution│ → 创建项目原则/规范。前置

└─────────────────┘

↓

┌─────────────────┐

│ /speckit.specify│ → 产品规格文档 (WHAT)

└─────────────────┘

↓

┌─────────────────┐

│ /speckit.plan │ → 技术方案 (HOW)

└─────────────────┘

↓

┌─────────────────┐

│ /speckit.tasks │ → 拆任务 (DO)

└─────────────────┘

↓

┌─────────────────┐

│ /speckit.impletment │ → 执行任务 (DO)

└─────────────────┘

三个职责：

阶段	回答的问题	输出特点	面向对象
Specify	用户需要什么？	业务导向，技术无关	产品经理/客户
Plan	技术上怎么实现？	技术决策，架构设计	架构师/Tech Lead
Tasks	谁做什么事？	可执行步骤，工作量	开发团队

命令说明

`speckit.constitution` — 定义项目宪法（约束层）

整个项目的最高约束文档，定义技术栈、编码规范、架构原则、禁止事项等。所有后续命令生成的内容都必须遵守 constitution 的约束。只需定义一次，长期有效。

`/speckit.specify` — 编写功能规格

基于 constitution 的约束，将一个需求转化为结构化的功能规格（等价于 open-spec 的 new + ff 合并版）。产出接口定义、数据模型、边界条件、验收标准。

`/speckit.plan` — 生成实现方案

对 specify 产出的规格，生成技术实现路径：涉及哪些模块、改动顺序、依赖关系、风险点。是介于规格和任务之间的架构决策层。

`/speckit.tasks` — 拆解为可执行任务

将 plan 中的实现方案拆解为具体的开发任务清单，每个 task 有明确的输入、输出、完成标准，可直接分配给开发者或 AI 执行。

`/speckit.implement` — 执行任务生成代码

逐个执行 tasks 中的任务，生成实际代码变更。每次 implement 对应一个 task，保证改动粒度可控、可回滚。

完整示例：延用「手机号短信验证码登录」

Step 0 — `speckit.constitution`（一次性定义，全局生效）

constitution 相当于团队的”法律”，后续所有命令的产出都在这个边界内运作。

# speckit.constitution.yaml
project: user-service
language: TypeScript
runtime: Node.js 20
framework: Fastify
database: PostgreSQL + Prisma ORM
cache: Redis 7
auth: JWT (RS256)

principles:
  - 所有接口必须有 request/response 类型声明
  - 禁止在 route 层直接操作 DB，必须经过 service 层
  - 错误码统一用 AppError 类抛出，禁止裸 throw string
  - 单元测试覆盖率 ≥ 80%

forbidden:
  - 禁止使用 any 类型
  - 禁止明文存储任何凭证
  - 禁止跨 service 直接读对方的 DB 表

# speckit.constitution.yaml

project: user-service

language: TypeScript

runtime: Node.js 20

framework: Fastify

database: PostgreSQL + Prisma ORM

cache: Redis 7

auth: JWT (RS256)

principles:

- 所有接口必须有 request/response 类型声明

- 禁止在 route 层直接操作 DB，必须经过 service 层

- 错误码统一用 AppError 类抛出，禁止裸 throw string

- 单元测试覆盖率 ≥ 80%

forbidden:

- 禁止使用 any 类型

- 禁止明文存储任何凭证

- 禁止跨 service 直接读对方的 DB 表

Step 1 — `/speckit.specify`

对比 open-spec：specify = opsx:new + opsx:ff 二合一，且天然遵守 constitution

/speckit.specify "用户可以用手机号 + 短信验证码登录，原有邮箱登录保持不变"

1	/speckit.specify "用户可以用手机号 + 短信验证码登录，原有邮箱登录保持不变"

产出： specs/phone-login.specify.md

feature: 手机号短信验证码登录
version: 1.0.0

interfaces:
  POST /auth/sms/send:
    request:
      phone: string          # E.164 格式，仅支持 +86
    response:
      request_id: uuid
      expires_in: 300        # 秒
    errors:
      429: 60s 内重复请求
      400: 手机号格式非法

  POST /auth/sms/verify:
    request:
      phone: string
      code: string           # 6位数字
      request_id: uuid
    response:
      token: string          # JWT RS256
      user_id: string
    errors:
      401: 验证码错误 / 过期
      403: request_id 已被锁定（错误3次）

data_model:
  SmsRecord (Redis):
    key: sms:{phone}
    value: { code, request_id, attempts }
    TTL: 300s

acceptance_criteria:
  - 正常流程可拿到有效 JWT
  - 60s 内重发返回 429
  - 验证码错误 3 次锁定 request_id
  - 验证码 5 分钟后过期返回 401
  - 不影响现有邮箱登录流程

feature: 手机号短信验证码登录

version: 1.0.0

interfaces:

POST /auth/sms/send:

request:

phone: string # E.164 格式，仅支持 +86

response:

request_id: uuid

expires_in: 300 # 秒

errors:

429: 60s 内重复请求

400: 手机号格式非法

POST /auth/sms/verify:

request:

phone: string

code: string # 6位数字

request_id: uuid

response:

token: string # JWT RS256

user_id: string

errors:

401: 验证码错误 / 过期

403: request_id 已被锁定（错误3次）

data_model:

SmsRecord (Redis):

key: sms:{phone}

value: { code, request_id, attempts }

TTL: 300s

acceptance_criteria:

- 正常流程可拿到有效 JWT

- 60s 内重发返回 429

- 验证码错误 3 次锁定 request_id

- 验证码 5 分钟后过期返回 401

- 不影响现有邮箱登录流程

Step 2 — `/speckit.plan （技术方案）`

plan 是架构师视角——回答”怎么改、改哪里、顺序是什么”，但还不是具体任务。

/speckit.plan specs/phone-login.specify.md

1	/speckit.plan specs/phone-login.specify.md

产出： specs/phone-login.plan.md

implementation_plan:

  modules_affected:
    - src/routes/auth/          # 新增 sms 路由
    - src/services/sms/         # 新增 SmsService
    - src/lib/redis.ts          # 复用现有 Redis client
    - src/errors/AppError.ts    # 复用，无需修改
    - src/routes/index.ts       # 注册新路由（改动最小）

  execution_order:
    1. 定义类型：SmsRequest / SmsVerifyRequest / SmsVerifyResponse
    2. 实现 SmsService（核心逻辑：发码、限流、校验、锁定）
    3. 实现路由层（薄薄一层，调用 service）
    4. 注册路由
    5. 编写单元测试

  risks:
    - Redis 不可用时降级策略：暂不支持，直接返回 503
    - 短信服务商 SDK 需作为外部依赖注入，方便 mock 测试

  dependencies:
    external: aliyun-sms-sdk（新增）
    internal: redis.ts, AppError, jwt.util

implementation_plan:

modules_affected:

- src/routes/auth/ # 新增 sms 路由

- src/services/sms/ # 新增 SmsService

- src/lib/redis.ts # 复用现有 Redis client

- src/errors/AppError.ts # 复用，无需修改

- src/routes/index.ts # 注册新路由（改动最小）

execution_order:

1. 定义类型：SmsRequest / SmsVerifyRequest / SmsVerifyResponse

2. 实现 SmsService（核心逻辑：发码、限流、校验、锁定）

3. 实现路由层（薄薄一层，调用 service）

4. 注册路由

5. 编写单元测试

risks:

- Redis 不可用时降级策略：暂不支持，直接返回 503

- 短信服务商 SDK 需作为外部依赖注入，方便 mock 测试

dependencies:

external: aliyun-sms-sdk（新增）

internal: redis.ts, AppError, jwt.util

Step 3 — `/speckit.tasks`

tasks 是执行者视角——每个 task 独立、有明确的完成标准，粒度刚好是”一次可提交的改动”。

/speckit.tasks specs/phone-login.plan.md

1	/speckit.tasks specs/phone-login.plan.md

产出： specs/phone-login.tasks.md

tasks:

  T01:
    title: 定义 SMS 相关 TypeScript 类型
    input: specify 中的 interfaces 定义
    output: src/types/sms.d.ts
    done_when: 类型文件无 TS 报错，覆盖所有 request/response

  T02:
    title: 实现 SmsService — 发码逻辑
    input: T01 的类型，redis.ts
    output: src/services/sms/sms.service.ts (sendCode 方法)
    done_when: 限流逻辑 + 验证码生成 + Redis 存储均通过单测

  T03:
    title: 实现 SmsService — 验证逻辑
    input: T01、T02
    output: src/services/sms/sms.service.ts (verifyCode 方法)
    done_when: 错误计数、锁定、过期场景均通过单测

  T04:
    title: 实现路由层
    input: T02、T03
    output: src/routes/auth/sms.route.ts
    done_when: 路由正确调用 service，错误通过 AppError 抛出

  T05:
    title: 注册路由 & 集成测试
    input: T04
    output: src/routes/index.ts 变更 + tests/auth/sms.test.ts
    done_when: 所有 acceptance_criteria 通过

tasks:

T01:

title: 定义 SMS 相关 TypeScript 类型

input: specify 中的 interfaces 定义

output: src/types/sms.d.ts

done_when: 类型文件无 TS 报错，覆盖所有 request/response

T02:

title: 实现 SmsService — 发码逻辑

input: T01 的类型，redis.ts

output: src/services/sms/sms.service.ts (sendCode 方法)

done_when: 限流逻辑 + 验证码生成 + Redis 存储均通过单测

T03:

title: 实现 SmsService — 验证逻辑

input: T01、T02

output: src/services/sms/sms.service.ts (verifyCode 方法)

done_when: 错误计数、锁定、过期场景均通过单测

T04:

title: 实现路由层

input: T02、T03

output: src/routes/auth/sms.route.ts

done_when: 路由正确调用 service，错误通过 AppError 抛出

T05:

title: 注册路由 & 集成测试

input: T04

output: src/routes/index.ts 变更 + tests/auth/sms.test.ts

done_when: 所有 acceptance_criteria 通过

Step 4 — `/speckit.implement`

每次执行一个 task：

/speckit.implement T01
/speckit.implement T02
/speckit.implement T03
/speckit.implement T04
/speckit.implement T05

/speckit.implement T01

/speckit.implement T02

/speckit.implement T03

/speckit.implement T04

/speckit.implement T05

两套命令对比总览

open-spec 流程（偏文档驱动）：
  opsx:new  →  opsx:ff  →  opsx:apply  →  opsx:archive
  [草稿]       [推演补全]   [生成代码]     [归档]

speckit 流程（偏工程驱动）：
  constitution  →  specify  →  plan  →  tasks  →  implement
  [全局约束]       [功能规格]   [架构方案]  [任务清单]  [逐条生成代码]

open-spec 流程（偏文档驱动）：

opsx:new → opsx:ff → opsx:apply → opsx:archive

[草稿] [推演补全] [生成代码] [归档]

speckit 流程（偏工程驱动）：

constitution → specify → plan → tasks → implement

[全局约束] [功能规格] [架构方案] [任务清单] [逐条生成代码]

维度	open-spec	speckit
粒度控制	整体一次性 apply	按 task 逐步 implement
约束管理	无全局约束层	constitution 兜底
适合场景	快速原型、单功能交付	团队协作、多模块改动
可追溯性	archive 归档 spec	tasks 天然就是变更日志

两套可以组合用：speckit 管理规格和任务，open-spec 的 archive 负责最终归档。

在 Claude Code 中使用 spec-kit

# 1. 安装（需要 Python + uv）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 2. 初始化项目，指定 claude
specify init my-project --ai claude

# 3. 进入项目目录，打开 Claude Code
cd my-project
claude
```

在 Claude Code 中的流程：
```
# 第一步：建立项目原则
/speckit.constitution 专注代码质量、测试标准、用户体验一致性

# 第二步：写需求
/speckit.specify 构建一个用户认证系统，支持邮箱注册、登录、密码重置

# 第三步：技术规划
/speckit.plan 使用 Next.js + PostgreSQL + JWT

# 第四步：任务拆解
/speckit.tasks

# 第五步：执行
/speckit.implement

# 1. 安装（需要 Python + uv）

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 2. 初始化项目，指定 claude

specify init my-project --ai claude

# 3. 进入项目目录，打开 Claude Code

cd my-project

claude

```

在 Claude Code 中的流程：

```

# 第一步：建立项目原则

/speckit.constitution 专注代码质量、测试标准、用户体验一致性

# 第二步：写需求

/speckit.specify 构建一个用户认证系统，支持邮箱注册、登录、密码重置

# 第三步：技术规划

/speckit.plan 使用 Next.js + PostgreSQL + JWT

# 第四步：任务拆解

/speckit.tasks

# 第五步：执行

/speckit.implement

spec-kit装载Claude的原理是什么呢？

核心原理其实非常简单，分三层来理解：

第一层：Claude Code 的 slash command 机制

Claude Code 原生支持一个约定：项目根目录下的 .claude/commands/ 里，每一个 .md 文件就是一条自定义斜杠命令。文件名即命令名，文件内容就是给 Claude 的”提示词指令”。比如 speckit.specify.md 文件存在，Claude Code 启动时就会自动注册 /speckit.specify 命令。这是 Claude Code 本身的能力，不需要任何插件系统。

第二层：specify-cli 做了什么

specify init --ai claude 本质上就是一个”文件复制器”，它从 GitHub 上拉取 spec-kit 的模板，然后在你的项目里生成这几样东西：

.claude/commands/speckit.*.md — 各命令的提示词文件（核心）
.specify/ — 存放规格文档、脚本、模板的目录
CLAUDE.md — 项目级的上下文说明，Claude Code 启动时会读取

第三层：命令执行时发生了什么

当你输入 /speckit.specify 做一个待办应用 时，Claude Code 实际上是把对应 .md 文件的内容 + 你的参数一起作为 prompt 发给模型，模型按照里面的指令执行工作流（创建 git 分支、写 spec 文件、调用 shell 脚本等）。

澄清/speckit.clarify 、/speckit.analyze、/speckit.checklist

这三个都是可选的质量门禁命令，分别插入在流程的不同节点。完整 speckit 流程（含可选命令）

constitution
     ↓
  specify
     ↓
 [clarify]     ← 🆕 可选：结构化澄清，消除歧义
     ↓
   plan
     ↓
 [checklist]   ← 🆕 可选：验证规格完整性和一致性
     ↓
   tasks
     ↓
 [analyze]     ← 🆕 可选：跨产物一致性检查
     ↓
 implement

constitution

↓

specify

↓

[clarify] ← 🆕 可选：结构化澄清，消除歧义

↓

plan

↓

[checklist] ← 🆕 可选：验证规格完整性和一致性

↓

tasks

↓

[analyze] ← 🆕 可选：跨产物一致性检查

↓

implement

完整流程 + 每个命令的定位

命令	类型	核心问题	输入	输出
`constitution`	必选	我们的约束是什么？	人工定义	全局规则
`specify`	必选	要做什么？	需求描述	功能规格
`clarify`	可选	规格里哪些地方会翻车？	specify 产出	澄清问卷 + 决策
`plan`	必选	怎么做？	specify 产出	架构方案
`checklist`	可选	规格够不够好、能不能拆任务？	specify + plan	质量报告
`tasks`	必选	具体做哪些事？	plan 产出	任务清单
`analyze`	可选	三份文档互相对齐了吗？	所有产物	一致性报告
`implement`	必选	生成代码	tasks 产出	代码变更

`/speckit.clarify` — 结构化澄清问卷

位置： specify 之后、plan 之前 作用： 在进入技术方案前，针对规格中的模糊区域生成结构化问题，逼出所有隐藏假设。

和我之前说的 specify --clarify 的区别：--clarify 是在写规格之前问业务问题；/speckit.clarify 是规格写完后做二次审查，发现 specify 阶段没察觉的风险点。

/speckit.clarify specs/phone-login.specify.md
```

**产出示例：**
```
🔍 [speckit.clarify] 高风险歧义点：

[风险等级: HIGH]
Q1 「验证码错误3次锁定 request_id」—— 锁定后用户如何解锁？
   → spec 未定义解锁路径，可能导致用户永久无法登录
   选项: A. 重新发码自动解锁  B. 需要人工客服介入  C. 5分钟自动解锁

[风险等级: MEDIUM]
Q2 同一手机号在多设备同时请求验证码，Redis key 会覆盖 —— 是否符合预期？
   → 当前设计会导致旧设备的验证码立即失效
   选项: A. 符合预期（以最新码为准）  B. 需要支持多设备并发

[风险等级: LOW]
Q3 JWT 过期时间未在 specify 中定义，将沿用 constitution 默认值（7天）—— 确认？
   选项: A. 确认  B. 手机号登录需要更短的有效期

/speckit.clarify specs/phone-login.specify.md

```

**产出示例：**

```

🔍 [speckit.clarify] 高风险歧义点：

[风险等级: HIGH]

Q1 「验证码错误3次锁定 request_id」—— 锁定后用户如何解锁？

→ spec 未定义解锁路径，可能导致用户永久无法登录

选项: A. 重新发码自动解锁 B. 需要人工客服介入 C. 5分钟自动解锁

[风险等级: MEDIUM]

Q2 同一手机号在多设备同时请求验证码，Redis key 会覆盖 —— 是否符合预期？

→ 当前设计会导致旧设备的验证码立即失效

选项: A. 符合预期（以最新码为准） B. 需要支持多设备并发

[风险等级: LOW]

Q3 JWT 过期时间未在 specify 中定义，将沿用 constitution 默认值（7天）—— 确认？

选项: A. 确认 B. 手机号登录需要更短的有效期

`/speckit.checklist` — 规格质量检查清单

位置： plan 之后、tasks 之前 作用： 从完整性、清晰度、一致性三个维度验证规格是否达到可拆任务的标准，防止带着残缺规格进入开发。

/speckit.clarify specs/phone-login.specify.md

1	/speckit.clarify specs/phone-login.specify.md

产出示例：

📋 [speckit.checklist] 规格质量报告

完整性检查:
  ✅ 所有接口均有 request/response 类型定义
  ✅ 所有错误码均有描述
  ❌ 缺少：/auth/sms/send 的成功率 SLA 定义（plan 中提到需要监控却无基准值）
  ❌ 缺少：验证码发送失败（短信商超时）的 fallback 行为

清晰度检查:
  ✅ 边界条件明确（60s限流、5min过期、3次锁定）
  ⚠️  「E.164格式」未给出校验正则，实现者可能理解不一致

一致性检查:
  ✅ 数据模型与接口定义对齐
  ✅ 错误码与 AppError 规范一致（符合 constitution）
  ❌ plan 中提到「短信供应商抽象为 SmsSdkPort」，但 specify 的 data_model 中未体现该接口定义

结论: ❌ 未通过（2个ERROR，1个WARNING）
建议: 补全后重新运行 /speckit.checklist，通过后再执行 /speckit.tasks

📋 [speckit.checklist] 规格质量报告

完整性检查:

✅ 所有接口均有 request/response 类型定义

✅ 所有错误码均有描述

❌ 缺少：/auth/sms/send 的成功率 SLA 定义（plan 中提到需要监控却无基准值）

❌ 缺少：验证码发送失败（短信商超时）的 fallback 行为

清晰度检查:

✅ 边界条件明确（60s限流、5min过期、3次锁定）

⚠️ 「E.164格式」未给出校验正则，实现者可能理解不一致

一致性检查:

✅ 数据模型与接口定义对齐

✅ 错误码与 AppError 规范一致（符合 constitution）

❌ plan 中提到「短信供应商抽象为 SmsSdkPort」，但 specify 的 data_model 中未体现该接口定义

结论: ❌ 未通过（2个ERROR，1个WARNING）

建议: 补全后重新运行 /speckit.checklist，通过后再执行 /speckit.tasks

`/speckit.analyze` — 跨产物一致性分析

位置： tasks 之后、implement 之前 作用： 把 specify / plan / tasks 三份产物放在一起做横向对齐检查，确保任务清单没有遗漏规格要求、没有和架构方案冲突。是 implement 前的最后一道质量门。

/speckit.analyze specs/phone-login.*.md

1	/speckit.analyze specs/phone-login.*.md

产出示例：

🔬 [speckit.analyze] 跨产物一致性报告

specify → plan 对齐:
  ✅ 所有接口均在 plan 的 modules_affected 中有对应模块
  ✅ Redis 数据模型在 plan 中有实现路径
  ❌ specify 定义了「错误3次锁定」，plan 中未出现对应的锁定状态存储设计

plan → tasks 对齐:
  ✅ execution_order 的5个步骤均映射到了 T01-T05
  ❌ plan 中的「aliyun-sms-sdk 作为外部依赖注入」未在任何 task 中体现
  ⚠️  T05 的集成测试覆盖了 acceptance_criteria 中4/5条，缺少「不影响邮箱登录」的回归测试

specify → tasks 对齐:
  ✅ 所有 acceptance_criteria 均有对应 task 覆盖（含上述缺口修复后）

结论: ❌ 发现 2 处 ERROR，请修复后再执行 /speckit.implement
快速修复建议:
  → 在 T03 中补充：Redis 存储锁定状态，key = sms:lock:{request_id}，TTL = 300s
  → 新增 T06：安装并注入 aliyun-sms-sdk，实现 SmsSdkPort interface

🔬 [speckit.analyze] 跨产物一致性报告

specify → plan 对齐:

✅ 所有接口均在 plan 的 modules_affected 中有对应模块

✅ Redis 数据模型在 plan 中有实现路径

❌ specify 定义了「错误3次锁定」，plan 中未出现对应的锁定状态存储设计

plan → tasks 对齐:

✅ execution_order 的5个步骤均映射到了 T01-T05

❌ plan 中的「aliyun-sms-sdk 作为外部依赖注入」未在任何 task 中体现

⚠️ T05 的集成测试覆盖了 acceptance_criteria 中4/5条，缺少「不影响邮箱登录」的回归测试

specify → tasks 对齐:

✅ 所有 acceptance_criteria 均有对应 task 覆盖（含上述缺口修复后）

结论: ❌ 发现 2 处 ERROR，请修复后再执行 /speckit.implement

快速修复建议:

→ 在 T03 中补充：Redis 存储锁定状态，key = sms:lock:{request_id}，TTL = 300s

→ 新增 T06：安装并注入 aliyun-sms-sdk，实现 SmsSdkPort interface

什么时候用这三个可选命令？

场景	建议
需求清晰 + 独立开发 + 快速原型	全部跳过，走最短路径
需求模糊 / 跨团队协作	加 `clarify`，把隐藏假设逼出来
多人同时写 spec 和 plan	加 `checklist`，防止规格带病进入开发
大型功能 / 多模块改动	加 `analyze`，implement 前做最后的一致性兜底

【Spec Coding】spec-kit 和 openspec

背景：Ai Coding演进

一、spec-kit VS openspec

核心区别

推荐选择

二、open-spec

open-spec 命令流程解析

命令说明

/opsx:new — 创建新规格

/opsx:ff — Fast Forward（推演/完善）

/opsx:apply — 应用规格到代码

/opsx:archive — 归档规格

完整示例：给用户服务新增「手机号登录」功能

Step 1 — /opsx:new

Step 2 — /opsx:ff

Step 3 — /opsx:apply

Step 4 — /opsx:archive

流程总览

在 Claude Code 中使用 OpenSpec（推荐）

三、speckit

speckit 命令流程解析

命令说明

speckit.constitution — 定义项目宪法（约束层）

/speckit.specify — 编写功能规格

/speckit.plan — 生成实现方案

/speckit.tasks — 拆解为可执行任务

/speckit.implement — 执行任务生成代码

完整示例：延用「手机号短信验证码登录」

Step 0 — speckit.constitution（一次性定义，全局生效）

Step 1 — /speckit.specify

Step 2 — /speckit.plan （技术方案）

Step 3 — /speckit.tasks

Step 4 — /speckit.implement

两套命令对比总览

在 Claude Code 中使用 spec-kit

spec-kit装载Claude的原理是什么呢？

澄清/speckit.clarify 、/speckit.analyze、/speckit.checklist

/speckit.clarify — 结构化澄清问卷

/speckit.checklist — 规格质量检查清单

/speckit.analyze — 跨产物一致性分析

Related Posts:

分类&标签

`/opsx:new` — 创建新规格

`/opsx:ff` — Fast Forward（推演/完善）

`/opsx:apply` — 应用规格到代码

`/opsx:archive` — 归档规格

Step 1 — `/opsx:new`

Step 2 — `/opsx:ff`

Step 3 — `/opsx:apply`

Step 4 — `/opsx:archive`

`speckit.constitution` — 定义项目宪法（约束层）

`/speckit.specify` — 编写功能规格

`/speckit.plan` — 生成实现方案

`/speckit.tasks` — 拆解为可执行任务

`/speckit.implement` — 执行任务生成代码

Step 0 — `speckit.constitution`（一次性定义，全局生效）

Step 1 — `/speckit.specify`

Step 2 — `/speckit.plan （技术方案）`

Step 3 — `/speckit.tasks`

Step 4 — `/speckit.implement`

`/speckit.clarify` — 结构化澄清问卷

`/speckit.checklist` — 规格质量检查清单

`/speckit.analyze` — 跨产物一致性分析