はじめに
このガイドでは、OpenSpecをインストールして初期化した後の使い方を説明します。インストール手順については、メインのREADMEを参照してください。
仕組み
OpenSpecは、コードを書く前に、あなたとAIコーディングアシスタントが何を構築するかを合意するのを助けます。
デフォルトのクイックパス（コアプロファイル）：
text
/opsx:propose ──► /opsx:apply ──► /opsx:archive拡張パス（カスタムワークフロー選択）：
text
/opsx:new ──► /opsx:ff または /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archiveデフォルトのグローバルプロファイルは core で、propose、explore、apply、archive を含みます。拡張ワークフローコマンドは、openspec config profile で有効にし、その後 openspec update を実行して有効にできます。
OpenSpecが作成するもの
openspec init を実行した後、プロジェクトは以下の構造になります：
openspec/
├── specs/ # 信頼できる情報源（システムの動作）
│ └── <domain>/
│ └── spec.md
├── changes/ # 提案された更新（変更ごとに1フォルダ）
│ └── <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が必要
- GIVEN 2FAが有効なユーザー
- WHEN ユーザーが有効な資格情報を送信する
- THEN OTPチャレンジが提示される
## 変更された要件
### 要件：セッションタイムアウト
システムは30分間の非アクティブ後にセッションを期限切れにしなければなりません。
（以前：60分）
#### シナリオ：アイドルタイムアウト
- GIVEN 認証済みセッション
- WHEN アクティビティなしで30分が経過する
- THEN セッションが無効になる
## 削除された要件
### 要件：Remember Me
（2FAに代わり廃止）アーカイブ時に何が起こるか
変更をアーカイブすると：
- 追加された要件はメインの仕様に追加されます
- 変更された要件は既存のバージョンを置き換えます
- 削除された要件はメインの仕様から削除されます
変更フォルダは監査履歴のために openspec/changes/archive/ に移動されます。
例：最初の変更
アプリケーションにダークモードを追加する例を説明します。
1. 変更を開始（デフォルト）
text
You: /opsx:propose add-dark-mode
AI: 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のデルタ
## 追加された要件
### 要件：テーマ選択
システムはユーザーがライトテーマとダークテーマを選択できるようにしなければなりません。
#### シナリオ：手動切り替え
- GIVEN 任意のページにいるユーザー
- WHEN ユーザーがテーマ切り替えをクリックする
- THEN テーマはすぐに切り替わる
- AND 設定はセッション間で保持される
#### シナリオ：システム設定
- GIVEN 保存された設定がないユーザー
- WHEN アプリケーションが読み込まれる
- THEN システムの推奨カラースキームが使用されるtasks.md - 実装チェックリスト：
markdown
# タスク
## 1. テーマ基盤
- [ ] 1.1 ライト/ダーク状態のThemeContextを作成
- [ ] 1.2 色のCSSカスタムプロパティを追加
- [ ] 1.3 localStorageの永続化を実装
## 2. UIコンポーネント
- [ ] 2.1 ThemeToggleコンポーネントを作成
- [ ] 2.2 設定ページに切り替えを追加
- [ ] 2.3 ヘッダーにクイック切り替えを追加
## 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