Spec Workflow MCPによる仕様駆動開発入門

最近はClaude CodeやGitHub Copilotなどを使ってコードを生成することが一般的になってきました。
しかし、生成されたコードが自分の指示通りに生成されず、結局自分で書き直した経験がある人も多いのではないでしょうか。
私も意図通りのコードを生成してもらうために、CLAUDE.mdを改良したりカスタムコマンドを用意したりと試行錯誤を続けています。
もちろん効果はあるのですが、うまく指示が伝わることもあれば、思うようにいかないこともあります。
そんな中、AmazonがリリースしたKiroに代表されるようなSpec-driven Development（仕様駆動開発）に注目している人も多いと思います。
Kiroは無料プランでは制限が厳しく、月額プランの導入も少しハードルがあるので、今回はオープンソースで利用できるSpec Workflow MCPを試してみることにしました。

Spec Workflow MCPについて

Spec Workflow MCPは、Kiroのような仕様駆動開発をMCPで実現するためのツールです。
https://github.com/Pimzino/spec-workflow-mcp

同じ開発者によるClaude Codeのカスタムコマンド版「claude-code-spec-workflow」も存在しますが、開発はMCP版に移っており、今後はSpec Workflow MCPが主流になる予定です。
今回はClaude Codeを例に、Spec Workflow MCPのインストール方法と使い方を紹介します。
MCPとしてインストールするため、Claude Code以外にもCursorやその他のMCP対応ツールでも利用可能です。

Spec Workflow MCPのインストール方法

実際に、bitfanのAndroidアプリのリポジトリにインストールしてみます。

Spec WorkflowはMCPサーバーですので、Claude Codeの場合はmcpコマンドを使ってインストールします。

claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/repository

※/path/to/repositoryの部分は、実際のリポジトリのパスに置き換えてください。
特にエラーが出なければインストール完了です。
実際にClaude Codeを起動してインストールされているか確認しましょう。

claude
/mcp list
spec-workflow ✔ connected # インストールされていることが確認できます

Spec Workflow MCPの使い方

実際にSpec Workflow MCPの使い方を紹介します。
今回はbitfanのAndroidアプリのリポジトリにSpec Workflow MCPを導入する例で説明します。

ステアリング文書の作成

まず、Spec Workflow MCPではステアリング文書という３ファイルを用意します。

• product.md
• tech.md
• structure.md

これは、プロジェクトの「作るもの」、「作り方」、「進め方」に関するガイドラインを記載するものです。
一見複雑そうに感じられますが、まずは実際に試してみましょう。

既存のプロジェクトにREADME.mdなど参考になる文書がある場合は、自動的に読み込まれます。
また、他にドキュメント等が存在する場合、指定することで精度が向上します。
今回は特別な指定をせずに作成してみます。

steering-guideのワークフローに従ってステアリング文書を作ってください

⏺ ステアリング文書を作成するために、まず必要なツールを使用してガイドとテンプレートを取得します。
⏺ ステアリング文書の作成ワークフローを開始します。まず、ガイドを読み込んでから、既存のステアリング文書を確認します。
⏺ ステアリング文書がまだ作成されていないことを確認しました。それでは、順番に3つのステアリング文書を作成していきます。
⏺ プロダクト文書のテンプレートを取得しました。次に、コードベースとCLAUDE.mdの情報を基に、Bitfan Androidアプリのプロダクト文書を作成します。
⏺ プロダクト文書を作成しました。次に承認をリクエストします。
⏺ 承認リクエストを作成しました。プロダクト文書の承認状況を確認します。
⏺ プロダクト文書の承認待ちです。VS Code拡張機能またはダッシュボードで承認していただく必要があります。

プロダクト文書の作成が完了しました。現在承認待ちの状態です。
承認プロセスが組み込まれているのは興味深い仕組みですね。
操作はVS Codeの拡張機能で行うか、専用のWebダッシュボードで行うことができます。
今回はCLIで操作しているため、専用のWebダッシュボードを使用します。

ダッシュボードの起動

ダッシュボードを起動します。

npx -y @pimzino/spec-workflow-mcp@latest /path/to/repository --dashboard

※/path/to/repositoryの部分は、実際のリポジトリのパスに置き換えてください。

product.mdの作成

ダッシュボードが起動すると、このような画面が表示されます。

メイン画面は3つのセクションに分かれています：

• 仕様書（左）: 現在0件のアクティブな仕様書があることが表示されています
• タスク進捗（中央）: 「0/0 アクティブな仕様書がありません」と表示され、まだタスクが存在しないことがわかります
• 承認（右）: 「1 レビュー待ち」と表示されており、先ほど作成したプロダクト文書の承認待ちが確認できます

この画面から承認待ちのプロダクト文書を確認し、承認作業を進めることができそうです。

続いて承認を見てみましょう。
右上の「承認」セクションをクリックすると、承認待ちの文書一覧画面に移動します。

画面上部には「承認 保留中の承認リクエストをレビュー・管理」と表示され、右上に「保留中1件」のバッジが確認できます。

先ほど作成した文書の内容を確認できます。

画面下部には3つのアクションボタンが用意されています：

• レビューと注釈（青）: 詳細レビューを行う
• 即時承認（緑）: すぐに承認する
• 即時却下（赤）: 却下する

内容を確認してみましょう。
CLAUDE.mdやモジュール構成を確認して実際の機能名などが記載されています。
ここで注目したいのは、技術的なことが一切記載されていない点です。「作るもの」に重点が置かれています。

レビューのワークフローも確認したいので指摘をしてみましょう。
指摘もダッシュボードから行えます。
部分コメントと全般コメントが行えます。

部分コメント
以下のように行選択するとコメントモーダルが表示されます。（表示されない場合は選択箇所をクリックする）

モーダルに指摘事項を入力しコメントします。

コメントしたことが反映されます。

全般コメント
全体に関わるコメントも行えます。
今回はあえて不要な指摘をしてみます。

プロダクトに親しみをもってもらえるように、ずんだもんの口調で書いてもらいましょう。

反映されました。

これで指摘を修正してもらいます。
ダッシュボードの修正を依頼をクリックします。

Claude Codeに戻り、修正依頼したことを伝えます。

修正依頼しました。

すると指摘事項を確認して修正してくれました。

Product文書を修正しました：
  1. NFT連携の項目を削除
  2. ずんだもんの口調（「〜なのだ」）に変更

新しい承認リクエストをダッシュボードで確認してください。承認後、Tech文書の承認に進みます。

ダッシュボード上でもずんだもん口調になっていることが確認できました。

これで即時承認して、次のフローに進みます。

承認しました。次のフローに進みましょう

これでtech.mdの作成が開始されます。

tech.mdの作成

ダッシュボードでtech.mdを確認してみましょう。
tech.mdには、product.mdで定義されたプロダクトをどう作るか記載されています。

リポジトリ内のコードを分析し、実際のモジュール構成に基づいた文書を作成してくれています。
大まかな技術スタックやアーキテクチャは正確に把握されていますが、細かい部分で修正が必要な箇所もあります。

product.mdと同様に、必要な修正点をフィードバックしてから承認を行います。
修正が完了し、内容に問題がないことを確認できたので、即時承認して次のフローに進みます。

承認しました。次のフローに進みましょう

最後の文書となるstructure.mdの作成が開始されます。

structure.mdの作成

ダッシュボードでstructure.mdを確認してみましょう。
structure.mdには、実装をどう進めるかのガイドラインが記載されています。

プロジェクト構造を詳細に分析し、実際のコードベースで開発ガイドラインを作成してくれています。
内容を見ると、tech.mdでは一部省略されていたディレクトリ構造やファイル命名規則、実際の実装コード構成パターンまで具体的に記載されております。

特に注目したい箇所は、Activity/FragmentやViewModelなどの実装パターンが具体的なコード例とともに示されていることです。

これらのテンプレートがあることで、新しい機能を追加する際の実装の流れが明確になり、チーム全体で統一された書き方ができるようになります。開発者が迷うことなく、一貫性のあるコードを書けるのは大きなメリットです。
そしてこのメリットはAIのコード生成時に、より精度の高いコードを生成するために必要になります。

この文書の精度がコード生成の精度に直接影響するため、時間をかけて丁寧にレビューします。
bitfanはAndroidViewからComposeへの移行期で、ViewModelの実装が大きく異なるので、新しい画面用にComposeの実装パターンを詳細に記載します。
特に以下の点を重点的に記載しました。

• Compose用のViewModelでのStateFlow、SharedFlowの使い方
• UiStateの実装パターン
• UiEventの実装パターン
• ComposeのRoute/Screen/Componentの実装パターン
• エラーハンドリングのパターン
• Stableの活用

修正完了後、内容に問題がないことを確認し、即時承認してステアリング文書の作成を完了します。

まとめ

これで3つのステアリング文書（product.md、tech.md、structure.md）がすべて揃いました。プロジェクトの「作るもの」「作り方」「進め方」という基盤となるガイドラインが整備され、いよいよ具体的な機能仕様の作成に進むことができます。

今回Spec Workflow MCPを試してみて特に効果が大きいと感じたことは、開発基盤の言語化です。暗黙的な実装パターンを文書化（明文化）することで、人とAIの両方が同じ知識ベースで開発できるようになります。そしてプロダクトの成長とともにこの文書も育てていくことができます。

また、MCPとして動作するため今回はClaude Codeで試しましたが、例えばCursor、Codex CLI、その他のMCP対応AIツールでも利用可能です。

ステアリング文書の作成は一見面倒に思えますが、ここに時間をかけることで

• AIによるコード生成の精度が大幅に向上する
• チーム全体での開発方針が統一される
• 新しい開発者のオンボーディングが効率化される

といったメリットが得られます。

なお、今回のステアリング文書作成にかかった時間は約2時間から3時間でした。
少し時間は必要ですが、今後のAIを活用した開発において十分に回収可能な時間だと考えています。
また、作成した文書はそのままオンボーディング資料としても活用でき、実際に自分も入社時にこの文書があれば理解がもっと早くなっただろうと感じました。

次回は、実際にこのステアリング文書を基にした機能仕様の作成から実装までの流れを紹介する予定です。Spec-driven Developmentに興味のある方は、ぜひSpec Workflow MCPを試してみてください！