OPSXワークフロー
Discord でのフィードバックをお待ちしております。
これは何ですか？
OPSXは、OpenSpecの標準ワークフローとなりました。
これは、OpenSpecの変更に対する流動的で反復的なワークフローです。固定フェーズはもうありません。必要な時に実行できるアクションが揃っています。
なぜこれが存在するのか
レガシーなOpenSpecワークフローは機能しますが、固定されています：
- 指示がハードコードされている — TypeScriptに埋め込まれており、変更できません
- 全か無か — 1つの大きなコマンドで全てを作成し、個別にテストできません
- 固定された構造 — 誰もが同じワークフローを使用し、カスタマイズできません
- ブラックボックス — AIの出力が悪い場合、プロンプトを調整できません
OPSXはそれを解放します。 これで誰もが：
- 指示を実験できる — テンプレートを編集し、AIがより良く動作するか確認できる
- 粒度を細かくテストできる — 各成果物の指示を独立して検証できる
- ワークフローをカスタマイズできる — 独自の成果物と依存関係を定義できる
- 素早く反復できる — テンプレートを変更し、即座にテストし、再ビルドなし
レガシーなワークフロー: OPSX:
┌────────────────────────┐ ┌────────────────────────┐
│ パッケージにハードコード │ │ schema.yaml │◄── これを編集
│ （変更不可） │ │ templates/*.md │◄── またはこれ
│ ↓ │ │ ↓ │
│ 新しいリリースを待つ │ │ 即座に効果が現れる │
│ ↓ │ │ ↓ │
│ 改善されることを願う │ │ 自分でテストする │
└────────────────────────┘ └────────────────────────┘これは誰のためのものか：
- チーム — 実際の作業方法に合ったワークフローを作成
- パワーユーザー — プロンプトを調整して、コードベースに最適なAI出力を得る
- OpenSpec貢献者 — リリースなしで新しいアプローチを実験
私たちは皆、何が最適かを学び続けています。OPSXはそれを共に学ぶことを可能にします。
ユーザーエクスペリエンス
リニアなワークフローの問題： 「計画フェーズ」にいて、次に「実装フェーズ」、そして「完了」。しかし、実際の作業はそうではありません。何かを実装し、設計が間違っていたことに気づき、仕様を更新し、実装を続ける必要があります。リニアなフェーズは、実際の作業の進め方と矛盾します。
OPSXのアプローチ：
- フェーズではなくアクション — 作成、実装、更新、アーカイブ — いつでも好きなものを行える
- 依存関係は促進要因 — 次に何が必要かではなく、何が可能かを示す
proposal ──→ specs ──→ design ──→ tasks ──→ implementセットアップ
bash
# openspecがインストールされていることを確認 — スキルは自動生成されます
openspec initこれにより、.claude/skills/（または同等の場所）にAIコーディングアシスタントが自動検出するスキルが作成されます。
デフォルトでは、OpenSpecはcoreワークフロープロファイル（propose、explore、apply、archive）を使用します。拡張されたワークフローコマンド（new、continue、ff、verify、sync、bulk-archive、onboard）を使用したい場合は、openspec config profileで設定し、openspec updateで適用します。
セットアップ中、プロジェクト設定（openspec/config.yaml）の作成を求められます。これはオプションですが、推奨されます。
プロジェクト設定
プロジェクト設定により、デフォルトを設定し、すべての成果物にプロジェクト固有のコンテキストを注入できます。
設定の作成
設定はopenspec init中に作成されるか、手動で作成します：
yaml
# openspec/config.yaml
schema: spec-driven
context: |
技術スタック: TypeScript, React, Node.js
API規約: RESTful, JSONレスポンス
テスト: Vitest（単体テスト）、Playwright（E2E）
スタイル: ESLint + Prettier、厳格なTypeScript
rules:
proposal:
- ロールバック計画を含める
- 影響を受けるチームを特定する
specs:
- シナリオにGiven/When/Then形式を使用する
design:
- 複雑なフローにはシーケンス図を含める設定フィールド
| フィールド | 型 | 説明 |
|---|---|---|
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: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つの成果物を1回ずつ作成
/opsx:ff # すべての計画成果物を一度に作成成果物を作成する
/opsx:continue依存関係に基づいて作成可能なものを表示し、1つの成果物を作成。繰り返し使用して、変更を段階的に構築。
/opsx:ff add-dark-modeすべての計画成果物を一度に作成。構築するものが明確にわかっている場合に使用。
実装する（流動的な部分）
/opsx:applyタスクを処理し、完了ごとにチェック。複数の変更を同時に処理している場合は/opsx:apply <name>を実行可能。そうでない場合は、会話から推測し、判断できない場合は選択を促す。
完了する
/opsx:archive # 完了時にアーカイブに移動（必要に応じて仕様の同期を促す）更新するか、新しく始めるか
実装前は常に提案や仕様を編集できます。しかし、いつ改善が「異なる作業」になるのでしょうか？
提案が捉えるもの
提案は3つのことを定義します：
- 意図 — 何の問題を解決していますか？
- 範囲 — 何が含まれ、何が含まれないか？
- アプローチ — どのように解決しますか？
問題は：何が変わり、どれくらい変わったかです。
既存の変更を更新する場合：
同じ意図、改善された実装
- 考慮していなかったエッジケースを発見
- アプローチの微調整が必要だが、目標は変更なし
- 実装により設計が少し間違っていたことが判明
範囲が狭まる
- 完全な範囲は大きすぎ、まずMVPを出荷したい
- 「ダークモードを追加」→「ダークモード切り替えを追加（v2でシステム設定を使用）」
学習に基づく修正
- コードベースが想定通りに構成されていない
- 依存関係が期待通りに機能しない
- 「CSS変数を使用」→「代わりにTailwindのdark:プレフィックスを使用」
新しい変更を開始する場合：
意図が根本的に変わった
- 問題自体が異なる
- 「ダークモードを追加」→「カスタムカラー、フォント、間隔を含む包括的なテーマシステムを追加」
範囲が爆発的に拡大
- 変更が大きくなり、本質的に異なる作業になった
- 元の提案は更新後も認識できない
- 「ログインバグを修正」→「認証システムを書き直す」
元の変更が完了可能
- 元の変更を「完了」とマークできる
- 新しい作業は独立しており、改善ではない
- 「ダークモードMVPを追加」を完了 → アーカイブ → 新しい変更「ダークモードを強化」
ヒューリスティック
┌─────────────────────────────────────┐
│ これは同じ作業か？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
同じ意図？ 50%以上重複？ 元の変更は
同じ問題？ 同じ範囲？ これらなしで
│ │ 「完了」にできるか？
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
はい いいえ はい いいえ いいえ はい
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
更新 新規 更新 新規 更新 新規| テスト | 更新 | 新しい変更 |
|---|---|---|
| 同一性 | 「同じもの、改善版」 | 「異なる作業」 |
| 範囲の重複 | 50%以上重複 | 50%未満重複 |
| 完了 | 変更なしでは「完了」できない | 元の変更を完了でき、新しい作は独立している |
| ストーリー | 更新チェーンが一貫した物語を語る | パッチは混乱を招く |
原則
更新はコンテキストを保持する。新しい変更は明確さを提供する。
思考の履歴が価値がある場合は更新を選択。 パッチよりも新しく始める方が明確な場合は新規を選択。
gitブランチのように考える：
- 同じ機能に取り組んでいる間はコミットを続ける
- 本質的に新しい作業の場合は新しいブランチを開始
- 時には部分的な機能をマージし、フェーズ2のために新しく始める
何が異なるのか？
レガシー (/openspec:proposal) | OPSX (/opsx:*) | |
|---|---|---|
| 構造 | 1つの大きな提案ドキュメント | 依存関係を持つ個別のアーティファクト |
| ワークフロー | 線形フェーズ：計画 → 実装 → アーカイブ | 流動的なアクション — いつでも何でも実行可能 |
| イテレーション | 戻るのが困難 | 学びに応じてアーティファクトを更新 |
| カスタマイズ | 固定構造 | スキーマ駆動（独自のアーティファクトを定義可能） |
重要な洞察： 作業は線形ではありません。OPSXはそうであるかのように振る舞うことをやめます。
アーキテクチャ深掘り
このセクションでは、OPSXが内部でどのように機能するか、そしてレガシーワークフローとどのように比較されるかを説明します。 このセクションの例では拡張コマンドセット（new、continueなど）を使用しています。デフォルトのcoreユーザーは、同じフローをpropose → apply → 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: [] ◄── 依存関係 │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── グロブパターン │ │
│ │ requires: [proposal] ◄── proposal後に有効化 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 成果物グラフエンジン │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • 位相ソート（依存関係の順序付け） │ │
│ │ • 状態検出（ファイルシステムの存在） │ │
│ │ • 豊富な指示生成（テンプレート＋コンテキスト） │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ スキルファイル（.claude/skills/openspec-*/SKILL.md） │
│ │
│ • クロスエディタ互換（Claude Code、Cursor、Windsurf） │
│ • スキルがCLIをクエリして構造化データを取得 │
│ • スキーマファイルで完全にカスタマイズ可能 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘依存関係グラフモデル
成果物は有向非巡回グラフ（DAG）を形成します。依存関係はゲートではなく有効化要件です：
proposal
（ルートノード）
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
（requires: （requires:
proposal） proposal）
│ │
└─────────────┬─────────────┘
│
▼
tasks
（requires:
specs, design）
│
▼
┌──────────────┐
│ APPLY フェーズ │
│ （requires: │
│ tasks） │
└──────────────┘状態遷移：
BLOCKED ────────────────► READY ────────────────► DONE
│ │ │
依存関係が不足 すべての依存関係 ファイルが
がDONE ファイルシステムに存在情報フロー
レガシーワークフロー — エージェントは静的な指示を受け取る：
ユーザー: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ 静的な指示： │
│ • proposal.mdを作成 │
│ • tasks.mdを作成 │
│ • design.mdを作成 │
│ • specs/<capability>/spec.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"]}│ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ステップ2: readyな成果物の豊富な指示を取得 │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# 仕様\n\n## 追加された要件...", │ │
│ │ "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
# 新しいスキーマをゼロから作成（対話式）
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：
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（デフォルト）：提案 → 仕様 → 設計 → タスク
bash
# 利用可能なスキーマを一覧表示
openspec schemas
# すべてのスキーマとその解決ソースを表示
openspec schema which --all
# 対話的に新しいスキーマを作成
openspec schema init my-workflow
# 既存のスキーマをフォークしてカスタマイズ
openspec schema fork spec-driven my-workflow
# 使用前にスキーマの構造を検証
openspec schema validate my-workflowヒント
- 変更を適用する前に、
/opsx:exploreを使ってアイデアを練りましょう - 目的が決まっている場合は
/opsx:ff、探索中は/opsx:continueを使用します /opsx:applyの実行中に問題が発生した場合は、アーティファクトを修正してから続行してください- タスクの進捗は
tasks.md内のチェックボックスで追跡します - ステータスはいつでも確認できます：
openspec status --change "name"
フィードバック
これはまだ粗削りです。意図的なもので、何が機能するかを学んでいる段階です。