こんにちは、とまだです。

みなさん、AI駆動開発でコードは書けるようになったけど、要件定義や設計がうまくいかないと感じたことはありませんか？

実は私も最初は「AIに任せすぎて何を作っているのか見失う」という経験をよくしていました。

今回は、Codex CLI専用の仕様駆動開発ツール「Spec Driven Codex」を作ったので、その使い方と実践例を紹介します！

忙しい人のために要約

Codex CLI対応の仕様駆動開発ツールをOSSでリリース
1コマンドで導入できて既存プロジェクトにも使える
要件定義→設計→実装の流れを6つのコマンドで実現
実務でも個人開発でも効果を実感

仕様駆動開発とは？

仕様駆動開発は、コードを書く前に仕様書を作成し、その仕様書に基づいてコードを生成する開発手法です。

Kiro での採用をきっかけに、AI駆動開発の文脈でも注目されています。

日常生活で例えると、料理を作る前にレシピを決めるようなものですね。

いきなり食材を切り始めるのではなく、まず「何を作るか」「材料は何か」「手順はどうするか」を決めてから調理を始めます。

なぜ今、仕様駆動開発が注目されるのか

AI駆動開発が当たり前になった今、新たな課題が生まれています。

AIに任せすぎて、何を作っているのか見失ってしまう。
要件が曖昧なまま実装に入り、後から大きな手戻りが発生する。

こうした問題に対して、仕様駆動開発は明確な答えを提供します。

要件定義→設計→実装という自然な流れに沿って、AIと人間が適切に協業できるというわけです。

Codex CLI に仕様駆動開発ツールが必要だった理由

Claude CodeやCursor、Gemini CLIなど、VS Code系のエディタには既存の仕様駆動開発ツール（spec-kit、cc-sddなど）があります。

別な記事でも、国産ツール cc-sdd を紹介しました。

しかし、Codex CLIには対応していませんでした。

なぜかというと、Codex CLIはカスタムコマンドの引数受付に制限があるという技術的な制約があったからです。

そこで私は、Codex CLI専用の仕様駆動開発ツール「Spec Driven Codex」を OSS として開発しました。

NPMパッケージとして公開しているので、コマンド一発で誰でも使えます。

Spec Driven Codexの導入方法

シンプルさを大事にしているので、導入は超簡単です。

プロジェクトのルートディレクトリで以下のコマンドを実行するだけ。

# 日本語版
npx spec-driven-codex init --locale ja

# 英語版（デフォルト）
npx spec-driven-codex init

これで以下が自動的に整います。

.sdd/ ディレクトリ構造の生成
Codex CLI用プロンプト（6個）の配置
機能説明テンプレートの作成

既存のプロジェクトでも、新規プロジェクトでも、すぐに始められます。

ちなみに、--locale ja を付けると日本語版のテンプレートが生成されます。
また、コマンド実行時の出力も日本語になりますので、日本語環境の方はぜひ付けてください。

6つのステップで進む仕様駆動開発

それでは実際の開発フローを、4択クイズアプリの実装を例に見ていきましょう。

1. Steering（舵取り）でプロジェクト理解

まずはプロジェクトの全体像を把握します。

Steering の目的は、AIにプロジェクトの文脈を理解させることです。

では、あらかじめ Codex CLI を起動しましょう。

codex

そして、以下のコマンドを実行します。

/sdd-steering

このコマンドを実行すると、以下3つのドキュメントが自動生成されます。

.sdd/steering/
├── product.md      # プロダクト概要
├── tech.md        # 技術スタック
└── structure.md   # プロジェクト構造

例えば、Vite + React + TypeScriptのプロジェクトなら、その構成を自動で解析してドキュメント化してくれます。

これにより、AIがプロジェクトの全体像を理解できるようになります。

このコマンドは定期的に実行して、プロジェクトの変化を記録しておくと良いでしょう。

2. description.md に「やりたいこと」を記載

次に、実装したい機能を明確にします。

Codex CLI ではコマンド実行時に引数を渡せません。
そこで、インストール時に生成される.sdd/description.md に実装したい機能の概要を記載します。

今回は.sdd/description.md に以下のような内容を記載します。

# 実装したい機能

## 概要
4択式のクイズアプリを作成します。
ユーザーはクイズに回答し、正解数に応じてスコアが表示されます。

## 詳細
- MVPなので3問だけクイズを出題します
- 英単語の日本語訳を4択で答える形式にします
- JSONでクイズデータを管理します

シンプルな記述で大丈夫です。
詳細は次のステップで詰めていきます。

3. Requirements（要件定義）で要件を明確化

では、要件定義に進みます。

/sdd-requirements

このコマンドで、機能要件と受入基準を含む要件定義書が生成されます。

生成される .sdd/specs/multiple-choice-quiz/requirements.md には、以下のような内容が含まれます。

機能概要
ユーザーストーリー
機能要件（受入基準付き）
非機能要件

例えば、このようにユーザーストーリーや受入基準が明確に定義されます。

# 要件定義書

## 機能概要
英単語の日本語訳を4択で答える全3問のクイズを提供し、回答数に応じたスコアを表示するフロントエンド機能を実装する。

## ユーザーストーリー
- 学習者として、英単語の意味をクイズ形式で復習したい。なぜなら短時間で語彙力の定着度を確認したいから。

## 機能要件
### 要件1：クイズデータの読み込み
- クイズに使用する問題・選択肢・正答をJSON形式で管理し、アプリ起動時に読み込む。
- 受入基準：
  - [ ] JSONファイルには少なくとも3問分のデータが含まれていること。
  - [ ] 各問題が4つの選択肢と正解情報を持ち、UIに表示できること。

### 要件2：問題の出題と回答操作

...
...

「完成」の定義が曖昧になることを防げます。

実務で使う場合には、このタイミングでチームメンバーと要件をレビューして承認を得ると良いでしょう。

4. Design（設計）でアーキテクチャを決定

次に、設計フェーズです。

/sdd-design

設計フェーズでは、技術的な詳細が決まります。

.sdd/specs/multiple-choice-quiz/design.md には以下が含まれます。

アーキテクチャ概要
主要コンポーネントの責務
データモデル
処理フロー
エラーハンドリング

例えば、Reactコンポーネントの構成などを含めた設計書が生成されます。

# 技術設計書

## アーキテクチャ概要
既存プロジェクトは Vite + React + TypeScript のシングルページアプリケーションで構成されている。クイズ機能はクライアントサイドで完結する UI 機能として `App` コンポーネントに統合し、外部バックエンドを持たない。クイズデータは `public/quiz-data.json` に配置し、アプリ起動時に `fetch` で取得する。取得後は React のステート管理で進行状態を保持し、結果表示まで単一ページ内で遷移する。

## 主要コンポーネント
### コンポーネント1：`QuizApp`
- 責務：クイズデータの取得、現在の問題・スコア・進行状態の管理、UI の条件分岐表示を行うトップレベルコンテナ。
- 入力：`fetch` で取得した `QuizQuestion[]`。再挑戦時にはリセットされたステート。
- 出力：`QuestionCard` もしくは `ResultScreen` の描画。ユーザー操作に応じた状態更新。
- 依存関係：`QuestionCard`、`ResultScreen`、ブラウザの `fetch` API。

### コンポーネント2：`QuestionCard`
...

既存コードとの統合方法も明記されるので、実装時に迷いません。

5. Tasks（タスク分解）で実装計画を作成

では、実装計画を立てましょう。

/sdd-tasks

実装可能な粒度にタスクを分解します。

.sdd/specs/multiple-choice-quiz/tasks.md には、チェックボックス付きのタスクリストが生成されます。

## セクション1：データモデル実装
- [ ] 1.1 クイズ用の型定義とバリデーションを実装する
- [ ] 1.2 クイズデータの読み込み処理を実装する

## セクション2：ビジネスロジック実装
- [ ] 2.1 QuizAppの進行制御ロジックを実装する
- [ ] 2.2 結果画面および再挑戦処理を実装する

進捗が一目瞭然で、何をすればいいか明確です。

次の実装コマンドも、これらのチェックボックスを参照して動作しますので、タスクの抜け漏れがありません。
また、大規模な実装でも途中で中断して、後から再開することも容易です。

6. Implementation（実装）で開発スタート

いよいよ実装です。
以下のコマンドを実行します。

/sdd-implement

このコマンドを実行すると、tasks.mdのタスクを一つずつ順番に実装してくれます。

興味深いのは、タスクリストのチェックボックスに自動でチェックが入ること。

進捗が可視化されるので、達成感を感じながら開発を進められます。

実際の動画では、約10分で完全なクイズアプリが完成しました。

ちなみにコマンド実行時に送信されるプロンプトのおかげで、テスト駆動開発（TDD）で進みますので、品質も確保されています。

実装後のアーカイブ

開発が完了したら、以下のコマンドで成果物をアーカイブします。

/sdd-archive

完了したスペックが日付付きで保存され、次の機能開発の準備が整います。

specs
└── archives
│   └── 20250924_multiple-choice-quiz
│       ├── design.md
│       ├── requirements.md
│       └── tasks.md

知識の蓄積と再利用ができるので、チーム開発でも有効ですね。
また、個人開発でも過去の仕様を振り返るのに役立ちます。

生成される構造の詳細

一通りの流れを見てきましたが、生成されたディレクトリ構造は以下の通りです。

プロジェクト/
├── .sdd/
│   ├── description.md        # 実装したい機能の説明
│   ├── target-spec.txt      # 現在作業中のspec名
│   ├── steering/            # プロジェクトの記憶
│   │   ├── product.md      # 製品情報
│   │   ├── tech.md         # 技術情報
│   │   └── structure.md    # 構造情報
│   └── specs/              # 各機能の仕様
│       ├── user-auth/      # 例：認証機能
│       └── archives/       # 完了済み仕様
│           └── 20250924_multiple-choice-quiz # 日付付きで保存
│               ├── design.md
│               ├── requirements.md
│               └── tasks.md
└── src/                     # 既存のソースコード

仕様と実装が同じリポジトリで管理され、Gitによるバージョン管理も自然に行えます。

実際の使用感と効果

Spec Driven Codexを実際に使ってみて感じた効果を紹介します。

複雑な実装でもAIと認識を合わせられる

AIに複雑な機能を実装してもらうとき、以前は長い説明を何度も繰り返していました。

でも仕様書があれば、コマンド一つで済みます。

/sdd-implement を実行するだけで、AIが仕様書を参照しながら実装を進めてくれます。

これで、意図した通りのコードが少ない手間で得られるようになりました。

手戻りが激減

要件が明確になっているので、「あれ、これって違うな」という手戻りがほぼなくなりました。

実装前に設計フェーズで問題に気づけます。

仕様書をもとにAIがコードを書くので、認識のズレも減ります。

これまではAIにとりあえず作らせ、最終的に調整といった流れが多かったですが、今は最初から正しいコードが出てきます。

開発効率が大幅アップ

先述の通り、毎回細かく指示を出す必要がなくなりました。

各ステップでコマンドを実行するだけで、AIが必要な情報を仕様書から読み取って作業を進めてくれます。

指示を考える時間が減り、開発に集中できるようになりました。

タスクの進捗が可視化される

チェックボックスにチェックが入っていくのを見ると、進捗が一目瞭然です。

「今日はこんなに進んだ」という達成感があります。

開発には直接関係ありませんが、モチベーション維持に役立っています。

どんな場面で使えるか

個人開発での活用

個人開発では「作りながら考える」になりがちです。

ですが仕様駆動開発を使うと、開発の道筋が明確になります。

次に何を実装すべきか迷うことがなくなり、スムーズに開発を進められます。

また、最初に要件や設計が作られた時点で「なんか違うな」と気づけることも多いです。

実際、私はその段階で仕様を修正することが何度もありました。

AIが思考するフェーズを挟むことにより、客観的に考えられるようになるのだと思います。

複雑な機能の実装

複数のコンポーネントが絡む複雑な機能でも、設計書があれば整理して実装できます。

AIも全体像を理解した上でコードを生成します。

また、sdd-steering でプロジェクトの構造を把握できるので、既存コードとの統合もスムーズです。

大規模なプロジェクトでも、仕様駆動開発の効果を実感できるでしょう。

過去の開発を振り返るとき

アーカイブ機能で過去の仕様書が残ります。

「あのときはどう実装したっけ？」がすぐに分かります。

似たような機能を作るときの参考にもなりますし、ドキュメントとしても価値があります。

チーム開発の場面では、新メンバーへのオンボーディングや、仕様変更の履歴確認にも役立つでしょう。

補足：Codex CLIで承認を求められたら

Codex CLIは、コマンドを実行する前に作業計画を表示したり、承認を求めることがあります。

その場合は ok などの承認メッセージを入力してEnterを押すと、処理が続行されます。

AIが何をしようとしているか確認してから実行できるので安心です。

テンプレートを最新化したい場合

私の今後のアップデートにより、カスタムコマンド（プロンプト）の更新が行われることがあります。

最新版にしておきたい場合は以下を実行します。

npx spec-driven-codex upgrade --locale ja

定期的にアップグレードすることで、最新の機能を使えるようになります。

おそらくは、プロンプトを改善したり、新しいコマンドを追加したりする内容になると思います。

まとめ

Spec Driven Codexは、仕様駆動開発という確立された手法を、現代のAIペアプログラミング環境に最適化したツールです。

仕様が先、実装が後。

このシンプルな原則が、開発をより予測可能で、より品質の高いものに変えてくれます。

導入も簡単なので、ぜひ試してみてください。

npx spec-driven-codex init --locale ja

日本語のドキュメントはこちらをご覧ください。

質問や改善要望があれば、GitHubのIssuesやDMでお待ちしています！