OpenSpec 迭代开发流程
基于 OpenSpec 的规范驱动开发流程，适用于一切创建和迭代任务。
核心哲学
→ 流动而非僵化 — Actions, not phases。命令是你可做的事，不是你被困住的阶段
→ 迭代而非瀑布 — 边建边学，随时修正。依赖关系是使能器，不是强制门控
→ 简单而非复杂 — 最轻量的规范，按需加深（Progressive Rigor）
→ 增量而非全量 — delta spec 描述变更，不重写全部
→ 先同意再构建 — 任何产物写出前必须与用户确认
→ Brownfield-first — 面向现有代码库的变更优先，而非全新系统
工作模式
OpenSpec 支持两种工作模式，本 skill 默认使用 Core Profile（快速路径），但支持 Expanded Workflow 的完整功能。
模式对比
| 特性 | Core Profile (默认) | Expanded Workflow |
|---|
| 流程 | /opsx:propose → /opsx:apply → /opsx:archive | /opsx:new → /opsx:ff/continue → /opsx:apply → /opsx:verify → /opsx:archive |
| 适用场景 | 清晰需求，快速执行 | 需要逐步控制，复杂变更 |
| 创建方式 | 一步创建所有规划产物 | 逐步创建，每步确认 |
| 验证步骤 | 可选 | 推荐（/opsx:verify） |
模式选择原则
- 使用 Core Profile（
/opsx:propose）：需求明确，可以直接描述完整范围
- 使用 Expanded（
/opsx:new + /opsx:continue）：边探索边规划，需要逐步审查
- 使用 Fast-Forward（
/opsx:ff）：Expanded 模式下，范围清晰但想要显式控制开始
目录结构
每次变更在工作区 openspec/ 下维护：
openspec/
├── specs/ # 系统真相（当前行为描述）
│ └── <domain>/ # 按领域组织
│ └── spec.md
├── changes/ # 活跃变更（一个变更一个文件夹）
│ └── <change-name>/
│ ├── .openspec.yaml # 变更元数据（可选）
│ ├── proposal.md # 意图、范围、方案
│ ├── design.md # 技术方案
│ ├── tasks.md # 实现清单
│ └── specs/ # Delta specs（变更内容）
│ └── <domain>/
│ └── spec.md
├── changes/archive/ # 已归档变更
│ └── YYYY-MM-DD-<name>/ # 按日期归档
└── config.yaml # 项目配置（可选）
Spec 组织方式（Domain）
按领域组织 spec，选择适合项目的策略：
| 策略 | 示例 | 适用场景 |
|---|
| 按功能区域 | auth/, payments/, search/ | 大多数项目 |
| 按组件 | api/, frontend/, workers/ | 技术架构清晰 |
| 按限界上下文 | ordering/, fulfillment/, inventory/ | DDD 风格 |
关键原则：
- 一个 domain = 一个逻辑分组
- spec 描述行为契约，不是实现计划
- 避免在 spec 中包含：内部类/函数名、库/框架选择、逐步实现细节
流程步骤
Step 1: Explore（可选）
需求不明确时先探索。
- 调查代码库、分析现状
- 列出可选方案
- 明确需求边界
- 不产生任何 artifact
Step 2: Propose — 创建变更 + 规划产物
⚠️ 关键：这是交互式流程，不是一步到位的。必须分阶段与用户确认。
2.1 信息收集（必须）
在创建任何文件之前，先与用户讨论并确认以下信息：
- 意图（Intent）：为什么要做这件事？解决什么问题？
- 范围（Scope）：
- 做什么？（In scope）
- 不做什么？（Out of scope）
- 方案（Approach）：高层面怎么做？
收集方式：
- 如果用户需求描述已经很清晰，可以直接整理成 proposal 草稿让用户确认
- 如果用户需求模糊，必须先追问关键问题：
- "这个功能的预期用户是谁？"
- "有没有参考示例或竞品？"
- "哪些边界情况需要处理？"
- "有没有不想做的部分？"
- "对技术栈有偏好吗？"
- 用简洁的列表展示收集到的信息，请用户确认或补充
确认话术示例：
我来确认一下需求：
- 意图：...
- 范围：...
- 方案：...
这样理解对吗？有需要补充或修改的吗？
2.2 创建 proposal.md（用户确认后）
收到用户确认后，创建 proposal.md 并再次请用户审阅：
我写了一个 proposal，核心要点：
- ...
- ...
- ...
请看看有没有遗漏或需要调整的。
2.3 创建其余产物（用户确认 proposal 后）
proposal 确认后，依次创建：
openspec/changes/<change-name>/
├── proposal.md # 已确认
├── specs/ # Delta specs — 需求变更（ADDED/MODIFIED/REMOVED）
├── design.md # 技术方案
└── tasks.md # 实现清单（checkbox）
创建完后展示任务清单摘要，请用户确认可以开始实现。
Artifact 依赖关系
产物按依赖顺序创建，依赖关系是使能器（什么可以创建），不是强制门控（必须创建什么）：
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)
关键理解：
specs 和 design 可以并行创建（都只依赖 proposal）tasks 需要 specs 和 design 都完成后才能创建- 可以跳过
design（如果不需要）
- 任何时候都可以回退更新已创建的产物
proposal.md 格式：
# Proposal: <标题>
## Intent（意图）
为什么做这件事？
## Scope（范围）
### In scope
- ...
### Out of scope
- ...
## Approach（方案）
高层面怎么做？
Delta specs 格式（specs/下）：
# Delta for <Domain>
## ADDED Requirements
### Requirement: <名称>
The system SHALL/MUST/SHOULD ...
#### Scenario: <场景名>
- GIVEN ...
- WHEN ...
- THEN ...
## MODIFIED Requirements
### Requirement: <名称>
(Previously: ...)
## REMOVED Requirements
### Requirement: <名称>
(原因)
Spec 写作规范
RFC 2119 关键词（表示需求强度）：
| 关键词 | 含义 | 使用场景 |
|---|
MUST / SHALL | 绝对要求 | 不可偏离的核心行为 |
SHOULD | 推荐 | 允许例外，但需充分理由 |
MAY | 可选 | 真正可选的功能 |
Scenario 格式（Given/When/Then）：
GIVEN - 初始状态/前置条件WHEN - 触发动作/事件THEN - 预期结果/后置条件AND - 补充条件
示例：
### Requirement: User Authentication
The system MUST issue a JWT token upon successful login.
#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
Progressive Rigor（渐进严谨度）：
大多数变更使用 Lite spec（默认），保持轻量：
- ✅ 短小精悍的行为优先需求
- ✅ 清晰的范围和非目标
- ✅ 几个具体的验收检查
仅在以下情况使用 Full spec：
- 跨团队/跨仓库变更
- API/合约变更、迁移、安全/隐私相关
- 模糊可能导致昂贵返工的变更
design.md 格式：
# Design: <标题>
## Technical Approach
技术方案概述
## Architecture Decisions
### Decision: <决策标题>
选择 X 因为...
## Data Flow / File Changes
...
tasks.md 格式：
# Tasks
## 1. <分组名>
- [ ] 1.1 <任务描述>
- [ ] 1.2 <任务描述>
## 2. <分组名>
- [ ] 2.1 <任务描述>
Step 3: Apply — 逐项实现
- 读取
tasks.md
- 按顺序实现每个未完成的任务
- 每完成一组任务后向用户汇报进度
- 完成后标记
[x]
- 实现中发现问题可回退更新 design.md / proposal.md（需告知用户）
- 中断后可从上次进度继续
实现原则：
- 严格按 tasks.md 顺序执行
- 每完成一组任务汇报一次进度
- 发现方案问题时先更新 artifact 再继续，并告知用户变更原因
- 保持上下文干净，避免偏离
Step 4: Verify — 验证实现（推荐）
从三个维度验证并向用户汇报结果：
| 维度 | 英文 | 检查内容 |
|---|
| 完整性 | Completeness | 所有 task 已完成，所有需求有对应代码，场景已覆盖 |
| 正确性 | Correctness | 实现符合 spec 意图，边界情况已处理，错误状态匹配 |
| 一致性 | Coherence | 设计决策反映在代码中，命名与设计一致 |
验证输出示例：
Verifying add-auth...
COMPLETENESS
✓ All 12 tasks in tasks.md are checked
✓ All requirements in specs have corresponding code
⚠ Scenario "Session timeout after inactivity" not tested
CORRECTNESS
✓ Implementation matches spec intent
✓ Edge cases from scenarios are handled
✓ Error states match spec definitions
COHERENCE
✓ Design decisions reflected in code structure
✓ Naming conventions consistent with design.md
⚠ Design mentions "event-driven" but implementation uses polling
SUMMARY
─────────────────────────────
Critical issues: 0
Warnings: 2
Ready to archive: Yes (with warnings)
Recommendations:
1. Add test for session timeout scenario
2. Consider refactoring to event-driven as designed, or update design.md
验证不阻塞归档，但应修复 Critical 问题。
Step 5: Archive — 归档变更
- 合并 delta specs 到
openspec/specs/
- 移动变更文件夹到
openspec/changes/archive/YYYY-MM-DD-<name>/
- 保留完整历史用于审计
- 通知用户变更已归档
工作流模式
Quick Feature（快速功能）
需求明确，直接执行：
触发: /opsx:propose add-dark-mode
流程: propose → apply → archive
适用: 小到中等功能、简单 bug 修复
Exploratory（探索式）
需求不清晰，先调查：
触发: /opsx:explore
流程: explore → /opsx:new → /opsx:continue → ... → /opsx:apply
示例对话:
User: /opsx:explore
AI: What would you like to explore?
User: I want to improve page load performance but not sure where bottlenecks are.
AI: [Analyzes bundle sizes, queries, render patterns]
Found three bottlenecks:
1. Large unoptimized images
2. Synchronous data fetching in ProductList
3. Re-renders from context changes
Which to address first?
适用: 性能优化、调试、架构决策、需求模糊
Parallel Changes（并行变更）
同时处理多个变更：
场景: 正在 add-dark-mode，被 pull 去修 bug
流程:
Change A: /opsx:propose → /opsx:apply (进行中)
│ context switch
│
Change B: /opsx:propose → ──────────→ /opsx:apply
完成后: /opsx:bulk-archive 批量归档
适用: 并行工作流、紧急中断、团队协作
/opsx:bulk-archive 示例：
AI: Found 3 completed changes:
- add-dark-mode (all tasks done)
- fix-login-redirect (all tasks done)
- update-footer (all tasks done)
Checking for spec conflicts...
⚠ add-dark-mode and update-footer both touch specs/ui/
Inspecting codebase to resolve...
Both changes are implemented. Will apply in chronological order.
Archive all 3 changes?
适用: 多变更并行完成后，自动检测冲突并解决
/opsx:onboard（引导式教程）
首次使用或学习完整流程：
功能: 使用实际代码库的完整工作流教程
阶段:
1. 扫描代码库找改进机会
2. 创建真实变更
3. 实现真实工作（小而安全的变更）
4. 完成归档
5. 每步都有讲解
时间: 15-30 分钟
结果: 获得一个真实的已归档变更
更新 vs 新建
| 情况 | 操作 |
|---|
| 同一意图，方案微调 | 更新现有变更 |
| 范围收窄（先 MVP） | 更新然后归档，再新建后续 |
| 意图根本改变 | 新建变更 |
| 范围膨胀超 50% | 新建变更 |
| 原变更可以独立完成 | 归档原变更，新建后续 |
命令速查
本 skill 在 Claude Code 环境中不使用 /opsx:* 斜杠命令，而是由 agent 直接执行文件操作。映射关系：
| OpenSpec 命令 | 本 skill 对应操作 |
|---|
/opsx:explore | 调查分析，不创建文件 |
/opsx:propose | 信息收集 → 用户确认 → 创建 proposal → 用户确认 → 创建其余产物 |
/opsx:new | 创建变更 scaffold，等待 /opsx:continue 或 /opsx:ff |
/opsx:continue | 逐步创建下一个 artifact（基于依赖关系） |
/opsx:ff | Fast-forward，一次性创建所有规划产物 |
/opsx:apply | 逐项实现 tasks.md，分组汇报进度 |
/opsx:verify | 三维度验证实现（Completeness/Correctness/Coherence），汇报结果 |
/opsx:sync | 可选命令，提前合并 delta specs 到 main（归档时会自动处理） |
/opsx:archive | 合并 specs + 移动到 archive/YYYY-MM-DD-<name>/，通知用户 |
/opsx:bulk-archive | 批量归档多个完成变更，自动检测和解决 spec 冲突 |
/opsx:onboard | 引导式教程，使用实际代码库完成完整工作流 |
注意：
- Core Profile 默认路径：
propose → apply → archive
- Expanded Workflow 支持更细粒度的控制
- 不同 AI 工具的命令语法可能不同（Cursor 用
/opsx-propose）
/opsx:ff vs /opsx:continue 选择指南
| 场景 | 使用 |
|---|
| 需求明确，准备好构建 | /opsx:ff |
| 探索中，想逐步审查 | /opsx:continue |
| 想 specs 之前迭代 proposal | /opsx:continue |
| 时间压力，需要快速推进 | /opsx:ff |
| 复杂变更，需要控制 | /opsx:continue |
经验法则：如果可以提前描述完整范围，用 /opsx:ff；如果边做边摸索，用 /opsx:continue。
适用场景
- ✅ Skill 开发
- ✅ 功能开发
- ✅ Bug 修复（复杂 bug）
- ✅ 重构
- ✅ 架构调整
- ✅ 任何需要 > 1 步的创建任务
不适用场景
注意事项
- 变更命名用 kebab-case：
add-dark-mode、fix-login-redirect
- Delta spec 只写变更部分，不重写全部 spec
- tasks.md 要细分到单次可完成的粒度
- 长任务中保持上下文卫生，避免累积过多无关信息
- 每个阶段都要与用户确认，不要自作主张
- 如果用户说"直接搞"或"不用确认"，可以跳过确认环节快速执行
术语表
| 术语 | 定义 |
|---|
| Artifact | 变更文件夹中的文档（proposal、design、tasks、delta specs） |
| Archive | 完成变更的过程，将 delta specs 合并到 main specs |
| Change | 系统的提议修改，打包为一个包含 artifacts 的文件夹 |
| Delta spec | 描述相对于当前 specs 的变更（ADDED/MODIFIED/REMOVED） |
| Domain | spec 的逻辑分组（如 auth/、payments/） |
| Requirement | 系统必须具备的特定行为 |
| Scenario | 需求的具体示例，通常使用 Given/When/Then 格式 |
| Schema | artifact 类型及其依赖关系的定义 |
| Spec | 描述系统行为的规范，包含 requirements 和 scenarios |
| Source of truth | openspec/specs/ 目录，包含当前约定的行为 |
参考资源
