仕様駆動開発で作った Spec ファイルってどうするの ? ~ 仕様とコードの乖離問題を考えてみる ~
2026-01-05 | Author : 宇賀神みずき (しょぼちむ)
はじめに
こんにちは！アプリケーション開発コンサルタントのしょぼちむです。
2025 年 11 月 に Kiro が一般公開され、Kiro の得意分野である仕様駆動開発も徐々に注目を集めてきています。仕様駆動開発では、明確な仕様を起点に設計・実装を進めていくことで、AI を活用した開発を効率化できます。
しかし、「仕様を定義したファイル (Spec ファイル) は一時的なもので、正式なドキュメントは別途作成・管理する」という方も多いのではないでしょうか。
その結果、次のような「よくある困りごと」が発生します。
- バグ修正時に「なぜこの設計にしたのか」が分からず、影響範囲の特定に時間がかかる
- 新メンバーのオンボーディングで、実装の背景となった要件が不明
- 機能追加時に過去の設計判断との整合性が取れない
- 仕様変更時にどのファイルを更新すべきかわからない
- Spec ファイルが古いため AI に質問しても誤った回答が返ってくる
- 複数のドキュメントを手動で同期する作業で二重修正が発生する
そのため、Spec ファイルを捨てるのではなく、継続的に育てることが重要です。
本記事では、Agent Hooks を活用 して Spec ファイルを「生きたドキュメント」として継続的に管理する方法を紹介します！
X ポスト » | Facebook シェア » | はてブ »
builders.flash メールメンバー登録
builders.flash メールメンバー登録で、毎月の最新アップデート情報とともに、AWS を無料でお試しいただけるクレジットコードを受け取ることができます。
この記事で得られること
この記事を読むことで、次のことができるようになります。
- Spec ファイルを継続的に管理し、一時的なものから生きたドキュメントに変える方法がわかる
- 適切な Spec 分割により、チームの並行開発と保守性を両立する
- Agent Hooks を活用して、Spec ファイルから必要なドキュメントを自動生成する仕組みをつくる
よくある問題パターン
Kiro では、仕様駆動開発において、3 つのファイルを段階的に作成します。それぞれ、レビューをしてファイルの内容をブラッシュアップしていきます。今回は、この 3 つをまとめて Spec ファイルとして扱います。
- requirements.md : 要件・仕様を定義したファイル
- design.md : 設計方針を定義したファイル
- tasks.md : 実装のためのタスクリストがまとめられたファイル
そして、起こりがちなのが、Spec ファイルを一時的なファイルとして扱い、開発が完了した後はそれらを捨ててしまうことです。
- Spec ファイル生成
- 実装
- Spec ファイル削除 (もしくは塩漬け)
- 正式なドキュメント作成（要件定義.md, インフラ設計.md など）
この運用では、実装の根拠となった仕様が失われてしまい、将来の機能追加時に過去の設計意図が不明になってしまいます。近年はアーキテクチャの意思決定を残しておく ADR (Architecture Decision Record) という手法もありますが、せっかく Spec ファイルに意思決定が残っているのに、わざわざ ADR を残すのは二度手間になってしまいます。
Spec ファイルを継続的に管理しよう
仕様駆動開発の効果を最大化するために、Spec ファイルを継続的にアップデートすることが重要です。Kiro の FAQ でも更新について言及されています。
Spec ファイルをアップデートしつづけるとこで、Single Source of Truth としての価値を得られます。
- 要件変更時の影響範囲を正確に把握
- AI が常に最新の仕様を理解
- 実装とドキュメントの整合性保証
境界づけられたコンテキストによる Spec 分割
Spec ファイルを継続的にメンテナンスをする場合、Spec をどういった単位で作り、適切なサイズや責任範囲を持っていることが気になってくるのではないでしょうか。1 つのアイデアとして、ドメイン駆動設計の境界づけられたコンテキストを活用することで、適切なサイズと責任範囲を持つ Spec を作成できます。
境界づけられたコンテキストは、ここでは「仕様とコードの責任範囲を切る単位」として扱います。ドメイン駆動設計を深く理解していなくても、「境界づけられたコンテキスト = 変更の責任範囲の単位」と捉えるだけで十分活用できます。
なお、プロジェクト全体に影響させたい知識については streeing の機能を利用して保持できます。
なぜ境界づけられたコンテキストと Spec の分割が相性が良いのか
- 責任境界の一致 : 境界づけられたコンテキストの責任範囲 = Spec の責任範囲となり、変更の影響範囲が明確
- チーム構造との整合 : チーム間またはメンバー間で並行して作業する場合、1 つのチーム / メンバーが 1 つのコンテキストを担当することで、Spec の所有権も明確化
- 独立した進化 : 各コンテキストが独立して進化できるため、並行開発が可能
- レビューのしやすさ : 取り扱う業務範囲を特定し、変更の範囲を限定することでレビューのしやすさが向上
Spec 分割の例
EC サイトを例にすると、以下のような分割が考えられます。
ecommerce-system/
├── order-management/ # 注文管理の境界づけられたコンテキスト
│ ├── requirements.md # 注文に関する要件
│ ├── design.md # 注文処理の設計
│ └── tasks.md # 実装タスク
├── inventory-management/ # 在庫管理の境界づけられたコンテキスト
│ ├── requirements.md
│ ├── design.md
│ └── tasks.md
└── payment-processing/ # 決済処理の境界づけられたコンテキスト
├── requirements.md
├── design.md
└── tasks.md1 Spec として扱うのが大きすぎる場合
また、1 つの境界づけられたコンテキストが複数のユースケースを含み、1 Spec として扱うのが大きすぎる場合は、関連するユースケース群で分割します。
order-management/ # 注文管理の境界づけられたコンテキスト
├── order-creation/ # 注文作成のユースケース群
│ ├── requirements.md
│ ├── design.md
│ └── tasks.md
├── order-fulfillment/ # 注文履行のユースケース群
│ ├── requirements.md
│ ├── design.md
│ └── tasks.md
└── order-cancellation/ # 注文キャンセルのユースケース群
├── requirements.md
├── design.md
└── tasks.mdSpec サイズ管理の自動化
適切なサイズで分割をしたいという気持ちがあっても、開発を続けるうちにいつの間にか Spec ファイルが大きくなりすぎることもあるかと思います。そんな時には Kiro の Agent Hook の機能が役に立ちます。
Agent Hook は、何かしらのファイルの変更を契機に、生成 AI のプロンプトを実行するための機能です。例えばソースコードを変更した時にテストや API ドキュメントを生成させるなど、様々な用途に使える便利な機能です。 もちろん、Agent Hook が動作して提案を適用されたものを反映するかどうかはしっかりレビューが必要です！
Agent Hook の設定
以下は Spec ファイルを変更したときに分割を提案する Agent Hook の設定です。
{
"enabled": true,
"name": "Document Size Monitor",
"description": "Monitors requirements.md, design.md, and tasks.md files for size limits and suggests splitting strategies when they exceed thresholds (requirements.md: 2000 lines, design.md: 1500 lines, tasks.md: 1000 lines)",
"version": "1",
"when": {
"type": "fileEdited",
"patterns": [
"requirements.md",
"design.md",
"tasks.md"
]
},
"then": {
"type": "askAgent",
"prompt": "ファイルサイズをチェックし、以下の基準を超えている場合は分割を提案してください：requirements.md: 2000行超過、design.md: 1500行超過、tasks.md: 1000行超過。分割提案内容: 1) ドメイン境界での分割案 2) ユースケース単位での分割案 3) 分割後の依存関係図。現在編集されたファイルの行数を確認し、基準を超えている場合のみ分割提案を行ってください。"
}
}今回は分割の提案でしたが、コードを変更したら Spec ファイルとの整合性をチェックするという設定も可能です。ただし、Agent Hook を広い範囲で設定してしまうと、毎回修正する度にプロンプトが動いてしまって Agentic Coding の妨げになったり、不要にトークンを消費したりするので、注意が必要です。最低限どういった設定をすれば品質を高く保てるのかを検討して、設定しましょう。
運用フローの変化
Spec ファイルをメンテナンスしない開発フローでは、以下のような問題が発生していました。
- Spec ファイルは実装時の一時的な参考資料として扱われる
- 実装完了後、Spec ファイルは削除または放置される
- 正式ドキュメントは別途作成される
- この結果、実装と Spec の間で乖離が発生し、将来の保守性が低下する
新しいアプローチでは、以下の流れで一貫性を保ちます。
- Kiro Spec を継続的に管理し、実装と並行してアップデート
- Agent Hooks が変更を検知し、関連ドキュメントを自動更新
- 実装されたコードからも逆方向で Spec やドキュメントに情報を反映
- この結果、Spec と実装が常に同期された生きたドキュメントとして機能する
まとめ
仕様を中心に据えて、Spec を継続的に育てることが、仕様駆動開発では重要です。Agent Hooks を活用することで、Spec ファイルを一時的なものではなく、継続的に進化する生きたドキュメントとして運用できます。適切なサイズでの Spec 管理と自動化により、長期的な保守性と開発効率を両立することが可能になります。
- AI が常に最新 Spec を参照できるため、プロンプトからの回答精度が向上
- Spec を参照したコード生成の信頼性向上
- 仕様変更後も AI に「最新仕様に基づいた回答」を得られる
- テストケース生成や API ドキュメント生成との整合性が保たれる
ぜひ、Kiro の仕様駆動開発を試してみてください ! Kiro には今回ご紹介していない便利な機能 (MCP, steering など) も多くあります。実際に機能を試していただいて、保守性の高いシステムをどう作っていくかを X などでシェアいただけると嬉しいです !
筆者プロフィール
宇賀神 みずき (しょぼちむ / @syobochim)
アマゾン ウェブ サービス ジャパン合同会社
アプリケーション開発コンサルタント
SIer でのアプリケーション開発者を経験後、2020 年にパートナーソリューションアーキテクトとして AWS Japan に入社し、2024 年にデリバリコンサルタントへ異動。主に開発者の方に向けてシステム開発のご支援を担当しています。初心者向けの『いちばんやさしいGit&GitHubの教本』という本も書きました。
インドア派でしたが、最近は子どもと一緒に毎週公園で日を浴びています。
