Kiro × Sphinxで効率化するプロジェクト開発手法

これは豆蔵デベロッパーサイトアドベントカレンダー2025第24日目の記事です。

AWSは2025年11月18日、AIエージェント型IDEKiro(https://kiro.dev)の一般提供を発表しました。

筆者は以前プレビュー版を使ってのレビュー記事を執筆しました。
それ以来Kiroのファンとなり、現在は実業務でKiroを使用しています。

AIエージェント型IDE「Kiro」の登場により、個人開発やプロトタイピングの速度は劇的に向上しました。
しかし、開発規模が大きくなるにつれて、「AIへの指示（コンテキスト）」をどのように管理するかという新たな課題も生まれています。

筆者は、この課題を解決するためにドキュメントビルドツール「Sphinx」を導入しました。
この試みは今のところうまくいっています。今回は、その開発スタイルを紹介します。

Kiroは非常に優秀ですが、ある程度規模の大きい開発プロジェクトに適用しようとすると、以下の2点でコンテキスト管理の限界に直面します。

① requirements.md の肥大化と混乱

Kiroの基本的な使い方は、.kiro/specsディレクトリ内の requirements.md に要件を記述することです。
しかし、機能が増えるにつれてこのファイルは数百行・数千行に膨れ上がり、AIが文脈を見失ったり、人間側もメンテナンスが困難になります。

② ディレクトリ分割のジレンマ

これに対する策として、.kiro/specs ディレクトリ内に機能ごとのサブディレクトリを作り、そこに requirements.md を分散させる方法があります。
しかし、これには 「鶏と卵」の問題 があります。開発初期の要求分析段階では、どのような機能分割が最適かはまだ見えていません。
Kiroと会話しながら要件を詰めたい段階で、事前にディレクトリ構造をカチッと決めるのは不向きであり、柔軟性を損ないます。

そこで提案したいのが、Python製ドキュメントツールとして有名な Sphinx を、要求仕様書や設計書の管理・ビルド基盤として採用する方法です。

Sphinxは単なるマニュアル作成ツールではありません。テキストベースで構造化されたドキュメントを管理できるため、Kiroとの親和性が極めて高いのです。

要求仕様書や設計書をSphinxプロジェクトとして管理することで、具体的に以下の効果が得られます。

1. 人間にとっての可読性向上（HTML/PDF化）

   • 複数のテキストファイルをビルドし、見やすいHTMLやPDFとして出力できる
   • 開発者やステークホルダーは、コードのようなテキストファイルではなく、整理された「仕様書」としてブラウザで全体像を確認できる

2. 文書構造によるコンテキスト整理

   • Sphinxの toctree 機能を使えば、ファイルを機能やレイヤーごとに分けて管理しつつ、1つの体系的なドキュメントとして統合できる
   • Kiroに指示を出す際も「今回は auth.rst（認証機能）を参照して」と明確にスコープを限定できる

3. テキストベースだからKiroが読める

   • Sphinxのソースコードはプレーンテキストであるため、Kiroはプロジェクト内のドキュメントを直接読み込み、理解できる
   • 「仕様書そのもの」がAIへのプロンプトとして機能する

4. 図解（画像）によるコンテキスト共有

   • Sphinxプロジェクト内に配置した画面モックアップ、ER図、分析モデルなどの画像をKiroは認識できる
   • 「この図に従って実装して」と指示することで、テキストだけでは伝わりにくいニュアンスを共有可能となる

5. 概要から詳細仕様への自動生成フロー
   • 人間が「システムの概要」や「業務フロー」をざっくりと書き、それをベースにKiroへ「各機能のユースケース記述を作成して」と依頼できる
   • AI自身にドキュメントを書かせ、仕様を固めてから実装に移る「上流工程の自動化」が可能になる

実際にKiroへどのように指示を出せばよいか、具体例を紹介します。

Specモードで下記のプロンプトを打ち込みます。

アルバムアプリを作成したい。

docs/requirements内にSphinxで要求仕様書を作成して欲しい。
HTMLのテーマはsphinx-rtd-themeを使用して。
PodmanでビルドできるようにDockerfileとHTML, PDFビルド用のバッチファイルを作成して。
Dockerfileのベースイメージはsphinxdoc/sphinx-latexpdfを使用して。

Kiroは要求仕様書を作成するためのプロジェクトを開始します。

ある程度、要求仕様書に書く内容がイメージできている場合は、文書の構成を指示しても良いでしょう。

requirements.mdと要求仕様書は日本語で書いて
ドキュメント構成は下記のようにして

index.rst      # 全体目次
├ overview/
│  └ index.rst # システム概要
├ usecase/
│  ├ index.rst         # ユースケース目次
│  ├ uc01-login        # UC01_ログインする
|  ├ uc02-browse       # UC02_アルバムを閲覧する 
|  ├ uc03-upload       # UC03_コンテンツをアップロードする
|  ├ uc04-edit         # UC04_コンテンツを編集する
|  ├ uc05-delete       # UC05_コンテンツを削除する
|  └ uc06-manage-users # UC06_ユーザーを管理する
├ screen/
│  ├ index.rst         # 画面仕様目次
│  ├ login.rst         # ログイン画面
│  ├ main.rst          # メイン画面
│  ├ edit.rst          # 編集画面
│  └ manage-users.rst  # ユーザ管理画面
└ changelog/
   └ index.rst         # 改訂履歴

上記の指示で作成された仕様書が下記です。
何も要件を入力していないですが、AIが勝手に想像して仕様を書いてくれています。

バッチファイルは軽微な修正が必要でしたが、HTMLやPDFにビルドするときれいに出力されます。

PDFにはスタイルの不自然なところがありますが、Kiroと相談しながら進めれば、専門的なTexの知識がなくても修正は可能です。

要求仕様書の修正は、手書きで修正可能なほか、
下記のようにSpecモードで要件を列挙して修正させることも可能です。

docs/requirements内のアルバムアプリの仕様ですが、下記のようにしたい

ユーザー認証はGoogleアカウントを使用すること。
管理者権限のあるユーザーのみ、ログイン可能なユーザーを追加・削除ができること。
管理者権限のあるユーザーは、バックエンドアプリケーションの設定ファイルで可能なこと。
写真だけでなく、動画もアップロード可能であること。
アップロード可能なファイルの上限は100MBであること。
アップロード可能なファイルの拡張子はJPG, PNG, HEIC, MP4, MOVであること。
ファイルのメタ情報から日付を取得し、『/data/pict/<YYYYMMDD>』というパターンのディレクトリを作成し、その中にファイルを保存すること。
ファイルのサムネイル画像を作成し、『/data/thumb/<YYYYMMDD>』というパターンのディレクトリを作成し、その中にサムネイル画像を保存すること。
写真の一覧はサムネイル画像を表示すること。
サムネイル画像のサイズは縦幅、横幅が300ピクセル以下となること。

要求仕様書が書けたら設計書も作成します。Specモードで下記の指示を出します。

docs/requirements内のアルバムアプリの仕様に基づいて、
docs/design内にSphinxでアーキテクチャ設計書を作成して欲しい。

フロントエンドはAngular、バックエンドはASP.NET Coreで。
実行環境と開発環境はPodmanコンテナ上で動くこと。

上記の指示で作成された設計書が下記です。

Dockerイメージにsphinxcontrib-mermaid拡張機能がインストールされていたため、ドキュメントをビルドするとKiroがMermaidで描いた図も表示されました。

実装フェーズでは、Specモードで下記のように指示を与えます。

docs\requirementsの要求仕様書と、
docs\designの設計書を参考に、
アルバムアプリのログイン機能を実装して

これだけの指示で、Kiroはログイン機能に必要な情報を探し出してrequirements.mdを作成してくれます。

これ以降は、下図のフローに従って実装まで進めていくだけです。

Sphinxを導入することで、要求仕様書や設計書を「人間が読みやすい形式」と「AIが処理しやすい形式」の両方で管理できるようになります。

今回ご紹介した手法であれば、開発規模の大きなプロジェクトでもKiroを扱いやすくなるのではないでしょうか。

本記事を今後の開発の参考にしていただければ幸いです。