设计哲学

核心价值

价值	说明
审查意图，而非代码	通过 spec delta 审查需求变更，比看 diff 更高效
持久化上下文	Specs 存在仓库中随代码版本控制，不会因聊天窗口丢失
减少幻觉	AI 只在明确的规格边界内实现，不会自由发挥
快速评审	编码前生成全套提案 + 设计 + 任务，可评审可调整

系统要求

Node.js 20.19.0 或更高版本。支持 npm / pnpm / yarn / bun 包管理器。

安装

# 全局安装
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

项目初始化

# 交互式初始化（推荐）— 会引导选择 AI 工具
cd your-project
openspec init

# 指定 AI 工具（非交互式，适合 CI/CD）
openspec init --tools claude
openspec init --tools claude,cursor
openspec init --tools all

# 指定工作流配置文件
openspec init --profile core

初始化时 OpenSpec 会询问你使用的 AI 工具，然后自动生成对应的配置文件（如 Claude Code 的 skills、Cursor 的 commands 等）。

支持的 AI 工具（20+）

Claude Code、Cursor、GitHub Copilot、Windsurf、Gemini CLI、Codex、Kilo Code、Roo Code、Cline、Amazon Q、Trae、Qwen 等。

your-project/
├── openspec/
│   ├── config.yaml              # 项目配置（schema、context、rules）
│   ├── specs/                   # 基线规格（Source of Truth）
│   │   ├── auth-login/
│   │   │   └── spec.md          # 登录能力基线
│   │   └── payment/
│   │       └── spec.md          # 支付能力基线
│   ├── changes/                 # 活跃变更提案
│   │   ├── add-dark-mode/       # 一个变更 = 一个子目录
│   │   │   ├── .openspec.yaml   # 变更元数据
│   │   │   ├── proposal.md      # 提案（Why + What）
│   │   │   ├── design.md        # 技术设计（How）
│   │   │   ├── tasks.md         # 任务清单（checkbox）
│   │   │   └── specs/           # Delta specs（变更规格）
│   │   │       └── ui/
│   │   │           └── spec.md
│   │   └── archive/             # 已归档变更
│   │       └── 2026-04-08-add-dark-mode/
│   └── agent-instructions.md    # AI 代理指令（自动生成）
├── .claude/skills/              # Claude Code skills（自动生成）
└── src/                         # 你的项目源码

关键目录说明

目录/文件	作用	谁维护
specs/	系统当前能力的 Source of Truth，AI 读取它来理解已有行为	归档时自动同步
changes/	隔离的变更提案，每个功能独立子目录，防止需求污染	AI 生成 + 人 review
config.yaml	项目级配置：schema 选择、项目上下文、各 artifact 规则	人手动编辑
agent-instructions.md	"机器人的 README"，注入 AI 的系统级工作流指令	openspec update 自动生成
archive/	已完成变更的历史归档，保留审计轨迹	归档时自动移入

schema: spec-driven        # 使用的工作流 schema

context: |                 # 注入所有 artifact 生成的全局上下文
  项目：EagleEyes — 服务治理平台
  技术栈：Go 1.23 + Iris + GORM + Wire + PostgreSQL
  前端：React 18 + TypeScript + Ant Design
  架构：Controller → Service → DAO → Model 四层
  API 风格：RESTful，JSON 响应
  测试：Go testing + React Testing Library

rules:                     # 各 artifact 专属约束规则
  proposal:
    - 使用中文撰写
    - "Why" 部分必须说明业务背景和动机
    - 包含回滚方案
    - 标识受影响的团队
  design:
    - 使用中文撰写
    - 必须说明分层归属（Controller/Service/DAO/Model）
  specs:
    - 使用中文撰写
    - 使用 Given/When/Then 格式
    - 优先引用已有 patterns，再考虑新建
  tasks:
    - 使用中文撰写
    - 每个任务 30 分钟以内可完成
    - 必须有明确的验收标准

三个核心字段

字段	作用	影响范围
schema	选择工作流模式，决定产出哪些 artifact	全局
context	项目上下文描述，注入所有 artifact 生成过程	所有 artifact
rules	各 artifact 的专属约束规则，只注入对应 artifact	对应 artifact

Schema 解析优先级

# 从高到低：
1. CLI 参数：--schema <name>
2. 变更元数据：changes/<name>/.openspec.yaml
3. 项目配置：openspec/config.yaml
4. 默认值：spec-driven

proposal (ready)                 ← 无依赖，最先创建
    ↓ unlocks
specs (blocked → ready)         ← 依赖 proposal
design (blocked → ready)        ← 依赖 proposal
    ↓                   ↓
    └──── tasks (blocked → ready) ────┘    ← 依赖 specs + design
              ↓
         implement（apply 阶段）

1. proposal.md — 变更提案

回答 Why（为什么要做）和 What（做什么）。

# Proposal: add-dark-mode

## Why
用户反馈夜间使用时屏幕刺眼，希望有暗色模式减轻眼部疲劳。

## What Changes
- 添加主题切换功能（设置页 + 快捷按钮）
- 支持系统偏好自动检测
- 持久化用户偏好到 localStorage

## New Capabilities
- theme-toggle: 主题切换能力

## Impact
- Files: src/contexts/ThemeContext.tsx, src/components/ThemeToggle.tsx
- APIs: 无变更
- Dependencies: 无新增

2. specs/ — Delta Specs（变更规格）

用 GIVEN / WHEN / THEN 格式定义可测试的行为规格。详见下一节。

3. design.md — 技术设计

回答 How（怎么做），记录架构决策。

# Design: add-dark-mode

## Approach
使用 CSS Custom Properties 实现主题变量，React Context 管理状态。

## Key Decision: 复用 CSS 变量 vs CSS-in-JS
- 选择：CSS Custom Properties
- 理由：零运行时开销，浏览器原生支持
- 备选：styled-components — 运行时开销较大

## Layer Assignments
- Context 层：ThemeContext（状态 + 持久化）
- Component 层：ThemeToggle（UI 切换按钮）
- Style 层：globals.css（CSS 变量定义）

4. tasks.md — 任务清单

原子粒度的 checkbox 清单，AI 逐个执行。

# Tasks: add-dark-mode

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Validation
- [ ] 3.1 Manual theme switching verification
- [ ] 3.2 System preference detection verification

完整示例

# Delta for Auth

## ADDED Requirements

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

#### Scenario: OTP Verification Required
- GIVEN a user with 2FA enabled
- WHEN correct username and password provided
- THEN system SHALL present an OTP challenge
- AND OTP expires after 5 minutes

#### Scenario: OTP Incorrect
- GIVEN a user on the OTP verification step
- WHEN an incorrect OTP is submitted 3 times
- THEN the account SHALL be temporarily locked for 15 minutes

## 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 SHALL be invalidated
- AND user is redirected to login page

## REMOVED Requirements

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

Core 工作流状态机

  ┌─────────────────────────────────────────────┐
  │                                             │
  │  /opsx:propose                              │
  │  ┌──────────┐    ┌──────────┐    ┌────────┐│
  │  │ Proposal │───▶│  Specs   │───▶│ Tasks  ││
  │  │          │    │  Design  │    │        ││
  │  └──────────┘    └──────────┘    └────────┘│
  │                                      │      │
  ├──────────────────────────────────────┘      │
  │                                             │
  │  /opsx:apply                                │
  │  ┌──────────────────────────────────┐       │
  │  │  逐个执行 Task → 写代码 → 标记完成  │       │
  │  └──────────────────────────────────┘       │
  │                    │                        │
  │  /opsx:archive     ▼                        │
  │  ┌──────────────────────────────────┐       │
  │  │  Delta specs 合并到主 specs/      │       │
  │  │  变更目录移入 archive/            │       │
  │  └──────────────────────────────────┘       │
  │                    │                        │
  └────────────────────┼────────────────────────┘
                       ▼
                  下一轮迭代

使用方法

# 在 Claude Code 中输入
/opsx:propose <用自然语言描述你的需求>

# 示例
/opsx:propose 在用户列表页添加批量导出 CSV 功能

Claude 自动执行的步骤

1. 读取上下文 — 加载 config.yaml、project.md、已有 specs/
2. 调研代码 — 搜索相关文件、API、组件，理解现状
3. 创建变更目录 — openspec/changes/<feature-name>/
4. 按依赖顺序生成 Artifact：
   • proposal.md（Why + What）
   • specs/（Requirements + Scenarios）
   • design.md（How + 架构决策）
   • tasks.md（原子任务清单）
5. 输出摘要 — 变更范围、受影响文件、下一步建议

提案完成后的检查清单

• Proposal：AI 理解了你的「为什么」吗？
• Design：技术选型和分层是否合理？
• Specs：Scenario 是否覆盖了主流程 + 异常流程？
• Tasks：任务粒度是否足够小？是否有测试/验证任务？

使用方法

/opsx:apply

AI 的执行逻辑：

1. 加载 tasks.md，把 specs 作为不可违反的指令
2. 按任务顺序依次执行，每完成一个标记 [x]
3. 只关注「如何实现」，不重新定义「做什么」
4. 输出每个 task 的完成进度

实现过程示例

Implementing: add-dark-mode (schema: spec-driven)

Working on task 1/8: Create ThemeContext with light/dark state
  → Created src/contexts/ThemeContext.tsx
Task 1 complete. ✓

Working on task 2/8: Add CSS custom properties for colors
  → Modified src/styles/globals.css
Task 2 complete. ✓

Working on task 3/8: Implement localStorage persistence
  → Modified src/contexts/ThemeContext.tsx
Task 3 complete. ✓

...

Implementation Complete
Change: add-dark-mode
Progress: 8/8 tasks complete

上下文管理技巧

使用方法

# 交互式归档
/opsx:archive

# CLI 直接归档
openspec archive add-dark-mode
openspec archive add-dark-mode --yes          # 跳过确认
openspec archive update-ci --skip-specs       # 跳过 spec 同步（纯基建变更）

归档过程

1. 验证 — 检查所有 artifact 格式正确（除非 --no-validate）
2. 确认 — 提示用户确认（除非 --yes）
3. 合并 Delta Specs：
   • ADDED → 追加到 openspec/specs/
   • MODIFIED → 替换对应内容
   • REMOVED → 删除对应内容
4. 归档目录 — 移动到 openspec/changes/archive/YYYY-MM-DD-<name>/

Archive Complete
Change: add-dark-mode
Schema: spec-driven
Archived to: openspec/changes/archive/2026-04-08-add-dark-mode/
Specs: Synced to openspec/specs/ui/spec.md
All artifacts complete. All tasks complete.

切换到扩展模式

openspec config profile
# 选择 expanded

扩展命令一览

命令	作用	典型场景
/opsx:new	创建新的变更（只创建目录，不生成 artifact）	需要手动编写 proposal
/opsx:ff	Fast-Forward：一次性生成所有 artifact	需求明确，想快速推进
/opsx:continue	恢复中断的工作	上下文丢失后继续
/opsx:verify	验证实现是否符合 specs	apply 完成后的质量检查
/opsx:sync	同步变更状态	多人协作时同步进度
/opsx:bulk-archive	批量归档多个变更	迭代末期清理
/opsx:onboard	团队入职引导	新成员了解 SDD 工作流

用户输入需求描述
    ↓
1. 解析输入 → 提取 kebab-case 变更名
    ↓
2. openspec new change "<name>"
   → 创建 openspec/changes/<name>/
   → 写入 .openspec.yaml（schema + 创建时间）
    ↓
3. openspec status --change "<name>" --json
   → 获取 applyRequires + artifact 依赖状态
    ↓
4. 循环创建 artifact（按依赖拓扑序）:
   a. openspec instructions <artifact-id> --change "<name>" --json
   b. 读取 template + instruction + context + rules
   c. 读取已完成的 dependency 文件
   d. 调研项目代码（搜索相关文件）
   e. 生成 artifact 文件
   f. 重新检查 status，直到 applyRequires 全部 done
    ↓
5. 输出摘要，等待用户 review

Step 1：需求描述技巧

propose 的输入质量直接决定生成质量。以下是不同粒度的输入对比：

质量	输入示例	效果
差	/opsx:propose 加个功能	AI 被迫猜测，产出不可控
中	/opsx:propose 添加用户导出功能	方向正确，但缺少具体约束
好	/opsx:propose 在用户管理页添加批量导出 CSV 功能，支持筛选条件（角色、注册时间），最大导出 10000 条，超出提示分批	明确的功能边界 + 业务约束

Step 2：变更目录创建

openspec new change "add-user-export"
# 创建的目录结构：
# openspec/changes/add-user-export/
# └── .openspec.yaml

.openspec.yaml 内容：

schema: spec-driven      # 使用的工作流 schema
created: 2026-04-09      # 创建日期

该文件决定了这个变更使用哪个 schema 的 artifact 流水线。后续所有命令会自动读取此文件。

Step 3：依赖拓扑序生成

OpenSpec 使用 Kahn 算法计算 artifact 创建顺序，确保依赖关系正确：

openspec status --change "add-user-export" --json

{
  "changeName": "add-user-export",
  "schemaName": "spec-driven",
  "isComplete": false,
  "applyRequires": ["tasks"],
  "artifacts": [
    { "id": "proposal", "outputPath": "proposal.md",    "status": "ready" },
    { "id": "specs",    "outputPath": "specs/**/*.md",   "status": "blocked", "missingDeps": ["proposal"] },
    { "id": "design",   "outputPath": "design.md",       "status": "blocked", "missingDeps": ["proposal"] },
    { "id": "tasks",    "outputPath": "tasks.md",        "status": "blocked", "missingDeps": ["specs", "design"] }
  ]
}

关键字段说明：

• applyRequires：进入 apply 阶段的前置条件，所有列出的 artifact 必须完成
• status: "ready"：依赖已满足，可以创建
• status: "blocked"：存在未完成的依赖
• missingDeps：缺少的具体依赖列表

Step 4：逐个生成 Artifact

AI 按照 ready → blocked 变 ready → ... 的循环，逐个创建 artifact：

# 第 1 轮：proposal 是 ready
openspec instructions proposal --change "add-user-export" --json
# → 获取 template + instruction → 生成 proposal.md

# 第 2 轮：specs 和 design 都变成 ready
openspec instructions specs --change "add-user-export" --json
# → 获取 template + 读取 proposal.md 作为上下文 → 生成 specs/
openspec instructions design --change "add-user-export" --json
# → 获取 template + 读取 proposal.md → 生成 design.md

# 第 3 轮：tasks 变成 ready
openspec instructions tasks --change "add-user-export" --json
# → 读取 specs/ + design.md → 生成 tasks.md

Step 5：Review 检查点

propose 完成后，这是人最重要的参与点。Review 清单：

Artifact	Review 重点	常见问题
proposal.md	Why 是否准确？影响范围是否完整？	AI 扩大了范围、遗漏了影响系统
specs/	Scenario 是否覆盖异常路径？	只有 happy path，缺少边界条件
design.md	技术选型是否符合项目规范？	引入了不需要的新依赖
tasks.md	粒度是否合适？顺序是否正确？	任务过大（>1小时）或缺少测试任务

                    ┌─────────────────────┐
                    │   schema.yaml       │
                    │  (instruction 字段)  │
                    └──────────┬──────────┘
                               │
┌──────────────┐    ┌──────────▼──────────┐    ┌──────────────┐
│ config.yaml  │───▶│  Instruction        │◀───│  templates/  │
│ (context +   │    │  Enrichment Engine  │    │ (模板文件)    │
│  rules)      │    │                     │    │              │
└──────────────┘    └──────────┬──────────┘    └──────────────┘
                               │
                    ┌──────────▼──────────┐
                    │  依赖 artifact 文件  │
                    │  (已完成的产物路径)  │
                    └─────────────────────┘

完整输出结构

openspec instructions proposal --change "add-user-export" --json

{
  "changeName": "add-user-export",
  "artifactId": "proposal",
  "schemaName": "spec-driven",
  "changeDir": "/project/openspec/changes/add-user-export",
  "outputPath": "proposal.md",
  "description": "Initial proposal document outlining the change",
  "instruction": "Create the proposal document that establishes WHY...",
  "context": "项目：EagleEyes — 服务治理平台\n技术栈：Go 1.23 + Iris...",
  "rules": ["使用中文撰写", "Why 部分必须说明业务背景"],
  "template": "## Why\n\n<!-- 解释动机 -->\n\n## What Changes\n...",
  "dependencies": [],
  "unlocks": ["specs", "design"]
}

各字段的角色定位

字段	角色	AI 如何使用
instruction	来自 schema 的创作指导	理解 artifact 应该写什么、怎么写
context	来自 config.yaml 的项目上下文	作为约束条件参考，不写入产出文件
rules	来自 config.yaml 的 artifact 专属规则	作为约束条件遵循，不写入产出文件
template	来自 templates/ 的结构模板	就是输出文件的结构框架，按此格式填写
dependencies	已完成的前置 artifact 列表	读取这些文件获取上下文
unlocks	完成后解锁的 artifact	了解下一步产出

apply 阶段的 instructions

# 获取实现阶段的指令
openspec instructions apply --change "add-user-export" --json

apply instructions 返回的内容包含：

• tasks.md 路径：AI 按此文件的 checkbox 逐个执行
• specs/ 路径：作为实现约束，AI 不能违反 spec 定义的行为
• apply.instruction：来自 schema 的实现指导
• apply.tracks：进度追踪文件（默认 tasks.md）

对于每个 artifact 的 generates 字段：
  ├── 简单路径（如 "proposal.md"）
  │   → fs.existsSync(changeDir + "/proposal.md")
  │
  └── Glob 模式（如 "specs/**/*.md"）
      → fast-glob 匹配，有任意匹配文件即视为完成

status 命令完整用法

# 查看特定变更的状态
openspec status --change add-user-export

# JSON 输出（AI 和脚本使用）
openspec status --change add-user-export --json

# 人类可读输出：
Change: add-user-export
Schema: spec-driven
Progress: 2/4 artifacts complete

  [x] proposal    → proposal.md
  [x] specs       → specs/**/*.md
  [ ] design      → design.md (ready)
  [-] tasks       → tasks.md (blocked by: design)

三种状态含义

状态	符号	含义	下一步
done	[x]	generates 文件已存在	无需操作
ready	[ ]	所有依赖已完成，可以创建	运行 openspec instructions
blocked	[-]	有未完成的依赖	先完成 missingDeps 中的 artifact

Task 进度追踪

在 apply 阶段，OpenSpec 还会解析 tasks.md 中的 checkbox 来追踪实现进度：

# tasks.md 中：
- [x] 1.1 Create data model          ← 已完成
- [x] 1.2 Add database migration      ← 已完成
- [ ] 2.1 Implement export service    ← 待完成
- [ ] 2.2 Add CSV formatter           ← 待完成

# apply 阶段的进度追踪
Task Progress: 2/4 complete (50%)

/opsx:apply 触发后：
    ↓
1. 检查 applyRequires（默认 [tasks]）是否全部 done
   → 未满足则提示用户先完成前置 artifact
    ↓
2. 读取 tasks.md，解析所有 checkbox 任务
    ↓
3. 加载 specs/ 作为「不可违反的行为约束」
    ↓
4. 按顺序逐个执行未完成的 task：
   a. 读取任务描述
   b. 定位相关源文件
   c. 编写/修改代码
   d. 标记 tasks.md 中对应 checkbox 为 [x]
    ↓
5. 所有 task 完成后，输出总结

Specs 在 apply 中的角色

apply 阶段，specs 是不可违反的硬约束，不是参考建议：

• 每个 Requirement 的 SHALL/MUST 语句必须被代码实现
• 每个 Scenario 的 WHEN/THEN 必须是可验证的行为
• AI 不能自行添加 spec 未定义的功能
• AI 不能修改 spec 定义的行为边界

中断恢复

apply 过程中如果上下文窗口耗尽或手动中断，可以使用 /opsx:continue 恢复：

# 恢复中断的实现
/opsx:continue

# AI 会：
# 1. 读取 tasks.md，找到最后一个 [x] 的位置
# 2. 从下一个 [ ] 继续执行
# 3. 不会重复已完成的任务

apply 的上下文加载策略

AI 在 apply 阶段需要读取的文件：

必读文件（每个 task 都读）：
├── tasks.md              → 获取当前任务描述
└── specs/*/spec.md       → 行为约束

按需文件（当前 task 相关）：
├── design.md             → 技术决策参考
├── src/relevant-file.ts  → 要修改的源文件
└── package.json          → 依赖信息

不需要读取：
├── proposal.md           → 已内化到 specs 中
└── 其他无关源文件        → 降低 token 消耗

openspec archive add-user-export
    ↓
1. 验证阶段（除非 --no-validate）
   → 检查 proposal.md 格式
   → 检查 specs/ 中每个 delta spec 格式
   → 检查 tasks.md checkbox 格式
    ↓
2. 确认阶段（除非 --yes）
   → 提示用户确认归档
    ↓
3. Delta Spec 合并
   → 扫描 changes/add-user-export/specs/ 下所有目录
   → 对于每个 capability 目录：
     a. 读取 delta spec（ADDED/MODIFIED/REMOVED 分区）
     b. 读取主 specs/ 中对应文件（如存在）
     c. 合并操作：
        - ADDED Requirements → 追加到主 spec
        - MODIFIED Requirements → 按名称匹配替换
        - REMOVED Requirements → 从主 spec 删除
        - RENAMED Requirements → 修改名称
     d. 写回主 specs/
    ↓
4. 归档目录
   → openspec/changes/add-user-export/
   → openspec/changes/archive/2026-04-09-add-user-export/

Delta Spec 合并的四种操作

操作	Delta 格式	合并行为	注意事项
ADDED	## ADDED Requirements 下的内容	追加到主 spec 的 Requirements 部分末尾	重名检测，不允许添加已存在的 Requirement
MODIFIED	## MODIFIED Requirements 下的内容	按 Requirement 名称匹配，整块替换	必须包含完整内容，不能只写差异
REMOVED	## REMOVED Requirements 下的名称	从主 spec 中删除匹配的 Requirement	建议附带 Reason 和 Migration 说明
RENAMED	FROM:/TO: 格式	修改主 spec 中的 Requirement 名称	只改名称，不改内容

归档选项

# 标准归档
openspec archive add-user-export

# 跳过确认提示（CI 环境）
openspec archive add-user-export --yes

# 跳过 spec 同步（纯基建变更，无 delta spec）
openspec archive add-user-export --skip-specs

# 跳过验证（紧急情况）
openspec archive add-user-export --no-validate

# 批量归档
/opsx:bulk-archive

归档后的目录变化

# 归档前：
openspec/
├── specs/
│   └── user-management/spec.md      ← 已有基线
├── changes/
│   └── add-user-export/             ← 活跃变更
│       ├── proposal.md
│       ├── specs/user-management/spec.md  ← delta spec
│       └── tasks.md

# 归档后：
openspec/
├── specs/
│   └── user-management/spec.md      ← 已合并新 Requirement
├── changes/
│   ├── archive/
│   │   └── 2026-04-09-add-user-export/   ← 归档历史
│   └── (空)

验证范围

OpenSpec 的验证系统使用 Zod schema + 自定义规则进行多层验证：

验证对象	检查内容
Spec 文件	Purpose 长度 ≥ 最小值、每个 Requirement 必须有 ≥1 Scenario、Scenario 使用 WHEN/THEN 格式、RFC 2119 关键字检查
Change 文件	proposal.md 存在且格式正确、delta spec 使用 ADDED/MODIFIED/REMOVED 分区、tasks.md 使用 checkbox 格式
Delta Spec	MODIFIED 部分包含完整内容（非差异）、REMOVED 部分附带原因、Requirement 名称无重复

验证命令

# 验证特定变更
openspec validate add-user-export

# 验证所有变更
openspec validate --all

# 严格模式（warning 也视为错误）
openspec validate --all --strict

# 只验证变更（不验证基线 spec）
openspec validate --changes

# JSON 输出
openspec validate add-user-export --json

常见验证错误及修复

错误信息	原因	修复方法
Requirement has no scenarios	Requirement 下没有 #### Scenario:	添加至少一个 Scenario
Scenario heading must use 4 hashtags	用了 ### Scenario: 而非 #### Scenario:	改为 4 个 #
Purpose section too short	spec 的 Purpose/描述太简短	补充更详细的目的说明
Duplicate requirement in ADDED	ADDED 分区有同名 Requirement	合并或重命名其中一个

config.yaml 配置注入路径：

context: "项目上下文..."
  → 注入到所有 artifact 的 instructions.context 字段
  → AI 读取后作为背景约束，不写入文件

rules:
  proposal:                    ← 只注入 proposal artifact
    - "使用中文撰写"
  specs:                       ← 只注入 specs artifact
    - "使用 Given/When/Then"
  → 注入到对应 artifact 的 instructions.rules 字段

不同项目类型的 context 模板

Go 后端项目

context: |
  项目：EagleEyes — 服务治理平台
  技术栈：Go 1.23 + Iris v12 + GORM v2 + Wire DI + PostgreSQL 16
  架构：Controller → Service → DAO → Model 四层
  API 风格：RESTful，JSON，统一 Response{code, message, data}
  认证：JWT Token + RBAC 权限模型
  测试：Go testing + testify + httptest
  部署：Docker + K8s + ArgoCD
  编码规范：
    - 所有公开函数必须有 godoc 注释
    - error 必须 wrap 后向上传递
    - DAO 层使用 GORM Scope 模式

React 前端项目

context: |
  项目：Dashboard — 管理后台前端
  技术栈：React 18 + TypeScript 5 + Vite + Ant Design 5
  状态管理：Zustand + React Query
  路由：React Router v6，约定式路由
  样式：CSS Modules + Tailwind CSS
  测试：Vitest + React Testing Library
  API 调用：封装 axios instance，统一错误处理
  编码规范：
    - 组件使用函数式 + hooks
    - 自定义 hook 以 use 开头
    - 表单使用 Ant Design Form

全栈项目

context: |
  项目：BookStore — 在线书店
  后端：Node.js 20 + Express + Prisma + PostgreSQL
  前端：Next.js 14 (App Router) + TypeScript + Tailwind
  API：RESTful + tRPC（内部调用）
  认证：NextAuth.js + Prisma Adapter
  测试：后端 Vitest + Supertest / 前端 Playwright
  部署：Vercel (前端) + Railway (后端 + DB)
  Monorepo：pnpm workspace，apps/ + packages/ 结构

rules 精细化配置

rules:
  proposal:
    - 使用中文撰写
    - "Why" 部分必须说明业务背景和用户痛点
    - "Impact" 部分必须列出受影响的微服务和 API endpoint
    - 如果涉及数据库变更，必须标注是否需要 migration

  specs:
    - 使用中文撰写
    - 每个 Scenario 使用 GIVEN/WHEN/THEN 三段式
    - 涉及 API 的 Requirement 必须包含：请求方法、路径、参数、响应码
    - 涉及权限的 Requirement 必须列出允许的角色列表
    - 优先引用已有 spec 中的 patterns，避免重复定义

  design:
    - 使用中文撰写
    - 必须说明代码变更归属的分层（Controller/Service/DAO/Model）
    - 数据库设计使用 Mermaid ER 图
    - 必须包含 "Alternatives Considered" 部分

  tasks:
    - 使用中文撰写
    - 每个任务 30 分钟以内可完成
    - 按依赖顺序排列：Model → DAO → Service → Controller → UI → Test
    - 最后一组必须是验证/测试任务
    - 包含 migration 任务时必须排在最前面

全局配置 vs 项目配置

配置	路径	作用域	内容
全局配置	~/.config/openspec/config.json	所有项目	profile（core/custom）、delivery（skills/commands/both）、workflows 列表
项目配置	openspec/config.yaml	当前项目	schema、context、rules
变更元数据	changes/<name>/.openspec.yaml	单个变更	schema override、created date

# 修改全局 profile
openspec config profile
# → 选择 core 或 custom

# 修改 delivery 模式
openspec config delivery
# → skills / commands / both

统一命令内容（CommandContent）
  ├── name: "openspec-propose"
  ├── description: "Propose a new change..."
  ├── category: "openspec"
  ├── tags: ["openspec", "sdd"]
  └── body: "...详细指令..."
         │
         ├── Claude Adapter → .claude/commands/opsx/propose.md
         │   (YAML frontmatter + Markdown body)
         │
         ├── Cursor Adapter → .cursor/rules/opsx/propose.md
         │   (tool-specific frontmatter)
         │
         ├── Copilot Adapter → .github/prompts/opsx-propose.prompt.md
         │   (prompt file format)
         │
         └── Gemini Adapter → .gemini/commands/opsx/propose.md
             (Gemini-specific format)

两种集成模式

模式	文件类型	触发方式	适用工具
Agent Skills	YAML frontmatter + instruction	/opsx:propose slash command	Claude Code、Cursor 等
Commands	工具特定的命令文件	工具内置命令系统	GitHub Copilot、Windsurf 等

# 配置 delivery 模式
openspec config delivery
# → skills: 只生成 skill 文件
# → commands: 只生成 command 文件
# → both: 两者都生成（推荐）

Claude Code 集成详解

Claude Code 使用 .claude/commands/ 和 .claude/skills/ 目录：

# 初始化后生成的文件：
.claude/
├── commands/opsx/
│   ├── propose.md       # /opsx:propose 命令
│   ├── apply.md         # /opsx:apply 命令
│   ├── archive.md       # /opsx:archive 命令
│   ├── continue.md      # /opsx:continue 命令
│   ├── ff.md            # /opsx:ff 命令
│   ├── verify.md        # /opsx:verify 命令
│   └── ...
└── skills/opsx/
    └── *.md             # Skill 文件

Claude Code skill 文件格式：

---
name: openspec-propose
description: "Propose a new change with all artifacts"
category: openspec
tags: [openspec, sdd, propose]
---

Propose a new change - create the change and generate
all artifacts in one step.

**Steps**
1. Ask what they want to build (if not clear)
2. Create change directory: openspec new change "<name>"
3. Get artifact build order: openspec status --change "<name>" --json
4. Create artifacts in dependency order...
...

多工具共存

# 同时为多个工具生成配置
openspec init --tools claude,cursor,github-copilot

# 升级后更新所有工具配置
openspec update

# 只更新特定工具（重新初始化）
openspec init --tools cursor --force

Step 1: 提案

你：/opsx:propose add-dark-mode 添加暗色模式，支持手动切换和系统偏好自动检测

AI：Created openspec/changes/add-dark-mode/
    ✓ proposal.md — 动机和范围
    ✓ specs/ui/spec.md — 需求和场景
    ✓ design.md — 技术方案
    ✓ tasks.md — 8 个实施任务
    Ready for implementation!

Step 2: Review（人的关键参与点）

# 查看变更详情
openspec show add-dark-mode

# 验证 spec 格式
openspec validate add-dark-mode

# 查看 artifact 状态
openspec status --change add-dark-mode

确认 specs 中的 Scenario 是否覆盖了：手动切换、系统偏好检测、持久化、页面刷新后保持。

Step 3: 实现

你：/opsx:apply

AI：Working through tasks...
    ✓ 1.1 Created ThemeContext
    ✓ 1.2 Added CSS custom properties
    ✓ 1.3 Implemented localStorage persistence
    ✓ 2.1 Created ThemeToggle component
    ✓ 2.2 Added toggle to settings page
    ✓ 2.3 Updated Header
    ✓ 3.1 Theme switching verification
    ✓ 3.2 System preference detection verification
    All tasks complete!

Step 4: 归档

你：/opsx:archive

AI：Archiving add-dark-mode...
    ✓ Merged specs into openspec/specs/ui/spec.md
    ✓ Moved to openspec/changes/archive/2026-04-08-add-dark-mode/
    Done!

从 spec 到代码的完整流程

# 提案时可以直接给出 API 规格
/opsx:propose 新增书评功能 — POST /books/:bookId/reviews 创建评论（rating 1-5 必填，comment 可选），
GET /books/:bookId/reviews 支持分页。每条评论有 id(UUID)、bookId、rating、comment、createdAt

Claude 会根据这段描述自动生成：

• Proposal：书评功能的业务动机和影响范围
• Specs：每个 API endpoint 的 Request/Response 规格 + 校验场景
• Design：Controller/Service/DAO 分层 + 数据库表结构
• Tasks：Model → DAO → Service → Controller → 验证

Apply 生成的代码特点

• DTO 包含完整的验证装饰器（如 @IsInt() @Min(1) @Max(5)）
• Controller 路由严格匹配 spec 定义的 URL 和 Method
• Service 层生成结构化 stub，标记 // TODO: implement
• 分页参数、错误码、响应格式全部符合 spec 要求

openspec init

openspec init [path] [options]

# Options:
  --tools <list>      指定 AI 工具（all / none / 逗号分隔）
  --force              自动清理遗留文件
  --profile <name>     覆盖全局 profile（core / custom）

# 支持的 Tool IDs:
  claude, cursor, github-copilot, windsurf, gemini,
  codex, kilocode, roocode, cline, amazon-q, trae, ...

# 示例:
  openspec init
  openspec init ./my-project
  openspec init --tools claude,cursor --profile core

openspec update

openspec update [path] [options]

# Options:
  --force    强制更新

# 用途：CLI 升级后更新 agent-instructions.md 和 skills 文件
npm update @fission-ai/openspec && openspec update

openspec list / show / view / validate

# 列出变更
openspec list                    # 列出活跃变更
openspec list --specs            # 列出基线 specs
openspec list --json             # JSON 输出（适合脚本）

# 查看详情
openspec show add-dark-mode
openspec show auth --type spec
openspec show add-dark-mode --json

# 交互式仪表盘
openspec view

# 验证格式
openspec validate add-dark-mode
openspec validate --all --strict
openspec validate --changes --json

openspec status

openspec status --change add-dark-mode

# 输出示例：
Change: add-dark-mode
Schema: spec-driven
Progress: 2/4 artifacts complete

[x] proposal
[ ] design
[x] specs
[-] tasks (blocked by: design)

openspec instructions

# 获取 artifact 创建指令（AI 用来理解下一步该做什么）
openspec instructions --change add-dark-mode
openspec instructions design --change add-dark-mode
openspec instructions apply --change add-dark-mode   # 获取实现指令
openspec instructions design --change add-dark-mode --json

openspec templates / schemas

# 查看模板路径
openspec templates
openspec templates --schema my-workflow

# 列出可用 schema
openspec schemas
openspec schemas --json

Schema 管理

# 从已有 schema 派生
openspec schema fork spec-driven my-workflow

# 从头创建
openspec schema init rapid
openspec schema init rapid \
  --description "Rapid iteration" \
  --artifacts "proposal,tasks" \
  --default

# 验证自定义 schema
openspec schema validate my-workflow

# 查看使用的 schema
openspec schema which my-workflow
openspec schema which --all

schema.yaml 格式

name: my-workflow
version: 1
description: 我团队的自定义工作流

artifacts:
  - id: proposal
    generates: proposal.md
    description: 变更提案
    template: proposal.md        # templates/ 目录下的模板
    instruction: |
      创建一个提案，说明 WHY 需要这个变更。
      聚焦问题本身，不要涉及解决方案。
    requires: []                 # 无依赖

  - id: design
    generates: design.md
    description: 技术设计
    template: design.md
    instruction: |
      创建技术设计文档，说明 HOW 实现。
    requires:
      - proposal                 # 依赖 proposal

  - id: tasks
    generates: tasks.md
    description: 任务清单
    template: tasks.md
    requires:
      - design                   # 依赖 design

apply:
  requires: [tasks]             # apply 阶段的前置条件
  tracks: tasks.md              # 追踪进度的文件

快速迭代 Schema 示例

name: rapid
version: 1
description: 最简工作流，适合小改动

artifacts:
  - id: proposal
    generates: proposal.md
    template: proposal.md
    instruction: |
      创建简短提案，说明做什么和为什么。
      不需要详细设计。
    requires: []

  - id: tasks
    generates: tasks.md
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

使用方式：

# 设为项目默认
# openspec/config.yaml
schema: rapid

# 或单次使用
openspec instructions --change quick-fix --schema rapid

模板文件位置

openspec/
└── schemas/
    └── my-workflow/
        ├── schema.yaml
        └── templates/
            ├── proposal.md
            ├── design.md
            ├── specs.md
            └── tasks.md

模板示例

<!-- templates/proposal.md -->
## Why

<!-- 解释这个变更的动机。解决什么问题？ -->

## What Changes

<!-- 描述具体要改什么。明确列出新能力。 -->

## Impact

<!-- 受影响的代码、API、依赖、系统 -->

模板使用 HTML 注释作为引导提示。AI 会根据注释填充内容。

各工具的集成方式

AI 工具	集成方式	命令触发
Claude Code	.claude/skills/ 目录下的 skill 文件	/opsx:propose
Cursor	.cursor/skills/ + .cursor/commands/	Chat 中输入 /openspec:proposal
GitHub Copilot	.github/prompts/*.prompt.md	CLI 自动识别 slash commands
Windsurf	自动工作流发现	内置集成
Kilo Code	.kilocode/workflows/	可配置测试自动通过

Proposal 写作

• 原子提案：每个 propose 聚焦一个小的、独立的变更
• 业务动机先行：Why 部分写业务原因，不写技术细节
• 明确影响范围：列出受影响的文件、API、团队

Specs 写作

• 定义系统行为和约束，不要规定代码写法
• 使用 SHALL / MUST 表达强制要求
• 每个 Requirement 至少一个 GIVEN / WHEN / THEN Scenario
• 覆盖边界条件和错误处理，不只是 happy path

Tasks 拆分

• 每个 task 30 分钟以内
• 按依赖顺序排列（Model → Service → Controller → UI）
• 验证任务单独成组，放在最后

上下文管理

• 实现前清理上下文：apply 之前 compact 或新开会话
• project.md 写详细：技术栈版本、架构模式、编码规范、业务域知识
• AI 忽略 specs？运行 openspec update，并在 prompt 中要求 "先读 @openspec/agent-instructions.md"

团队协作 & CI/CD

• Code Review 同时审查 代码 + proposal.md + specs/
• 在 CI 中加入 openspec validate --all --strict
• openspec/ 整个目录纳入 Git 版本控制
• 归档后积极提交 openspec/specs/ 变更

问题速查表

问题	原因	解决方案
AI 忽略 specs	上下文过载或 AGENTS.md 未被读取	运行 openspec update；要求 AI 先读 AGENTS.md
命令找不到	npm 全局路径不在 PATH	检查 npm list -g --depth=0；配置 shell PATH
无法归档	AI 安全模式限制	在 Chat 中授权，或手动 openspec archive <id>
Spec 验证失败	缺少 Scenario 或格式错误	运行 openspec validate 查看具体错误
AI 幻觉严重	project.md 缺少技术栈信息	在 project.md 中写明依赖版本和架构约束
Task 依赖被阻塞	前置 artifact 未完成	openspec status --change <name> 查看阻塞原因

退出码

退出码	含义
0	成功
1	一般错误
2	验证失败
3	配置缺失或无效

遥测与隐私

# OpenSpec 收集匿名统计（仅命令名 + 版本，不含参数/路径/PII）
# 退出遥测：
export OPENSPEC_TELEMETRY=0
# 或
export DO_NOT_TRACK=1

核心命令速记

# 日常三步走
/opsx:propose <需求>     # 1. 描述需求 → 生成全套 artifact
/opsx:apply              # 2. AI 逐个实现 task
/opsx:archive            # 3. 归档 + 同步基线

# 常用 CLI
openspec list            # 查看活跃变更
openspec show <name>     # 查看变更详情
openspec status          # 查看 artifact 进度
openspec validate --all  # 验证所有 artifact
openspec view            # 交互式仪表盘

延伸阅读

• 源码分析：OpenSpec 源码深度解析
• GitHub 仓库：Fission-AI/OpenSpec
• 官方网站：openspec.dev
• 深度指南：OpenSpec Deep Dive
• 入门教程：Getting Started with SDD
• 自定义 Schema：OpenSpec Custom Schemas