OpenSpec 迭代开发流程

基于 OpenSpec 的规范驱动开发流程，适用于一切创建和迭代任务。

核心哲学

→ 流动而非僵化 — Actions, not phases。命令是你可做的事，不是你被困住的阶段
→ 迭代而非瀑布 — 边建边学，随时修正。依赖关系是使能器，不是强制门控
→ 简单而非复杂 — 最轻量的规范，按需加深（Progressive Rigor）
→ 增量而非全量 — delta spec 描述变更，不重写全部
→ 先同意再构建 — 任何产物写出前必须与用户确认
→ Brownfield-first — 面向现有代码库的变更优先，而非全新系统

工作模式

OpenSpec 支持两种工作模式，本 skill 默认使用 Core Profile（快速路径），但支持 Expanded Workflow 的完整功能。

模式对比

模式选择原则

• 使用 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，选择适合项目的策略：

关键原则：

• 一个 domain = 一个逻辑分组
• spec 描述行为契约，不是实现计划
• 避免在 spec 中包含：内部类/函数名、库/框架选择、逐步实现细节

流程步骤

Step 1: Explore（可选）

需求不明确时先探索。

• 调查代码库、分析现状
• 列出可选方案
• 明确需求边界
• 不产生任何 artifact

Step 2: Propose — 创建变更 + 规划产物

⚠️ 关键：这是交互式流程，不是一步到位的。必须分阶段与用户确认。

2.1 信息收集（必须）

在创建任何文件之前，先与用户讨论并确认以下信息：

1. 意图（Intent）：为什么要做这件事？解决什么问题？
2. 范围（Scope）：
• 做什么？（In scope）
• 不做什么？（Out of scope）
3. 方案（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 关键词（表示需求强度）：

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 — 逐项实现

1. 读取 tasks.md
2. 按顺序实现每个未完成的任务
3. 每完成一组任务后向用户汇报进度
4. 完成后标记 [x]
5. 实现中发现问题可回退更新 design.md / proposal.md（需告知用户）
6. 中断后可从上次进度继续

实现原则：

• 严格按 tasks.md 顺序执行
• 每完成一组任务汇报一次进度
• 发现方案问题时先更新 artifact 再继续，并告知用户变更原因
• 保持上下文干净，避免偏离

Step 4: Verify — 验证实现（推荐）

从三个维度验证并向用户汇报结果：

验证输出示例：

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 — 归档变更

1. 合并 delta specs 到 openspec/specs/
2. 移动变更文件夹到 openspec/changes/archive/YYYY-MM-DD-/
3. 保留完整历史用于审计
4. 通知用户变更已归档

工作流模式

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 新建

命令速查

本 skill 在 Claude Code 环境中不使用 /opsx:* 斜杠命令，而是由 agent 直接执行文件操作。映射关系：

注意：

• Core Profile 默认路径：propose → apply → archive
• Expanded Workflow 支持更细粒度的控制
• 不同 AI 工具的命令语法可能不同（Cursor 用 /opsx-propose）

/opsx:ff vs /opsx:continue 选择指南

经验法则：如果可以提前描述完整范围，用 /opsx:ff；如果边做边摸索，用 /opsx:continue。

适用场景

• ✅ Skill 开发
• ✅ 功能开发
• ✅ Bug 修复（复杂 bug）
• ✅ 重构
• ✅ 架构调整
• ✅ 任何需要 > 1 步的创建任务

不适用场景

• ❌ 单行命令执行
• ❌ 简单问答
• ❌ 信息查询

注意事项

• 变更命名用 kebab-case：add-dark-mode、fix-login-redirect
• Delta spec 只写变更部分，不重写全部 spec
• tasks.md 要细分到单次可完成的粒度
• 长任务中保持上下文卫生，避免累积过多无关信息
• 每个阶段都要与用户确认，不要自作主张
• 如果用户说"直接搞"或"不用确认"，可以跳过确认环节快速执行

术语表

参考资源

• OpenSpec 官方文档
• Getting Started: https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md
• Workflows: https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md
• Commands: https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md
• Concepts: https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md