はじめに
このガイドでは、OpenSpecをインストールして初期化した後の動作について説明します。インストール手順については、メインのREADMEを参照してください。
動作の仕組み
OpenSpecは、コードが書かれる前に、何を構築するかについてあなたとAIコーディングアシスタントが合意するのに役立ちます。
デフォルトのクイックパス（コアプロファイル）：
text
/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive拡張パス（カスタムワークフローの選択）：
text
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archiveデフォルトのグローバルプロファイルはcoreで、propose、explore、apply、sync、archiveが含まれます。openspec config profileで拡張ワークフローコマンドを有効にし、その後openspec updateを実行できます。
OpenSpecが作成するもの
openspec initを実行すると、プロジェクトには以下の構造が作成されます。
openspec/
├── specs/ # 信頼できるソース（システムの動作）
│ └── <domain>/
│ └── spec.md
├── changes/ # 提案された更新（変更ごとにフォルダ）
│ └── <change-name>/
│ ├── proposal.md
│ ├── design.md
│ ├── tasks.md
│ └── specs/ # デルタ仕様（変更内容）
│ └── <domain>/
│ └── spec.md
└── config.yaml # プロジェクト設定（オプション）2つの主要ディレクトリ：
specs/- 信頼できるソース。これらの仕様はシステムの現在の動作を記述します。ドメイン別（例：specs/auth/、specs/payments/）に整理されます。changes/- 提案された変更。各変更には関連するすべての成果物を含む独自のフォルダが作成されます。変更が完了すると、その仕様はメインのspecs/ディレクトリにマージされます。
成果物の理解
各変更フォルダには、作業を導く成果物が含まれています。
| 成果物 | 目的 |
|---|---|
proposal.md | 「なぜ」と「何を」 - 意図、範囲、アプローチを記録 |
specs/ | 追加/変更/削除された要件を示すデルタ仕様 |
design.md | 「どのように」 - 技術的アプローチとアーキテクチャの決定 |
tasks.md | チェックボックス付きの実装チェックリスト |
成果物は相互に構築されます：
proposal ──► specs ──► design ──► tasks ──► implement
▲ ▲ ▲ │
└───────────┴──────────┴────────────────────┘
学習しながら更新実装中にさらに学んだら、いつでも前の成果物に戻って洗練できます。
デルタ仕様の動作
デルタ仕様はOpenSpecの重要な概念です。現在の仕様に対する変更内容を示します。
フォーマット
デルタ仕様はセクションを使用して変更の種類を示します。
markdown
# Authのデルタ
## 追加要件
### 要件：二要素認証
システムはログイン時に第二要素を要求する必要があります。
#### シナリオ：OTPが必要
- 2FAが有効なユーザーがいる場合
- ユーザーが有効な資格情報を送信した場合
- OTPチャレンジが提示される
## 変更要件
### 要件：セッションタイムアウト
システムは30分間の非アクティブ後にセッションを期限切れにする必要があります。
（以前：60分）
#### シナリオ：アイドルタイムアウト
- 認証されたセッションがある場合
- 30分間アクティビティがない場合
- セッションは無効になる
## 削除要件
### 要件：ログイン状態を保持
（2FAに置き換えられたため廃止）アーカイブ時の処理
変更をアーカイブすると：
- 追加要件はメイン仕様に追加されます
- 変更要件は既存のバージョンを置き換えます
- 削除要件はメイン仕様から削除されます
変更フォルダは監査履歴のためにopenspec/changes/archive/に移動されます。
例：最初の変更
アプリケーションにダークモードを追加する手順を見ていきましょう。
1. 変更を開始（デフォルト）
text
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md — なぜこれを行うのか、何が変わるのか
✓ specs/ — 要件とシナリオ
✓ design.md — 技術的アプローチ
✓ tasks.md — 実装チェックリスト
実装の準備ができました！拡張ワークフロープロファイルを有効にしている場合、2つのステップで行うこともできます：/opsx:newの後に/opsx:ff（または段階的に/opsx:continue）。
2. 作成されるもの
proposal.md - 意図を記録：
markdown
# 提案：ダークモードの追加
## 意図
ユーザーから、夜間の使用時の目の疲れを軽減するためのダークモードオプションが要望されています。
## 範囲
- 設定にテーマ切り替えを追加
- システム設定の検出をサポート
- localStorageに設定を保存
## アプローチ
テーマにCSSカスタムプロパティを使用し、状態管理にReactコンテキストを使用します。specs/ui/spec.md - 新しい要件を示すデルタ：
markdown
# UIのデルタ
## 追加要件
### 要件：テーマ選択
システムはユーザーがライトテーマとダークテーマの間で選択できるようにする必要があります。
#### シナリオ：手動切り替え
- 任意のページにいるユーザーがいる場合
- ユーザーがテーマ切り替えをクリックした場合
- テーマが即座に切り替わる
- そして設定はセッション間で持続する
#### シナリオ：システム設定
- 保存された設定がないユーザーがいる場合
- アプリケーションが読み込まれた場合
- システムの優先カラースキームが使用されるtasks.md - 実装チェックリスト：
markdown
# タスク
## 1. テーマインフラストラクチャ
- [ ] 1.1 ライト/ダーク状態のThemeContextを作成
- [ ] 1.2 色のCSSカスタムプロパティを追加
- [ ] 1.3 localStorageの永続性を実装
## 2. UIコンポーネント
- [ ] 2.1 ThemeToggleコンポーネントを作成
- [ ] 2.2 設定ページにトグルを追加
- [ ] 2.3 クイックトグルを含むようにHeaderを更新
## 3. スタイリング
- [ ] 3.1 ダークテーマのカラーパレットを定義
- [ ] 3.2 CSS変数を使用するようにコンポーネントを更新3. 実装
You: /opsx:apply
AI: タスクを処理中...
✓ 1.1 ライト/ダーク状態のThemeContextを作成
✓ 1.2 globals.cssにCSSカスタムプロパティを追加
✓ 1.3 localStorageの永続性を実装
✓ 2.1 ThemeToggleコンポーネントを作成
...
すべてのタスクが完了しました！実装中に、設計の調整が必要だとわかった場合は、成果物を更新して続行してください。
4. アーカイブ
You: /opsx:archive
AI: add-dark-modeをアーカイブ中...
✓ 仕様をopenspec/specs/ui/spec.mdにマージ
✓ openspec/changes/archive/2025-01-24-add-dark-mode/に移動
完了！次の機能の準備ができました。デルタ仕様はメイン仕様の一部となり、システムの動作を文書化します。
検証とレビュー
CLIを使用して変更を確認します。
bash
# アクティブな変更を一覧表示
openspec list
# 変更の詳細を表示
openspec show add-dark-mode
# 仕様のフォーマットを検証
openspec validate add-dark-mode
# インタラクティブなダッシュボード
openspec view