ワークフロー
このガイドでは、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を参照してください。
2つのモード
デフォルトのクイックパス（coreプロファイル）
新規インストールではcoreがデフォルトとなり、以下の機能を提供します。
/opsx:explore/opsx:propose/opsx:apply/opsx:sync/opsx:archive
一般的なフロー：
text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
(オプション)まず探索から始める（身につけるべき習慣）
/opsx:exploreは高度なアドオンではなく、デフォルトプロファイルの一部です。これは、問題はあるもののまだ計画がない場合に取るべき行動であり、AIアシスタントがいる現代ではほとんどの場合に該当します。
text
You: /opsx:explore
AI: 何を探索したいですか？
You: 検索結果が陳腐に感じます。キャッシュの問題なのか、インデックスの問題なのか、それともクエリ自体に問題があるのか確信が持てません。
AI: 確認してみましょう... [検索サービスとキャッシュレイヤーを読み込む]
原因はインデックスです。これは夜間に一度だけ再構築されるため、編集内容は翌日まで表示されません。2つの選択肢があります。書き込み時に再構築する（シンプルだが負荷大）か、短いTTLのキャッシュ無効化を行う（要素が多くなるが負荷小）。書き込み量が少ないことを考慮すると、書き込み時再構築がよりクリーンな解決策です。スコープを絞りますか？
You: はい。
You: /opsx:propose rebuild-search-index-on-writeExploreはアーティファクトを作成せず、コードも一切書きません。これは漠然とした懸念を正確な変更へと変えるための無料のノーリスクな会話であり、その結果として続く提案が明確になります。すでに何が欲しいか完全に分かっている場合は、これをスキップして/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: openspec/changes/add-logout-button/ を作成しました。
提案の作成準備ができています。
You: /opsx:ff
AI: すべての計画アーティファクトを作成中...
✓ proposal.md
✓ specs/
✓ design.md
✓ tasks.md
実装の準備ができました！
You: /opsx:apply
AI: タスクを実行中です...
✓ ヘッダーへのログアウトボタン追加
✓ セッションクリアの実装
✓ 確認ダイアログの追加
すべてのタスクが完了しました！
You: /opsx:archive
AI: ✓ 仕様書のマージ
✓ 変更のアーカイブ最適な用途: 小〜中規模のフィーチャー、バグ修正、単純な変更。
探索的（Exploratory）
要件が不明確であるか、まず調査する必要がある場合：
text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply会話例:
text
You: /opsx:explore
AI: 何を探索したいですか？
You: ページロードのパフォーマンスを改善したいのですが、どこにボトルネックがあるのか分かりません。
AI: 調査をお手伝いします...
[バンドルサイズを分析し、遅いクエリを特定し、コンポーネントのレンダリングパターンを確認]
3つの主なボトルネックを発見しました：
1. 大量の最適化されていない画像
2. ProductListにおける同期的なデータ取得
3. コンテキスト変更による再レンダリング
どれから対処しますか？
You: データ取得の問題に対処しましょう。
You: /opsx:new optimize-product-list-fetching
AI: 変更を作成しました。提案の作成準備ができています。
You: /opsx:continue
AI: 調査結果に基づいた提案書の作成中...
[調査結果を取り入れた提案書を記述]
仕様、デザインの作成準備ができました。次に何をしますか？
You: /opsx:continue
AI: 仕様書の作成中...最適な用途: パフォーマンス最適化、デバッグ、アーキテクチャ設計、不明確な要件。
並行作業（Parallel Changes）
複数の変更を同時に進める場合：
text
Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (進行中)
│
コンテキストスイッチ
│
Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply会話例:
text
You: add-dark-modeに取り組んでいますが、バグ修正に割り込まれました。
You: /opsx:new fix-login-redirect
AI: openspec/changes/fix-login-redirect/ を作成しました。
You: /opsx:ff
AI: ✓ 計画アーティファクトを作成しました。
You: /opsx:apply
AI: fix-login-redirectに取り組んでいます...
[修正を実装]
すべてのタスクが完了しました！
You: /opsx:archive
AI: ✓ fix-login-redirect をアーカイブ
You: ダークモードに戻りましょう。
You: /opsx:apply add-dark-mode
AI: add-dark-mode の再開...
タスク2.3：ヘッダーの更新から再開...最適な用途: 並行する作業ストリーム、緊急割り込み、チームコラボレーション。
完了した複数の変更がある場合は、/opsx:bulk-archiveを使用します。
text
You: /opsx:bulk-archive
AI: 3つの完了済み変更が見つかりました：
- add-dark-mode (すべてのタスクが完了)
- fix-login-redirect (すべてのタスクが完了)
- update-footer (すべてのタスクが完了)
仕様の競合を確認中...
⚠ add-dark-mode と update-footer の両方が specs/ui/ に影響を与えています。
解決のためにコードベースを検査中...
両方の変更は実装されています。時系列順に適用します。
3つの変更すべてをアーカイブしますか？
You: はい
AI: ✓ add-dark-mode をアーカイブ
✓ fix-login-redirect をアーカイブ
✓ update-footer をアーカイブ
仕様書は順番にマージされました：add-dark-mode → update-footerBulk archiveは、複数の変更が同じ仕様に影響を与えていることを検知し、実際に何が実装されているかをチェックすることで競合を解決します。
変更の完了
推奨される完了フロー：
text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
│ │
検証 同期を促す
実装の確認 必要な場合Verify（検証）：作業のチェック
/opsx:verifyは、3つの側面からアーティファクトに対する実装を検証します。
text
You: /opsx:verify
AI: add-auth の検証中...
完全性 (COMPLETENESS)
✓ tasks.md にある12個のタスクすべてがチェック済み
✓ 仕様書にあるすべての要件に対応するコードが存在します
⚠ 「非アクティブ状態でのセッションタイムアウト」シナリオはテストされていません
正確性 (CORRECTNESS)
✓ 実装が仕様の意図と一致しています
✓ シナリオからのエッジケースが処理されています
✓ エラー状態が仕様定義と一致しています
一貫性 (COHERENCE)
✓ デザイン上の決定事項がコード構造に反映されています
✓ 命名規則がdesign.mdと一貫しています
⚠ デザインでは「イベント駆動」を言及していますが、実装はポーリングを使用しています
サマリー (SUMMARY)
─────────────────────────────
重大な問題: 0
警告: 2
アーカイブ可能か: はい（警告あり）
推奨事項：
1. セッションタイムアウトシナリオのテストを追加すること
2. 設計通りイベント駆動へのリファクタリングを検討するか、design.mdを更新することVerifyがチェックするもの:
| 側面 | 検証内容 |
|---|---|
| 完全性 (Completeness) | すべてのタスク完了、すべての要件実装済み、シナリオカバー済み |
| 正確性 (Correctness) | 実装が仕様の意図と一致、エッジケースを処理済み |
| 一貫性 (Coherence) | デザイン上の決定事項がコードに反映、パターンが一貫している |
Verifyはアーカイブをブロックしませんが、先に解決したい可能性のある問題を表面化させます。
Archive（アーカイブ）：変更の確定
/opsx:archiveは変更を完了し、アーカイブに移動させます。
text
You: /opsx:archive
AI: add-auth のアーカイブ中...
アーティファクトの状態：
✓ proposal.md が存在します
✓ specs/ が存在します
✓ design.md が存在します
✓ tasks.md が存在します（12/12タスク完了）
仕様書のデルタ: まだメインに同期されていません
→ 今すぐ同期しますか？
You: はい
AI: ✓ openspec/specs/auth/spec.md に仕様書を同期しました
✓ openspec/changes/archive/2025-01-24-add-auth/ へ移動しました
変更は正常にアーカイブされました。Archiveは、仕様が同期されていない場合にプロンプトを表示します。未完了のタスクでブロックすることはありませんが、警告を発します。
どちらを使うべきか
/opsx:ff vs /opsx:continue
| 状況 | 使用するもの |
|---|---|
| 要件が明確で、構築準備ができている | /opsx:ff |
| 探索しており、各ステップを確認したい場合 | /opsx:continue |
| 仕様書作成前に提案を反復させたい場合 | /opsx:continue |
| 時間的制約があり、迅速に進めたい場合 | /opsx:ff |
| 複雑な変更で、コントロールを握りたい場合 | /opsx:continue |
経験則: 全体のスコープを事前に説明できる場合は/opsx:ffを使用します。進めながら解決策を見つけている場合は/opsx:continueを使用します。
更新するべきか、ゼロから始めるべきか
よくある質問：既存の変更を更新するのはいつで、新しいものを開始すべきですか？
既存の変更を更新する場合:
- 意図は同じだが実行方法を洗練させた場合
- スコープが絞られた場合（MVPを先に作り、残りは後で対応）
- 学習に基づいた修正（コードベースが期待通りではなかった場合）
- 実装上の発見に基づくデザインの調整
新しい変更を開始する場合:
- 意図が根本的に変わった場合
- スコープが完全に異なる作業にまで肥大化した場合
- 元の変更を単独で「完了」とマークできる場合
- パッチが明確にするよりも混乱させる可能性が高い場合
text
┌─────────────────────────────────────┐
│ これは同じ作業ですか？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
同じ意図か? >50%の重複があるか? 元の変更がこれらの変更なしで「完了」できるか?
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
YES NO YES NO NO YES
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
更新 (UPDATE) 新規 (NEW) 更新 (UPDATE) 新規 (NEW) 更新 (UPDATE) 新規 (NEW)例：「ダークモードの追加」
- 「カスタムテーマのサポートも必要」→ 新規変更（スコープが肥大化）
- 「システム設定の検出は予想以上に難しい」→ 更新（意図は同じ）
- 「まずトグルをリリースし、後で設定を追加する」→ 更新してからアーカイブし、その後新規変更を作成
ベストプラクティス
変更に焦点を絞る
1つの論理的な作業単位を1つの変更としてください。もし「機能Xの追加とYのリファクタリングの両方を行う」のであれば、2つの別々の変更を検討してください。
重要な理由:
- レビューし理解するのが容易
- アーカイブ履歴がクリーンになる
- 単独でリリースできる
- 必要であればロールバックが簡単
要件が不明確な場合は/opsx:exploreを使用する
変更にコミットする前に、問題領域を探索してください。
text
You: /opsx:explore
AI: 何を探索したいですか？
You: APIのレート制限をどのように処理すべきでしょうか？
AI: 現在のセットアップとオプションについて調査します...
[コードベースをリサーチし、パターンを考慮]
取り得る可能性のある3つのアプローチが見つかりました：
1. ミドルウェアベース（シンプル、エンドポイントごと）
2. Redisバック（スケーラブル、共有状態）
3. ユーザーごとのトークンバケット（公平、複雑）
現在のスタックは#1または#2を示唆しています。スケール感はいかがですか？探索を行うことで、アーティファクトを作成する前に思考を明確にします。
アーカイブする前に検証する
/opsx:verifyを使用して、実装がアーティファクトと一致しているかを確認してください。
text
You: /opsx:verify
AI: add-dark-mode の検証中...
✓ tasks.md にあるすべてのタスクがチェック済み
✓ 仕様書にある要件が対応するコードを持っている
✓ デザイン上の決定事項が実装に反映されている
アーカイブ準備完了！変更をクローズする前に、不一致点を検出します。
変更名を明確にする
良い名前はopenspec listを役立てます：
text
良い例: 避けるべき例:
add-dark-mode feature-1
fix-login-redirect update
optimize-product-query changes
implement-2fa wipコマンドクイックリファレンス
完全なコマンドの詳細とオプションについては、Commandsを参照してください。
| Command | 目的 | 使用するタイミング |
|---|---|---|
/opsx:propose | 変更および計画アーティファクトの作成 | 標準的な高速パス（coreプロファイル） |
/opsx:explore | AIによるアイデアの検討 | 不明な要件、調査、オプション比較がある場合 |
/opsx:new | 変更スキャフォールドの開始 | 詳細モード、明示的なアーティファクト制御が必要な場合 |
/opsx:continue | 次のアーティファクト作成 | 詳細モード、ステップバイステップでのアーティファクト作成 |
/opsx:ff | すべての計画アーティファクト作成 | 詳細モード、スコープが明確な場合 |
/opsx:apply | タスクの実装 | コードを記述する準備ができている場合 |
/opsx:verify | 実装の検証 | アーカイブする前の詳細モード |
/opsx:sync | デルタ仕様のマージ | 詳細モード、オプション |
/opsx:archive | 変更の完了 | すべての作業が完了したとき |
/opsx:bulk-archive | 複数の変更をアーカイブ | 詳細モード、並行作業を行う場合 |
次のステップ
- Commands - オプションを含む完全なコマンドリファレンス
- Concepts - 仕様、アーティファクト、スキーマに関する詳細な解説
- Customization - カスタムワークフローの作成