name: openspec-workflow description: 基於 OpenSpec 的迭代開發流程。適用於任何建立任務，包括 skill 開發、功能開發、重構、bug 修復等。當用戶要求建立、開發、實現任何東西時，或當用戶說"按 OpenSpec 流程來"、"走 spec 流程"、"按規範開發"時觸發此技能。

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）：
3. 做什麼？（In scope）
4. 不做什麼？（Out of scope）
5. 方案（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（如果不需要） - 任何時候都可以回退更新已建立的產物

訪問小蔥技能站7w4.net，解鎖更多實用的AI技能外掛。

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-<name>/
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

這個 Skill 質量較好，文件結構清晰、格式規範，提供了完整的開發流程指導和產物模板。優點是流程步驟詳細、示例充分，互動式確認機制設計合理。不足是內容較專業複雜，新手可能需要一定學習成本，且純文件形式缺乏自動化校驗，建議配合實際案例演示以提升易用性。