OpenSpec 入門：仕様書で AI 協業フレームワークの境界感を制御する

入門編 | 約 15 分 | OpenSpec の中核概念（Delta Specs、Artifact 依存グラフ）を理解し、初期化の手順、OPSX ワークフロー（propose → apply → archive）、そして複数変更の並行管理を習得します

---

プロジェクト概要

まずは事実を認めましょう。AI プログラミング支援を使っていると、こんな状況に遭遇したことはありませんか——雑談しているうちに、元々変えたくなかった箇所まで AI が勝手に変更してしまった；あるいは会話の文脈を切り替えると、AI がそれまで話していた内容をまったく覚えていない；さらに毎回 AI に新機能を作らせても、出来上がったものがあなたの望むものと根本的に別物になってしまう。

これらは AI が単に賢くないからではありません。要件がそもそも「署名して同意された（サインオフされた）」ことがないからです。要件はチャット履歴の中にしか存在せず、AI の自由裁量の余地が大きすぎるのです。

OpenSpec が行うことはシンプルです。**コードを書き始める前に、人と AI が仕様書で揃える（アラインする）**こと。そして AI は、その仕様書に従って行動します。Fission-AI が開発し、20+ の AI プログラミングツール（Claude Code、Cursor、Windsurf など）に対応しており、本質的には AI プログラミング支援に、軽量な仕様管理レイヤーを追加するものです。

---

対象読者像

• 日常的に AI プログラミング支援を使う開発者
• チーム協業で、人と AI の要件理解が一致しないことに悩むエンジニア
• AI のアウトプットをより制御可能にしたいプロダクトマネージャー

中核依存と環境

• Node.js 20.19.0+

完全なプロジェクト構造ツリー

openspec/
├── specs/                    # システムの現在のふるまい仕様（ドメインごと）
│   └── <domain>/spec.md
├── changes/                  # 変更提案（変更ごとに 1 フォルダ）
│   ├── <change-name>/
│   │   ├── proposal.md       # 動機 + 範囲 + 方針
│   │   ├── specs/             # Delta 仕様（ADDED/MODIFIED/REMOVED）
│   │   │   └── <domain>/spec.md
│   │   ├── design.md         # 技術設計
│   │   └── tasks.md          # 実装チェックリスト
│   └── archive/               # アーカイブ履歴
└── config.yaml               # プロジェクト設定（任意）

---

手取り足取りステップ

第 1 ステップ：OpenSpec をグローバルインストール

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

インストール後にバージョンを確認：

openspec --version
# 1.2.0

第 2 ステップ：プロジェクトを初期化

プロジェクトディレクトリに移動し、初期化コマンドを実行：

cd your-project
openspec init

このコマンドは次の 3 つを行います：

1. openspec/ のディレクトリ構造を作成
2. .claude/ 配下に AI スキルファイルを生成（AI アシスタントが /opsx:* コマンドを認識できるようにする）
3. プロジェクト設定ファイル config.yaml を作成するかどうかを質問（任意。プロジェクトのコンテキストを注入するために使用）

初期化が完了すると、プロジェクトに次のディレクトリが追加されます：

openspec/
├── specs/       # 現在のシステムふるまい仕様（空ディレクトリ。埋められるのを待つ）
├── changes/     # 変更提案ディレクトリ（空ディレクトリ）
└── config.yaml  # プロジェクト設定（作成を選んだ場合）

第 3 ステップ：OPSX 拡張ワークフローを有効化

新しくインストールした OpenSpec はデフォルトで core モードです。コマンドは 4 つだけ：propose、explore、apply、archive。完全なワークフロー（new、continue、ff、verify、bulk-archive など）を使いたい場合は、次を実行：

openspec config profile
# expanded または full を選択
openspec update

openspec update は、選択した profile に基づいて AI スキルファイルを再生成し、AI との会話でより多くのコマンドを使えるようにします。

第 4 ステップ：最初の変更を作成——ダークモードを追加

では AI に変更を手伝わせましょう。例として「アプリにダークモードを追加する」を取り上げ、AI にそのまま伝えます：

/opsx:propose add-dark-mode

AI は自動的に openspec/changes/add-dark-mode/ の下へ、4 つの Artifact ファイルを作成します：

openspec/changes/add-dark-mode/
├── proposal.md     # この変更は何のため？範囲？方針？
├── specs/
│   └── ui/spec.md  # UI ドメインの Delta 仕様
├── design.md       # 技術方針はどう設計する？
└── tasks.md        # 具体的に何をする？手順で列挙

proposal.md はこのような形です（AI が自動生成。あなたと AI が一緒に編集できます）：

# Proposal: Add Dark Mode

## Intent
ユーザーの要望によりダークモードを追加し、夜間利用時の目の疲労を軽減します。

## Scope
- 設定にテーマ切り替えボタンを追加
- システムの好み（プリファレンス）検出をサポート
- 好みを localStorage に永続化する

## Approach
CSS 変数でテーマを扱い、React Context で状態を管理します。

specs/ui/spec.md は重要な Delta 仕様で、形式は以下のとおりです：

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
システム SHALL ユーザーがライトテーマとダークテーマの間を切り替えられるようにする。

#### Scenario: Manual toggle
- GIVEN ユーザーが任意のページを開いている
- WHEN ユーザーがテーマ切り替えボタンをクリックする
- THEN テーマは即座に切り替わり、好みはセッションをまたいで永続化される

#### Scenario: System preference
- GIVEN ユーザーが保存した好みを持っていない
- WHEN アプリがロードされる
- THEN システムの優先カラースキームを使用する

tasks.md は実装チェックリストです：

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 ThemeContext（light/dark 状態）を作成
- [ ] 1.2 色の CSS 変数定義を追加
- [ ] 1.3 localStorage の永続化を実装

## 2. UI Components
- [ ] 2.1 ThemeToggle コンポーネントを作成
- [ ] 2.2 設定ページに切り替えボタンを追加
- [ ] 2.3 Header にクイック切り替えを追加

## 3. Styling
- [ ] 3.1 ダークテーマの配色を定義
- [ ] 3.2 既存コンポーネントが CSS 変数を利用するようにする

第 5 ステップ：実装タスクを実行

仕様書が問題ないことを確認したら、実装を実行します：

/opsx:apply

AI は tasks.md のタスクを 1 つずつチェックし、完了するたびにチェックを入れます。AI の振る舞いが変わっているのを見つけるはずです——もはや自由に進めず、tasks.md に厳密に従って前進します。実装の途中で設計に問題が見つかったら、直接 design.md を修正し、その後もう一度 apply してください。AI は自動的に追従します。

第 6 ステップ：検証して変更をアーカイブ

検証（任意だが推奨）：

/opsx:verify

AI は 3 つの観点からあなたの実装をチェックします：

アーカイブ：

/opsx:archive

アーカイブは 2 つのことを行います：

1. Delta 仕様を主仕様 openspec/specs/ui/spec.md にマージする
2. 変更フォルダを openspec/changes/archive/2026-04-11-add-dark-mode/ に移動する

アーカイブが完了すると、システム仕様ファイルが更新され、完全な変更履歴がもう 1 つ手に入ります。

第 7 ステップ：複数変更の並行管理

実際の開発では、途中で別の問題対応に割り込まれることがよくあります。OpenSpec は複数変更の並行をサポートします：

# add-dark-mode を作業中だと仮定して、突然バグ修正が必要になった
/opsx:new fix-login-redirect

# バグ修正を正常に完了
/opsx:ff
/opsx:apply
/opsx:archive

# 先にやっていたダークモードの作業に戻る
/opsx:apply add-dark-mode

複数の変更がすべて完了したら、一緒にアーカイブします：

/opsx:bulk-archive

OpenSpec は自動的に仕様の衝突を検出（2 つの変更がどちらも specs/ui/ を更新している等）し、時間順にマージします。

第 8 ステップ：カスタム Schema

OpenSpec の OPSX ワークフローは Schema に基づいて定義されており、Artifact の種類や依存関係を完全にカスタマイズできます。たとえば「先に調査して、次に提案する」ワークフローが欲しい場合：

# デフォルトの schema から新しい schema を派生
openspec schema fork spec-driven research-first

生成される Schema の構造：

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

対応する依存グラフはこうなります：

research ──► proposal ──► tasks

schema.yaml で定義します：

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []

  - id: proposal
    generates: proposal.md
    requires: [research]

  - id: tasks
    generates: tasks.md
    requires: [proposal]

第 9 ステップ：よく使う CLI コマンド早見表

# 初期化
openspec init

# AI スキルファイルを更新（アップグレードするたび、または profile を変更した後は毎回実行）
openspec update

# 現在の設定を確認
openspec config show

# ワークフロープロファイルを切り替え
openspec config profile

# アクティブな変更を確認
openspec list

# ある変更の詳細を確認
openspec show add-dark-mode

# フォーマットの検証
openspec validate add-dark-mode

# インタラクティブな Dashboard
openspec view

# Schema 管理
openspec schemas              # 利用可能な schema を一覧表示
openspec schema which --all   # schema の出どころを確認
openspec schema validate my-schema  # schema を検証

---

よくある問題のトラブルシューティング

1. AI が /opsx:propose コマンドを見つけられない

これは最もよくある問題です。openspec init を実行したあと、AI アシスタントはスキルファイルを再読み込みする必要があります。実行：

openspec update

その後、対話を開き直してください。AI がそれでも認識しない場合は、手動で .claude/ ディレクトリが存在するか確認します。

2. openspec init が Node.js のバージョンエラーを報告

node --version
# >= 20.19.0 を確認

# バージョンが低い場合は nvm でアップグレード
nvm install 20 && nvm use 20

3. Delta 仕様のマージで競合が起きる

/opsx:bulk-archive で、2 つの変更が同じ仕様ファイルを更新している場合、OpenSpec は検出して通知します。時間順にマージするのがデフォルト動作で、必要なら手動で対応します：

# まず 1 つだけ個別にアーカイブ
/opsx:archive fix-login-redirect

# 次にもう 1 つをアーカイブ
/opsx:archive add-dark-mode

4. カスタム Schema の読み込みに失敗する

通常は schema.yaml の構文エラーが原因です。次で確認します：

openspec schema validate my-schema

よくあるエラー：YAML のインデントが不正、artifact の requires フィールドが存在しない ID を参照している（循環依存）など。

5. AI が生成した仕様フォーマットが要件を満たしていない

openspec/config.yaml にルールを追加できます：

rules:
  specs:
    - GIVEN/WHEN/THEN 形式で各シーンを記述すること
    - 各 Requirement は少なくとも 1 つの Scenario を持つこと

これらのルールは、AI が生成する仕様への指示として注入されます。

6. /opsx:apply の途中で AI が一部タスクをスキップする

AI に直接こう伝えてください：

タスクは tasks.md の順番で実行してください。タスク 1.3 が未完了なので、スキップしないでください。

OpenSpec の fluid 特性により、いつでも Artifact を編集できます。tasks.md を修正したあとで apply すれば、AI は前回止まった位置から続行します。

---

拡張リーディング / 進むべき方向性

Delta Specs の形式を深掘り：ADDED/MODIFIED/REMOVED の 3 種類の変更タイプには、それぞれ意味があります——ADDED は新しい要求、MODIFIED は既存の要求を置き換える、REMOVED は不要になった要求を削除する、ということです。これらのマージ規則を理解してこそ、OpenSpec を使いこなせます。

OPSX と Legacy ワークフローの比較：OpenSpec v1.x は Legacy ワークフロー（/openspec:proposal）を使用し、v1.2+ では OPSX を推しています。両者の核心的な違いは次の通りです。Legacy は phase-locked（全部あり／全部なし）、OPSX は fluid（任意のタイミングで任意の Artifact を編集可能）。

20+ の AI ツール接続ガイド：OpenSpec は .claude/skills/ ディレクトリからスキルファイルを生成し、Claude Code、Cursor、Windsurf、Copilot などの主要ツールに対応しています。詳しくは docs/supported-tools.md を参照してください。

チーム Slack 統合：企業チームは [email protected] まで連絡すると、専用の Slack チャンネルサポートが受けられます。複数人協業での仕様管理・レビュー手順に適しています。

プロジェクト設定の深いカスタマイズ：context と rules 以外にも config.yaml でデフォルト Schema を設定したり、プロジェクトの技術スタック情報（テストフレームワーク、コードスタイル規約など）を注入したりできます。これにより、AI が生成する仕様が実際のプロジェクトにより密着します。