目次
OpenSpecとは
OpenSpecは、コーディングエージェントを用いた仕様駆動開発を支援するためのフレームワークです。コーディングエージェントを使った開発において、意図した設計を保ち、品質を確保するためには、単に作るものだけを指示してコードを生成させるのではなく、設計段階からAIと取り組む方法が広がっています。
とはいっても、必要な情報を設計ドキュメントとして抜け漏れなく残すのは簡単ではありません。特に、機能の増加によってコードベースが拡大したり、チーム開発へ移行したりすると、ドキュメント形式の整備や変更管理も必要になります。OpenSpecは、こうした課題の解決を支援するツールです。
OpenSpecでの開発フロー
いきなり実装を始めるのではなく、OpenSpecでは以下の手順に沿って開発を進めます。
- 開発対象を明確にする
- 仕様と設計を明確にする
- タスクリストを作成する
- 実装する
- 仕様差分をメイン仕様に取り込む
AIと人が対話しながら要件や設計方式を明確にし、生成された成果物をその都度人がレビューすることで、誤りを修正していきます。
OpenSpecは、この開発フローを実現するためのオープンなフレームワークとして提供されています。また、Claude CodeやCodex、GitHub Copilotなど主要なコーディングツールに対応しており、簡単なセットアップでOpenSpecを導入できます。
OpenSpecはセットアップ後に、コーディングエージェントからスラッシュコマンドを使うことで利用できます。今回利用したコマンドは以下となります。
- /opsx:explore : 要件の深掘り、明確化
- /opsx:propose : 仕様や設計のドキュメント化
- /opsx:update：仕様や設計の修正
- /opsx:apply：仕様に基づく実装
- /opsx:sync：変更仕様をメイン仕様に反映
- /opsx:archive：変更仕様のアーカイブ化
本記事では、この手順に従ってWebアプリケーションを開発したため、その内容を紹介します。
OpenSpecを用いて開発してみた
OpenSpecを導入し、カンバン方式のシンプルなToDo管理Webアプリを開発しました。今回は、Claude CodeのVS Code拡張機能を使用しました。実際の成果物はGitHubで公開しているので、あわせて参考にしてください。
OpenSpecのセットアップ
まず、プロジェクトディレクトリを作成し、OpenSpecをインストールします。OpenSpecは、npmを使ってグローバルにインストールします。
mkdir task-board
cd task-board
npm install -g @fission-ai/openspec@latest
実際に利用したバージョンは以下となります。
| ソフト | バージョン |
|---|---|
| Claude Code VS拡張 | 2.1.116 |
| Node.js | v24.14.0 |
| OpenSpec | 1.6.0 |
次に、OpenSpecを初期化します。今回はClaude Codeを使用するため、対象ツールとしてclaudeを選択します。
openspec init --tools claude
初期化後のディレクトリ構成は以下のようになります。.claude/以下にスラッシュコマンドやスキルが配置されていることがわかります。
openspec/以下は変更内容を管理するchanges/ディレクトリとメイン仕様を管理するspecs/が作成されています。初期化時点ではアーティファクトは存在していませんが、これ以降の生成ドキュメントがこのディレクトリに保存されます。
.
├─.claude
│ ├─commands
│ │ └─opsx
│ └─skills
│ ├─openspec-apply-change
│ ├─openspec-archive-change
│ ├─openspec-explore
│ ├─openspec-propose
│ ├─openspec-sync-specs
│ └─openspec-update-change
└─openspec
├─changes
│ └─archive
└─specs
要件と実装方針の整理（explore）
まず、/opsx:exploreコマンドを使って、要件や技術スタックなどを検討、整理します。今回はToDoアプリを作ることは決めていましたが、技術スタックやシステム構成は未検討だったため、要件を深堀りして明確化しました。
/opsx:exploreコマンドの実行後は、AIと対話しながら要件やシステム構成、それを実現するための技術スタックを順に決めていきます。/opsx:explore は、自動で検討結果をファイルへ保存しません。今回は、対話で決定した内容を後続のアーティファクト生成にも反映させるため、Claude Codeに依頼して.\openspec\config.yamlへ追記しました。.\openspec\config.yamlでは、プロジェクトの前提情報や、アーティファクトを生成する際のルールをYAML形式で設定できます。
今回生成したYAMLは、次のとおりです。プロダクトの概要、システム構成、技術スタックなどが記載されています。# 進め方 ではADRを残すことを明示しています。これは、AIとの対話中に、設計判断の根拠や背景を明文化するよう指示したためです。
schema: spec-driven
# Project context (optional)
# This is shown to AI when creating artifacts.
context: |
# プロダクト概要
task-board は個人ローカルで利用するカンバン方式のタスク管理 Web アプリ。
自分ひとりで使う前提であり、認証・マルチユーザー・同期などは対象外。
# 実行形態
- ローカルサーバ型 (ターミナルから起動、ブラウザで localhost にアクセス)
- 単一プロセス構成 (Next.js が UI とデータ永続化の両方を担う)
- 配布バイナリ化はしない (npm run dev 相当で起動)
# 技術スタック
- Next.js (App Router)
- TypeScript
- Tailwind CSS
- Server Actions (書き込み系 API はこれを使う。Route Handler は原則使わない)
- @dnd-kit (ドラッグ&ドロップ)
# データ永続化
- JSON ファイルにローカル保存
- 保存先: リポジトリ配下 ./data/tasks.json
- ./data/ は .gitignore 対象
- SQLite などの DB は現時点では採用しない (将来的な移行余地は残す)
# 進め方
- Spec-First で進める (実装より先に proposal / design / tasks / spec を書く)
- 設計判断の理由を残す:
* proposal.md には "何を作るか / 何を作らないか" とその Why
* design.md には "どう作るか / なぜその技術選択か" を ADR 形式で残す
* 却下した案とその理由も明記する
- 会話と成果物は基本日本語
# Per-artifact rules (optional)
rules:
design:
- 主要な技術選択については ADR セクションを設けて記録する
- ADR には「文脈・選択肢・決定・理由・却下した案の理由・トレードオフ」を含める
proposal:
- '"Non-goals" セクションを必ず含める'
設計・実装計画のドキュメント化（propose）
次に設計のドキュメントの作成や実装計画を/opsx:propose コマンドで実施します。/opsx:propose コマンドを実行すると、新しいChangeが作成され、実装に向けて必要な4種類のアーティファクトが生成されます。
proposalでは、なぜこの変更が必要なのか、何を変更するのか、どのような影響が出るかをproposal.mdにまとめます。
designでは、どのように実装するかをドキュメント化します。今回config.yamlにADRを残すように指定しているため、このドキュメントに設計判断内容とその理由が記載されています。
specsは、要件や振る舞いを詳細化し、明文化します。単一のファイルではなく、ケイパビリティごとに分割されます。
最後にtasksでは、ここまでのアーティファクトをもとに、実装フェーズで行うべき作業をチェックリスト形式でまとめます。後続の実装フェーズでは、このタスクリストに基づいて実装を進めます。
各アーティファクトに記載すべき内容や生成順序は、以下のスキーマで定義されています。
実際に生成されたファイルは、以下のとおりです。
| 生成物 | 中身 |
|---|---|
| proposal.md | 今回の変更に対するWhy / Non-goals / Impact |
| design.md | アーキテクチャ決定時のADR一覧 |
| specs/kanban-board/spec.md | カンバンUI側の要求事項詳細 |
| specs/task-persistence/spec.md | タスクデータ永続化側の要求 |
| tasks.md | 実装チェックリスト |
アーティファクトの更新（update）
先ほど生成されたdesign.mdには、いくつかの未解決事項が残っていました。実装段階で決定することもできますが、今回は実装前に方針を決め、ドキュメントに反映しました。アーティファクトの修正には、/opsx:update コマンドを使用できます。/opsx:update はあくまで生成済みアーティファクトを修正する必要があるときのみ使用するため、必須の工程ではありません。
実装（apply）
/opsx:proposeで生成し、/opsx:updateで修正したtasks.mdやspecs/を参照して、実装を始めます。実装は、/opsx:apply コマンドを使って進めます。tasks.mdはチェックリスト形式になっているため、未完了の項目を順に実施します。
今回はUI開発が中心であったため、AIだけでは十分に検証しにくい機能がありました。そのような機能については、検証をスキップするか、その都度人が介在して検証するかなど事前に相談したうえで、実装を進めました。今回は成果物をGitに反映して完了となりました。
参考として、動作確認時のWebアプリケーションの画面を以下に示します。タスクは、ドラッグ＆ドロップで状態を変更できます。今回のような小規模なアプリケーションであれば、AIと対話し、人がレビューや動作確認するだけで、比較的短時間に作成できました。
メイン仕様への反映（sync）
今回作成した仕様差分をメイン仕様へ反映します。次回以降の機能追加では、このメイン仕様が変更のベースとなります。メイン仕様への取り込みは/opsx:syncコマンドで実行します。今回は新規からの開発であったため、今回作成した仕様差分が、そのまま初期のメイン仕様となります。
また、実装時に決定した「必要に応じて人が介在してUIを検証する」という方針も、.\openspec\config.yaml に追記してルール化しました。そのため、次回以降の機能追加では、人によるUIの動作確認が標準手順となります。
アーカイブ化
最後に、完了した変更をアーカイブします。/opsx:archiveコマンドを実行すると、アーティファクトやタスク状況が確認され、仕様差分をメイン仕様に反映するか確認できます。その後、/opsx:proposeで生成し、/opsx:updateで修正したChangeフォルダを、アーカイブフォルダに移動します。これで、開発の1サイクルが完了となります。
まとめ
本記事ではOpenSpecを導入し、仕様駆動開発によってWebアプリケーションを開発しました。必要なドキュメントを、その内容も含めて作成する支援をしてくれるので非常にスムーズに開発を進められました。変更差分も、その都度アーカイブとして残せるので、チーム開発でも、変更内容や意図を把握しやすいと感じました。
今回は新規開発にOpenSpecを利用しましたが、既存プロジェクトに適用することもできるので、機会があれば試したいと思います。
