はじめに
OpenSpec についての入門ドキュメントです。
OpenSpecとは
OpenSpecとは何か
OpenSpecは、あなたとAIコーディングアシスタントの間の軽量な合意レイヤーです。コードを書く前に「何を構築するか」を事前に合意するためのフレームワークです。
一言で言えば：まず合意し、その後、自信を持って構築することです。
なぜOpenSpecが必要か
AIコーディングアシスタント（Claude Code、Cursorなど）は「意欲的」です。漠然とした指示を出すと、AIは自信を持って誤った「何か」を構築してしまいます。OpenSpecは変更前に短い計画を書くことで、この問題を解決します：
- 誤った方向への進行を事前に発見できます。1段落の提案書で誤解を修正するのは無料ですが、AIが400行のコードを書いた後に修正するのは高額になります。
- 計画とコードが同じリポジトリに保存されます。6ヶ月後、システムがなぜそのように動作するのかを仕様が説明してくれます。
- 変更がレビュー可能になります。変更フォルダは整理されたパッケージです。
- 既存のコードベースに適合します。デルタ仕様（差分仕様）により、50,000行のアプリに対する変更を、全体を文書化せずに指定できます。
5つの概念
OpenSpecは以下の5つの概念から構築されています。
1. 仕様が真実
仕様は、システムが現在どのように動作するかを記述します。openspec/specs/ ディレクトリに保存され、ドメインごとに整理されます（auth/、payments/、ui/など）。
仕様は要件とシナリオで構成されます：
- 要件: 「システムは30分経過後にセッションを失効させるべきである（SHALL）」
- シナリオ: 具体的な「Given/When/Then」の例
2. 変更は1つの作業単位
動作を追加・変更・削除したい場合、openspec/changes/ にフォルダを作成します。このフォルダには、その作業に関するすべてが1箇所に保存されます：
- proposal（提案）
- design（設計）
- tasks（タスクリスト）
- specs（仕様変更）
1つの変更、1つのフォルダ、1つの機能です。
3. デルタ仕様
変更の中で、全体の仕様を再作成する必要はありません。小さなデルタ（差分）を書きます：
ADDED: この要件を追加MODIFIED: この要件を変更REMOVED: この要件を削除
既存システムに対する変更を得意とします。目的地ではなく、差分を記述するのです。
graph LR
A["現在の仕様"] --> B["デルタ仕様"]
B --> C["ADDED: 新要件"]
B --> D["MODIFIED: 変更"]
B --> E["REMOVED: 削除"]
C --> F["真実が更新"]
D --> F
E --> F
4. 成果物の連鎖
変更フォルダには、自然な順序で作成される文書が含まれます：
proposal ──► specs ──► design ──► tasks ──► implement
why what how steps do it
各文書が次の文書を可能にします。これらはゲートではなく促進要因で、いつでも編集できます。
5. アーカイブ
作業が完了したら、変更をアーカイブします：
- デルタ仕様がメインの仕様にマージされる
- 変更フォルダが
changes/archive/ に日付付きで移動される
これで仕様は新しい現実を記述し、次の変更の準備が整います。
graph LR
subgraph openspec[openspec/]
specs["specs/\n真のソース\n現在の実装"]
changes["changes/\n提案された変更"]
archive["changes/archive/\n変更フォルダの保管場所"]
end
changes -->|デルタ仕様をマージ| specs
changes -->|フォルダを移動| archive
コマンドの仕組み
OpenSpecには2種類の命令体系があり、異なる場所で実行されることに注意が必要です。
2種類の命令体系
| 種類 |
形式 |
場所 |
例 |
| CLIコマンド |
openspec ... |
ターミナル |
openspec init |
| スラッシュコマンド |
/opsx:... |
AIチャット |
/opsx:propose |
CLI（ターミナル側）はエンジンです。プロジェクトのセットアップ、変更のリスト化、バリデーション、アーカイブを行います。
スラッシュコマンド（チャット側）は操縦席です。AIにワークフローを実行させます。
ツール別の表記
| ツール |
表記方法 |
| Claude Code |
/opsx:propose, /opsx:apply |
| Cursorなど |
/opsx-propose, /opsx-apply |
迷ったら、AIチャットで /opsx と入力してオートコンプリートを確認してください。
基本的なワークフロー
最初の5分
インストールと初期化はターミナルで、それ以降はチャットで実行します：
TERMINAL $ npm install -g @fission-ai/openspec@latest
TERMINAL $ cd your-project && openspec init
AI CHAT /opsx:explore （任意：最初に考えを整理）
AI CHAT /opsx:propose add-dark-mode （AIが計画をドラフト作成）
AI CHAT /opsx:apply （AIが構築）
AI CHAT /opsx:archive （仕様を更新、変更を保管）
コマンドの流れ
コアパス（基本）：
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
（任意）
プロジェクト構造
openspec init 実行後、プロジェクトには以下の構造が作成されます：
openspec/
├── specs/ # 真のソース（システムの動作）
│ └── <domain>/
│ └── spec.md
├── changes/ # 提案された変更
│ └── <change-name>/
│ ├── proposal.md
│ ├── design.md
│ ├── tasks.md
│ └── specs/ # デルタ仕様
└── config.yaml
specs/ - 真のソース。システムが現在どのように動作するかchanges/ - 提案された変更。すべての関連成果物が1フォルダに
各変更フォルダ内では、成果物が自然な順序で配置されます：
| 成果物 |
役割 |
proposal.md |
「なぜ」と「何を」— 意図、範囲、アプローチ |
specs/ |
変更される要件とシナリオ（デルタ） |
design.md |
「どのように」— 技術的アプローチ |
tasks.md |
実装チェックリスト |
/opsx:explore の活用
思考パートナーとしての役割
/opsx:explore は思考パートナーです。問題はあるが計画がないときに使います。コードベースを検査し、オプションを比較し、本当に欲しいものを明確にします。
explore ──► propose ──► apply ──► archive
(思考) （合意） （構築） （記録）
使用タイミング
以下の場合、探索が適切な最初のステップです：
- 問題はわかるが解決策がわからない（「ページが遅い」「認証がぐちゃぐちゃ」）
- アプローチ間で選択したい、トレードオフを確認したい
- コードベースに慣れておらず、変更前に動作を理解したい
- 要件があいまいで、明確にしたい
- 作業の見積もりが正確か確認したい
すでに何が欲しいかわかっている場合は、直接 /opsx:propose に進んで構いません。
活用のコツ
- 解決策ではなく問題を持って来る：「Redisキャッシュを追加」ではなく「ログインが遅い」と伝える
- トレードオフを外に出させる：「各オプションの欠点は？」と聞く
- まずコードを読ませる：AIが実際にコードを確認してから議論を始める
- アイデアを放棄しても大丈夫：探索でアイデアの価値がないとわかったら、それは成功です（安く学べたということ）
デルタ仕様の仕組み
ADDED/MODIFIED/REMOVEDによる差分指定
デルタ仕様は、現在の仕様に対する変更を示します：
# 認証ドメインに対するデルタ
## ADDED Requirements
### Requirement: 二段階認証
システムはログイン時に第二要素を必須にする。
#### Scenario: OTP required
- GIVEN 2FAが有効なユーザー
- WHEN 有効な認証情報を提出
- THEN OTPチャレンジが表示される
## MODIFIED Requirements
### Requirement: セッションタイムアウト
システムは30分経過後にセッションを失効させる。（従来: 60分）
## REMOVED Requirements
### Requirement: Remember Me
（二段階認証に置き換えられた）
変更の追跡方法
アーカイブ時に：
- ADDED 要件がメイン仕様に追加される
- MODIFIED 要件が既存版と置き換えられる
- REMOVED 要件がメイン仕様から削除される
変更フォルダは openspec/changes/archive/ に移動され、監査履歴として保持されます。
まとめ
OpenSpecの価値は、AIと人間の間の明確な合意にあります。
- コードを書く前に計画することで、誤りを低コストで発見
- 計画とコードが同じリポジトリに保存され、長期的な保守性向上
- 変更がレビュー可能なパッケージとして整理
- 既存のコードベースに適合するデルタ仕様による軽量な変更管理
AIコーディングアシスタントとの協業において、「何を構築するか」を事前に合意するプロセスは、間違ったものを自信を持って構築されるリスクを大幅に減らします。
迷ったら、まず /opsx:explore から始めてみてください。それがOpenSpecで最も重要な習慣です。
|