OpenSpec

ワークフロー ​

本ガイドでは、OpenSpec の一般的なワークフローパターンと、それぞれの使用タイミングについて説明します。基本的なセットアップについては、Getting Started を参照してください。コマンドの参考については、Commands を参照してください。

哲学：フェーズではなくアクション ​

従来のワークフローでは、計画 → 実装 → 完了というフェーズを順に強制されます。しかし、実際の作業はこれにうまく収まるものではありません。

OPSX は異なるアプローチを採用しています：

text
Traditional (phase-locked):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "Can't go back"  │
      └────────────────────┘

OPSX (fluid actions):

  proposal ──► specs ──► design ──► tasks ──► implement

基本原則：

  • アクション、フェーズではない - コマンドは実行できるアクションであり、固定されたステージではありません
  • 依存関係は有効化要因 - 依存関係は次に何が必要かを示すのではなく、何が可能かを示します

カスタマイズ： OPSX のワークフローは、成果物のシーケンスを定義するスキーマによって駆動されます。カスタムスキーマの作成の詳細については、Customization を参照してください。

ワークフローの概要 ​

デフォルトのワークフローは流動的です：探索（Explore）と検証（Verify）はオプションであり、実装中に新たな発見があれば計画アーティファクトを更新できます。

mermaid
flowchart TD
    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planning artifacts<br/>ready?"}
    Review -->|"Refine"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implement"| Apply["/opsx:apply"]
    Apply -->|"Plan changed"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
    Verify --> Verified{"Ready to archive?"}
    Verified -->|"Fix implementation"| Apply
    Verified -->|"Revise plan"| Update
    Verified -->|"Ready"| Sync
    Verified -->|"Ready"| Archive
    Sync --> Archive

AI アシスタントがワークフローを駆動し、CLI は決定論的なスケルトン生成、ステータス表示、およびアーティファクトの指示を提供します。

mermaid
sequenceDiagram
    actor Human
    participant Assistant as AI assistant
    participant CLI as OpenSpec CLI
    participant Files as Planning and implementation files

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: Scaffold change metadata
    Assistant->>CLI: Request status and artifact instructions
    CLI-->>Assistant: Build order, paths, and templates
    Assistant->>Files: Write schema-defined planning artifacts
    Assistant-->>Human: Present artifacts for review

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Request apply instructions
    CLI-->>Assistant: Context files and task state
    Assistant->>Files: Implement tasks and update checkboxes
    Assistant-->>Human: Report implementation status

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Request archive inputs and artifact status
    CLI-->>Assistant: Planning paths and artifact completion
    Assistant->>Files: Read task state and compare delta specs
    opt Delta specs exist
        Assistant-->>Human: Offer to sync before archiving
        alt Sync accepted
            Human->>Assistant: Confirm sync
            Assistant->>Files: Merge delta specs into main specs
        else Sync skipped
            Human->>Assistant: Archive without syncing
        end
    end
    Assistant->>Files: Move the change into the archive
    Assistant-->>Human: Report archive location and sync result

    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts. It still validates, then applies any delta specs and archives

2つのモード ​

デフォルトのクイックパス（core プロファイル） ​

新規インストールでは core がデフォルトとなり、以下のコマンドが含まれます：

  • /opsx:explore
  • /opsx:propose
  • /opsx:apply
  • /opsx:update
  • /opsx:sync
  • /opsx:archive

典型的なフロー：

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (optional)

探索から始める（形成すべき習慣） ​

/opsx:explore はデフォルトプロファイルの一部であり、アドオンではありません。問題はあるがまだ計画がない場合に取るべきアクションです。AI アシスタントを使用する場合、これはほとんどの状況に該当します。

text
You: /opsx:explore

AI:  What would you like to explore?

You: Our search results feel stale. I'm not sure if it's caching,
     indexing, or the query itself.

AI:  Let me look... [reads the search service and cache layer]
     It's the index: it only rebuilds nightly, so edits don't show
     up until the next day. Two options: rebuild on write (simple,
     more load) or a short-TTL cache invalidation (more moving parts,
     less load). Given your write volume is low, rebuild-on-write is
     the cleaner fix. Want to scope it?

You: Yes.

You: /opsx:propose rebuild-search-index-on-write

探索はアーティファクトを作成せず、コードも書きません。漠然とした懸念を明確な変更提案に変えるための、リスクのない無料の対話です。これにより、続く提案が鋭敏になります。何をしたいかがすでに明確であれば、これをスキップして /opsx:propose に直接進んでください。詳細ガイド：Explore First。

拡張/フルワークフロー（カスタム選択） ​

明示的なスケルトン生成およびビルドコマンド（/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard）が必要な場合は、以下で有効化してください：

bash
openspec config profile
openspec update

ワークフローパターン（拡張モード） ​

クイック機能 ​

構築する内容が明確で、実行のみが必要な場合：

text
/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

会話例：

text
You: /opsx:new add-logout-button

AI:  Created openspec/changes/add-logout-button/
     Ready to create: proposal

You: /opsx:ff

AI:  Creating all planning artifacts...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Ready for implementation!

You: /opsx:apply

AI:  Working through tasks...
     ✓ Added logout button to header
     ✓ Implemented session clearing
     ✓ Added confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  ✓ Merged specs
     ✓ Archived change

適したケース： 小〜中規模の機能、バグ修正、単純な変更。

探索的 ​

要件が不明確な場合、または最初に調査が必要な場合：

text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

会話例：

text
You: /opsx:explore

AI:  What would you like to explore?

You: I want to improve page load performance but I'm not sure
     where the bottlenecks are.

AI:  Let me help investigate...
     [Analyzes bundle sizes, identifies slow queries, reviews
     component render patterns]

     I found three main bottlenecks:
     1. Large unoptimized images
     2. Synchronous data fetching in ProductList
     3. Re-renders from context changes

     Which would you like to address first?

You: Let's tackle the data fetching issue.

You: /opsx:new optimize-product-list-fetching

AI:  Created change. Ready to create: proposal

You: /opsx:continue

AI:  Creating proposal based on our exploration...
     [Writes proposal incorporating investigation insights]

     Ready to create: specs, design
     Which would you like next?

You: /opsx:continue

AI:  Creating specs...

適したケース： パフォーマンス最適化、デバッグ、アーキテクチャ意思決定、不明確な要件。

並列変更 ​

複数の変更を同時に作業する場合：

text
Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
                                         │
                                    context switch
                                         │
Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

会話例：

text
You: I'm working on add-dark-mode but got pulled into a bug fix

You: /opsx:new fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/

You: /opsx:ff

AI:  ✓ Created planning artifacts

You: /opsx:apply

AI:  Working on fix-login-redirect...
     [Implements the fix]
     All tasks complete!

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect

You: Let's get back to dark mode

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode...
     Picking up at task 2.3: Update Header...

適したケース： 並列作業ストリーム、緊急の割り込み、チームコラボレーション。

完了した変更が複数ある場合は、/opsx:bulk-archive を使用してください：

text
You: /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?

You: Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-redirect
     ✓ Archived update-footer
     Specs merged in order: add-dark-mode → update-footer

一括アーカイブは、複数の変更が同じ仕様（specs）に触れていることを検出し、実際に実装された内容を確認することで競合を解決します。

変更の完了 ​

推奨される完了フロー：

text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              validates          prompts to sync
              implementation     if needed

検証：作業の確認 ​

/opsx:verify は、アーティファクトに対して実装を3つの次元で検証します：

text
You: /opsx:verify

AI:  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

検証チェック項目：

次元検証内容
完全性すべてのタスク完了、すべての要件の実装、シナリオのカバレッジ
正しさ実装が仕様の意図と一致しているか、エッジケースが処理されているか
一貫性コード構造に設計判断が反映されているか、パターンが一貫しているか

検証はアーカイブをブロックしませんが、まず対処すべき問題を浮き彫りにします。

アーカイブ：変更の確定 ​

/opsx:archive は変更を完了し、アーカイブへ移動します：

text
You: /opsx:archive

AI:  Archiving add-auth...

     Artifact status:
     ✓ proposal.md exists
     ✓ specs/ exists
     ✓ design.md exists
     ✓ tasks.md exists (12/12 tasks complete)

     Delta specs: Not yet synced to main
     → Would you like to sync now?

You: Yes

AI:  ✓ Synced specs to openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-auth/

     Change archived successfully.

仕様が同期されていない場合、アーカイブはプロンプトを表示します。未完了のタスクがある場合はアーカイブをブロックしませんが、警告を表示します。

いつ何を使うか ​

/opsx:ff vs /opsx:continue ​

状況使用コマンド
要件が明確で、構築準備ができている/opsx:ff
探索中、各ステップを確認したい/opsx:continue
仕様作成前に提案を反復したい/opsx:continue
時間的制約があり、高速に進めたい/opsx:ff
複雑な変更で、制御を行いたい/opsx:continue

目安： 全体の範囲を事前に説明できる場合は /opsx:ff を、進めながら検討する場合は /opsx:continue を使用してください。

更新 vs 新規開始 ​

一般的な質問：既存の変更を更新するのはいつ適切で、いつ新規開始すべきでしょうか？

既存の変更を更新する場合：

  • 同じ意図だが、実行方法を洗練させる場合
  • スコープが狭まる場合（まずMVP、その後残りを）
  • 学習に基づく修正（コードベースが予想と異なる場合）
  • 実装の発見に基づいた設計の微調整

新規変更を開始する場合：

  • 意図が根本的に変化した場合
  • スコープが完全に異なる作業まで膨張した場合
  • 元の変更が単独で「完了」とみなせる場合
  • パッチの方が混乱をもたらす可能性がある場合
text
                     ┌─────────────────────────────────────┐
                     │     Is this the same work?          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Same intent?      >50% overlap?      Can original
          Same problem?     Same scope?        be "done" without
                 │                  │          these changes?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      YES               NO YES           NO  NO              YES
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    UPDATE            NEW  UPDATE       NEW  UPDATE          NEW

例：「ダークモードを追加」

  • 「カスタムテーマもサポートする必要がある」→ 新規変更（スコープが膨張）
  • 「システム設定の検出が予想より難しい」→ 更新（同じ意図）
  • 「まずは切り替えボタンをリリースし、設定は後で追加する」→ 更新してアーカイブ、その後新規変更

ベストプラクティス ​

変更を焦点を絞る ​

1つの変更につき1つの論理的な作業単位にしてください。「機能Xを追加しつつYのリファクタリングもする」場合は、2つの別の変更として扱うことをお勧めします。

なぜ重要か：

  • レビューと理解が容易になる
  • アーカイブ履歴がクリーンになる
  • 独立してリリースできる
  • 必要時のロールバックが簡単になる

要件が不明確な場合は /opsx:explore を使用する ​

変更を確定する前に、問題領域を探索してください：

text
You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle rate limiting for our API?

AI:  Let me investigate your current setup and options...
     [Researches codebase, considers patterns]

     I see three approaches we could take:
     1. Middleware-based (simple, per-endpoint)
     2. Redis-backed (scalable, shared state)
     3. Token bucket per user (fair, complex)

     Your current stack suggests #1 or #2. What's your scale?

探索は、成果物を作成する前に思考を明確にします。

アーカイブ前に検証する ​

/opsx:verify を使用して、実装が成果物と一致しているか確認してください：

text
You: /opsx:verify

AI:  Verifying add-dark-mode...

     ✓ All tasks in tasks.md are checked
     ✓ Requirements in specs have corresponding code
     ✓ Design decisions are reflected in implementation

     Ready to archive!

変更を完了する前に不整合を検出します。

変更名を明確に付ける ​

適切な名前付けにより openspec list が有用になります：

text
Good:                          Avoid:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

コマンドクイックリファレンス ​

コマンドの詳細とオプションについては、Commands を参照してください。

CommandPurposeWhen to Use
/opsx:propose変更と計画成果物を作成素早いデフォルトのパス（core プロファイル）
/opsx:exploreAI とアイデアを検討する不明確な場合の起点：要件が不明確、調査、選択肢の比較
/opsx:new変更のスカフォールドを開始拡張モード、成果物の明示的な制御
/opsx:continue次の成果物を作成拡張モード、成果物をステップバイステップで作成
/opsx:ffすべての計画成果物を作成拡張モード、スコープが明確な場合
/opsx:applyタスクを実装するコードを書き始める準備ができた場合
/opsx:verify実装を検証する拡張モード、アーカイブ前
/opsx:syncデルタ仕様をマージする拡張モード、オプション
/opsx:archive変更を完了するすべての作業が完了した場合
/opsx:bulk-archive複数の変更をアーカイブする拡張モード、並行作業

次のステップ ​

  • Writing Good Specs - 強力な要件とシナリオの書き方、変更の適切なサイズ設定について
  • Reviewing a Change - コードを書く前にドラフトされた計画を2分でレビューする方法
  • OpenSpec on a Team - 変更がブランチやプルリクエストとどのように連携するか
  • Commands - オプション付きの完全なコマンドリファレンス
  • Concepts - 仕様、成果物、スキーマの深掘り
  • Customization - カスタムワークフローの作成