spec-kitを導入して2ヶ月 ~SDD・AIコーディングを考える~
こんにちは。タイでソフトウェアエンジニアをしている市村(uchan3)と申します。
この記事はNTT docomo Business Advent Calendar 2025 4日目の記事です。
さて、皆さんは"spec-kit"というツールはご存知でしょうか。最近巷で話題のSDD(Spec Driven Development: 仕様駆動開発)を実現するGitHubから提供されているOSSです。
今回はこのspec-kitを使ってみた感じたメリット・デメリットについて、現場の目線からお届けしたいと思います。
そもそもSDDとは
SDDとはSpec Driven Developmentの略であり、日本語では仕様駆動開発と呼ばれています。
少し前から話題になっているこの開発手法は、AIを活用したソフトウェア開発が中心となりつつある今注目されている手法です。
イメージとしては、バイブコーディングのようにプロンプトから直接コードを生成するのではなく、AIを使用しつつドキュメント(仕様書)を整備し、その仕様書をもとにAIで開発を進めていくような感じです。
こう聞くと、AIに正確に指示をするために先にドキュメントを作成してから明確なコンテキストをAIにわたす、というAI駆動開発を円滑に進める開発手法のように見えます。
もちろんその側面もあるのですが、この開発手法のメリットはそこだけではありません。
SDD is about making your technical decisions explicit, reviewable, and evolvable. Think of it as version control for your thinking. Instead of having crucial architectural decisions trapped in email threads, scattered documents, or locked in someone’s head, you capture the “why” behind your technical choices in a format that can grow with your project and your understanding of the problem space.
MicrosoftのBlogでは上記のように書かれていました。
<意訳>
"技術的な意思決定を明確にし、レビュー可能にし、進化させられるもの"
"あなたの思考に対するバージョン管理"
これはSDDがただAIの開発精度を向上させるためだけのものではなく、明確な副産物があることを示しています。
コンテキストの共有不足が原因で認識の差異がチーム間で起きてしまう...
AIだけでなく人間同士のコンテキストの共有も、開発スピードが上がっている近年の開発現場においては重要です。
そんな課題をSDDでは解決できます。(イメージがつきづらかった人はぜひ原文を眺めてみてください)
spec-kitとは
spec-kitとは、そんなSDDを実現するべくGitHubが公開しているOSSです。
詳しい使用方法は本記事では述べません。詳細が気になる方は下記を見てみてください。(Zennでもたくさん紹介記事があります)
- 公式ドキュメント
- spec-kitを既存プロジェクトに活用する方法
現場で2ヶ月使ってみて感じたメリット
成果物の品質向上
- これは言わずもがなですが、バイブコーディングの出力と比較して品質は高いです。
constitution.mdにてプロジェクトのルールが指定される影響も大きいです。
こちらのブログが参考になりました。
変更日時・プロンプトの記録
- docsを真とし開発していく手法であるため、簡単に5W1Hを記録していくことができます。
※多くの方がバージョンをdocsに振ったり、コミットログ等で管理していたと思いますが、自動で記録されることにより漏れがなくなるといったニュアンスです。 - 使用したプロンプトも記録されるので、プロンプトエンジニアリングの分析等も可能です。(修正プロンプトまでは追えません、記録するよう
agents.mdやconstitution.md等を編集しておけば良いかもしれません)
clarify/checklist/analyzeなどの防波堤コマンド
- 抜け漏れ全部を拾ってくれる便利ツール、とまではいきませんが、考えから漏れていた仕様・エッジケースを細かく聞いてくれる感じでした。ただ実装内容の領域次第なところもありそうです。
- また
spec.mdに書いてあるのにtasks.mdにタスクとして記載されていない、などの矛盾も探してくれるので、ヒューマンエラー防止にも繋がります。
スクラムでの開発との親和性
-
spec.md(仕様策定フェーズ)では技術スタックについての言及は推奨されておらず、WhatとWhyに焦点を当てて記述されます。
それに従って進めるとUser Storyベースで仕様を明確に記載してくれるため、プロダクトバックログの細かい切り分けにも使用できます。 - また各要件ごとに"Acceptance Scenarios"を用意してくれるのも便利でした。
コミットの粒度が一定になりやすい
-
tasks.md(実装するタスクが書かれたdocs)では、ほとんど同じ粒度のタスクが並びます。
User Storyごとにタスクの大枠も分かれているため、随時どこまで実装が終わったのかが把握しやすく、駆け出しエンジニアでもコミットのタイミングが比較的わかりやすいと感じました。
Priority・Dependencies & Excution Orderによる実行順制御
- 実装順を理論に基づいて解説してくれます。マイグレーション時に非常に役立ちました。
現場で2ヶ月使ってみて感じたデメリット
生成されたドキュメントのレビューコストが莫大
- ドキュメントが大量にできます。若干レビューのモチベーションが削がれます。
- とはいえこれはAIコーディングの課題ではなく、元からあった課題であり、AIによってそのスピードが早まっただけだとt-wadaさんは述べられていました。
- あくまでコード量の話かと思いますが、ドキュメントでも同じことかと思いました。(曲解していたらすみません)
初期段階で仕様に抜け漏れがあった際のコスト
- 大きく分けて3パターンの対処法があるかと思いますが、どれも最良とはいえません。
- 仕様を書き直す
→最初から同じフェーズを繰り返すため時間がかかる。 - 次の機能として実装予定に入れる
→次の機能が実装完了するまで取り入れられない、場合によっては致命的。 - そこだけ自力で追加する
→AIを使うなら結局バイブコーディングになってしまう。一貫性のあるドキュメントは残りづらい。
- 仕様を書き直す
普通に設計スキルが必要
- 当然の如くこのツール自体が銀の弾丸とはなりません。
- ある程度経験のある人は上手く使える一方、当然設計経験が乏しければこのツールを使おうが何をしようが難しい、これはAIコーディング共通の課題です。
コーディングの楽しみが減る
- これもSDDというよりはAIコーディング共通ですが、開発者によってはモチベーションが少し下がります...
実行コマンドの多さ
- ステップごとに実行していくため、バイブコーディングよりプロンプト量は確実に増大していると思います。
- 一回コマンドを実行して終わりではないです。先ほど紹介した防波堤コマンドは修正後に再度実行しますし、implement(実装)コマンドも一括で実装はできないため、何度も実行する必要があります。
集中力が続かない
- AIコーディングあるあるだと思いますが、指示したあとの待ち時間が長いです。(特にtasks, implementフェーズ)
- コンテキストスイッチが半端じゃないです。集中力も切れます。
まとめ
コード品質はもちろんですが、引き継ぎをした後でも設計意図が確認できる、AI/チームメンバに正しくコンテキストを伝えることができる、といった部分でSDDの真価を感じることができるのではないかと思いました。
またアジャイルでよく見られる、ドキュメントの後回しや残し忘れ。(アジャイルだから是というわけではないです。ただ一般的にコードを書いてからドキュメントに残すということも少なくはないでしょう)
この開発手法はドキュメントベースで開発が進むため、私みたいなめんどくさがり屋でも確実にドキュメントが残せるのは嬉しいポイントです。
t-wadaさんの言葉で「労力は外注できるが、能力は外注できない」という言葉がありますが、まさしくその通りだと思います。
メリットデメリットでも書いた通り、自分の開発作業の補佐はしてくれますが、自分の能力が上がる代物ではないです。
あえてコードを手で書いてみる、生成されたコードを深く読む、AIコーディング中の待ち時間になぜそのような設計を採用したのかを考えてみる、など自分の能力を向上させる営みが大切だと思いました。
本日はここまでです。明日もお楽しみに。
Discussion