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セットアップ
# openspec がインストールされていることを確認してください — スキルは自動的に生成されます
openspec initこれにより、.claude/skills/（または同等のディレクトリ）にスキルが作成され、AI コーディングアシスタントが自動検出します。
デフォルトでは、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: |
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変更を作成し、実装に必要な計画アーティファクトを生成します。
拡張ワークフローを有効にしている場合は、代わりに以下を使用できます：
/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:sync現在のchangeのディルタ仕様を、アーカイブせずにメインの openspec/specs/ にマージします — 変更はアクティブなままです。ディルタ全体が適用されます：## REMOVED 下の要件はメイン仕様から削除され、名前が変更されたものはその場でタイトルが変更され、ディルタで言及されていないコンテンツはそのまま残されます。同期はオプションです — アーカイブ時に同期していない場合は最初に同期するように促されます。アーカイブする前にメイン仕様を更新したい場合、並行して進めている別の変更がこの変更が追加した仕様を基に構築する必要がある場合、またはアーカイブする前にマージされたメイン仕様を確認したい場合に使用します。
完了
/opsx:archive # 完了時にアーカイブへ移動（必要に応じて仕様の同期を促す）更新 vs 新規開始：いつどちらを使うべきか
実装の前に提案や仕様を編集することはいつでも可能です。しかし、 refining（洗練）がいつ「異なる作業」になるのでしょうか？
提案が捉えるもの
提案は以下の3つを定義します：
- 意図 — どのような問題を解決していますか？
- 範囲 — 何が含まれ、何が含まれないのか？
- アプローチ — どうやって解決しますか？
問われるのは：どれが変わったのか、そしてどの程度変わったのか？
既存の変更を更新する場合：
同じ意図、洗練された実行
- 考慮していなかったエッジケースを発見した
- アプローチの微調整が必要だが、目標は変わらない
- 実装を通じて設計が少しずれていたことが判明した
範囲が狭まる
- 全範囲が大きすぎると気づき、まずは MVP を出荷したい
- 「ダークモードを追加」 → 「ダークモードトグルを追加（v2でシステム設定）」
学習に基づく修正
- コードベースが想定していた構造ではない
- 依存関係が期待通りに動作しない
- 「CSS変数を使用」 → 「Tailwindの dark: プレフィックスを使用」
新しい変更を開始する場合：
意図が根本的に変更された
- 問題自体が今では異なっている
- 「ダークモードを追加」 → 「カスタムカラー、フォント、スペーシングを含む包括的なテーマシステムを追加」
範囲が爆発的に拡大した
- 変更が大きくなりすぎて、本質的に異なる作業となった
- 更新後には元の提案は認識不可能になる
- 「ログインバグを修正」 → 「認証システムを書き直す」
元の変更が完了可能である
- 元の変更を「完了」とマークできる
- 新しい作業は単独で成立し、 refinement ではない
- 「ダークモードMVPを追加」を完了 → アーカイブ → 新しい変更「ダークモードを強化」
ヒューリスティック
┌─────────────────────────────────────┐
│ これは同じ作業か？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
同じ意図？ >50% の重複？ 元の変更は
同じ問題？ 同じ範囲？ これらの変更なしで
│ │ 「完了」にできるか？
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
YES NO YES NO NO YES
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
UPDATE NEW UPDATE NEW UPDATE NEW| テスト | 更新 | 新規変更 |
|---|---|---|
| アイデンティティ | 「同じもの、洗練済み」 | 「異なる作業」 |
| 範囲の重複 | >50% が重複 | <50% が重複 |
| 完了性 | 変更なしでは「完了」にできない | 元の変更を終了でき、新しい作業は単独で成立 |
| ストーリー | 更新チェーンが一貫した物語を語る | パッチは曖昧さを増すばかりで明確さに欠ける |
原則
更新はコンテキストを保持する。新規変更は明確さを提供する。
あなたの思考の履歴が価値がある場合は更新を選択してください。 パッチを当てるよりも最初から始めた方が明確になる場合は新規変更を選択してください。
git ブランチのように考えてください：
- 同じ機能に取り組んでいる間はコミットを続ける
- 本質的に新しい作業の場合は新しいブランチを開始する
- 部分的な機能をマージしてフェーズ2のために最初から始めることもある
何が違いますか？
レガシー (/openspec:proposal) | OPSX (/opsx:*) | |
|---|---|---|
| 構造 | 1つの大きな提案ドキュメント | 依存関係を持つ個別の成果物 |
| ワークフロー | 線形フェーズ：計画 → 実装 → アーカイブ | 流動的なアクション — いつでも何でも実行可能 |
| 反復 | 戻るのが面倒 | 学習に応じて成果物を更新 |
| カスタマイズ | 固定された構造 | スキーマ駆動（独自の成果物を定義） |
重要なポイント： 作業は線形ではありません。OPSX はそれを装うことをやめました。
アーキテクチャの深掘り
このセクションでは、OPSXが内部でどのように動作するか、そして従来のワークフローとどのように比較されるかを説明します。このセクションの例では、拡張されたコマンドセット（new, continue など）を使用します。デフォルトのcoreユーザーは、同じフローをpropose → apply → sync → archiveにマッピングできます。
哲学: フェーズとアクション
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW │
│ (Phase-Locked, All-or-Nothing) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PLANNING │ ───► │ IMPLEMENTING │ ───► │ ARCHIVING │ │
│ │ PHASE │ │ PHASE │ │ PHASE │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ /openspec:proposal /openspec:apply /openspec:archive │
│ │
│ • Creates ALL artifacts at once │
│ • Can't go back to update specs during implementation │
│ • Phase gates enforce linear progression │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX WORKFLOW │
│ (Fluid Actions, Iterative) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ ACTIONS (not phases) │ │
│ │ │ │
│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
│ │ │ │ │ │ │ │
│ │ └──────────┴───────────┴───────────┘ │ │
│ │ any order │ │
│ └────────────────────────────────────────────┘ │
│ │
│ • Create artifacts one at a time OR fast-forward │
│ • Update specs/design/tasks during implementation │
│ • Dependencies enable progress, phases don't exist │
│ │
└─────────────────────────────────────────────────────────────────────────────┘コンポーネントアーキテクチャ
従来のワークフロー は、TypeScriptでハードコードされたテンプレートを使用します:
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Hardcoded Templates (TypeScript strings) │
│ │ │
│ ▼ │
│ Tool-specific configurators/adapters │
│ │ │
│ ▼ │
│ Generated Command Files (.claude/commands/openspec/*.md) │
│ │
│ • Fixed structure, no artifact awareness │
│ • Change requires code modification + rebuild │
│ │
└─────────────────────────────────────────────────────────────────────────────┘OPSX は外部スキーマと依存関係グラフエンジンを使用します:
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Schema Definitions (YAML) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ name: spec-driven │ │
│ │ artifacts: │ │
│ │ - id: proposal │ │
│ │ generates: proposal.md │ │
│ │ requires: [] ◄── Dependencies │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── Glob patterns │ │
│ │ requires: [proposal] ◄── Enables after proposal │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Artifact Graph Engine │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Topological sort (dependency ordering) │ │
│ │ • State detection (filesystem existence) │ │
│ │ • Rich instruction generation (templates + context) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Skill Files (.claude/skills/openspec-*/SKILL.md) │
│ │
│ • Cross-editor compatible (Claude Code, Cursor, Devin) │
│ • Skills query CLI for structured data │
│ • Fully customizable via schema files │
│ │
└─────────────────────────────────────────────────────────────────────────────┘依存関係グラフモデル
アーティファクトは、有向非巡回グラフ（DAG）を形成します。依存関係はイネーブラーであり、ゲートではありません:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)
│
▼
┌──────────────┐
│ APPLY PHASE │
│ (requires: │
│ tasks) │
└──────────────┘状態遷移:
BLOCKED ────────────────► READY ────────────────► DONE
│ │ │
Missing All deps File exists
dependencies are DONE on filesystem情報フロー
従来のワークフロー — エージェントは静的な指示を受け取ります:
User: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ Static instructions: │
│ • Create proposal.md │
│ • Create tasks.md │
│ • Create design.md │
│ • Create delta spec files │
│ │
│ No awareness of what exists or │
│ dependencies between artifacts │
└─────────────────────────────────────────┘
│
▼
Agent creates ALL artifacts in one goOPSX — エージェントはリッチなコンテキストを照会します:
User: "/opsx:continue"
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Step 1: Query current state │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ 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", "design"]} │ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 2: Get rich instructions for ready artifact │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# Specification\n\n## ADDED Requirements...", │ │
│ │ "dependencies": [{"id": "proposal", "path": "...", "done": true}│ │
│ │ "unlocks": ["tasks"] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 3: Read dependencies → Create ONE artifact → Show what's unlocked │
└──────────────────────────────────────────────────────────────────────────┘反復モデル
従来のワークフロー — 反復が厄介です:
┌─────────┐ ┌─────────┐ ┌─────────┐
│/proposal│ ──► │ /apply │ ──► │/archive │
└─────────┘ └─────────┘ └─────────┘
│ │
│ ├── "Wait, the design is wrong"
│ │
│ ├── Options:
│ │ • Edit files manually (breaks context)
│ │ • Abandon and start over
│ │ • Push through and fix later
│ │
│ └── No official "go back" mechanism
│
└── Creates ALL artifacts at onceOPSX — 自然な反復:
/opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
│ │ │
│ │ ├── "The design is wrong"
│ │ │
│ │ ▼
│ │ Just edit design.md
│ │ and continue!
│ │ │
│ │ ▼
│ │ /opsx:apply picks up
│ │ where you left off
│ │
│ └── Creates ONE artifact, shows what's unlocked
│
└── Scaffolds change, waits for directionカスタムスキーマ
スキーマ管理コマンドを使用してカスタムワークフローを作成します:
# 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.mdスキーマ.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
# 利用可能なスキーマを一覧表示
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"
フィードバック
これはまだ荒い状態です。これは意図的なことで、何が機能するかを学んでいる段階だからです。
バグを見つけましたか？アイデアがありますか？Discord で参加するか、GitHub でイシューをオープンしてください。