🦔

Claude CodeとOpenSpecを使った仕様駆動開発フロー

に公開
AI駆動開発
Claude Code
仕様駆動開発
OpenSpec
tech

はじめに

AIにコードを書かせていると、仕様が曖昧なまま実装が進んでいくことがよくあります。
そこで、仕様を明確にしてから実装に入る、いわゆる仕様駆動開発を助けるツールとして OpenSpec を導入してみました。
個人プロジェクトでしばらく使ってみたので、いまのところ落ち着いている開発フローを書いてみます。

OpenSpecとは

OpenSpecは、Fission AIが開発しているOSSの仕様駆動開発フレームワークです。

https://github.com/Fission-AI/OpenSpec

特徴

個人的に「いいな」と感じているポイントを並べると、こんな感じです。

  • 軽量なフレームワーク
    シンプルなワークフローで、出力される仕様書の分量も必要十分。AIによくある過剰な出力も抑えられている印象です。
  • 仕様が育つ
    仕様書がMarkdownで openspec/ 配下に積み上がっていき、過去の仕様とも自然にマージされるので経緯を追いやすい。
  • 1つの変更ごとに「change」というフォルダが切られる
    proposal（なぜやるか） / specs（要件） / design（設計） / tasks（実装チェックリスト）がワンセットで揃うので、議論・設計・実装が1箇所にまとまる。
  • エディタ・エージェント非依存
    Claude Code / Codex / Cursor / Cline など20以上のAIアシスタントに対応しているので、チーム内で別のエージェントを使う人がいてもワークフローを変えずに済む。

導入方法

npmパッケージとして配布されているのでインストールして初期化するだけで使い始められます。

install
# グローバルインストール（推奨）
npm install -g @fission-ai/openspec@latest

# プロジェクトに導入
cd your-project
openspec init

ディレクトリ構造

openspec init を実行すると、プロジェクト直下に openspec/ ディレクトリが作られます。
そのあと /opsx:new <変更名> で1つ提案を作ると、以下のような構造ができあがります。

openspec/
├── specs/                    # 確定済みの仕様（archive時に反映される）
│   └── <capability>/         # 機能単位ごとにフォルダが切られる
└── changes/
    ├── <change_name>/        # 進行中のchange（1変更=1フォルダ）
    │   ├── proposal.md       # なぜこの変更が必要か / 何をするのか
    │   ├── design.md         # 技術的なアプローチ・設計判断
    │   ├── tasks.md          # 実装タスクのチェックリスト
    │   └── specs/            # この変更で追加・更新される仕様の差分
    └── archive/
        └── 2026-05-28-<change_name>/   # 完了したchangeはここへ移動する

ポイントは、

  • 「いま進行中の変更」は changes/<change_name>/ に置かれる
  • 「確定した仕様」は specs/ にマージされる
  • 「過去の経緯」は changes/archive/ にスタックされる

という3層構造になっていることです。

主要コマンド

デフォルトでインストールされるのは propose / explore / apply / sync / archive の5コマンドだけです。ただ、これだけだと仕様を段階的に詰めたり、実装と仕様のズレを検出したりといった用途で物足りなく感じる場面が多かったです。

OpenSpecには拡張のコマンドも一通り用意されているので、最初から全部有効化してしまうのがオススメです。

拡張機能を有効化する

openspec config profile を実行すると、有効化するワークフローをインタラクティブに選べます。

openspec config profile

openspec config profile のワークフロー選択画面

デフォルトで無効になっているものも、スペースキーでチェックしておきます。
Enterで確定したら、以下のコマンドを実行してアップデート。

openspec update

これで全てのコマンドが呼び出せるようになります。

よく使うコマンド

普段使うコマンドを整理するとこんな感じです。

コマンド 役割
/opsx:explore アイデア出し・要件の深堀り。仕様化の前段で壁打ちに使う。
/opsx:new <change-name> 変更フォルダの雛形だけ作成（中身は空）
/opsx:continue 次に作るべきアーティファクトを1つずつ生成。段階的にレビューできる。
/opsx:apply tasks.md に沿って実装を進める。
/opsx:verify 実装が proposal / specs / design と一致しているかを整合性チェック。
/opsx:archive 完了したchangeを changes/archive/ に移動。

特に効いてくるのが以下の2つで、これらがデフォルトでは無効になっているので、最初から拡張機能を有効化しておきたい主な理由になっています。

  • /opsx:continue … proposal → design → specs → tasks を1つずつ確認しながら作れるので、AIに一気に全部書かせてしまう事故が防げる
  • /opsx:verify … 実装が進んだあとに、コードが仕様（proposal/specs/design）からズレていないかをAIに検証させられる

（今のところの）仕様駆動開発フロー

ここまででOpenSpecの概要は紹介できたので、実際にどんなフローで使っているかを書いていきます。

個人プロジェクトで回しながらちょこちょこ手を入れているので、来月には別のことを言っているかもしれません。

それでも、最近はだいたい以下のような流れに落ち着いていて、そこそこいい感じになってきたので、現時点のスナップショットとして残しておきます。

ざっくり言うと、「ふわっとした要件をAIと一緒に分解 → 仕様書を1ファイルずつレビュー → tasks単位で実装＆レビュー → 最後に仕様と実装の整合性チェック」というループです。
以下、各Stepで実際に何をしているかを順番に書いていきます。

Step 1: 要件の深堀り

「スタッフを登録したい」のような粒度のふわっとした要件を、/opsx:explore で壁打ちしながら以下4項目が埋まるレベルまで深堀りします。

  • 目的: 何を解決したいのか
  • スコープ: 今回やること
  • スコープ外: 今回やらないこと
  • 受入条件: 何をもって完了とするか

Step 2: OpenSpecアーティファクト（仕様書）作成

/opsx:new <チケット内容> で空のchangeフォルダを作り、そのあとは /opsx:continue で proposal.md → specs.md / design.md → tasks.md の順に1ファイルずつ生成していきます。

各ファイルができたら必ずレビューを挟み、気になる箇所はその場で直してから次のアーティファクトに進みます。
一気に全部書かせると後段になるほど前段の誤りが効いてくるので、面倒でも1ファイルずつレビューしたほうが結果的に仕様の精度は上がります。

Step 3: TDD（テスト駆動開発）で実装

OpenSpecはデフォルトではTDD形式で実装しません。
そこで openspec/config.yaml に tasks 生成時のルールを書いておき、RED → GREEN → REFACTOR の3タスクに自動分割されるようにしています。

openspec/config.yaml
schema: spec-driven

context: |
  ...

rules:
  tasks:
    - テスト可能な振る舞いを持つ実装単位は、必ず RED → GREEN → REFACTOR の3タスクへ分割する。
    - "RED タスク: 期待する振る舞いを表す失敗するテストを先に書き、実行して失敗（レッド）することを確認する内容にする。タスク文は `RED: ` で始める。"
    - "GREEN タスク: RED で書いたテストを通す最小限の実装を行う内容にする。タスク文は `GREEN: ` で始める。"
    - "REFACTOR タスク: テストを緑に保ったまま重複・命名・構造を整理する内容にする。整理不要なら省略してよい。タスク文は `REFACTOR: ` で始める。"
    - 1つの RED-GREEN-REFACTOR サイクルは1つの実装単位（凝集した関数・コンポーネント）を対象とし、その RED タスクでは当該単位の正常系・異常系をまとめてテストしてよい。独立した実装単位が複数あれば、単位ごとにサイクルを分ける。
    - テストは Vitest で記述し、テスト対象ソースと同じディレクトリへ co-locate する（`*.test.ts` / `*.test.tsx`）。

rules.tasks に書いたルールは、/opsx:continue で tasks.md を生成するときに反映されます。

こうしておくと、Step 2 で出来上がる tasks.md のチェックリストが最初から RED: ... / GREEN: ... / REFACTOR: ... の3点セットで並ぶようになります。
あとは /opsx:apply を回せば、テスト → 実装 → リファクタの順で進めてくれるので、自然とTDDのサイクルに乗せられます。

Step 4: AIコードレビュー

実装が一段落したら、2種類のAIレビューをかけています。

  • Claude Codeの /simplify … 直近のdiffをコード再利用 / コード品質 / 効率性の3観点で並列にレビューし、改善できる箇所は自動で修正してくれる（最近 /code-review --fix に統合されました）
  • OpenSpecの /opsx:verify … 実装が proposal / specs / design からズレていないかを整合性チェックする

「コードそのものの品質」と「仕様と合っているか」は別の観点なので、この2段階でレビューを掛けるのがいい感じです。

Step 5: アーカイブ

最後に、/opsx:archive でchangeをアーカイブします。

  • changes/<change_name>/specs/ の変更差分の仕様（デルタスペック）を specs/ 配下にマージ（確定仕様として固定）
  • 完了したchangeフォルダを changes/archive/YYYY-MM-DD-<change_name>/ に移動

このフローのメリット

  • AIに任せても破綻しにくい
    /opsx:continue で段階レビューを挟むので、AIが前提を取り違えたまま一気に実装まで突き進む、という事故が起きにくいです
  • 仕様と実装が同期する
    /opsx:verify で機械的に乖離をチェックできるので、「仕様書はあるけど実態は別」になりにくいです
  • TDDが自然と回る
    openspec/config.yaml のおかげで tasks.md が最初から RED/GREEN/REFACTOR で並ぶので、自然とテストファーストで実装が進みます

このフローのデメリット

  • 小さい変更にはオーバースペック
    ちょっとしたバグ修正など、軽微な変更にはこのフローは重すぎるかもしれません
  • リードタイムは伸びる
    仕様書ごとにレビューを挟むぶん、書き殴って実装するより素直に遅くなります。速くなるというより質が上がるタイプですね

おわりに

OpenSpecで一番気に入っているのは、openspec/config.yaml を書くだけでチーム独自の開発フローに寄せられるところです。今回はTDD（RGR分割）を rules.tasks に焼き付けましたが、他にもいろんなルールを追加できるので、チームの文化やプロジェクトの特性に合わせて柔軟に運用できるのがいいですね。

冒頭にも書いたとおり、これはいまのところのスナップショットです。
特に openspec/config.yaml はまだ調整余地があると思っているので、もっと良い運用があったらぜひ教えてください。

Discussion