はじめに
クラウドサイン Product Engineering 部で主にフロントエンドエンジニアとして活動している山下慧（@kirehashi_3）です。
さて、この記事をご覧になっている方は、Claude Code などの AI エージェントを用いて開発していることが多いでしょう。しかし、使っている中で「AI エージェントが自分の意図とは違う仕様で開発し始めた！」「途中で寄り道を始めて収拾がつかなくなった！」といった経験をしたことも多いのではないでしょうか。
本記事ではこういった問題を解決するための手法として、まずは Kiro が提唱する仕様書駆動開発について説明します。そのうえで、この仕様書駆動開発を Claude Code で利用できるようにした claude-code-spec-workflow について紹介します。
以降は以下の環境下を前提に説明していきます：Claude Code、Node.js 18+、macOS
Kiroが提唱する仕様書駆動開発
2025 年 7 月中旬に AWS は新たな AI IDE である Kiro を発表しました。Kiro は AI エージェントと統合した新たな開発手法として「Spec-driven Development（仕様書駆動開発）」を提唱しています。
Kiro が示す「仕様書駆動開発」は、仕様の基盤として 3 つのファイルをユーザーと対話しながら用意するところから始まります。requirements.md（ユーザーストーリーと受け入れ基準）、design.md（アーキテクチャやシーケンス、設計上の注意）、tasks.md（実装計画）です。これらをユーザーと対話しながら生成する過程で、ユーザーが指示したプロンプトと具体的な実装の間に認識の溝ができがちな部分を、橋渡ししていく考え方です。
この発想自体は他の AI エージェントでも適用可能で、Claude Code においてもテンプレートやカスタムコマンドを使って同様の流れを再現する取り組みがすでに複数あります。
claude-code-spec-workflow の紹介
今回紹介するのは、Claude Code でこの仕様書駆動開発のフローを CLI として実装した claude-code-spec-workflow です。ツールの機能は大きく 2 つ。ひとつは仕様書駆動の新機能開発（要件→設計→タスク→実装）、もうひとつはバグ修正（報告→分析→修正→検証）を、それぞれユーザーとの対話を通して具体化しながら回せることにあります。
他の仕様書駆動開発を行う取り組みと比較して優れていると感じた点は主に三点あります。
claude-code-spec-workflow自身がサブエージェントによる自己レビュー機能を持っており、ユーザーレビュー前に自律的に仕様書を改善する- 実装計画を元に小規模な task 単位に分割されたカスタムコマンドを生成する。このカスタムコマンドを実行するとサブエージェント内で task を実行します。このためコンテキストを圧迫せず、AI エージェントの暴走も引き起こしにくい点において優れています
- ダッシュボードで進捗や仕様の情報を GUI で確認できる
claude-code-spec-workflow の利用例
claude-code-spec-workflow の利用例のデモとして、Obsidian のサンプルプラグインを改修して「コマンド実行で、日付・時刻を挿入する」プラグインを作っていきます。
claude-code-spec-workflow の導入
claude-code-spec-workflow の導入は簡単です。
npm i -g @pimzino/claude-code-spec-workflow
グローバルインストールしたうえで、実装対象のプロジェクトのディレクトリルートで、
claude-code-spec-workflow
を実行すると、必要なカスタムコマンド・テンプレート・エージェントが導入されます。
仕様書の作成
Claude Code を起動したうえで、仕様書の作成を指示するコマンドを実行します。
/spec-create timestamp "このサンプルプラグインを改修して以下の要件を満たすようにしてください\ - コマンドを実行することで現在カーソルが選択している場所に現在の日付・時刻を`2025年8月19日 15:30` の形式で入力する"
このコマンドで Claude Code は、.claude/specs/timestamp に requirements.md（ユーザーストーリーと受け入れ基準）を作成し始めます。
頓珍漢なことをしても「まあずんだもんだしなぁ」と思えるだけでなく、コンテキストが長引いたときにずんだもんの人格が消えることがあるので、/clear の目安を知らせる「炭鉱のずんだもん」として活躍しています。
作成後はサブエージェントによるレビューが走り、改善したものをユーザーに提案します。ユーザーは作成された requirements.md を確認して適宜修正の指示を出し、最終的に承認します。
なお、claude-code-spec-workflow が .claude/templates/ に生成する仕様書テンプレートは英語です。標準のままでも動きますが、英語交じりの仕様書になるためテンプレートを日本語化しておいたほうがレビューしやすいでしょう。
design.md（アーキテクチャやシーケンス、設計上の注意）、tasks.md（実装計画）についても同様に生成・レビュー・承認のフローを実施します。最終的に実装計画が完成すると、claude-code-spec-workflow は tasks.md の実装タスクに基づいてカスタムコマンドを生成します。
カスタムコマンドの実行による実装
いよいよ実装を開始します。tasks.md に書かれたタスクはカスタムコマンドとして生えるので、/timestamp:task-1、/timestamp:task-2……のように順番に実行するだけで実装が進みます。これらの実装もサブエージェント内で実行されるため、コンテキストの圧迫を抑えつつ、1 コマンド ＝ 1 目的で因果を追いやすいのが特徴です。
全体の進捗は /spec-status timestamp で確認できます。ダッシュボード側でも、どのタスクがどこまで進んだかが一覧できます。
最後までタスクを実行することで、プラグインを完成させることができます。
実際に使用してみての感想
2 週間ほど claude-code-spec-workflow を使った仕様書駆動開発を進めてみて、一番の効果は「今 AI が何を意図して何を作業しているのか」が理解できることにあったと感じています。作業がタスク単位のカスタムコマンドに分かれるため AI エージェントの暴走や寄り道が激減し、もしも寄り道してもユーザーが事前に作業を認識しているためすぐに気づいて訂正できるようになりました。
また実装の意図・作業が仕様書という形式で残る点も優れています。大規模開発で「以前実装された特定の機能の実装意図がわからない」というのはよくある経験でしょう。しかしこの仕様書を何らかの形で残しておけば、実装意図の把握に大きく役立つでしょう。理想としては、開発フローに組み込み、Git の管理下に置いて参照しやすくすると活用が進むと考えています。
一方で欠点もいくつか感じました。例えばタスクの数が増えやすい（中規模の機能だと 10 個程度）ため、カスタムコマンドの実行が面倒になる場合があります。これは tasks.md を作る時点で細かすぎるタスクをまとめるよう指示することで軽減できます。tasks.md のレビュー時には粒度が細かすぎないかも見ておくと良いでしょう。また AI が過度に厳しいテストや性能要件を掲げたり、大規模リポジトリの改修では現実的に実装が困難なテストを実装しようとするケースもあります。こちらについても design.md・tasks.md のレビューで現実的なラインに落とすことが必要です。
またツールの便利さだけでなく仕様書駆動開発というアプローチそのものもとても新鮮に感じました。AI エージェントの開発においてテストを通して仕様を具体化する設計手法としてテスト駆動開発をさせようという取り組みもしばしば見かけます。この文脈において、仕様書駆動開発が AI エージェント特有の仕様を具体化する設計手法としてテスト駆動開発と代替、もしくは共存できるケースも多いのではないでしょうか。
余談：claude-code-spec-workflow の MCP 版が開発中のようです
spec-workflow-mcp というclaude-code-spec-workflow の MCP が現在開発中で、今後はこちらに移行していくようです。私は spec-workflow-mcp を試していないため、カスタムコマンドやエージェントで実行する claude-code-spec-workflow と同等の機能が提供されているのかは把握できていません。ですが、今から導入してみるほうはこちらを試してみるのも良いでしょう。MCP なので Claude Code 以外からでも使えるのが魅力です。
おわりに
仕様書駆動開発、そしてclaude-code-spec-workflow は、AI 時代の開発にありがちな「何をしているかわからないまま猛スピードで突き進む」を「事前に合意した仕様を土台に素早く進む」へ寄せてくれる手法だと感じました。手法自体はシンプルですが効果は実感しやすいはずです。冒頭で触れたような AI エージェントの難しさを感じたことがある方は、ぜひ試してみてください。
