はじめに
Claude Code や Cursor を使って開発していると、「曖昧な仕様のまま実装が進んでしまう」問題に直面することが多いです。
AI は与えられた指示に忠実に従います。しかし、指示自体が曖昧だと意図しない実装になりがちです。また、生成されたコードの仕様がどこにも残らず、後から「このコードは何をするものだったのか」わからなくなることもあります。
この課題へのアプローチとして OpenSpec を試してみました。仕様を明確にしてから実装に進むワークフローを提供するフレームワークで、AI と協働しながら仕様駆動開発を実現できそうです。
OpenSpec とは
OpenSpec は、AI コーディングエージェントとの協働を前提とした仕様駆動開発フレームワークです。
主な特徴
- 軽量で、シンプルなワークフロー。最小限のセットアップで始められる
- 既存プロジェクトにも対応。新規開発（0→1）だけでなく、既存機能の修正（1→n）も可能
- 変更追跡に優れ、提案・タスク・仕様差分を一箇所で管理・監査できる
- ツール非依存で、Claude Code、Cursor、Codex など、どの AI ツールでも利用可能
特に「ツール非依存」は重要なポイントだと感じました。チームによって使う AI ツールが異なるケースは珍しくないので、特定のツールに縛られないのは良さそうです。
ディレクトリ構造
OpenSpec を導入すると、プロジェクトに openspec/ ディレクトリが作成されます。
openspec/
├── project.md # プロジェクトの規約
├── specs/ # 現在の仕様（実装済み）
│ └── [capability]/
│ └── spec.md
└── changes/ # 変更提案（実装前）
├── [change-name]/
│ ├── proposal.md # 変更の背景と影響
│ ├── tasks.md # 実装タスク
│ └── specs/ # 仕様の差分
└── archive/ # 完了した変更
specs/ には「今どうなっているか」、changes/ には「これからどう変えるか」が格納されます。この分離はシンプルながら効果的に見えます。「今の仕様」と「変更提案」が混ざらない設計は、運用上のメリットになりそうです。
他ツールとの比較
仕様駆動開発を支援するツールは他にもあるので、比較してみました。
| 観点 | OpenSpec | spec-kit | Kiro |
|---|---|---|---|
| 対象 | 新規・既存両方 | 新規・既存両方 | IDE 統合型 |
| ツール依存 | なし | なし | Kiro IDE |
| 変更追跡 |
specs/ と changes/ の分離で明確 |
仕様ファイル単体 | IDE 内で管理 |
| 導入コスト | 低い | 低い | IDE 移行が必要 |
個人的には、OpenSpec は以下のようなケースで特に可能性を感じています。
- 既存プロジェクトに途中から仕様管理を導入したい
- チームメンバーが異なる AI ツールを使っている
- 変更の履歴を追跡可能な形で残したい
導入方法
セットアップ
導入は簡単で、npm でインストールして初期化するだけです。
# グローバルインストール
npm install -g @fission-ai/openspec@latest
# プロジェクトで初期化
cd your-project
openspec init
CLAUDE.md への設定追加
Claude Code を使う場合、openspec init を実行すると CLAUDE.md に以下のような指示ブロックが自動で追加されます。
<!-- OPENSPEC:START -->
# OpenSpec Instructions
These instructions are for AI assistants working in this project.
Always open `@/openspec/AGENTS.md` when the request:
- Mentions planning or proposals (words like proposal, spec, change, plan)
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
- Sounds ambiguous and you need the authoritative spec before coding
Use `@/openspec/AGENTS.md` to learn:
- How to create and apply change proposals
- Spec format and conventions
- Project structure and guidelines
Keep this managed block so 'openspec update' can refresh the instructions.
<!-- OPENSPEC:END -->
これにより、AI が変更提案を求められた際に OpenSpec のワークフローに沿って動作するようになります。
実践ワークフロー
実際にどう使うのか、具体例で見ていきましょう。「ユーザープロフィールに自己紹介文を追加する」機能を実装する流れを説明します。
Step 1: 提案作成
AI に「ユーザープロフィールに自己紹介文を追加する変更提案を作成して」と伝えると、changes/add-user-bio/ に以下のファイルが生成されます。
まず proposal.md が生成されます。
# Change: ユーザープロフィールに自己紹介文を追加
## Why
ユーザーが自分自身を紹介できる機能がなく、プロフィールページが寂しい。
## What Changes
- User モデルに bio フィールドを追加
- プロフィール編集画面に自己紹介文入力欄を追加
- プロフィール表示画面に自己紹介文を表示
## Impact
- Affected specs: user-profile
- Affected code: User モデル、プロフィール画面
次に tasks.md が生成されます。
## 1. Implementation
- [ ] 1.1 User モデルに bio カラムを追加するマイグレーション作成
- [ ] 1.2 プロフィール編集フォームに bio フィールドを追加
- [ ] 1.3 プロフィール表示画面で bio を表示
- [ ] 1.4 テストを追加
最後に specs/user-profile/spec.md の差分も生成されます。
## ADDED Requirements
### Requirement: 自己紹介文
ユーザーは自分のプロフィールに自己紹介文を設定できなければならない（SHALL）。
#### Scenario: 自己紹介文の保存
- **WHEN** ユーザーがプロフィール編集画面で自己紹介文を入力して保存
- **THEN** 入力した自己紹介文がプロフィールに反映される
Step 2: レビューと調整
生成された提案を確認し、修正したい箇所があれば直します。AI と対話しながら仕様を詰めていきます。
Step 3: 実装
提案が固まったら、AI に実装を依頼します。AI は tasks.md に沿って実装を進め、完了したタスクにチェックを入れていきます。仕様が明確になっていれば、AI も迷わず実装できそうです。
Step 4: アーカイブ
実装が完了したら、AI に「変更をアーカイブして」と伝えて変更をアーカイブします。
これにより changes/add-user-bio/ が changes/archive/YYYY-MM-DD-add-user-bio/ に移動します。同時に specs/user-profile/spec.md に差分が統合されます。アーカイブすることで変更履歴が残り、後から「いつ、なぜこの変更をしたのか」を追跡できます。
チーム開発での活用
期待できるメリット
まず、ツール選択の自由度が高いです。チームメンバーが Claude Code、Cursor、Codex など異なるツールを使っていても問題ありません。OpenSpec は Markdown ベースなので、どのツールからも読み書きできます。チーム運用では重要なポイントになりそうです。
次に、仕様が自動的に蓄積される点です。OpenSpec のレールに沿って開発すると、自然と仕様がドキュメントとして残り、「コードはあるが仕様書がない」「変更の背景が分からない」という状況を防げます。
そして、レビューの質が向上しそうです。実装前に仕様を明文化するため、PR レビュー時に「この実装は仕様通りか」という観点でレビューできます。仕様と実装の乖離を早期に発見しやすくなりそうです。
課題
いくつか気になる点もあります。
まず、チーム全員がワークフローに従う必要がある点です。一部のメンバーだけが使っている状態では、仕様の整合性が保てません。導入するなら全員で足並みを揃える必要がありそうです。
次に、仕様の粒度の判断が難しそうです。どこまで詳細に書くか、どの変更に対して OpenSpec を適用するかの線引きは、チームで合意を取る必要があります。
また、まだ新しいツールなので、ドキュメントや事例が少ない点も気になります。困ったときに参照できる情報が限られているのは、導入のハードルになりそうです。
まとめ
OpenSpec を試してみて感じたのは、やっていること自体は一般的な開発フロー（仕様策定→実装→レビュー）だということです。ただ、仕様を明確化するプロセスが明示的に含まれており、AI と伴走しながら進められる点に可能性を感じました。
特に、仕様が曖昧な状態からエンジニアが作業に着手するような開発プロセスでは効果がありそうです。既存プロジェクトに途中から導入できる設計なので、興味があればまずは小さな機能追加から試してみてください。
Discussion