OpenSpec 中文操作手册

1. 什么是 OpenSpec

OpenSpec 是 Fission AI 开源的规范驱动开发（Spec-Driven Development）框架。它让人和 AI 在写代码前，先在 markdown 规范文件上达成共识，避免"AI 写出来不是你想要的"。

→ fluid not rigid          流动而非刚性
→ iterative not waterfall  迭代而非瀑布
→ easy not complex         简单而非复杂
→ built for brownfield     为遗留项目设计
→ scalable                 个人到企业全适用

核心价值主张

• Agree before you build — 人和 AI 在 spec 上对齐后再开始编码
• Stay organized — 每个变更独立文件夹，包含 proposal/specs/design/tasks
• Work fluidly — 任何 artifact 随时可改，没有刚性阶段闸门
• Use your tools — 通过 slash command 工作于 25+ 种 AI 助手

它解决什么问题？

OpenSpec 适合谁？

• 2-5 人小团队：用 spec 文件代替会议纪要
• Brownfield 项目维护者：接手老代码先反向写 spec
• 合规要求高的行业（金融、医疗、政府）：每个变更可审计
• 独立开发者：当项目从 PoC 变为长期维护时引入

2. 安装与初始化

2.1 前置要求

2.2 全局安装 CLI

npm（推荐）：

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

# 验证
openspec --version
# 输出：1.3.1（或更新版本）

其他包管理器：

# pnpm
pnpm add -g @fission-ai/openspec@latest

# yarn
yarn global add @fission-ai/openspec@latest

# bun
bun add -g @fission-ai/openspec@latest

2.3 在项目中初始化

cd your-project
openspec init

这会做几件事：

1. 创建 openspec/ 目录（specs/、changes/、config.yaml）
2. 检测你的 AI host（OpenCode / Claude Code / Codex…），自动注册 slash commands
3. 生成 .opencode/skills/openspec-* 或对应 host 的 skill 文件
4. 生成 AGENTS.md（如果还没有），告知 AI 工具如何使用 OpenSpec

2.4 配置 config.yaml（强烈推荐）

这是 OpenSpec 最被低估的功能：把项目的"AI 宪法"写进 config.yaml，每次生成 proposal 都会自动遵守。

# openspec/config.yaml
schema: spec-driven

# 项目上下文：每次 AI 生成 artifact 都会看到这段
context: |
  Tech stack: TypeScript + Next.js 14 + Prisma + PostgreSQL
  Frontend: React Server Components + Tailwind CSS
  We use conventional commits (feat:, fix:, chore:, ...)
  Domain: B2B SaaS for IT 管理员
  
  约定：
  - 强制 default export 禁用，统一 named export
  - API 路由必须返回 { data, pagination } 或 { error } 二选一
  - 所有 DB 查询必须通过 Prisma，禁止 raw SQL（除非显式标注）

# 自定义规则（每个 artifact 类型可单独约束）
rules:
  proposal:
    - Keep proposals under 500 words
    - Always include "Non-goals" section
    - List affected stakeholders
  design:
    - Include at least one ASCII architecture diagram
    - Document failure modes
  tasks:
    - Each task max 2 hours
    - Test file path required for every code change
    - Use checkboxes (- [ ]) for trackability

修改后立即生效，下一次 /opsx:propose 自动套用。

3. 核心概念

3.1 目录结构

openspec init 后你的项目会多出这个结构：

3.2 4 件套 Artifacts

每个 change 文件夹都包含 4 个 markdown 文件，称为 4 件套：

4 件套相互依赖：

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
              在实现过程中可随时回头精炼

3.3 Delta Spec（最关键概念）

OpenSpec 的灵魂在 Delta Spec——它不重写整个 spec，只描述"相对于现有的 spec，本次要变什么"。

Delta 格式

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

archive 时发生什么

1. ADDED 需求被追加到主 spec（specs/auth/spec.md）
2. MODIFIED 需求替换现有的版本
3. REMOVED 需求从主 spec 删除
4. change 文件夹移到 changes/archive/YYYY-MM-DD-<name>/

4. 命令详解

OpenSpec 提供两种 profile（命令集）：

# 切换 profile
openspec config profile expanded
openspec update         # 重新生成 host 的 slash commands

4.1 Core Profile（默认 5 命令）

每个命令包含 4 个维度的解释：具体用法、为什么这样设计、这样用的好处、常见错误。

# 标准用法：传一个 kebab-case 的变更名
/opsx:propose add-dark-mode

# 也可以加描述帮助 AI 理解
/opsx:propose add-dark-mode "支持系统跟随 + 用户偏好"

# 多个相关变更建议加前缀分组
/opsx:propose payment-v2-stripe-integration
/opsx:propose payment-v2-refund-flow

# AI 自动在 openspec/changes/add-dark-mode/ 下创建：
#   ✓ proposal.md       — 为什么 + 改什么 + 不改什么
#   ✓ specs/ui/spec.md  — delta（ADDED/MODIFIED/REMOVED）
#   ✓ design.md         — 技术方案 + 架构图
#   ✓ tasks.md          — 可勾选的实现 checklist

# 探索模式，不创建任何文件
/opsx:explore 鉴权模块当前怎么工作？

# 让 AI 反向读现有代码总结 spec（brownfield 必备）
/opsx:explore 我们的 payment 流程

# 探讨方案对比
/opsx:explore 用 BullMQ 还是 Kafka 做异步任务

# 与 propose 的最大区别：explore 不写文件，propose 写
# explore = 头脑风暴，propose = 落地

# 单 change 项目可省略名字
/opsx:apply

# 多 change 并行时显式指定
/opsx:apply add-dark-mode

# 只做特定 task（适合断点续做）
/opsx:apply add-dark-mode --tasks 1.1,1.2

# dry-run 模式（看 AI 会做什么但不真改）
/opsx:apply add-dark-mode --dry-run

# 把代码现状反向同步到 spec
/opsx:sync

# 只同步特定 domain
/opsx:sync --domain auth

# 检查 drift 但不改文件
/opsx:sync --check

# 归档单个变更
/opsx:archive add-dark-mode

# 单 change 项目可省略名字
/opsx:archive

# 强制归档（即使 tasks.md 还没全勾）
/opsx:archive add-dark-mode --force

4.2 Expanded Profile（多 6 个命令）

切换 profile：

openspec config profile expanded
openspec update     # 重新生成 host slash commands

# 创建空骨架，每个文件只有 heading
/opsx:new payment-v2

# 然后人工或多个 AI 协作填充内容
# Lead 写 proposal.md
# 工程师 A 写 specs/payment/spec.md
# 工程师 B 写 design.md
# 大家协作写 tasks.md

# 接手未完成的 change，AI 自动找下一个未完成 task
/opsx:continue payment-v2

# 单 change 项目可省略
/opsx:continue

# 接手时让 AI 总结当前进度
/opsx:continue payment-v2 --summary

# "快进"到指定 task，跳过前置
/opsx:ff payment-v2 sub-task-3-refunds

# 适合大变更分块场景：
# 工程师 A 做 sub-task-1
# 工程师 B 做 sub-task-2（依赖 A）
# 工程师 C 直接做 sub-task-3（与 1/2 独立）→ 用 ff

# 合并 PR 前最后关卡
/opsx:verify payment-v2

# 严格模式（更多检查）
/opsx:verify payment-v2 --strict

# 只看 spec 一致性
/opsx:verify payment-v2 --only spec

# sprint 末期一次性归档所有完成的 changes
/opsx:bulk-archive

# 只归档过去 7 天完成的
/opsx:bulk-archive --since 7d

# 只归档特定前缀
/opsx:bulk-archive --prefix payment-v2-

# 给新加入项目的 AI 或人类生成 onboarding 文档
/opsx:onboard

# 针对特定模块
/opsx:onboard --domain payment

# 输出到指定文件
/opsx:onboard --output docs/ONBOARDING.md

5. 完整工作流

典型一次变更走完整流程：

详细步骤

# 步骤 1：探索（可选但强推）
/opsx:explore 给 SaaS 加 workspace 协作功能

# AI 会问：当前是怎么实现"项目"的？
#         是要做用户级权限还是只共享？
#         （讨论 5-10 分钟）

# 步骤 2：生成 proposal
/opsx:propose workspace-v1

# 现在 openspec/changes/workspace-v1/ 下有了 4 件套

# 步骤 3：人工 review
# 用编辑器打开 4 个文件检查
# 在 chat 里直接说 "把 design.md 里的 Kafka 换成 BullMQ"
# AI 会修改文件

# commit 提案让团队 review
git add openspec/changes/workspace-v1
git commit -m "spec: propose workspace-v1"
git push

# 团队成员 +1 后

# 步骤 4：实现
/opsx:apply

# AI 会一项一项跑 tasks.md，每完成一项打勾
# 你在 chat 里看到进度

# 步骤 5：测试 + 推 PR
# （这一步 OpenSpec 不管，用 gstack 或手工）
npm test
git push
gh pr create

# 步骤 6：合并后归档
/opsx:archive workspace-v1

# 现在：
# - workspace-v1 文件夹移到 archive/2026-05-20-workspace-v1/
# - delta spec 内容并入 openspec/specs/workspace/spec.md

6. 实战示例

6.1 第一次使用：加暗黑模式

# 进入项目
cd my-saas-app
openspec init

# 编辑 openspec/config.yaml 加项目上下文（5 分钟）

# 让 AI 提案
> /opsx:propose add-dark-mode

# AI 输出：
✓ openspec/changes/add-dark-mode/proposal.md
✓ openspec/changes/add-dark-mode/specs/ui/spec.md
✓ openspec/changes/add-dark-mode/design.md
✓ openspec/changes/add-dark-mode/tasks.md
Ready for implementation!

# 你打开 design.md，看到 AI 选了 next-themes 库 + CSS 变量
# OK，你同意

> /opsx:apply

# AI 一项一项做：
✓ 1.1 安装 next-themes
✓ 1.2 添加 ThemeProvider
✓ 1.3 创建 ThemeToggle 组件
✓ 2.1 添加 CSS 变量
✓ 2.2 接入 localStorage
All tasks complete!

# 测试通过、推 PR、合并后

> /opsx:archive add-dark-mode

# OK，spec 已合并入 specs/ui/spec.md

6.2 Brownfield：重构遗留鉴权

# 你刚接手 5 年老项目，要重构鉴权
# 先 explore（不动文件）

> /opsx:explore 当前鉴权模块怎么工作？

# AI 读 src/auth/，输出：
- Cookie 名 'sid'，HMAC 签名
- session 永不主动失效，靠 30d ttl
- src/legacy/admin.ts 直接绕过 middleware ⚠️
- 邮箱大小写敏感（可能是 bug）

# 你确认这些发现，让 AI 写当前 spec

> /opsx:propose document-current-auth

# AI 在 specs/auth/spec.md 写下当前真实行为
# 这就是反向工程的成果——你现在拥有了一份"老代码的真实规格"

# 然后做重构提案
> /opsx:propose refactor-auth-v2

# delta 清晰列出哪些是要改的（比如修复邮箱大小写 bug）

> /opsx:apply

# 测试通过，PR 合并

> /opsx:archive refactor-auth-v2

6.3 多人协作：3 人做支付重构

# Lead 切换到 expanded profile
openspec config profile expanded
openspec update

# Lead 起头
> /opsx:propose payment-v2

# 把 4 件套 commit + push 让团队 review
git add openspec/changes/payment-v2
git commit -m "spec: payment-v2 proposal"
git push

# 团队 +1 之后：

# 工程师 A 拉取，做第一块
git pull
> /opsx:new payment-v2-stripe-integration
> /opsx:apply

# 完工后 commit
git add openspec/changes/payment-v2-stripe-integration src/
git commit -m "feat: stripe integration (payment-v2)"
git push

# 工程师 B 接手第二块
git pull
> /opsx:continue payment-v2

# AI 检查 tasks.md 进度，从未完成项继续
> /opsx:apply

# 工程师 C 跳到第三块
> /opsx:ff payment-v2-refunds

# 周末 lead 验收
> /opsx:verify payment-v2

# 一致性 OK，归档
> /opsx:bulk-archive

7. 实战经验总结

1config.yaml 是金矿，每个项目都要写

把"项目宪法"写进去：技术栈、命名约定、API 风格、禁忌。每次 /opsx:propose 都自动套用。5 分钟投资，每次都受益。

2提案生成后必读 design.md，不要直接 apply

AI 经常做"看似合理实则不符"的技术选型，比如给 5 人项目引入 Kafka。流程：

/opsx:propose ...
# 人工读 design.md 和 tasks.md
# 在 chat 修正："把 Kafka 换成 BullMQ"
# AI 更新文件
/opsx:apply

3archive 是宝藏，不要跳过

archive/ 半年后回看 = 项目设计决策史。比 git log 有意义 10 倍。审计员问起也有据可查。

4用高推理模型，开干净 context

OpenSpec 对模型推理深度敏感。官方建议：Opus 4.5 或 GPT-5.2。每次 propose 前 /clear 一下 context。弱模型生成的 spec 看似对、实则有逻辑漏洞。

5Brownfield 项目先 explore 再 propose

接手老代码的 SOP：

1. /opsx:explore 让 AI 反向读代码总结当前行为
2. 人工确认这些总结是否准确
3. /opsx:propose document-current-X 写当前 spec
4. 再 /opsx:propose refactor-X 写重构 spec

6把 spec commit，让 git history 有意义

每次 propose 后立即 commit：git commit -m "spec: propose <change-name>"。这样 git history = 设计史 + 代码史。

7多人协作切到 expanded profile

2 人以上做同一个 change 时切到 expanded：

openspec config profile expanded
openspec update

多了 /continue 和 /ff，让接手者无需读 chat 就能精确定位进度。

8delta 的 ADDED/MODIFIED/REMOVED 不要混用

很多人写 delta 时把 ADDED 当 MODIFIED 用。区分：

• ADDED：现有 spec 没有这个 requirement
• MODIFIED：spec 有但内容要改
• REMOVED：spec 有但要废弃

9定期升级 OpenSpec

# 每月或每个 sprint 跑一次
npm install -g @fission-ai/openspec@latest
cd your-project
openspec update    # 同步最新 host 模板

10OpenSpec 不替代代码 review

spec 对齐后还是要 PR review。OpenSpec 让 spec 不漂移，但不保证实现质量。spec review + code review 双保险才完整。

8. 常见问题

context: |
  Tech stack: ...
  Domain: ...
  Conventions:
    - 我们用 Tailwind CSS（不用 styled-components）
    - 后端用 NestJS（不用 Express）
    - 数据库强制软删除
  Existing patterns:
    - API 路由统一返回 { data } 或 { error }

9. 参考资源

• GitHub 仓库：Fission-AI/OpenSpec
• npm 包：@fission-ai/openspec
• Discord：OpenSpec Discord（求助和讨论）
• 支持的 25+ AI 工具：supported-tools.md
• 作者 Twitter：@0xTab
• 对比 GitHub Spec Kit：spec-kit（重量级、刚性）
• 对比 AWS Kiro：Kiro（绑定 Claude + IDE）

配套阅读

• 主页：三剑客总览
• gstack 中文操作手册
• Superpowers 中文操作手册
• 三剑客对比文档
• 实战示例集