仕様書駆動開発の理想と現実 - Claude Code実践で直面した課題

レバテックLABのイベント「実装の精度を上げる、設計フェーズのAI活用」で発表した資料です。
https://levtech.jp/media/article/event/010/
https://levtechlab.connpass.com/event/369166/presentation/

Transcript

1. 仕様書駆動開発の理想と現実 
 Claude Code実践で直面した課題
 Hiroki Itani @ スマートバンク
 2025-10-10

2. 2 SmartBank, Inc. 
 Software Engineer 
 井谷 裕紀
 @w650
 @tanihiro
 自己紹介

4. 4 はじめに - スマートバンクでのAI活用について
 • スマートバンクは組織としてAI活用を推進中
 ◦ https://blog.smartbank.co.jp/entry/investment-committee-ai-support
 • 開発におけるAI活用は現在各自が試行錯誤中
 • 本日のお話は、業務の中で私が個人的に取り組んでいる事例の紹介

5. 5 1. 仕様書駆動開発とは
 2. Claude Codeでの実践と課題
 3. 仕様書分割による開発の試み
 4. まとめ
 今日お話すること

6. 仕様書駆動開発とは

7. 7 仕様書駆動開発とは
 • AWSが2025年7月に発表したAI統合開発環境『Kiro』で注目を集めた開発手法
 • すぐにコーディングせず、要件定義書→設計書→タスクリスト→実装の順で進めるアプローチ
 • 仕様書駆動開発がもたらすメリット
 ◦ 仕様書を事前に交わすことで人間とAIの間で認識の齟齬を減らせる
 ◦ 仕様書がAIの道標となる（いつでも提供できるコンテキストになる）
 ◦ タスクの進捗を段階的にチェックできるようになる
 要件定義書
 設計書
 タスクリスト

8. 8 事前に丁寧に設計書を作ることができれば
 AIに「あとはやっておいて」と全てを任せられるのでは？
 仕様書駆動開発に抱いた理想

9. Claude Codeでの実践と課題

10. 10 https://blog.smartbank.co.jp/entry/2025/07/04/115000 Claude Codeでの実践

11. 11 要件定義書
 設計書
 タスクリスト
 • このときはまだKiroが出る前だったので、要件定義書/設計書は人間が主体となって用意した
 ◦ AIは主に壁打ちがメイン
 • 人間が主体となって作成した仕様書をもとに、タスクリストの生成をAIに依頼した
 • 感覚的には従来の1.5倍程度の開発効率を体感
 Claude Codeでの実践

12. 12 見えてきた課題
 自律性
 並列化
 ボトルネックになる人間
 • どれだけ丁寧な設計書があっても、AIは微妙なコードを出力する
 • 人間が都度修正を確認しないと、タスクを完走させることも難しい
 • タスクに依存関係が存在するので、そもそも並列指示を出すことが難しい
 • 並列化したときのスイッチングコストなど、人間の負担が大きい
 • AIが出力したコードに責任を持つのは人間
 • 「他人(AI)が書いたコードに対して自分が責任を持って最終的にPRを提出す る」という行為はものすごく大変

13. 仕様書分割による開発の試み

14. 14 新しいアプローチ：全体設計から仕様書分割へ
 • 仮説：全体設計から分割した仕様書を作成すれば生産性が向上するのではないか
 • 前回の課題
 ◦ 複数のAPI実装を１つの仕様書としてわたしてしまったため、タスクの数も多くなり、管理が大変になってし まった
 • 期待される効果
 ◦ 仕様書が小さくなれば、自ずとタスクの粒度も小さくなる
 ◦ タスクが小さくなれば、AIの自律性とレビュー負担が改善する
 ◦ 分割した仕様書は並列に進めることもできる（かもしれない）

15. 全体設計
 作業しやすい
 粒度に分割
 分割した単位で仕様書駆動開発
 要件定義書
 作成
 設計書
 作成
 タスクリスト
 作成
 実装
 実装レビュー
 開発の流れ
 • 基本的にすべての設計をAI主体で進める
 • 人間の役割は「責任を負うこと」「自分が作業しやすい粒度に分割すること」「レビューすること」
 15
16. 16 • 理想は1つの仕様書で1つのPRをつくるぐらいのもの
 • 複数の機能を1つの仕様書に含めない。ユースケース単位にする
 ユーザー管理機能をつくって
 ユーザー登録機能をつ くって
 ログイン機能をつくって
 パスワードリセット機能 をつくって
 ログアウト機能をつくっ て
 どのような粒度で分割するべきか

17. 17 たくさんの仕様書を作らないといけない

18. 18 Spec Workflow MCPとは
 • https://github.com/Pimzino/spec-workflow-mcp
 • 仕様書駆動開発をスムーズに行うためのフレームを提供するMCP
 • 大きな特徴として、明確な承認フローをGUIで提供する
 Spec Workflow MCPを導入

19. 19 Spec Workflow MCPが解決すること
 1. GUIによる状態管理
 ◦ どの仕様書が要件定義段階か、設計段階か、実装段階か一目瞭然
 ◦ 複数仕様書を並行管理しても破綻しない
 2. 承認フローで認識合わせ
 ◦ LLMとの認識齟齬を各承認フローで防ぐ
 3. テンプレートで高速イテレーション
 ◦ 複数の仕様書を素早く作成
 ◦ フィードバック・修正もGUIを使用することで的確に行える
 Spec Workflow MCPを導入

20. 実際の流れ

21. 実際の流れ
 21
22. 実際の流れ
 22
23. 実際の流れ
 23
24. 実際の流れ
 24
25. 実際の流れ
 25
26. 実際の流れ
 26
27. 実際の流れ
 27
28. 実際の流れ
 28
29. 実際の流れ
 29 番外編
 コードレビューにはdifitというツールを使うと非常に便利

30. 30 • 分割した仕様書を並列で作成していく
 ◦ 仕様書の作成であれば依存関係は薄いため並列化しやすい
 • 実装を並列に進められそうな場合はgit worktreeを利用して、別 プロセスでタスクを進めていく
 実際の流れ

31. 成果

32. 32 やってみた成果
 自律性
 並列化
 ボトルネックになる人間
 小さな仕様書で認識齟齬を減らすことで、タスクを丸投げしても見当違いのもの をつくることが減った
 分割する時点で並列化を意識することで実際に3-5並列を実現できたが、
 スイッチングコストの負担は変わらず思っていたほどの効果は出なかった
 細かい仕様書の段階で実装方針を理解しているため、コードレビューで「意図を 読み解く」作業が不要になり負担が軽減された

33. 33 やってみた成果
 自律性
 並列化
 ボトルネックになる人間
 小さな仕様書で認識齟齬を減らすことで、タスクを丸投げしても見当違いのもの をつくることが減った
 分割する時点で並列化を意識することで実際に3-5並列を実現できたが、
 スイッチングコストの負担は変わらず思っていたほどの効果は出なかった
 細かい仕様書の段階で実装方針を理解しているため、コードレビューで「意図を 読み解く」作業が不要になり負担が軽減された

34. 34 新たに見えてきた課題
 • 仕様書作成のオーバーヘッド
 ◦ 仕様書を作るにもコストがかかる
 ◦ どの規模から仕様書駆動開発を使うべきか、判断基準が必要
 • 依然として並列化の難しさ
 ◦ 仕様書を適度に分割しても、同時進行は人間の認知負荷が大きく思った効果を発揮できない
 ◦ 実装レベルでのコンフリクトが発生し新たなコストが生まれてしまう
 • AIが生成する仕様書の冗長さ
 ◦ AI向けには十分だが、人間が読むには編集・要約が必要

35. まとめ

36. 36 • 仕様書分割により、AIの自律性とレビュー負担が改善
 • 並列化は限定的だが、全体として開発効率は向上した 
 • Spec Workflow MCPのようなツールで管理することが重要

37. ご清聴ありがとうございました