📋

OpenSpec実践ガイド: AIコーディングを仕様駆動で進める

2026/02/07に公開

この記事について

対象読者: AIコーディングアシスタントを使っていて、仕様駆動開発（SDD）に興味がある開発者。特にOpenSpecを実際に導入してみたい方

この記事を読むと: OpenSpecのセットアップから実践的なワークフローまでを理解し、プロジェクトで仕様駆動開発を始められるようになります

OpenSpecとは

OpenSpec（⭐ 22.7k）は、AIコーディングアシスタントとの協業を「仕様駆動」で行うための軽量フレームワークです。Claude Code、Cursor、GitHub Copilotなど22以上のAIツールに対応しています。

従来のAIコーディングでは、プロンプトで直接指示を出し、その場でコードを生成していました。OpenSpecでは、実装前に仕様を明確にし、AIと人間が同じ仕様を見ながら開発を進めるというアプローチを取ります。

なぜ仕様駆動なのか

AIコーディングで陥りがちな問題：

曖昧な指示 → AIが意図と違う実装をする
コンテキスト消失 → 会話が長くなると前提が忘れられる
再現性の欠如 → 同じ機能を別の人が触ると混乱する
既存コードとの不整合 → 既存の設計を無視した実装になる

OpenSpecは、**仕様ドキュメントという「信頼できる唯一の情報源」**を作ることで、これらの問題に対処します。

4つの基本原則

Fluid not rigid — フェーズゲートなし、必要な作業から着手
Iterative not waterfall — 作りながら学び、仕様も随時改善
Easy not complex — 軽量なセットアップ、最小限のセレモニー
Brownfield-first — 既存コードベースに対応（グリーンフィールドだけでなく）

セットアップ

インストール

Node.js 20.19.0以上が必要です。

npm install -g @fission-ai/openspec@latest

プロジェクトで初期化：

cd your-project
openspec init

初期化時に使用するAIツールを選択できます。特定のツールを指定する場合：

openspec init --tools claude,cursor

ディレクトリ構成

初期化後、以下の構造が作成されます：

your-project/
├── openspec/
│   ├── specs/           # システムの現在の仕様（信頼できる情報源）
│   └── changes/         # 提案中の変更（機能ごとにフォルダ）
│       ├── my-feature/
│       │   ├── proposal.md
│       │   ├── specs/
│       │   ├── design.md
│       │   └── tasks.md
│       └── archive/     # 完了した変更
├── .claude/             # Claude Code用のスキル・コマンド
│   ├── skills/
│   └── commands/opsx/
└── ...

specs/ と changes/ の分離がポイントです：

specs/ — 現在のシステムがどう動くかを記述
changes/ — これから行う変更を個別のフォルダで管理

対応AIツール（22種類）

対応ツール一覧

Amazon Q Developer
Antigravity
Auggie (Augment CLI)
Claude Code
Cline
CodeBuddy
Codex
Continue
CoStrict
Crush
Cursor
Factory Droid
Gemini CLI
GitHub Copilot
iFlow
Kilo Code
OpenCode
Qoder
Qwen Code
RooCode
Trae
Windsurf

核心概念

4つの主要アーティファクト

各変更（change）は以下の4つのドキュメントで構成されます：

ファイル	役割
proposal.md	何を、なぜ作るか。目的とスコープを定義
specs/	デルタ仕様。追加・変更・削除される要件
design.md	どう作るか。技術的なアプローチと設計判断
tasks.md	実装チェックリスト。具体的な作業項目

これらは順番に依存しています：proposal → specs → design → tasks

デルタ仕様（Delta Specs）

OpenSpecの重要な概念が「デルタ仕様」です。仕様全体を書き直すのではなく、何が変わるかだけを記述します：

## ADDED Requirements

- REQ-001: ユーザーはダッシュボードからエクスポートボタンをクリックできる【MUST】
- REQ-002: エクスポート形式としてCSVとJSONを選択できる【SHOULD】

## MODIFIED Requirements

- REQ-100: （変更前）レポートは画面表示のみ
  - （変更後）レポートは画面表示に加え、エクスポートも可能

## REMOVED Requirements

- REQ-050: 旧形式のエクスポート機能（廃止）

シナリオの記述（GIVEN/WHEN/THEN）

各要件にはテスト可能なシナリオを付けることが推奨されています：

### REQ-001: テーマ選択

ユーザーは設定画面からテーマを選択できる

#### Scenario: ダークモードへの切り替え

- **GIVEN** ユーザーがライトモードを使用している
- **WHEN** 設定画面でダークモードを選択する
- **THEN** アプリ全体がダークテーマに切り替わる
- **AND** 選択が次回起動時も維持される

要件の優先度（RFC 2119）

要件の重要度を示すため、RFC 2119 のキーワードを使用します：

キーワード	意味
MUST / SHALL	必須。この要件は絶対に満たす必要がある
SHOULD	推奨。特別な理由がない限り満たすべき
MAY	任意。実装してもしなくてもよい

- REQ-001: ユーザーはログインできる【MUST】
- REQ-002: パスワードリセット機能を提供する【SHOULD】
- REQ-003: ソーシャルログインに対応する【MAY】

スキーマ（Schemas）

スキーマは、アーティファクト間の依存関係を定義します。デフォルトの spec-driven スキーマでは：

proposal → specs → design → tasks → 実装

の順序で作業が進みます。ただし、これは「可能な順序」であり「強制される順序」ではありません。チームの状況に応じて、アーティファクトをスキップしたり順序を変えたりできます。

カスタムスキーマを作成して、チーム独自のワークフローを定義することも可能です：

# カスタムスキーマの初期化
openspec schema init

# 既存スキーマをフォークしてカスタマイズ
openspec schema fork

デルタ仕様のメリット：

レビューしやすい — 変更点が明確
コンフリクトしにくい — 複数の変更が同時進行しても混乱しない
既存コードベースに適用しやすい — 全体を書き直す必要なし
テスト可能 — シナリオがそのまま受け入れテストになる

コマンドとワークフロー

OpenSpecの哲学は「コマンドは行動であり、フェーズではない」です。従来のウォーターフォールのようにフェーズに縛られるのではなく、状況に応じて柔軟にアクションを選べます。

コマンド一覧

コマンド	説明
`/opsx:explore`	アイデアの探索、問題の調査、要件の明確化
`/opsx:new <name>`	新しい変更を開始（フォルダ構造を作成）
`/opsx:continue`	次のアーティファクトを順番に作成
`/opsx:ff`	全アーティファクト（proposal→specs→design→tasks）を一括生成
`/opsx:apply`	tasks.mdに基づいて実装を実行
`/opsx:verify`	実装が仕様に沿っているか検証
`/opsx:sync`	デルタ仕様をメインのspecsにマージ
`/opsx:archive`	完了した変更をアーカイブ
`/opsx:bulk-archive`	複数の変更を一括アーカイブ
`/opsx:onboard`	チュートリアル（対話形式で一連の流れを体験）

ツール別のコマンド形式

AIツールによってコマンドの書き方が異なります：

ツール	形式
Claude Code / Windsurf / Copilot	`/opsx:command`
Cursor	`/opsx-command`
Trae	`/openspec-command-name`

開発サイクル

OpenSpecの開発は以下のサイクルで回ります：

┌─────────────────────────────────────────────────────┐
│                                                     │
│   specs（現在の仕様）                                │
│        ↓                                            │
│   changes（変更を提案）                              │
│        ↓                                            │
│   実装（コードを書く）                               │
│        ↓                                            │
│   archive（デルタをマージ）                          │
│        ↓                                            │
│   specs（更新された仕様）← 次のサイクルへ            │
│                                                     │
└─────────────────────────────────────────────────────┘

specs/ が「現在の真実」を表し、changes/ で変更を提案・実装し、完了したら archive でデルタ仕様をマージ。更新された specs/ が次のサイクルの起点になります。

基本フロー

/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive
   ↓           ↓           ↓            ↓              ↓
 開始     計画作成     実装        検証         完了

ワークフローパターン

1. クイックフィーチャー（Quick Feature）

スコープが明確で、要件が定義済みの場合に使用します。

/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

特徴：

/opsx:ff で全アーティファクトを一括生成
高速に実装まで進められる

適している場面：

小〜中規模の機能追加（ログアウトボタン、設定画面など）
バグ修正
要件が明確で、スコープが定義済み

2. 探索的開発（Exploratory）

要件が不明確で、調査が必要な場合に使用します。

/opsx:explore → 調査・分析 → /opsx:new → /opsx:continue → /opsx:apply

特徴：

実装前に /opsx:explore で問題を調査
/opsx:continue でアーティファクトを段階的に作成
各ステップで判断・修正が可能

適している場面：

パフォーマンス最適化（どこがボトルネックかわからない）
デバッグ（原因調査が必要）
アーキテクチャの判断が必要な場合
曖昧な要件を明確化したい

3. 並行開発（Parallel Changes）

複数の変更を同時に進める場合に使用します。各changeは独立したフォルダで管理されるため、自由に切り替えが可能です。

openspec/changes/
├── add-dark-mode/      ← Change A（作業中）
├── fix-login-bug/      ← Change B（緊急対応）
└── update-footer/      ← Change C（保留中）

切り替えの方法：

コマンドにchange名を明示することで、作業対象を切り替えます：

# Change Aで作業中に、緊急のバグ修正が発生
/opsx:new fix-login-bug          # Change Bを新規作成
/opsx:ff fix-login-bug           # Change Bの計画を生成
/opsx:apply fix-login-bug        # Change Bを実装
/opsx:archive fix-login-bug      # Change Bを完了

# 元の作業に戻る
/opsx:apply add-dark-mode        # Change Aの実装を再開
# → "Resuming add-dark-mode... Picking up at task 2.3"
#    中断した箇所から自動的に再開される

進捗の確認：

# 全changeの状態を一覧表示
openspec list

# 特定changeの詳細な進捗を確認
openspec show add-dark-mode

適している場面：

複数の機能を並行して開発
緊急の割り込みタスクへの対応
チームでの分担作業

複数changeの一括アーカイブ：

複数の変更が完了した場合、/opsx:bulk-archive で一括処理できます：

/opsx:bulk-archive
# → 完了済みchangeを一覧表示
# → 各changeを検証
# → 作成時系列順でアーカイブ処理

4. 変更の完了（Completing a Change）

実装後の検証とアーカイブのパターンです。

/opsx:verify → /opsx:archive

検証フェーズ（verify）で確認される観点：

観点	チェック内容
Completeness	全タスク完了、全要件実装、シナリオカバー
Correctness	コードが仕様の意図に沿っている、エッジケース処理
Coherence	設計がコード構造に反映、命名の一貫性

アーカイブフェーズ（archive）の動作：

デルタ仕様を specs/ にマージするか確認
変更フォルダを changes/archive/ に移動（タイムスタンプ付き）
未完了タスクがあっても実行可能（警告は表示）

アーティファクトの修正と再実装

OpenSpecにはアーティファクトを修正するための専用コマンドはありません。アーティファクトは単なるMarkdownファイルなので、直接編集して /opsx:continue で後続を再生成します。

修正の基本フロー

アーティファクトを直接編集 → /opsx:continue → 依存する後続が再生成

修正方法は自由です：

手動でファイルを編集
AIに「design.mdのこの部分を修正して」と依頼

例：設計を見直す場合

1. design.md を直接修正（手動 or AIに依頼）
2. /opsx:continue を実行
3. tasks.md が新しい design.md を元に再生成される
4. /opsx:apply で再実装

例：仕様に問題があった場合

1. specs/ 内のファイルを直接修正（手動 or AIに依頼）
2. /opsx:continue を実行
3. design.md → tasks.md が順に再生成される
4. /opsx:apply で再実装

verifyで問題が見つかった場合

/opsx:verify は問題を検出してもアーカイブをブロックしません（警告のみ）。修正が必要な場合：

問題の程度	対応
軽微な実装ミス	`/opsx:apply` で追加実装 → 再度 `/opsx:verify`
設計に問題	design.md を修正 → `/opsx:continue` → `/opsx:apply`
仕様自体が間違い	specs/ を修正 → `/opsx:continue` → `/opsx:apply`
根本的にやり直し	新しい change を `/opsx:new` で開始

コマンド選択の判断基準

`/opsx:ff` vs `/opsx:continue`

状況	推奨コマンド
要件が最初から明確	`/opsx:ff`（一括生成）
時間的なプレッシャーがある	`/opsx:ff`
探索しながら進めたい	`/opsx:continue`（段階的）
各アーティファクトを細かく確認したい	`/opsx:continue`

既存の変更を更新 vs 新しい変更を開始

既存の変更を更新する場合：

同じ問題に対してアプローチを修正する
スコープを絞り込む
学習した内容を反映して改善する

新しい変更を開始する場合：

目的が根本的に変わった
スコープが大きく膨らんだ
元の変更が独立して完結している

実践例：ダークモード機能の追加

公式ドキュメントで紹介されているダークモード機能の追加を例に、ワークフローを見ていきます。

1. 新しい変更を開始

/opsx:new dark-mode

openspec/changes/dark-mode/ フォルダが作成されます。

2. 計画を一括生成

/opsx:ff

AIが以下のドキュメントを一気に生成します：

proposal.md（提案書）の例：

# Dark Mode Support

## Problem
ユーザーから「夜間や暗い環境での使用時に目が疲れる」というフィードバック

## Solution
ライト/ダークテーマの切り替え機能を実装

## Scope
- テーマ切り替えUI
- システム設定との連携
- 設定の永続化

specs/（デルタ仕様）の例：

## ADDED Requirements

### REQ-001: テーマ選択
ユーザーは設定画面からテーマを選択できる（ライト/ダーク/システム連動）

### REQ-002: システム設定連動
「システム連動」選択時、OSのテーマ設定に追従する

tasks.md（タスク）の例：

## Theme Infrastructure
- [ ] ThemeContextの作成
- [ ] テーマ設定の永続化（localStorage）

## UI Components
- [ ] テーマ切り替えトグルの実装
- [ ] 設定画面への統合

## Styling
- [ ] ダークテーマのカラーパレット定義
- [ ] 全コンポーネントへのテーマ対応

3. 生成された仕様を確認・修正

生成されたドキュメントを確認し、必要に応じて修正します。この段階でチームメンバーとレビューすることも可能です。

4. 実装

/opsx:apply

tasks.mdのチェックリストに沿って、AIがコードを実装します。タスクが完了するごとにチェックボックスが更新されます。

5. 検証

/opsx:verify

以下の3つの観点で検証されます：

観点	チェック内容
Completeness（完全性）	全タスクが完了しているか、全要件が実装されているか、シナリオがカバーされているか
Correctness（正確性）	コードが仕様の意図に沿っているか、エッジケースが処理されているか
Coherence（一貫性）	設計判断がコード構造に反映されているか、命名が一貫しているか

6. アーカイブ

/opsx:archive

デルタ仕様がメインのspecs/にマージされ、変更フォルダはchanges/archive/に移動します。アーカイブには日付プレフィックスが付き、将来の参照用に保存されます。

CLIコマンド

ターミナルから直接使えるCLIも用意されています：

# 変更一覧を表示
openspec list

# 特定の変更の詳細を表示
openspec show dark-mode

# 構造的な問題をチェック
openspec validate

# インタラクティブダッシュボードを開く
openspec view

# 次のステップの指示を取得
openspec instructions

ベストプラクティス

変更の粒度を適切に保つ

1つの変更 = 1つの論理的な作業単位
大きすぎる変更は分割する
小さすぎる変更は管理オーバーヘッドになる

探索を惜しまない

不明確な問題に対しては、まず /opsx:explore で調査してから変更を開始する。「とりあえず作ってみる」より効率的。

アーカイブ前に検証を実行

/opsx:verify でミスマッチを検出してからアーカイブする。後から問題が見つかると手戻りが大きい。

命名規則を統一する

変更名は明確で説明的に：

✅ add-user-authentication
✅ fix-login-redirect-bug
❌ feature1
❌ update

チームでの活用

仕様ドキュメントをPRレビューの対象にする
openspec/specs/ をコードと一緒にバージョン管理
新メンバーのオンボーディングに /opsx:onboard を活用

参考リンク

OpenSpec 公式リポジトリ / 公式サイト
AIコーディングの仕様管理: 標準機能とSDDツールの使い分け — SDDツール全体の比較と選び方

この記事について

OpenSpecとは

なぜ仕様駆動なのか

4つの基本原則

セットアップ

インストール

ディレクトリ構成

対応AIツール（22種類）

核心概念

4つの主要アーティファクト

デルタ仕様（Delta Specs）

シナリオの記述（GIVEN/WHEN/THEN）

要件の優先度（RFC 2119）

スキーマ（Schemas）

コマンドとワークフロー

コマンド一覧

ツール別のコマンド形式

開発サイクル

基本フロー

ワークフローパターン

1. クイックフィーチャー（Quick Feature）

2. 探索的開発（Exploratory）

3. 並行開発（Parallel Changes）

4. 変更の完了（Completing a Change）

アーティファクトの修正と再実装

修正の基本フロー

例：設計を見直す場合

例：仕様に問題があった場合

verifyで問題が見つかった場合

コマンド選択の判断基準

/opsx:ff vs /opsx:continue

既存の変更を更新 vs 新しい変更を開始

実践例：ダークモード機能の追加

1. 新しい変更を開始

2. 計画を一括生成

3. 生成された仕様を確認・修正

4. 実装

5. 検証

6. アーカイブ

CLIコマンド

ベストプラクティス

変更の粒度を適切に保つ

探索を惜しまない

アーカイブ前に検証を実行

命名規則を統一する

チームでの活用

参考リンク

Discussion

`/opsx:ff` vs `/opsx:continue`