「さっき直したバグが、また別の場所で復活している」
「AIに指示を出せば出すほど、コードが複雑怪奇になっていく」
AIコーディング支援ツールを使っていると、このような不安や徒労感に襲われることはありませんか。修正を依頼したはずが、関係のないファイルを書き換えられてビルドが通らなくなる。
まるで、指示を聞いているようで聞いていない新人にタスクを振っているような、あの何とも言えない不自由さです。これは、プロンプトの書き方が悪いのではありません。
実は、「コンテキスト（文脈）の共有不足」という、より本質的な問題が隠れています。私たちはチャットの履歴に頼りすぎていますが、AIは過去の会話全てを完璧に理解してコードを書いているわけではありません。
「現在の仕様がどうあるべきか」という正解（仕様書）が常に参照できる状態にないことが、AIの迷走を生む最大の原因です。
この問題を放置すれば、AIは確率的な単語の羅列でコードを生成し続け、あなたは永遠にその後始末に追われることになります。生産性を上げるために導入したAIのせいで、逆にレビュー工数が肥大化するなんて笑えません。
そこで今回紹介するのが、spec-workflow-mcpです。
これは、仕様（Spec）を中心にした開発フローを強制的に作り出す画期的なツールです。このツールを使えば、AIは「仕様書」という地図を持ってコーディングの森を進めるようになります。
私は長年Javaエンジニアとして、堅牢なシステム開発に携わってきました。その経験から言っても、この「仕様駆動」のアプローチは非常に理にかなっています。
今回は、実際にこのツールを導入し、どのように開発体験が変わったのか、具体的な手順とともに解説します。
この記事を読めば、AIに振り回される日々から解放され、「意図通りに動くコード」を確実に手に入れる未来が待っています。
spec-workflow-mcpとは何か
Spec-Driven Developmentの背景
spec-workflow-mcpは、Spec-Driven Development（仕様駆動開発）を実現するためのツールです。
結論から言えば、これはAIに「いきなりコードを書かせない」ための仕組みです。理由は、AI開発において手戻りが発生する最大の要因が「要件の曖昧さ」にあるから。
例えば、「ユーザー登録機能を作って」とだけ指示したとします。AIは一般的な知識でコードを書きますが、プロジェクト特有のバリデーションルールや、データベースの制約までは考慮しません。
結果として、動くけれど使えないコードが出来上がります。
spec-workflow-mcpを使うと、まず「何を作るのか」「どんな制約があるのか」を明確なファイル（仕様書）として定義させられます。AIはこの仕様書を読み込み、それに合致するようにしかコードを書きません。
人間が頭の中で描いている設計図を、AIが理解可能なテキストとして外在化させるプロセス、それがSpec-Driven Developmentの本質です。
spec-workflow-mcpの概要と主要機能
spec-workflow-mcpは、Model Context Protocol（MCP）という規格に準拠したサーバーとして動作します。
MCPは、Claude DesktopやCursorといったAIエディタと、外部ツールを安全に接続するための標準規格です。
主な機能は以下の3点です。
- 仕様書の管理Markdown形式で要件や設計を記述し、それをプロジェクトの正本として管理します。
- タスクの細分化と追跡仕様に基づき、実装すべきタスクを小さな単位に分解します。各タスクには「Pending」「In Progress」「Completed」といったステータスが付与され、進捗が可視化されます。
- 整合性のチェック実装されたコードが仕様と矛盾していないか、AI自身にチェックさせるフローを組み込めます。
要するに、これまでは人間のPMが脳内で行っていた管理業務を、ツールとAIが肩代わりしてくれるのです。
導入手順と初期セットアップ
インストール方法
導入は非常に簡単です。まずはNode.jsがインストールされている環境を用意してください。
MCPサーバーとして動作させるための設定を、Claude DesktopやCursorの設定ファイル（claude_desktop_config.json など）に追加する必要があります。
設定ファイルへの記述例は以下のようになります。
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/project"]
}
}
}これで、AIエディタ側から spec-workflow ツールを呼び出す準備が整いました。
VSCode拡張とWebダッシュボードの使い方
spec-workflow-mcpの魅力は、視覚的なインターフェースも備えている点です。
推奨されているVSCode拡張機能をインストールすると、サイドバーにワークフローの管理画面が表示されます。
また、ローカルサーバーを立ち上げることで、Webブラウザ上で動作するダッシュボードも利用可能です。
npx -y @pimzino/spec-workflow-mcp@latest --dashboard ※デフォルトポートは5000なので被る場合は明示的にポートを指定する--port XXXX
このダッシュボードでは、現在のプロジェクトの仕様書一覧、未消化のタスク、完了した実装などがカンバン方式のような見た目で確認できます。
黒い画面（ターミナル）だけでは全体像を見失いがちですが、このダッシュボードがあるおかげで、「今、自分たちは山の何合目にいるのか」を一目で把握できるのです。
実際に使ってみた：ワークフロー体験
要件 → 設計 → タスク → 実装の流れ
ここからは、実際に私が簡単なAPIサーバーを構築した際の体験をお話しします。
spec-workflow-mcpを導入して最も変化したのは、「コードを書く前の準備」に時間をかけるようになったことです。
まず、AIに対して「ユーザー一覧を取得するAPIを作りたい」と話しかけます。これまでのAI開発なら、すぐにPythonやJavaのコードが出力されていたでしょう。
しかし、spec-workflow-mcpが有効になっていると、AIはまずツールを呼び出し、specs/user-list-api.md というファイルを作成します。
「エンドポイントのURLはどうしますか？」
「ページネーションは必要ですか？」
「レスポンスのJSON形式は？」
AIはコードを書く代わりに、これらの質問を投げかけ、仕様書を埋めていきます。このプロセスを経ることで、私自身も「あ、エラーハンドリングのことを忘れていた」と気づけるのです。
仕様が固まると、次にAIはそれを実装可能なタスクに分解します。
- DTO（データ転送オブジェクト）の作成
- Controllerの実装
- Service層のロジック実装
- ユニットテストの作成
このようにタスク化されて初めて、コーディングが始まります。
小さなステップで実装が進むため、エラーが発生しても原因の特定が容易です。
まるで、熟練のシニアエンジニアが隣でペアプログラミングをしてくれているような安心感がありました。
ダッシュボードで見る進捗管理と承認フロー
実装が進むにつれて、ダッシュボード上のタスクが次々と「Completed」に変わっていきます。
この視覚的なフィードバックは、モチベーション維持に非常に効果的です。
特に便利だったのが、承認フローの概念です。
AIが「実装が完了しました」と報告してきても、私がコードを確認し、テストが通ることを確認するまではタスクを「完了」にしません。
ダッシュボード上で人間が「Approve（承認）」ボタンを押して初めて、次のタスクに進めるように運用しました。
これにより、AIが勝手に暴走して、バグを含んだまま次の機能を実装してしまう事態を完全に防げました。
「人間が管理者であり、AIは作業者である」という役割分担が、システム的に強制される点が素晴らしいと感じます。
良かった点とメリット
ドキュメントが「信頼できる仕様書」として残ること
spec-workflow-mcpを導入して最大のメリットだと感じたのは、開発が終わった時点で、完璧な仕様書が手元に残っていることです。
これまでの開発では、コードが完成した後に、慌ててドキュメントを書くのが常でした。
そのため、実際のコードとドキュメントの内容に乖離（かいり）があることもしばしば。
しかし、このツールでは「ドキュメント（仕様）を書かないとコードが書けない」ため、常にドキュメントが最新の状態に保たれます。
これは、将来の保守において価値を生みます。
半年後、自分が書いたコードを見直したとき、あるいは新しいメンバーがチームに参加したとき、specs フォルダを見ればシステムの全容が理解できるからです。
「動くコードが仕様書だ」という極論に頼らず、自然言語で書かれたロジックが存在する安心感は絶大です。
AIによる実装の「迷走」が減り、安定したコード生成
もうひとつの大きなメリットは、AIの回答精度が劇的に向上したことです。
AIはコンテキストウィンドウ（記憶できる容量）に制限があります。
長い会話の中で、初期の要件を忘れてしまうことは珍しくありません。
しかし、spec-workflow-mcpを使えば、AIは常に仕様ファイルを参照しながら回答を生成します。
「仕様書に『削除フラグは物理削除ではなく論理削除にする』と書いてあります。先ほどのコードは物理削除になっていませんか？」
と指摘すると、AIは
「申し訳ありません。仕様書 specs/database.md の記述を確認し、修正します」
と即座に軌道修正します。
このように、**AI自身が立ち返るべき「アンカー（錨）」**が存在することで、会話がどれだけ長くなっても、実装の方向性がブレなくなるのです。
注意点や課題 — 実際に感じたこと
タスク粒度による工数・手間の増加
もちろん、良いことばかりではありません。
率直に言って、「ちょっとしたスクリプト」を書くには重すぎます。
例えば、「CSVファイルを読み込んで集計するだけの20行のPythonスクリプト」が欲しい場合、いちいち仕様書を作り、タスク分解するのは明らかにオーバーエンジニアリングです。
spec-workflow-mcpを使うと、コードを書くまでの「儀式」が増えるため、スピード感は確実に落ちます。
プロトタイピングや、使い捨てのコードを書く場合は、このツールをオフにするか、通常のチャットモードで進める方が賢明です。
導入すべきかどうかの判断基準は、「このコードを1週間以上運用するかどうか」に置くと良いでしょう。
AI提案の有用性と過剰さの兼ね合い
また、AIが提案してくる仕様が、時に過剰になることもあります。
簡単なCRUDアプリを作りたいだけなのに、マイクロサービスアーキテクチャを提案されたり、必要以上に複雑なデザインパターンを盛り込まれたりすることがありました。
これはAIの学習データが「大規模システム」のパターンを含んでいるためでしょう。
人間の側で「いや、そこまでは求めていない。もっとシンプルでいい」と手綱を引く判断力が求められます。
ツール任せにするのではなく、あくまで人間が仕様の決定権を持つという意識を忘れてはいけません。
Javaエンジニアの視点で
既存コードベースへの導入を検討するなら
私は普段Javaをメインに扱っていますが、Javaのような静的型付け言語とspec-workflow-mcpの相性は抜群です。
Javaプロジェクトはクラス数やファイル数が多くなりがちで、全体像を把握するのが難しいためです。
既存の巨大な「レガシーコード」にこのツールを導入する場合、まずは「新機能の追加」や「特定モジュールのリファクタリング」から始めることをお勧めします。
いきなり全機能を仕様化しようとすると、ドキュメント作成だけで数ヶ月かかってしまいます。
例えば、「決済機能の改修」というタスクが発生したときだけ、specs/payment-refactor.md を作成し、そこに関連する仕様を書き出していく。
このように部分的に適用することで、徐々にプロジェクト全体を「管理された状態」に移行できます。
チーム開発／コード品質とドキュメント管理への影響
チーム開発においても、このツールは共通言語として機能します。
プルリクエスト（PR）を送る際、「実装コード」だけでなく「更新された仕様書」も一緒にレビューできるようになるからです。
「なぜこのロジックにしたの？」というレビュアーの疑問に対し、
「仕様書のこの要件に基づいています」と明確に答えられるようになります。
これにより、感覚的なコードレビューではなく、要件に基づいた論理的なレビューが可能になります。
また、Javaエンジニアとしては、Javadocなどのコード内コメントだけでなく、アーキテクチャレベルの決定事項がMarkdownで残る点に大きな喜びを感じます。
コードの品質だけでなく、プロジェクトの「情報品質」が向上するのです。
まとめと今後の展望
spec-workflow-mcpを使う価値
spec-workflow-mcpは、AI開発における「地図」と「コンパス」を提供してくれるツールです。
もしあなたが中規模以上の開発や、長期的にメンテナンスが必要なプロジェクトにAIを活用したいなら、spec-workflow-mcpの導入はありだと言えます。
理由は、AIの確率的な不安定さを、仕様書という確実な構造で補完できるから。
最初は手間に感じる「仕様作成」のプロセスも、結果的には最短ルートでゴールにたどり着くための近道だったのです。
運用で気を付けるべきポイント
最後に、運用において最も重要なポイントをお伝えします。
それは、「仕様書の更新をサボらない」ことです。開発が進むにつれ、仕様変更は必ず発生します。その際、コードだけを修正して仕様書を放置すると、このツールの価値はゼロになります。
AIは古い仕様書を見て誤ったコードを書き始め、現場は混乱に陥るでしょう。「コードを直す前に、まず仕様書（Markdown）を直す」
この規律を守れるかどうかが、spec-workflow-mcp活用の成否を分けます。
AIは強力なエンジンですが、ハンドルを握るのは私たち人間です。spec-workflow-mcpという優れたナビゲーションシステムを使いこなし、迷走することなく、最高のプロダクトを作り上げてください。
