OPSX ワークフロー

Discord でのフィードバックを歓迎します。

OPSX とは

OPSX は現在、OpenSpec の標準ワークフローです。

OpenSpec の change に対応する 柔軟で反復的なワークフロー です。固定されたフェーズではなく、いつでも実行できるアクションで構成されます。

なぜ導入されたのか

従来の OpenSpec ワークフローは機能しますが、制約が強いものでした。

• 指示がハードコードされている — TypeScript の中に埋め込まれ、変更できない
• 一括処理のみ — 1つの大きなコマンドですべてが作成され、個々の部分をテストできない
• 固定された構成 — 全員が同じワークフローを使い、カスタマイズできない
• ブラックボックス — AI の出力が悪くても、プロンプトを調整できない

OPSX はこれらを開放します。 誰でも次のことができます。

1. 指示を試す — テンプレートを編集し、AI の出力が改善するか確認する
2. 細かくテストする — 各成果物への指示を個別に検証する
3. ワークフローをカスタマイズする — 独自の成果物と依存関係を定義する
4. 素早く反復する — テンプレートを変更してすぐにテストする。再ビルドは不要

従来のワークフロー:                    OPSX:
┌────────────────────────┐           ┌────────────────────────┐
│  パッケージにハードコード│           │  schema.yaml           │◄── こちらを編集
│  （変更できない）      │           │  templates/*.md        │◄── またはこちら
│        ↓               │           │        ↓               │
│  新しいリリースを待つ  │           │  すぐに反映              │
│        ↓               │           │        ↓               │
│  改善に期待する        │           │  自分でテスト            │
└────────────────────────┘           └────────────────────────┘

すべての人に役立ちます。

• チーム — 実際の作業方法に合うワークフローを作成する
• 上級ユーザー — コードベースに合った AI 出力を得るためにプロンプトを調整する
• OpenSpec のコントリビューター — リリースを待たずに新しい方法を試す

何が最適かは、まだ誰もが学んでいるところです。OPSX を使えば一緒に学べます。

ユーザー体験

直線的なワークフローの問題: 「計画フェーズ」に入り、次に「実装フェーズ」、そして「完了」と進みます。しかし実際の作業はそのようには進みません。何かを実装してから設計の誤りに気付き、仕様を更新して実装を続けることもあります。直線的なフェーズは、実際の作業方法と相反します。

OPSX の方法:

• フェーズではなくアクション — 作成、実装、更新、アーカイブをいつでも実行できる
• 依存関係は可能性を広げるもの — 次に必須の作業ではなく、可能な作業を示す

  proposal ──→ specs ──→ design ──→ tasks ──→ implement

セットアップ

# openspec がインストールされていることを確認 — スキルは自動生成される
openspec init

AI コーディングアシスタントが自動検出するスキルを .claude/skills/（または同等の場所）に作成します。

既定では、OpenSpec は core ワークフロープロファイル（propose、explore、apply、update、sync、archive）を使います。拡張ワークフローコマンド（new、continue、ff、verify、bulk-archive、onboard）を使うには、openspec config profile で設定し、openspec update で適用します。

セットアップ中に プロジェクト設定（openspec/config.yaml）の作成を求められます。任意ですが、作成を推奨します。

プロジェクト設定

プロジェクト設定では、既定値を指定し、プロジェクト固有のコンテキストをすべての成果物に注入できます。

設定の作成

設定は openspec init 時に作成するか、手動で作成できます。

openspec/config.yaml

schema: spec-driven

context: |
  技術スタック: TypeScript、React、Node.js
  API 規約: RESTful、JSON レスポンス
  テスト: 単体テストに Vitest、E2E に Playwright
  スタイル: ESLint と Prettier、strict TypeScript

rules:
  proposal:
    - ロールバック計画を含める
    - 影響を受けるチームを特定する
  specs:
    - シナリオには Given/When/Then 形式を使う
  design:
    - 複雑なフローにはシーケンス図を含める

設定フィールド

フィールド	型	説明
schema	string	新しい change に使う既定スキーマ（例: spec-driven）
context	string	すべての成果物指示に注入するプロジェクトコンテキスト
rules	object	成果物 ID をキーとする成果物ごとのルール

仕組み

スキーマの優先順位（高い順）:

1. CLI フラグ（--schema <name>）
2. change のメタデータ（change ディレクトリの .openspec.yaml）
3. プロジェクト設定（openspec/config.yaml）
4. 既定値（spec-driven）

コンテキストの注入:

• すべての成果物の指示の先頭にコンテキストを追加する
• <context>...</context> タグで囲む
• AI がプロジェクトの規約を理解するのに役立つ

ルールの注入:

• 一致する成果物にのみルールを注入する
• <rules>...</rules> タグで囲む
• コンテキストの後、テンプレートの前に配置する

スキーマごとの成果物 ID

spec-driven（既定）:

• proposal — change の提案
• specs — 仕様
• design — 技術設計
• tasks — 実装タスク

設定の検証

• rules に未知の成果物 ID があると警告が生成される
• スキーマ名は利用可能なスキーマと照合される
• コンテキストの上限は50 KB
• 無効な YAML は行番号付きで報告される

トラブルシューティング

「Unknown artifact ID in rules: X」

• 成果物 ID がスキーマに一致するか確認してください（上の一覧を参照）。
• openspec schemas --json を実行すると、各スキーマの成果物 ID を確認できます。

設定が適用されない:

• ファイルが openspec/config.yaml にあることを確認します（.yml ではありません）。
• バリデーターで YAML 構文を確認します。
• 設定変更はすぐに反映されます（再起動不要）。

コンテキストが大きすぎる:

• コンテキストは50 KB に制限されています。
• 要約するか、外部ドキュメントへのリンクを使ってください。

コマンド

コマンド	動作
/opsx:propose	change と計画成果物を一度に作成（既定の簡易フロー）
/opsx:explore	アイデアを検討し、問題を調査し、要件を明確にする
/opsx:new	新しい change のひな型を作成（拡張ワークフロー）
/opsx:continue	次の成果物を作成（拡張ワークフロー）
/opsx:ff	計画成果物を一気に作成（拡張ワークフロー）
/opsx:apply	タスクを実装し、必要に応じて成果物を更新
/opsx:update	change の計画成果物を見直し、一貫性を保つ
/opsx:verify	成果物と照らして実装を検証（拡張ワークフロー）
/opsx:sync	差分仕様をメイン仕様にマージ（任意）
/opsx:archive	完了した change をアーカイブ
/opsx:bulk-archive	複数の完了済み change をアーカイブ（拡張ワークフロー）
/opsx:onboard	change の全工程をガイド付きで体験（拡張ワークフロー）

使い方

アイデアを explore する

/opsx:explore

アイデアを検討し、問題を調査し、選択肢を比較します。決まった形式は不要です。思考パートナーとして使ってください。考えがまとまったら、既定の /opsx:propose または拡張ワークフローの /opsx:new//opsx:ff に移行します。

新しい change を始める

/opsx:propose

change を作成し、実装前に必要な計画成果物を生成します。

拡張ワークフローを有効にしている場合は、代わりに次を使えます。

/opsx:new        # ひな型のみ作成
/opsx:continue   # 成果物を1つずつ作成
/opsx:ff         # すべての計画成果物を一度に作成

成果物を作成する

/opsx:continue

依存関係に基づいて作成可能な成果物を表示し、そのうち1つを作成します。繰り返し実行して change を段階的に整えます。

/opsx:ff add-dark-mode

すべての計画成果物を一度に作成します。作るものが明確な場合に使います。

実装する（柔軟な部分）

/opsx:apply

タスクに取り組み、完了したものにチェックを付けます。複数の change を並行している場合は /opsx:apply <name> を実行できます。それ以外の場合、会話から対象を推測し、特定できなければ選択を促します。

change を更新する

/opsx:update add-dark-mode - テーマを Cookie に保存することにしました

change の既存の計画成果物を見直し、どの方向にも一貫性を保ちます（設計の編集が提案に影響する場合もあります）。コードは編集しません。すべての編集は事前に確認します。新しい成果物を開始せずに不足ファイルを処理する方法は、update のリファレンスを参照してください。

change がすでに実装済みの場合、更新した計画にコードを合わせるため /opsx:apply の実行を推奨します。更新によって change の 目的 が変わる場合は、新しく始めてください。更新するか新しく始めるかを参照してください。

差分仕様を同期する

/opsx:sync

現在の change の差分仕様をメインの openspec/specs/ にマージしますが、アーカイブは行わないため change は作業中のままです。差分全体を適用します。## REMOVED の要件はメイン仕様から削除され、名前を変更した要件はその場で改題されます。差分で言及されていない内容には触れません。同期は任意です。まだ同期していない場合、archive 実行時に同期するか確認されます。アーカイブ前にメイン仕様を更新したい場合、この change が追加した仕様を基に並行する change を作りたい場合、またはマージ後のメイン仕様を確認してからアーカイブしたい場合に使ってください。

作業を完了する

/opsx:archive   # 完了後にアーカイブへ移動（必要なら仕様同期を確認）

更新するか、新しく始めるか

実装前であれば、いつでも提案や仕様を編集できます。では、どこからが「別の作業」になるのでしょうか？

提案に含まれるもの

提案では3つのことを定義します。

1. 目的 — どの問題を解決するのか。
2. 範囲 — 何を対象にし、何を対象外にするのか。
3. 方針 — どのように解決するのか。

考えるべきなのは、どの要素がどの程度変わったかです。

既存の change を更新する場合:

目的は同じで、実行方法を洗練する

• 考慮していなかった境界ケースが見つかった
• 目的は変わらないが、方針の調整が必要になった
• 実装してみると設計に少し誤りがあった

範囲を縮小する

• 全範囲が大きすぎると分かり、まず MVP をリリースしたくなった
• 「ダークモードを追加」→「ダークモード切り替えを追加（システム設定は v2）」

新たな理解に基づいて修正する

• コードベースの構成が想定と異なる
• 依存関係が想定どおりに動作しない
• 「CSS 変数を使う」→「代わりに Tailwind の dark: プレフィックスを使う」

新しい change を始める場合:

目的が根本的に変わった

• 問題自体が変わった
• 「ダークモードを追加」→「カスタムカラー、フォント、間隔を含む包括的なテーマシステムを追加」

範囲が大幅に拡大した

• change が大きくなり、実質的に別の作業になった
• 更新後には元の提案の意図が分からなくなる
• 「ログインのバグを修正」→「認証システムを書き直す」

元の作業を完了できる

• 元の change を「完了」にできる
• 新しい作業が改善ではなく独立している
• 「ダークモード MVP を追加」を完了 → アーカイブ → 新しい change「ダークモードを強化」

判断の目安

                        ┌─────────────────────────────────────┐
                        │     これは同じ作業か？                │
                        └──────────────┬──────────────────────┘
                                       │
                    ┌──────────────────┼──────────────────┐
                    │                  │                  │
                    ▼                  ▼                  ▼
             目的は同じ？      50%超が重複？      元の作業は
             問題は同じ？      範囲は同じ？       これらの変更なしで
                    │                  │          完了できる？
                    │                  │                  │
          ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
          │                 │  │             │   │               │
         YES               NO YES           NO  NO              YES
          │                 │  │             │   │               │
          ▼                 ▼  ▼             ▼   ▼               ▼
       更新              新規   更新         新規   更新           新規

判定項目	更新	新しい change
同一性	「同じ作業を洗練」	「別の作業」
範囲の重複	50%超が重複	50%未満が重複
完了可能性	更新なしでは「完了」できない	元の作業を完了でき、新しい作業は独立している
経緯	更新の連続で一貫した経緯を説明できる	継ぎ足しの修正が明確さより混乱をもたらす

原則

更新は文脈を保つ。新しい change は明確さをもたらす。

考えた経緯が重要なら更新を選びます。 継ぎ足すより新しく始める方が明快なら、新しい change を選びます。

git ブランチと同じように考えてください。

• 同じ機能に取り組んでいる間はコミットを続ける
• 本当に新しい作業を始めるときは新しいブランチを作成する
• 機能の一部をマージし、第2段階のために新しく始める場合もある

何が違うのか

	従来方式 (/openspec:proposal)	OPSX (/opsx:*)
構成	1つの大きな提案ドキュメント	依存関係を持つ個別の成果物
ワークフロー	直線的なフェーズ: 計画 → 実装 → アーカイブ	柔軟なアクション — いつでも実行可能
反復	前に戻りにくい	分かったことに合わせて成果物を更新
カスタマイズ	固定された構成	スキーマ駆動（独自の成果物を定義）

重要な洞察: 作業は直線的ではありません。OPSX は直線的であるかのように扱うことをやめます。

アーキテクチャの詳細

この節では、OPSX の内部動作と従来のワークフローとの違いを説明します。 ここでは拡張コマンドセット（new、continue など）を使います。既定の core を使う場合も、同じ流れを propose → apply → sync → archive に対応させられます。

基本理念: フェーズとアクション

┌─────────────────────────────────────────────────────────────────────────────┐
│                         従来のワークフロー                                      │
│                    （フェーズ固定、一括方式）                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌──────────────┐      ┌──────────────┐      ┌──────────────┐             │
│   │   計画   │ ───► │ 実装 │ ───► │   アーカイブ  │             │
│   │    フェーズ     │      │    フェーズ     │      │    フェーズ     │             │
│   └──────────────┘      └──────────────┘      └──────────────┘             │
│         │                     │                     │                       │
│         ▼                     ▼                     ▼                       │
│   /openspec:proposal   /openspec:apply      /openspec:archive              │
│                                                                             │
│   • すべての成果物を一度に作成                                          │
│   • 実装中に戻って仕様を更新できない                    │
│   • フェーズの関門が直線的な進行を強制                                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────────────────┐
│                            OPSX ワークフロー                                     │
│                      （柔軟なアクション、反復型）                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│              ┌────────────────────────────────────────────┐                 │
│              │           アクション（フェーズではない）             │                 │
│              │                                            │                 │
│              │   new ◄──► continue ◄──► apply ◄──► archive │                 │
│              │    │          │           │           │    │                 │
│              │    └──────────┴───────────┴───────────┘    │                 │
│              │              任意の順序                     │                 │
│              └────────────────────────────────────────────┘                 │
│                                                                             │
│   • 成果物を1つずつ作成、または一括作成                         │
│   • 実装中に specs/design/tasks を更新                        │
│   • 依存関係が進行を可能にし、フェーズは存在しない                       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

コンポーネントのアーキテクチャ

従来のワークフロー は TypeScript 内のハードコードされたテンプレートを使います。

┌─────────────────────────────────────────────────────────────────────────────┐
│                      従来のワークフローのコンポーネント                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ハードコードされたテンプレート（TypeScript の文字列）                                  │
│                    │                                                        │
│                    ▼                                                        │
│   ツール固有の設定処理/アダプター                                      │
│                    │                                                        │
│                    ▼                                                        │
│   生成されるコマンドファイル（.claude/commands/openspec/*.md）                  │
│                                                                             │
│   • 構成が固定され、成果物を認識しない                                  │
│   • 変更にはコードの修正と再ビルドが必要                             │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

OPSX は外部スキーマと依存関係グラフエンジンを使います。

┌─────────────────────────────────────────────────────────────────────────────┐
│                         OPSX のコンポーネント                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   スキーマ定義（YAML）                                                 │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  name: spec-driven                                                  │   │
│   │  artifacts:                                                         │   │
│   │    - id: proposal                                                   │   │
│   │      generates: proposal.md                                         │   │
│   │      requires: []              ◄── 依存関係                     │   │
│   │    - id: specs                                                      │   │
│   │      generates: specs/**/*.md  ◄── Glob パターン                    │   │
│   │      requires: [proposal]      ◄── proposal の後に作成可能           │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                    │                                                        │
│                    ▼                                                        │
│   成果物グラフエンジン                                                     │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  • トポロジカルソート（依存関係の順序付け）                           │   │
│   │  • 状態検出（ファイルシステム上の存在）                           │   │
│   │  • 詳細な指示の生成（テンプレート + コンテキスト）                │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                    │                                                        │
│                    ▼                                                        │
│   スキルファイル（.claude/skills/openspec-*/SKILL.md）                          │
│                                                                             │
│   • エディター横断で互換（Claude Code、Cursor、Devin）                    │
│   • スキルが構造化データを CLI に問い合わせる                                    │
│   • スキーマファイルで完全にカスタマイズ可能                                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

依存関係グラフモデル

成果物は有向非巡回グラフ（DAG）を形成します。依存関係は関門ではなく、進行を可能にするものです。

                              proposal
                             (ルートノード)
                                  │
                    ┌─────────────┴─────────────┐
                    │                           │
                    ▼                           ▼
                 specs                       design
              (必要:                       (必要:
               proposal)                   proposal)
                    │                           │
                    └─────────────┬─────────────┘
                                  │
                                  ▼
                               tasks
                           (必要:
                           specs, design)
                                  │
                                  ▼
                          ┌──────────────┐
                          │ 実装フェーズ │
                          │（必要:       │
                          │  tasks)      │
                          └──────────────┘

状態遷移:

   BLOCKED ────────────────► READY ────────────────► DONE
      │                        │                       │
   依存関係が不足             すべての依存先が        ファイルが
                             完了                   存在する

情報の流れ

従来のワークフロー — エージェントは静的な指示を受け取ります。

  ユーザー: "/openspec:proposal"
           │
           ▼
  ┌─────────────────────────────────────────┐
  │  静的な指示:                            │
  │  • proposal.md を作成                    │
  │  • tasks.md を作成                       │
  │  • design.md を作成                      │
  │  • 差分仕様ファイルを作成                │
  │                                         │
  │  何が存在するか、成果物間の依存関係を    │
  │  認識しない                              │
  └─────────────────────────────────────────┘
           │
           ▼
  エージェントがすべての成果物を一度に作成

OPSX — エージェントが詳細なコンテキストを問い合わせます。

  ユーザー: "/opsx:continue"
           │
           ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  手順1: 現在の状態を問い合わせる                                        │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │  $ openspec status --change "add-auth" --json                      │  │
  │  │                                                                    │  │
  │  │  {                                                                 │  │
  │  │    "artifacts": [                                                  │  │
  │  │      {"id": "proposal", "status": "done"},                         │  │
  │    │      {"id": "specs", "status": "ready"},      ◄── 最初の ready      │  │
  │  │      {"id": "design", "status": "ready"},                          │  │
  │  │      {"id": "tasks", "status": "blocked",                          │  │
  │  │       "missingDeps": ["specs", "design"]}                          │  │
  │  │    ]                                                               │  │
  │  │  }                                                                 │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  │                                                                          │
  │  手順2: 準備できた成果物の詳細な指示を取得                              │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │  $ openspec instructions specs --change "add-auth" --json          │  │
  │  │                                                                    │  │
  │  │  {                                                                 │  │
  │  │    "template": "# Specification\n\n## ADDED Requirements...",      │  │
  │  │    "dependencies": [{"id": "proposal", "path": "...", "done": true}│  │
  │  │    "unlocks": ["tasks"]                                            │  │
  │  │  }                                                                 │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  │                                                                          │
  │  手順3: 依存先を読む → 成果物を1つ作成 → 次に可能な作業を表示            │
  └──────────────────────────────────────────────────────────────────────────┘

反復モデル

従来のワークフロー — 反復しにくい:

  ┌─────────┐     ┌─────────┐     ┌─────────┐
  │/proposal│ ──► │ /apply  │ ──► │/archive │
  └─────────┘     └─────────┘     └─────────┘
       │               │
       │               ├── 「待って、設計が間違っている」
       │               │
       │               ├── 選択肢:
       │               │   • 手動でファイルを編集（文脈が失われる）
       │               │   • 破棄して最初からやり直す
       │               │   • そのまま進めて後で修正
       │               │
       │               └── 正式な「前に戻る」仕組みがない
       │
       └── すべての成果物を一度に作成

OPSX — 自然に反復できる:

  /opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
      │                │                  │
      │                │                  ├── 「設計が間違っている」
      │                │                  │
      │                │                  ▼
      │                │            design.md を編集するだけで
      │                │            続けられる
      │                │                  │
      │                │                  ▼
      │                │         /opsx:apply が中断した
      │                │         場所から再開
      │                │
      │                └── 成果物を1つ作成し、次に可能な作業を表示
      │
      └── change のひな型を作成し、次の指示を待つ

カスタムスキーマ

スキーマ管理コマンドを使って、カスタムワークフローを作成します。

# スキーマを新規作成（対話形式）
openspec schema init my-workflow

# または既存のスキーマをフォークして開始
openspec schema fork spec-driven my-workflow

# スキーマの構成を検証
openspec schema validate my-workflow

# スキーマの解決元を表示（デバッグに便利）
openspec schema which my-workflow

スキーマは openspec/schemas/（プロジェクトローカル、バージョン管理対象）または ~/.local/share/openspec/schemas/（ユーザーのグローバル領域）に保存されます。

スキーマの構成:

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

schema.yaml の例:

name: research-first
artifacts:
  - id: research        # proposal より前に追加
    generates: research.md
    requires: []

  - id: proposal
    generates: proposal.md
    requires: [research]  # research に依存

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

依存関係グラフ:

   research ──► proposal ──► tasks

まとめ

項目	従来方式	OPSX
テンプレート	TypeScript にハードコード	外部の YAML + Markdown
依存関係	なし（一括作成）	トポロジカルソートを使う DAG
状態	フェーズベースの考え方	ファイルシステム上の存在
カスタマイズ	ソースを編集して再ビルド	schema.yaml を作成
反復	フェーズ固定	柔軟で、何でも編集可能
エディター対応	ツール固有の設定処理/アダプター	単一のスキルディレクトリ

スキーマ

スキーマは、成果物とその依存関係を定義します。現在、次のスキーマが利用できます。

• spec-driven（既定）: proposal → specs → design → tasks

# 利用可能なスキーマを一覧表示
openspec schemas

# 解決元を含めてすべてのスキーマを表示
openspec schema which --all

# 対話形式でスキーマを新規作成
openspec schema init my-workflow

# カスタマイズ用に既存スキーマをフォーク
openspec schema fork spec-driven my-workflow

# 使用前にスキーマの構成を検証
openspec schema validate my-workflow

ヒント

• change に着手する前にアイデアを検討するには /opsx:explore を使う
• 実現したいことが明確なら /opsx:ff、調査しながら進めるなら /opsx:continue
• /opsx:apply 中に問題があれば、成果物を修正してから続行する
• tasks.md のチェックボックスでタスクの進捗を追跡する
• openspec status --change "name" でいつでも状態を確認する

フィードバック

これはまだ発展途上です。何がうまくいくかを学ぶため、意図的にそうしています。

バグを見つけたりアイデアがあったりする場合は、Discord に参加するか、GitHub で Issue を作成してください。