OPSX Workflow
Discord でのフィードバックをお待ちしております。
概要
OPSX は現在、OpenSpec の標準ワークフローです。
OpenSpec の変更のための柔軟で反復的なワークフローです。厳格なフェーズはもうありません — いつでも実行できるアクションだけがあります。
なぜ存在するのか
レガシーな OpenSpec ワークフローは機能しますが、制約が多すぎます：
- 命令がハードコードされている — TypeScript に埋め込まれているため変更できない
- all-or-nothing — 1つの大きなコマンドですべてを作成するため、個別のパーツをテストできない
- 固定構造 — 全員が同じワークフローを使用するため、カスタマイズできない
- ブラックボックス — AI の出力が悪い場合、プロンプトを調整できない
OPSX はこれを開放します。 誰でも以下のことができるようになります：
- 命令を実験する — テンプレートを編集し、AI の動作が改善されるか確認する
- 細かくテストする — 各アーティファクトの命令を個別に検証する
- ワークフローをカスタマイズする — 独自のアーティファクトと依存関係を定義する
- 迅速に反復する — テンプレートを変更し、すぐにテストする。再ビルド不要
レガシーワークフロー: OPSX:
┌────────────────────────┐ ┌────────────────────────┐
│ Hardcoded in package │ │ schema.yaml │◄── あなたが編集する
│ (can't change) │ │ templates/*.md │◄── またはこれ
│ ↓ │ │ ↓ │
│ Wait for new release │ │ Instant effect │
│ ↓ │ │ ↓ │
│ Hope it's better │ │ Test it yourself │
└────────────────────────┘ └────────────────────────┘対象ユーザー：
- チーム — 実際の業務に合わせたワークフローを作成
- パワーユーザー — プロンプトを調整して、コードベースに対する AI の出力を改善
- OpenSpec コントリビューター — リリースなしに新しいアプローチを実験
私たちはまだ何が最適か学んでいる段階です。OPSX は一緒に学ぶことを可能にします。
ユーザーエクスペリエンス
線形ワークフローの問題点： 「計画フェーズ」→「実装フェーズ」→「完了」という流れですが、実際の業務はそうではありません。実装してみて設計が間違っていたと気づき、仕様を更新し、再び実装する。線形フェーズは実際の業務の進め方に反しています。
OPSX のアプローチ：
- フェーズではなくアクション — 作成、実装、更新、アーカイブ — いつでも任意のアクションを実行可能
- 依存関係はイネーブラー — 次に何が必要かを示すのではなく、何が可能かを示す
proposal ──→ specs ──→ design ──→ tasks ──→ implementセットアップ
bash
# openspec がインストールされていることを確認してください — スキルは自動生成されます
openspec initこれにより .claude/skills/（または同等のディレクトリ）にスキルが作成され、AI コーディングアシスタントが自動検出します。
デフォルトでは、OpenSpec は core ワークフロープロファイル（propose、explore、apply、sync、archive）を使用します。拡張ワークフローコマンド（new、continue、ff、verify、bulk-archive、onboard）を使用したい場合は、openspec config profile で設定し、openspec update で適用してください。
セットアップ中にプロジェクト設定（openspec/config.yaml）の作成を求められます。これは任意ですが推奨されます。
プロジェクト設定
プロジェクト設定により、デフォルト値を設定し、すべてのアーティファクトにプロジェクト固有のコンテキストを注入できます。
設定の作成
設定は openspec init 中に作成されるか、手動で作成できます：
yaml
# openspec/config.yaml
schema: spec-driven
context: |
Tech stack: TypeScript, React, Node.js
API conventions: RESTful, JSON responses
Testing: Vitest for unit tests, Playwright for e2e
Style: ESLint with Prettier, strict TypeScript
rules:
proposal:
- Include rollback plan
- Identify affected teams
specs:
- Use Given/When/Then format for scenarios
design:
- Include sequence diagrams for complex flows設定フィールド
| フィールド | 型 | 説明 |
|---|---|---|
schema | string | 新しい変更のデフォルトスキーマ（例: spec-driven） |
context | string | すべてのアーティファクトの命令に注入されるプロジェクトコンテキスト |
rules | object | アーティファクト ID をキーとした、アーティファクトごとのルール |
仕組み
スキーマの優先順位（高い順）：
- CLI フラグ（
--schema <name>） - 変更メタデータ（変更ディレクトリ内の
.openspec.yaml） - プロジェクト設定（
openspec/config.yaml） - デフォルト（
spec-driven）
コンテキスト注入：
- コンテキストは各アーティファクトの命令の先頭に付加される
<context>...</context>タグで囲まれる- AI がプロジェクトの規約を理解するのに役立つ
ルール注入：
- ルールは一致するアーティファクトにのみ注入される
<rules>...</rules>タグで囲まれる- コンテキストの後、テンプレートの前に表示される
スキーマ別アーティファクト ID
spec-driven（デフォルト）：
proposal— 変更提案specs— 仕様書design— 技術設計tasks— 実装タスク
設定の検証
rules内の不明なアーティファクト ID は警告を生成する- スキーマ名は利用可能なスキーマに対して検証される
- コンテキストは 50KB のサイズ制限がある
- 無効な YAML は行番号とともに報告される
トラブルシューティング
"Unknown artifact ID in rules: X"
- アーティファクト ID がスキーマと一致しているか確認してください（上記のリストを参照）
openspec schemas --jsonを実行して、各スキーマのアーティファクト ID を確認してください
設定が適用されない：
- ファイルが
openspec/config.yamlにあることを確認してください（.ymlではない） - バリデーターで YAML 構文を確認してください
- 設定の変更は即座に反映されます（再起動不要）
コンテキストが大きすぎる：
- コンテキストは 50KB に制限されています
- 要約するか、外部ドキュメントへのリンクを使用してください
コマンド
| コマンド | 説明 |
|---|---|
/opsx:propose | 変更を作成し、計画アーティファクトを1ステップで生成（デフォルトのクイックパス） |
/opsx:explore | アイデアを検討し、問題を調査し、要件を明確化 |
/opsx:new | 新しい変更スキャフォールドを開始（拡張ワークフロー） |
/opsx:continue | 次のアーティファクトを作成（拡張ワークフロー） |
/opsx:ff | 計画アーティファクトをファストフォワード（拡張ワークフロー） |
/opsx:apply | タスクを実装し、必要に応じてアーティファクトを更新 |
/opsx:update | 変更の計画アーティファクトを改訂し、整合性を維持 |
/opsx:verify | アーティファクトに対する実装を検証（拡張ワークフロー） |
/opsx:sync | 差分仕様をメインに同期（デフォルトワークフロー、任意） |
/opsx:archive | 完了時にアーカイブ |
/opsx:bulk-archive | 複数の完了した変更をアーカイブ（拡張ワークフロー） |
/opsx:onboard | エンドツーエンドの変更のガイド付きウォークスルー（拡張ワークフロー） |
使用方法
アイデアを検討する
/opsx:exploreアイデアを検討し、問題を調査し、選択肢を比較します。構造は不要です — 思考パートナーとして機能します。洞察が固まったら、/opsx:propose（デフォルト）または /opsx:new//opsx:ff（拡張）に移行してください。
新しい変更を開始する
/opsx:propose変更を作成し、実装前に必要な計画アーティファクトを生成します。
拡張ワークフローを有効にしている場合は、代わりに以下を使用できます：
text
/opsx:new # スキャフォールドのみ
/opsx:continue # 1つのアーティファクトずつ作成
/opsx:ff # すべての計画アーティファクトを一度に作成アーティファクトを作成する
/opsx:continue依存関係に基づいて作成可能なものを表示し、1つのアーティファクトを作成します。変更を徐々に構築するために繰り返し使用してください。
/opsx:ff add-dark-modeすべての計画アーティファクトを一度に作成します。構築するものが明確に把握できている場合に使用してください。
実装（流動的な部分）
/opsx:applyタールを実行し、チェックオフしていきます。複数の変更を並行処理している場合は /opsx:apply <name> を実行できます。それ以外の場合は会話から推論し、判断できない場合は選択を求められます。
変更の更新
/opsx:update add-dark-mode - we're storing the theme in a cookie now変更の既存の計画アーティファクトを改訂し、整合性を維持します — どの方向にも（設計の編集が提案に波及する可能性があります）。計画アーティファクトのみ：コードを編集することはなく、不足しているアーティファクトを作成することもありません（それは /opsx:continue の役割です）。すべての編集は最初にあなたに確認されます。変更がすでに実装されている場合、改訂された計画にコードが追いつくよう /opsx:apply を推奨します。改訂が変更の意図を変える場合は、新規作成してください — 更新 vs 新規作成の判断を参照してください。
仕上げ
/opsx:archive # 完了時にアーカイブに移動（必要に応じて仕様の同期をプロンプト）更新 vs 新規作成の判断
実装前に提案や仕様を編集することはいつでも可能です。しかし、いつ「改良」が「これは別の作業」になるのでしょうか？
提案が捉える3つの要素
- 意図 — 何の問題を解決しているか？
- スコープ — 範囲内/範囲外は何か？
- アプローチ — どう解決するか？
問題は、どれが変化し、どの程度変化したかです。
既存の変更を更新する場合：
同じ意図、洗練された実行
- 考慮していなかったエッジケースを発見した
- アプローチの調整が必要だが目標は変わらない
- 実装により設計が少しずれていることが判明した
スコープの縮小
- フルスコープが大きすぎると判断し、MVP を先に出したい
- 「ダークモードを追加」→「ダークモードトグルを追加（v2 でシステム設定対応）」
学習に基づく修正
- コードベースの構造が想定と異なっていた
- 依存関係が想定通りに動作しなかった
- 「CSS 変数を使用」→「Tailwind の dark: プレフィックスを使用する」
新しい変更を開始する場合：
意図が根本的に変化
- 問題自体が変わった
- 「ダークモードを追加」→「カスタム色、フォント、余白を含む包括的なテーマシステムを追加」
スコープの爆発
- 変更が膨大になり、実質的に別の作業になった
- 元の提案は更新後も認識不能になる
- 「ログインバグを修正」→「認証システムを再構築」
元の変更が完了可能
- 元の変更を「完了」とマークできる
- 新しい作業は単独で成立し、改良ではない
- 「ダークモード MVP を追加」→アーカイブ→新規変更「ダークモードの強化」
判断基準
┌─────────────────────────────────────┐
│ これは同じ作業か？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
同じ意図？ 50%以上の重複？ 元の変更を
同じ問題？ 同じスコープ？ これらの変更なしに
│ │ 「完了」できるか？
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
はい いいえ はい いいえ いいえ はい
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
更新 新規 更新 新規 更新 新規| テスト | 更新 | 新規変更 |
|---|---|---|
| 同一性 | 「同じもの、洗練された」 | 「異なる作業」 |
| スコープの重複 | 50%以上重複 | 50%未満重複 |
| 完了可能性 | 変更なしでは「完了」できない | 元の変更を完了でき、新しい作業は単独で成立 |
| ストーリー | 更新チェーンが整合性のあるストーリーを語る | パッチを当てる方が混乱を招く |
原則
更新はコンテキストを保存する。新規変更は明確性を提供する。
思考の履歴が価値がある場合は更新を選択する。 新規作成の方がパッチを当てるより明確な場合は新規変更を選択する。
Git ブランチのように考えてください：
- 同じ機能の作業中はコミットを続ける
- genuinely に新しい作業の場合は新しいブランチを開始する
- 部分的に完成した機能をマージし、フェーズ2のために新規作成することもある
何が異なるか？
レガシー（/openspec:proposal） | OPSX（/opsx:*） | |
|---|---|---|
| 構造 | 1つの大きな提案ドキュメント | 依存関係を持つ個別のアーティファクト |
| ワークフロー | 線形フェーズ：計画 → 実装 → アーカイブ | 流動的なアクション — いつでも任意のアクションを実行可能 |
| 反復 | 戻るのが煩雑 | 学習に応じてアーティファクトを更新 |
| カスタマイズ | 固定構造 | スキーマ駆動（独自のアーティファクトを定義可能） |
重要な洞察： 作業は線形ではない。OPSX はそうではないふりをやめる。
アーキテクチャの詳細
このセクションでは、OPSX が内部でどのように動作するか、およびレガシーワークフローとの比較について説明します。このセクションの例では、拡張コマンドセット（new、continue など）を使用しています。デフォルトの core ユーザーは、同じフローを propose → apply → sync → archive にマッピングできます。
哲学: フェーズ vs アクション
┌─────────────────────────────────────────────────────────────────────────────┐
│ レガシーワークフロー │
│ （フェーズロック型、オールオアナッシング） │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 計画フェーズ│ ───► │ 実装フェーズ │ ───► │ アーカイブフェーズ│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ /openspec:proposal /openspec:apply /openspec:archive │
│ │
│ • すべての成果物を一度に作成 │
│ • 実装中に仕様を更新するために戻ることができない │
│ • フェーズゲートが線形の進行を強制 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX ワークフロー │
│ （流動的なアクション、反復的） │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ アクション（フェーズではない） │ │
│ │ │ │
│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
│ │ │ │ │ │ │ │
│ │ └──────────┴───────────┴───────────┘ │ │
│ │ 任意の順序 │ │
│ └────────────────────────────────────────────┘ │
│ │
│ • 成果物を一度に1つずつ作成するか、または高速転送 │
│ • 実装中に仕様/設計/タスクを更新可能 │
│ • 依存関係が進行を可能にし、フェーズは存在しない │
│ │
└─────────────────────────────────────────────────────────────────────────────┘コンポーネントアーキテクチャ
レガシーワークフロー は、TypeScript のハードコードされたテンプレートを使用します。
┌─────────────────────────────────────────────────────────────────────────────┐
│ レガシーワークフローのコンポーネント │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ハードコードされたテンプレート（TypeScript文字列） │
│ │ │
│ ▼ │
│ ツール固有のコンフィギュレータ/アダプタ │
│ │ │
│ ▼ │
│ 生成されたコマンドファイル（.claude/commands/openspec/*.md） │
│ │
│ • 固定構造、成果物の認識なし │
│ • 変更にはコード修正と再ビルドが必要 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘OPSX は、外部スキーマと依存関係グラフエンジンを使用します。
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX のコンポーネント │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ スキーマ定義（YAML） │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ name: spec-driven │ │
│ │ artifacts: │ │
│ │ - id: proposal │ │
│ │ generates: proposal.md │ │
│ │ requires: [] ◄── Dependencies │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── Glob patterns │ │
│ │ requires: [proposal] ◄── Enables after proposal │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 成果物グラフエンジン │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • トポロジカルソート（依存関係の順序付け） │ │
│ │ • 状態検出（ファイルシステムの存在確認） │ │
│ │ • リッチな命令生成（テンプレート + コンテキスト） │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ スキルファイル（.claude/skills/openspec-*/SKILL.md） │
│ │
│ • クロスエディタ互換（Claude Code、Cursor、Windsurf） │
│ • 構造化データ用のスキルクエリCLI │
│ • スキーマファイルによる完全なカスタマイズ可能 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘依存関係グラフモデル
成果物は有向非巡回グラフ（DAG）を形成します。依存関係はイネーブラーであり、ゲートではありません。
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)
│
▼
┌──────────────┐
│ 適用フェーズ │
│ (requires: │
│ tasks) │
└──────────────┘状態遷移:
ブロック済み ────────────────► 準備完了 ────────────────► 完了
│ │ │
欠落している すべての依存関係 ファイルシステムに
依存関係 が完了 ファイルが存在情報フロー
レガシーワークフロー — エージェントは静的な命令を受信します。
User: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ 静的な命令: │
│ • proposal.mdを作成 │
│ • tasks.mdを作成 │
│ • design.mdを作成 │
│ • specs/<capability>/spec.mdを作成 │
│ │
│ 成果物の存在や依存関係を │
│ 認識していない │
└─────────────────────────────────────────┘
│
▼
Agent creates ALL artifacts in one goOPSX — エージェントはリッチなコンテキストをクエリします。
User: "/opsx:continue"
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ ステップ1: 現在の状態をクエリ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec status --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "artifacts": [ │ │
│ │ {"id": "proposal", "status": "done"}, │ │
│ │ {"id": "specs", "status": "ready"}, ◄── First ready │ │
│ │ {"id": "design", "status": "ready"}, │ │
│ │ {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ステップ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つのアーティファクトを作成し、利用可能になった機能を表示します
│
└── 変更の骨格を作成し、指示を待ちますカスタムスキーマ
スキーマ管理コマンドを使用してカスタムワークフローを作成します：
bash
# Create a new schema from scratch (interactive)
openspec schema init my-workflow
# Or fork an existing schema as a starting point
openspec schema fork spec-driven my-workflow
# Validate your schema structure
openspec schema validate my-workflow
# See where a schema resolves from (useful for debugging)
openspec schema which my-workflowスキーマは openspec/schemas/（プロジェクトローカル、バージョン管理対象）または ~/.local/share/openspec/schemas/（ユーザーグローバル）に保存されます。
スキーマ構造：
openspec/schemas/research-first/
├── schema.yaml
└── templates/
├── research.md
├── proposal.md
└── tasks.mdschema.yaml の例：
yaml
name: research-first
artifacts:
- id: research # Added before proposal
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research] # Now depends on research
- id: tasks
generates: tasks.md
requires: [proposal]依存関係グラフ：
research ──► proposal ──► tasks概要
| 項目 | レガシー | OPSX |
|---|---|---|
| テンプレート | ハードコードされたTypeScript | 外部YAML + Markdown |
| 依存関係 | なし（一括作成） | トポロジカルソートによるDAG |
| 状態 | フェーズベースのメンタルモデル | ファイルシステムの存在 |
| カスタマイズ | ソースを編集して再ビルド | schema.yamlを作成 |
| イテレーション | フェーズ固定 | 柔軟に、どこでも編集可能 |
| エディタサポート | ツール固有のコンフィギュレータ/アダプタ | 単一のスキルディレクトリ |
スキーマ
スキーマは、存在するアーティファクトとその依存関係を定義します。現在利用可能なスキーマ：
- spec-driven (デフォルト): proposal → specs → design → tasks
bash
# List available schemas
openspec schemas
# See all schemas with their resolution sources
openspec schema which --all
# Create a new schema interactively
openspec schema init my-workflow
# Fork an existing schema for customization
openspec schema fork spec-driven my-workflow
# Validate schema structure before use
openspec schema validate my-workflowヒント
- 変更をコミットする前にアイデアを検討するには
/opsx:exploreを使用してください - やりたいことが決まっているときは
/opsx:ff、探索中のときは/opsx:continue /opsx:applyの実行中に問題がある場合は、アーティファクトを修正してから続行してください- タスクは
tasks.mdのチェックボックスで進捗を追跡します - いつでもステータスを確認:
openspec status --change "name"
フィードバック
これは初期段階です。意図的なものであり、何が機能するかを学んでいる最中です。