ワークフロー
このガイドでは、OpenSpec の一般的なワークフローパターンと、それぞれの使用タイミングについて説明します。基本的なセットアップについては、「はじめに」を参照してください。コマンドリファレンスについては、「コマンド」を参照してください。
哲学：フェーズではなくアクション
伝統的なワークフローは、計画、実装、完了というフェーズに沿って進めることを強制します。しかし、実際の作業は単純なカテゴリにきれいに収まるわけではありません。
OPSX は異なるアプローチを採用しています：
text
Traditional (phase-locked):
PLANNING ────────► IMPLEMENTING ────────► DONE
│ │
│ "Can't go back" │
└────────────────────┘
OPSX (fluid actions):
proposal ──► specs ──► design ──► tasks ──► implement主要な原則：
- フェーズではなくアクション - コマンドは実行可能なことであり、固定されたステージではない
- 依存関係はイネーブラー - 次に何が必要かを示すのではなく、何が可能かを示す
カスタマイズ： OPSX ワークフローは、成果物のシーケンスを定義するスキーマによって駆動されます。カスタムスキーマの作成の詳細については、「カスタマイズ」を参照してください。
2つのモード
デフォルトのクイックパス（core プロファイル）
新規インストールではデフォルトで core が使用され、以下を提供します：
/opsx:explore/opsx:propose/opsx:apply/opsx:sync/opsx:archive
典型的なフロー：
text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
(optional)探索から始める（形成すべき習慣）
/opsx:explore はデフォルトプロファイルの一部であり、高度なアドオンではありません。これは、問題はあるがまだ計画がない場合、つまりAIアシスタントと作業するほとんどの場合に取るべき行動です。
text
You: /opsx:explore
AI: 何を探索したいですか？
You: 検索結果が古い感じがします。キャッシュ、インデックス、クエリのどれが原因かわかりません。
AI: 調べてみます... [検索サービスとキャッシュ層を確認]
インデックスが原因です：毎夜再構築されるため、編集内容が翌日まで反映されません。
2つの選択肢があります：書き込み時に再構築（シンプル、負荷が高い）か、
短いTTLのキャッシュ無効化（構成要素が多い、負荷が低い）。
書き込み量が少ないため、書き込み時再構築の方がクリーンな修正です。
スコープを設定しますか？
You: はい。
You: /opsx:propose rebuild-search-index-on-write探索は成果物を作成せず、コードも書きません。曖昧な懸念を明確な変更に変える、リスクのない無料の会話であり、その後の提案が的確なものになります。既に何を望んでいるか正確に把握している場合は、スキップして直接 /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: ✓ 仕様をマージ
✓ 変更をアーカイブ最適な用途： 中小規模の機能、バグ修正、単純な変更。
探索的アプローチ
要件が不明確な場合や、最初に調査が必要な場合：
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: 仕様を作成しています...最適な用途： パフォーマンス最適化、デバッグ、アーキテクチャ決定、不明確な要件。
並列変更
複数の変更を同時に作業する場合：
text
Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
│
context switch
│
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-footerバルクアーカイブは、複数の変更が同じ仕様に影響する場合を検出し、実際に実装されている内容を確認して競合を解決します。
変更の完了
推奨される完了フロー：
text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
│ │
validates prompts to sync
implementation if needed検証：作業内容の確認
/opsx:verify は、成果物に対する実装を3つの側面から検証します：
text
You: /opsx:verify
AI: add-auth を検証しています...
完全性
✓ tasks.md の全12タスクがチェック済み
✓ 仕様のすべての要件に対応するコードが存在
⚠ シナリオ「非アクティブ後のセッションタイムアウト」がテストされていません
正確性
✓ 実装が仕様の意図と一致
✓ シナリオのエッジケースが処理されている
✓ エラー状態が仕様の定義と一致
整合性
✓ 設計判断がコード構造に反映されている
✓ 命名規則が design.md と一致
⚠ 設計では「イベント駆動」と記載されているが、実装はポーリングを使用
サマリー
─────────────────────────────
重大な問題：0
警告：2
アーカイブ可能：はい（警告あり）
推奨事項：
1. セッションタイムアウトシナリオのテストを追加
2. 設計通りイベント駆動へのリファクタリングを検討するか、design.md を更新検証内容：
| 側面 | 検証内容 |
|---|---|
| 完全性 | すべてのタスクが完了、すべての要件が実装、シナリオがカバーされていること |
| 正確性 | 実装が仕様の意図と一致、エッジケースが処理されていること |
| 整合性 | 設計判断がコードに反映、パターンが整合していること |
検証はアーカイブをブロックしませんが、先に対処すべき問題を明らかにします。
アーカイブ：変更の確定
/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/ に移動しました
変更をアーカイブしました。仕様が同期されていない場合、アーカイブはプロンプトを表示します。未完了のタスクがある場合でもブロックしませんが、警告を表示します。
使い分け
/opsx:ff と /opsx:continue の比較
| 状況 | 使用するコマンド |
|---|---|
| 要件が明確で、構築準備完了 | /opsx:ff |
| 探索中で、各ステップを確認したい | /opsx:continue |
| 提案書の前に反復したい | /opsx:continue |
| 時間的制約があり、迅速に進める必要がある | /opsx:ff |
| 複雑な変更で、制御したい | /opsx:continue |
基本原則： 事前に全体のスコープを説明できる場合は /opsx:ff を使用してください。作業しながら理解を深める場合は /opsx:continue を使用してください。
更新するか新規作成するか
よくある質問：既存の変更を更新してもよい場合と、新規に変更を作成すべき場合の違いは何ですか？
既存の変更を更新する場合：
- 同じ意図で、実行方法を改善する場合
- スコープが縮小する場合（MVPを先にリリース、残りは後で）
- 学習による修正（コードベースが想定と異なっていた）
- 実装の発見に基づく設計の調整
新規変更を作成する場合：
- 意図が根本的に変わった場合
- スコープが爆発的に拡大し、完全に異なる作業になった場合
- 元の変更をこれらの変更なしで「完了」とマークできる場合
- パッチを適用すると混乱が生じる場合
text
┌─────────────────────────────────────┐
│ Is this the same work? │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
Same intent? >50% overlap? Can original
Same problem? Same scope? be "done" without
│ │ these changes?
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
YES NO YES NO NO YES
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
UPDATE NEW UPDATE NEW UPDATE NEW例：「ダークモードの追加」
- 「カスタムテーマもサポートする必要がある」→ 新規変更（スコープが爆発的に拡大）
- 「システム設定の検出が想定より難しい」→ 更新（同じ意図）
- 「まずトグルをリリースし、後で設定を追加する」→ 更新してアーカイブ、その後新規変更
ベストプラクティス
変更を絞り込む
変更ごとに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
Good: Avoid:
add-dark-mode feature-1
fix-login-redirect update
optimize-product-query changes
implement-2fa wipコマンドクイックリファレンス
コマンドの詳細とオプションについては、Commands を参照してください。
| コマンド | 目的 | 使用タイミング |
|---|---|---|
/opsx:propose | 変更と計画成果物を作成 | 高速なデフォルトパス（core プロファイル） |
/opsx:explore | AI とともにアイデアを検討 | 不明確な場合の出発点：要件が不明確な場合、調査、選択肢の比較 |
/opsx:new | 変更スキャフォールドを開始 | 拡張モード、明示的な成果物制御 |
/opsx:continue | 次の成果物を作成 | 拡張モード、段階的な成果物作成 |
/opsx:ff | すべての計画成果物を作成 | 拡張モード、明確なスコープ |
/opsx:apply | タスクを実装 | コードを記述する準備ができた |
/opsx:verify | 実装を検証 | 拡張モード、アーカイブ前 |
/opsx:sync | デルタ仕様をマージ | 拡張モード、オプション |
/opsx:archive | 変更を完了 | すべての作業が完了 |
/opsx:bulk-archive | 複数の変更をアーカイブ | 拡張モード、並列作業 |
次のステップ
- Writing Good Specs - 強固な要件とシナリオの例、および変更の適切な規模の設定方法
- Reviewing a Change - コード作成前の草案プランの2分間レビュー
- OpenSpec on a Team - 変更がブランチとプルリクエストにどのように適合するか
- Commands - オプションを含む完全なコマンドリファレンス
- Concepts - 仕様、成果物、スキーマの詳細な解説
- Customization - カスタムワークフローの作成