Spec Kitを活用した仕様駆動開発を1ヶ月やってみて

はじめに

こんにちは、ぬまです。

ここ1ヶ月ほど、AIコーディングエージェントを使った開発に Spec Kit（speckit） を取り入れて、仕様駆動開発を試していました。

AIに「この機能を作って」とお願いすれば、ある程度動くものは短時間で実装しやすくなりました。一方で、実際に開発していると、

• 途中で要件の解釈がずれる
• 実装は進んでいるが、何を満たせば完了なのか曖昧になる
• 後から見返したときに、なぜその実装になったのか分かりにくい
• タスクが大きすぎて、AIエージェントが途中で迷子になる

といった課題も感じていました。

そこで試してみたのが、GitHubが公開している Spec Kit を使った仕様駆動開発です。

今回は、Spec Kitとは何か、仕様駆動開発とは何か、Cursorでの導入方法、そして1ヶ月ほど使ってみて分かった点をまとめてみます。

Spec Kit（speckit）とは？

Spec Kit（speckit）は、GitHubが公開している Spec-Driven Development（仕様駆動開発） のためのツールキットです。

公式ドキュメントでは、AI駆動開発において「いきなりコードを書く」のではなく、仕様を中心に開発を進めるための仕組みとして紹介されています。各 slash コマンドや導入手順の詳細も、こちらにまとまっています。

Spec Kitを導入すると、主に以下のような流れで開発を進められるようになります。

• /speckit.specify：何を作るのか、なぜ作るのかを仕様として整理する
• /speckit.clarify：曖昧な要件を洗い出して、仕様を具体化する
• /speckit.checklist：仕様の品質をチェックする
• /speckit.plan：技術スタックや設計方針を含む実装計画を作る
• /speckit.tasks：実装可能な粒度のタスクに分解する
• /speckit.analyze：仕様、計画、タスクの不整合を確認する
• /speckit.implement：タスクに沿って実装する

AIに対して毎回長いプロンプトを投げるのではなく、仕様書、実装計画、タスクリストという形で開発の文脈を残しながら進めるための仕組みです。

仕様駆動開発とは？

「仕様どおりに実装する」。それが、今までの私の開発の理解でした。

要件を決めて、それに沿って実装し、ズレたら直す。ウォーターフォール開発でもアジャイル開発でも、共通する話です。

ところが、AI コーディングエージェントを使い始めてから、同じパターンを何度も繰り返していました。

• チケットの一行説明や、頭の中のイメージだけで実装を依頼している
• AI はそれっぽく動くものを返してくれるので、一見うまくいっている
• でも「何を満たせば完了か」が曖昧なまま進み、あとから「そういう意味じゃなかった」となる

よく考えると、仕様書をちゃんと持たずにプロンプトだけで進めていた、という状態でした。仕様どおりに実装する、という理解自体は間違っていなかったのに、仕様そのものが薄い、更新されない、AIと共有されていない。そこがボトルネックだったと気づきました。

Spec Kit を1ヶ月使ってみて、「仕様駆動開発」という言葉の意味が少し変わりました。一般に仕様駆動開発は、実装に先立って仕様を明確にし、その仕様を基準に設計・実装・検証を進める考え方です。Spec Kitを使ったAIコーディングエージェント開発では、この仕様をAIと共有しながら、仕様、計画、タスク、実装へと段階的に進められる点が特徴だと感じました。

仕様駆動開発では、まず以下のようなことを整理します。

• 誰のための機能なのか
• 何を解決したいのか
• どのようなユーザー体験にしたいのか
• 何ができれば完了なのか
• 逆に、今回やらないことは何か

ここで大事なのは、最初から技術スタックや実装方法に寄りすぎないことです。

たとえば、/speckit.specify の段階では「Next.jsで実装する」「DynamoDBを使う」といった技術の話よりも、「ユーザーがどういう操作をして、どういう結果を得られるべきか」を中心に書きます。

その後、/speckit.plan で技術方針を決め、/speckit.tasks で実装タスクに落とし込んでいきます。

この順番を守ることで、AIに任せる範囲と人間が判断すべき範囲がかなり整理されるように感じました。

CursorでSpec Kitを導入する

ここからは、CursorでSpec Kitを使うための導入方法です。

前提として、以下が必要になります。

• Python 3.11以上
• uv
• Git
• Cursor

※本記事ではCursorでの利用例を紹介しますが、Spec KitはCursorに限定されたツールではなく、複数のAIコーディングエージェントとの連携を前提としたツールです。利用する開発環境に応じて、公式ドキュメントの対応状況を確認してください。

まず、Spec KitのCLIである specify を使えるようにします。

一度だけ試す場合は、以下のように uvx で実行できます。

uvx --from git+https://github.com/github/spec-kit.git specify init --here --integration cursor-agent

継続的に使う場合は、公式ドキュメントで推奨されているように uv tool install でインストールしておくと便利です。

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

vX.Y.Z は、GitHub の Releases にある最新バージョンに置き換えます。

インストール後、既存プロジェクトで初期化する場合は以下を実行します。

specify init --here --integration cursor-agent

新しいプロジェクトとして作成する場合は、次のようにプロジェクト名を指定します。

specify init my-project --integration cursor-agent

初期化が完了すると、.specify ディレクトリにテンプレートやスクリプトが作成されます。Cursor向けのintegrationでは、.cursor/skills にSpec Kit用のスキル、.cursor/rules にルールも追加されます。

バージョンによって見え方は少し異なる可能性がありますが、基本的にはCursor上でSpec Kitの手順に沿って、仕様、計画、タスク、実装を進められるようになります。

うまく動作しない場合は、次の点を確認するとよさそうです。

• uv がインストールされているか
• specify version でCLIが実行できるか
• プロジェクトのルートディレクトリで specify init を実行しているか
• Cursor側でSpec Kit用のskillsやrulesが追加されているか
• エージェント検出で失敗する場合は --ignore-agent-tools を付けて初期化できるか

1ヶ月使ってみてよかったところ

要件の曖昧さに早めに気づける

一番よかったのは、実装に入る前に要件の曖昧さに気づきやすくなったことです。

AIにそのまま実装を依頼すると、こちらが曖昧に書いた部分もAIがよしなに補完して進めてくれます。これは便利な反面、あとから「そこはそういう意味じゃなかった」となることがあります。

Spec Kitを使うと、/speckit.specify や /speckit.clarify の段階で、AIが仕様の穴や未確定な点を指摘してくれます。

たとえば、画面を作るだけのつもりでも、

• エラー時はどう表示するのか
• 空データの場合はどう見せるのか
• 権限によって操作できる範囲は変わるのか
• 既存データとの互換性は必要なのか

といった観点が出てきます。

これらを実装後に考えるのではなく、先に考えられるのは大きなメリットの一つでした。

AIエージェントの実装が安定しやすい

仕様、計画、タスクが分かれていることで、AIエージェントに渡る文脈が整理されます。

特に効果を感じたのは、少し大きめの機能を実装するときです。

以前は「この機能を作って」とまとめて依頼して、途中で実装方針がぶれたり、関係ないファイルまで大きく変更されたりすることがありました。

Spec Kitでは、/speckit.tasks で実装タスクが細かく分解されるため、AIに任せる単位を小さくできます。タスクごとに差分を確認しながら進められるので、レビューもしやすくなりました。

後から見返したときに判断の理由が残る

AI駆動開発では、実装速度が速い分、あとから「なぜこの設計にしたんだっけ？」となりがちです。

Spec Kitを使うと、仕様書や計画書がMarkdownとして残るため、後から見返しやすくなります。

これはチーム開発でも便利だと思いました。

Pull Requestの説明を書くときにも、仕様や計画を見返せば「何のための変更か」「何をスコープ外にしたか」を説明しやすくなります。

AIに任せる前に自分の考えが整理される

Spec Kitを使うと、実装前に必ず「何を作りたいのか」を言語化することになります。

自分の中で曖昧だった要件がかなり見えるようになりました。

AIにうまく指示を出すためのツールというより、人間側の思考を整理するためのツールとしても効果があると感じています。

1ヶ月使ってみてよくなかったところ

小さい修正には少し重い

すべての変更にSpec Kitを使うのは、少々オーバースペックな印象です。

たとえば、軽微な文言修正、スタイル調整、明らかなバグ修正のような作業まで、毎回 specify、plan、tasks と進める必要はないと感じました。

Spec Kitが向いているのは、要件の解釈が分かれそうな機能追加や、複数ファイルにまたがる変更、後から判断理由を残しておきたい変更です。

逆に、変更内容が明確で小さい場合は、Cursorへ直接依頼した方が速いです。

仕様を書く力は必要

Spec Kitを使えば自動的に良い仕様ができるわけではありません。

最初に入力する内容が曖昧すぎると、生成される仕様も曖昧になります。

もちろん /speckit.clarify で補助はしてくれますが、最終的に「これは何のための機能なのか」「どこまでを今回のスコープにするのか」を決めるのは人間です。

AIに仕様作成を丸投げするというより、AIと壁打ちしながら仕様を育てていく感覚に近いです。

生成物が増える

Spec Kitを使うと、仕様書、計画書、タスクリストなどのMarkdownファイルが増えます。

これ自体はメリットでもありますが、運用を決めないとノイズになります。実験的に作った仕様が残り続けたり、実装と仕様がずれたまま放置されたりすると、あとから見た人が混乱します。

我々の開発では、Spec Kit が生成する Markdown と 最終決定された仕様書 を分けて管理することにしました。

Spec Kit 側の Markdown は、要件の整理やタスク分解、AI への文脈渡しのために使います。途中経過が残るので、内容が揺れたり古くなったりすることもあります。

実装が進んで Spec Kit の成果物とズレてきたら、最終仕様書を更新するか、Spec Kit 側を戻して再同期するか。ここはルールを決めておいた方がよさそうです。

使い始める前に、少なくとも次は決めておくと運用しやすいと思います。

• どの粒度の変更で Spec Kit を使うか
• Spec Kit の生成物をリポジトリに含めるか
• 最終仕様書へ反映するタイミング（PR マージ前、リリース前など）
• 機能完了後、Spec Kit の作業用ファイルをどう扱うか（アーカイブ、削除、参照用に残す）

途中で仕様を変えるときの扱いに慣れが必要

実装中に「やっぱりこの仕様を変えたい」となることはよくあります。

そのときに、実装だけを直すのか、仕様やタスクまで戻って更新するのかを意識する必要があります。

ここを雑にすると、せっかく仕様駆動で始めたのに、最終的には仕様と実装がずれてしまいます。

私の場合は、仕様変更が入ったら一度 /speckit.specify や /speckit.plan の成果物に戻り、必要に応じて更新してから実装を続ける方がうまくいきました。

うまくいきやすいと感じた使い方

「何を作らないか」も書く

Spec Kitを使うときは、作りたいものだけでなく、今回やらないことも書くとかなり安定します。

たとえば、

• 認証は今回のスコープに含めない
• 管理画面は作らない
• 既存データの移行は別タスクにする
• パフォーマンス改善は最低限に留める

のようにスコープ外を明示しておくと、AIが勝手に気を利かせすぎることを防ぎやすくなります。

/speckit.clarify を飛ばさない

最初は、/speckit.specify の後にすぐ /speckit.plan へ進みたくなります。

ただ、使ってみた感覚では、曖昧さが残っている機能ほど /speckit.clarify が重要でした。

ここで質問に答えていくことで、仕様の解像度がかなり上がります。特に、ユーザー操作、エラーケース、データの扱い、権限まわりは最初に詰めておくと後が楽です。

タスクは小さめにして、こまめにレビューする

/speckit.implement で一気に最後まで実装させるより、タスク単位で進めた方が安定しました。

AIエージェントは大きな作業もこなせますが、コンテキストが大きくなるほど意図しない変更が混ざる可能性も上がります。

タスクを小さく分けて、実装、確認、必要なら修正、というサイクルで進める方が、結果的に手戻りが少なかったです。

仕様はPR説明やレビューにも使う

Spec Kitの成果物は、実装時だけでなくレビュー時にも役立ちます。

PRを作るときに仕様書やタスクリストを見返すと、変更の目的や確認観点を整理しやすくなります。

レビューする側も、「このPRは何を満たすためのものなのか」が分かりやすくなるので、単なるコード差分の確認ではなく、仕様に対して正しいかを見やすくなります。

全部をSpec Kitに寄せすぎない

すべての開発をSpec Kitに寄せすぎないことです。

Spec Kitは便利ですが、開発のすべてを置き換えるものではありません。

小さい修正はCursorに直接依頼する。要件が曖昧な機能や、後から説明責任が必要になりそうな変更はSpec Kitを使う。というように、使い分けるのがちょうどよさそうです。

まとめ

Spec Kitを使った仕様駆動開発を1ヶ月試してみて、AI駆動開発の進め方がかなり変わりました。

特によかったのは、実装前に要件を整理し、AIエージェントに渡す文脈を明確にできることです。結果として、実装のぶれが減り、レビューもしやすくなりました。

Spec Kitは、単にAIにより正確な実装を依頼するためのツールというより、人間とAIが同じ仕様を参照しながら開発を進めるための土台として有効だと感じました。一方で、すべての作業に適しているわけではなく、仕様を書く力や生成物の運用ルールも必要です。要件の解釈が分かれやすい機能追加や、後から判断理由を残したい変更に対して、選択的に活用するのが現実的だと考えます。

AIコーディングエージェントを使った開発で、要件のずれや実装のぶれに悩んでいる方は、一度Spec Kitを導入を検討する価値があります。

今後も、実際の開発の中でどの粒度のタスクにSpec Kitを使うのがよいか、チーム開発ではどう運用するとよいかを試していきたいです。

numa