はじめに
Claude Code のような AI コーディングエージェントに「いい感じに作って」と頼むと、確かにそれっぽいコードは出てきます。ただ、
- 会話の途中で要件がブレて、どこまで合意したのか分からなくなる
- セッションを跨ぐと前回の前提が失われる
- 「なぜこの実装になったのか」が後から追えない
といった問題にぶつかりがちです。
これを解決するアプローチが 仕様駆動開発(Spec-Driven Development) で、その代表的なツールが OpenSpec です。本記事では、Claude Code と OpenSpec を組み合わせた開発フローを、proposal や changes といった用語の意味を中心に解説します。
本記事は OpenSpec v1.9.0 時点の内容です。OpenSpec は更新が速く、旧バージョン(/openspec:proposal 系のコマンドや AGENTS.md / project.md を使う構成)とは細部が異なります。
OpenSpec とは
OpenSpec は、人間と AI が「何を作るか」を先にファイルで合意してから実装するための軽量なフレームワークです。
ポイントは次の 2 つです。
- 仕様(specs)を Markdown でリポジトリに置く:チャット履歴ではなく、Git 管理されたファイルが「真実の情報源」になる
- 変更(changes)を仕様への差分として扱う:今の仕様と、これから加える変更を明確に分けて管理する
導入
npm install -g @fission-ai/openspec
cd your-project
openspec init --tools claude
openspec init を実行すると、次のファイルが生成されます。
your-project/
├── .claude/
│ ├── commands/opsx/ # スラッシュコマンド(/opsx:propose など)
│ │ ├── explore.md
│ │ ├── propose.md
│ │ ├── update.md
│ │ ├── apply.md
│ │ ├── sync.md
│ │ └── archive.md
│ └── skills/openspec-*/ # 各コマンドに対応する Skill
└── openspec/
├── config.yaml # プロジェクト設定
├── specs/ # 現在の仕様(真実の情報源)
└── changes/ # 進行中の変更
└── archive/ # 完了した変更
Claude Code 側には /opsx:* というスラッシュコマンドと Skill がインストールされ、Claude が OpenSpec の CLI を叩きながらファイルを作っていく仕組みになっています。
用語とディレクトリの意味
OpenSpec で一番とっつきにくいのが用語です。ここを押さえると全体像が一気に分かります。
全体像
openspec/
├── config.yaml
├── specs/ ← 「今、システムがどう振る舞うか」
│ └── user-auth/
│ └── spec.md
└── changes/ ← 「これから、どう変えるか」
├── add-dark-mode/ ← 1つの変更 = 1フォルダ
│ ├── .openspec.yaml
│ ├── proposal.md ← なぜ・何を
│ ├── design.md ← どうやって
│ ├── tasks.md ← 作業手順
│ └── specs/ ← 仕様への差分(delta)
│ └── ui-theme/
│ └── spec.md
└── archive/
└── 2026-09-01-add-login/ ← 完了した変更
specs/:現在の仕様
「システムが今どう振る舞うべきか」を表す、プロジェクトの正本です。機能のまとまり(OpenSpec では capability と呼びます)ごとにフォルダを切り、spec.md を置きます。
specs/ は直接編集せず、後述する changes を archive したときに更新される、という運用が基本です。
changes/:変更の提案
「これから仕様をこう変えたい」という提案をまとめる場所です。機能追加・仕様変更・機能削除など、1 つの変更ごとに changes/<change-name>/ というフォルダを作ります(名前は add-dark-mode のような kebab-case)。
Git に例えると、specs/ が main ブランチ、changes/<name>/ がフィーチャーブランチ、のようなイメージです。複数の change を並行して進めることもできます。
change フォルダの中には、次の 4 つの artifact(成果物) を順番に作ります。
| artifact | ファイル | 役割 | 一言でいうと |
|---|---|---|---|
| proposal | proposal.md |
変更の動機と範囲 | なぜ・何を |
| specs | specs/**/spec.md |
仕様への差分 | 何ができるべきか |
| design | design.md |
技術的な設計判断 | どうやって |
| tasks | tasks.md |
実装のチェックリスト | どの順で作るか |
依存関係は proposal → specs / design → tasks です。openspec status を実行すると、どこまでできているかを確認できます。
$ openspec status --change add-dark-mode
Progress: 0/4 artifacts complete
[ ] proposal
[-] specs (blocked by: proposal)
[-] design (blocked by: proposal)
[-] tasks (blocked by: specs, design)
proposal.md:なぜ、何を変えるのか
変更の土台となるドキュメントです。実装方法(How)ではなく、動機(Why)と範囲(What) に集中して書きます。
## Why
夜間の利用者から「画面がまぶしい」という声が多く、離脱の一因になっている。
## What Changes
- ダークモードを追加する
- OS の設定に追従する自動切り替えを追加する
- ヘッダーに手動切り替えトグルを追加する
## Capabilities
### New Capabilities
- `ui-theme`: 画面テーマ(ライト/ダーク)の切り替え
### Modified Capabilities
- `user-settings`: テーマ設定の保存を追加
## Impact
- 全コンポーネントの色指定(CSS 変数化が必要)
- ユーザー設定 API
特に重要なのが Capabilities セクションです。ここに挙げた capability ごとに、次の specs/ で差分ファイルを作ることになります。proposal と specs をつなぐ「契約」の役割を持っています。
changes/<name>/specs/:仕様の差分(delta spec)
ここが OpenSpec の核心です。change 内の specs/ には、仕様全体ではなく「差分」だけを書きます。
## ADDED Requirements
### Requirement: テーマの自動切り替え
システムは OS のカラースキーム設定に応じてテーマを切り替えなければならない(SHALL)。
#### Scenario: OS がダークモードの場合
- **WHEN** ユーザーの OS がダークモードに設定されている
- **THEN** 初回表示時にダークテーマが適用される
#### Scenario: ユーザーが手動で選択済みの場合
- **WHEN** ユーザーが過去にライトテーマを手動選択している
- **THEN** OS の設定に関わらずライトテーマが適用される
差分は次の 4 種類の見出しで表現します。
| 見出し | 意味 | 注意点 |
|---|---|---|
## ADDED Requirements |
要件の追加 | |
## MODIFIED Requirements |
要件の変更 | 変更後の全文を書く |
## REMOVED Requirements |
要件の削除 | Reason(理由)と Migration(移行方法)が必須 |
## RENAMED Requirements |
名前の変更のみ |
FROM: / TO: 形式で書く |
各要件は ### Requirement: で始め、#### Scenario: に WHEN / THEN 形式で具体的な振る舞いを書きます。シナリオはそのままテストケースの素になります。
spec はあくまで振る舞いの契約です。クラス名、ライブラリの選定、実装手順などは書きません。「実装を変えても外から見た振る舞いが変わらないなら、それは spec に書くことではない」が判断基準です。
design.md:どうやって作るか
技術的な設計判断とその理由を書きます。小さな変更なら省略されることもあります。
## Context
現状、色は各コンポーネントにハードコードされている。
## Goals / Non-Goals
**Goals:** CSS 変数によるテーマ切り替え
**Non-Goals:** ユーザー独自のカスタムテーマ
## Decisions
- `prefers-color-scheme` と `data-theme` 属性を併用する
- 代替案:CSS-in-JS のテーマプロバイダ → バンドルサイズ増のため不採用
## Risks / Trade-offs
- 既存コンポーネントの色の置き換え漏れ
「なぜこの設計にしたのか」が残るので、後から見返したときに非常に役立ちます。
tasks.md:実装のチェックリスト
実装をどの順番で進めるかを、チェックボックス付きのリストにします。
## 1. 基盤
- [ ] 1.1 カラートークンを CSS 変数として定義する
- [ ] 1.2 テーマ切り替えロジックを実装する
## 2. UI
- [ ] 2.1 ヘッダーにトグルを追加する
- [ ] 2.2 既存コンポーネントの色指定を CSS 変数に置き換える
## 3. テスト
- [ ] 3.1 各シナリオに対応するテストを追加する
Claude Code は実装中にこのチェックボックスを [x] に更新していくので、進捗がファイル上で見えます。セッションが途切れても、続きから再開できます。
archive/:完了した変更
実装が終わった change は changes/archive/YYYY-MM-DD-<name>/ に移動します。このとき、delta spec の内容が openspec/specs/ の正本に反映されます。
つまり archive とは、**「変更を仕様の正本に取り込み、その経緯を履歴として残す」**操作です。
config.yaml:プロジェクトの前提
AI が artifact を作るときに参照するプロジェクト共通の設定です。
schema: spec-driven
context: |
Tech stack: TypeScript, Next.js, Supabase
コミットメッセージは Conventional Commits
ドキュメントは日本語で書く
rules:
proposal:
- 必ず Non-goals を含める
tasks:
- 1タスクは最大2時間程度に分割する
技術スタックや規約を書いておくと、生成される proposal や tasks の質が大きく上がります。最初に必ず設定しておきたいファイルです。
Claude Code での開発フロー
ここからは、実際に Claude Code で 1 つの機能を開発する流れを見ていきます。
/opsx:explore → /opsx:propose → レビュー・/opsx:update → /opsx:apply → /opsx:archive
(相談) (計画を作る) (計画を詰める) (実装) (仕様に反映)
Step 1. /opsx:explore ― アイデアを整理する(任意)
/opsx:explore ダークモード対応したいけど、どこから手をつけるべき?
考えるためのモードです。Claude はコードベースを調べたり、選択肢を比較したりしますが、コードは書きません。要件がまだ固まっていないときに使います。
Step 2. /opsx:propose ― change を作る
/opsx:propose ダークモードを追加したい。OS設定に追従しつつ手動でも切り替えられるように
Claude が openspec/changes/add-dark-mode/ を作成し、proposal → specs → design → tasks を一気に生成します。
このコマンドは計画だけを行い、実装には進みません。人間がレビューする時間が確保されている点が重要です。
Step 3. レビューと /opsx:update ― 計画を詰める
生成された artifact を読み、気になる点を修正します。
/opsx:update 手動切り替えはヘッダーではなく設定画面に置きたい
/opsx:update を使うと、proposal・specs・design・tasks の整合性を保ったまままとめて修正してくれます。
あわせて CLI で検証しておくと安心です。
openspec validate add-dark-mode --strict # フォーマットや必須項目のチェック
openspec show add-dark-mode # 内容の確認
このレビューが最も大事な工程です。 実装前の段階で認識のズレを潰せるので、「作ってもらったけど思ってたのと違う」という手戻りが大きく減ります。
Step 4. /opsx:apply ― 実装する
/opsx:apply add-dark-mode
Claude が tasks.md を上から順に実装し、完了したタスクにチェックを付けていきます。proposal・specs・design を読み込んだうえで実装するため、途中で要件がブレにくくなります。
セッションが切れても、もう一度 /opsx:apply を実行すれば未完了のタスクから再開できます。
Step 5. /opsx:archive ― 仕様に反映して完了
/opsx:archive add-dark-mode
実装とテストが終わったら archive します。
- delta spec の内容を
openspec/specs/にマージする(openspec/specs/ui-theme/spec.mdが新規作成されるなど) - change フォルダを
changes/archive/2026-09-26-add-dark-mode/に移動する
これで「今の仕様」が最新になり、次の change はこの仕様を前提に作られます。
/opsx:sync を使うと、archive せずに delta spec だけを先に specs/ へ反映できます。長期間の change で、途中の仕様を他の change と共有したいときに便利です。
よく使う CLI コマンド
スラッシュコマンドの裏では、OpenSpec の CLI が動いています。人間が状況を確認するときにも便利です。
| コマンド | 用途 |
|---|---|
openspec list |
進行中の change 一覧 |
openspec list --specs |
spec 一覧 |
openspec view |
対話型ダッシュボード |
openspec show <name> |
change / spec の内容表示 |
openspec status --change <name> |
artifact の進捗 |
openspec validate <name> --strict |
フォーマット検証 |
openspec archive <name> |
change の archive |
openspec update |
指示ファイルを最新版に更新 |
運用のコツ
-
config.yamlのcontextは最初に書く:技術スタックや規約を書くだけで、生成物の質が大きく変わります - 1 change = 1 つの目的:「ダークモード追加」と「ログイン改善」を 1 つの change に混ぜない
-
振る舞いが変わらない変更は specs を作らない:リファクタやツール整備だけの change は、
.openspec.yamlにskip_specs: trueを設定します(archive --skip-specsでも可) - change フォルダも Git にコミットする:PR に proposal と spec の差分が載るので、レビュアーが「何のための変更か」を理解しやすくなります
-
既存プロジェクトでは、触る部分から spec を書く:最初から全機能の spec を揃える必要はありません。変更のたびに少しずつ
specs/が育っていきます
まとめ
| 用語 | 意味 |
|---|---|
specs/ |
今のシステムの振る舞い(正本) |
changes/<name>/ |
これから加える 1 つの変更 |
proposal.md |
なぜ・何を変えるのか |
| delta spec | 仕様への差分(ADDED / MODIFIED / REMOVED / RENAMED) |
design.md |
どうやって作るか、設計判断の理由 |
tasks.md |
実装のチェックリスト |
| archive | 差分を正本にマージし、履歴として残す |
OpenSpec を使うと、Claude Code との開発が「チャットでのその場のやり取り」から「ファイルで合意して、合意どおりに作る」プロセスに変わります。特に「propose → レビュー → apply」の流れで、実装前に人間が計画を確認できる点が大きな価値です。
AI に任せる範囲が広がるほど、「何を作るか」を明確にしておく重要性は増していきます。ぜひ試してみてください。