こんにちは、AWSグループの藤岡です。AIを使って毎日楽しく開発しています。
2025年7月にKiroがリリースされ、仕様駆動開発が大きな注目を集めています。
AIを活用した開発スタイルの1つとしてVibe codingという「プロンプトを直接与えてコードを書かせる」シンプルかつ即興的な開発スタイルが注目されています。一方で、仕様をもとに開発を駆動させるという、より実業務に適用しやすい開発スタイルが、Kiroおよび仕様駆動開発の大きな魅力の1つです。
私自身も、これまではAmazon Q Developer CLIを使って開発していましたが、Kiroの登場以降は、仕様駆動開発に大きな期待を寄せています。
そこで今回は、私自身が使い慣れているAmazon Q Developer CLIを使って、エージェントとプロンプトをカスタマイズして、簡単な要件をもとにドキュメント作成（要件定義・仕様・設計）、実装、テストを進める仕様駆動開発を試してみたので、そのプロセスの共有と、やってみて分かった良い点・注意点などをご紹介します。
※仕様駆動開発についての説明は割愛しますので、詳しく知りたい方は参考に以下サイトをご確認ください。
仕様駆動開発（Spec-driven development）とは？：AI・機械学習の用語辞典 - ＠IT
Amazon Q Developer CLIとは
Amazon Q Developer CLI（以下、Qdev と記載します）は、ソフトウェア開発のためのコーディングエージェントであるAmazon Q Developerを、コマンドライン（CLI）で扱うことができます。ローカルPCにインストールしてQdevを起動し、コマンドラインから指示することで、ソースコードの説明や、アプリケーションの実装、テストケースの作成・実行などを行うことができます。
Qdevには、エージェントとプロンプトを設定することができます。今回はこれらを駆使して、仕様駆動開発にトライします。
（私見も含みますが、）それぞれのざっくりした説明・使い分けは以下の通りです。
詳細を知りたい方は、ユーザーガイドの以下ページをご覧ください。
セットアップ
仕様駆動開発を進めるために、最初に以下2つを準備します。
- エージェント・プロンプトの作成
- ラフな要件を決める
エージェント・プロンプトの作成
Qdevを起動して、今回のためにPoC開発エージェントを作成します。
q chat /agent create --name "poc-developer" --directory .
コマンド実行したディレクトリに、.amazonq/agents/poc-developer.jsonが作成されます。このファイルを編集して、エージェントを定義します。今回は以下のように編集しました。(空であったdescriptionとallowedToolsを追記しています。)
{ "$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json", "name": "poc-developer", "description": "This is a developer agent for PoC software application. It can implement and test, and make documentation such as requirements and design. It must follow the rules and instructions...(略)", "prompt": null, "mcpServers": {}, "tools": [ "*" ], "toolAliases": {}, "allowedTools": [ // 起動時にデフォルトで許可されるツール "fs_read", "fs_write", "thinking" ], "resources": [ "file://AmazonQ.md", "file://AGENTS.md", "file://README.md", "file://.amazonq/rules/**/*.md" ], "hooks": {}, "toolsSettings": {}, "useLegacyMcpJson": true, "model": null }
一度セッションを切って、作成したエージェントを指定して再度Qdevを起動します。
q chat --agent poc-developer
デフォルトではないカスタマイズしたエージェントが起動します。以降の開発はこのエージェントを使用します。
次にプロンプトを作成します。今回は以下のプロンプトを揃えて、仕様駆動開発を進める準備を整えます。
.amazonq/prompts/ ├── require.md # 要件定義書の作成・レビュー ├── spec.md # 仕様書の作成・レビュー ├── design.md # 設計書の作成・レビュー ├── impl-plan.md # 実装計画の作成 ├── impl.md # 実装の作成・修正 └── test.md # テストの作成・実行
ここでは参考に、testプロンプト（test.md）をお見せします。AIが手抜きして品質が落ちないように指示を書きました。
# prompt for testing implementation (frontend/backend) あなたは、ソフトウェアテストのエキスパートです。以下の指示・原則に従い、テスト計画・実装・品質担保を進めてください。 ## 1. 全体方針 - 実装後は必ずテストコードの追従・テスト実行を行い、全テストがOKになることを確認する。 - テスト観点の網羅性はdocsフォルダを元に担保し、特に`docs/specifications.md`の仕様と`docs/design.md`の設計を考慮して、必ずテスト観点に盛り込む。 ## 2. テスト実装指針 - テストコードは`tests`ディレクトリに配置する。 - テストケース名は"test_関数名_条件"形式で命名。 - 正常系: `test_関数名_ok` - 異常系: `test_関数名_ng_理由`（例: `test_関数名_ng_not_found`） - レポート - プログラミング言語ごとに推奨されるライブラリを使用して、レポート作成HTMLレポートを生成し、`tests/reports/`配下に保存する。 - Assertions（期待値の検証）を重視し、値/データ型の検証や完全一致の検証を必ず行う。 - 正常系だけでなく異常系テストも必ず実装する。
業務レベルのテストを生成するには上記の記載以上の指示を与える必要がありますが、実装やテストは繰り返し行いたいので、毎度指示していたら大変です。そこでプロンプトを設定することで、@test テストお願いしますのように@プロンプト名 〇〇してくださいという形で効率的に指示することが可能になります。
以上でエージェントとプロンプトの準備が完了しました。
ラフな要望を決める
仕様駆動開発の起点となる、つくりたいアプリをラフに決めます。今回はタスク管理Webアプリケーションを成果物として、以下のようにdocs/basement.mdを作成しました。（正味30行です）
# basement requirements このドキュメントは、仕様駆動開発の一環として、Amazon Q developer CLIを使用して、タスク管理Webアプリケーションを実装するためのラフな仕様・動作イメージをまとめたものです。 ## 目的 - スイムレーン形式でタスクを管理できるWebアプリケーションを作成する - タスクには日時で期限を設定できるようにする ## 仕様イメージ ### 画面イメージ - Webページはシングルで、上下２画面構成とする - 上部に検索などの画面、下部にタスク一覧を表示する - 選択しているタスクが無い場合には、タスク一覧のみが表示されている - タスク一覧は、スイムレーン形式で表示する - スイムレーンは、タスクの状態ごとに分けて表示する ### タスク詳細イメージ - タスクは以下の情報を持つ - 必須 - タイトル - 状態（着手検討待ち、着手待ち、進行中、完了、連絡待ち、中止、ストック） - 任意 - 詳細 - 期限日 - 期限時間 - タスクの状態は、順序のルールなく自由に変更可能とする ## 技術スタックに対する要望 - フロントエンド - React - TypeScript - バックエンド - Lambda - TypeScript - DynamoDB
仕様駆動開発の実践
いよいよ仕様駆動開発をはじめます。流れとしては以下の4ステップで、ステップ1, 2, 3ではプロンプトを中心に進めます。ステップ4は手動で行います。
ドキュメント作成（要件定義書・仕様書・設計書）
まず要件定義書を作成するために、requireプロンプトを実行します。
[poc-developer] > @require docs/basement.mdに記載されたラフな要望をもとに、タスク管理Webアプリケーションの要件定義書を作成してください。
すると、記載したプロンプトが表示（エージェントに指示）されてから、ドキュメント作成が始まりました。
# prompt for create requirements document あなたは、要件定義・業務分析のエキスパートです。ユーザーから、指定されたドキュメントをもとに、あるいは業務・システム要件をヒアリングし、体系的な要件定義書ドラフトを作成します。 その後、ユーザーにレビューを促して、セクションごとにレビューを行います。レビューをもとにユーザーから修正依頼や質問・確認を受けた場合には、レビューを中断してユーザーの指示（記載の修正、質問・確認への回答）を忠実に行います。 以下プロンプトを省略 承知しました。要件定義・業務分析のエキスパートとして、docs/basement.mdをもとに、タスク管理Webアプリケーションの要件定義書を作成します。 以下略
出来上がった要件定義書（docs/requirements.md）を確認してみます。
# タスク管理Webアプリケーション 要件定義書 ## 1. 基本情報 | 項目 | 内容 | |------|------| | サービス名 | タスク管理Webアプリケーション | | 作成日 | 2025-10-09 | | 作成者 | [作成者名] | | バージョン | 1.0 | | 対象システム | スイムレーン形式タスク管理システム | ## 2. 背景・目的 ### 2.1 背景 - 個人・チームでのタスク管理において、視覚的で直感的な管理方法が求められている - 既存のタスク管理ツールでは、タスクの状態遷移が分かりにくい - タスクの期限管理による進捗把握が必要 ### 2.2 目的 - スイムレーン形式による視覚的なタスク管理の実現 - タスクの状態遷移を直感的に操作可能なUIの提供 - 期限設定による効率的なタスク管理 中略 ## 4. 機能要件 ### 4.1 タスク管理機能 #### 4.1.1 タスク作成 - WHEN ユーザーが新規タスク作成を選択 THEN タスク作成フォームが表示される - WHEN 必須項目（タイトル、状態）を入力して保存 THEN 新しいタスクが作成される #### 4.1.2 タスク表示 - WHEN アプリケーションにアクセス THEN スイムレーン形式でタスク一覧が表示される - WHEN タスクを選択 THEN 下部にタスク詳細が表示される - IF タスクが選択されていない THEN タスク一覧のみが表示される #### 4.1.3 タスク編集 - WHEN タスク詳細画面で編集 THEN 以下の項目を変更可能 - 必須項目：タイトル、状態 - 任意項目：詳細、期限日、期限時間 以下略
プロンプトに書いた通りの章/節立てをベースとして、適切に節が追加されていて、ドキュメントとして適切な構成になっています。また記載内容も、ラフな要望をベースに、背景や目的、詳細な機能要件や非機能要件などが詳しく書かれています。想定以上の出来栄えでした。
少し気になる点もありますが、用意したプロンプトに作業を委ねるために、requireプロンプトを再度実行して、要件定義書をレビューと修正を進めます。
[poc-developer] > @require レビューよろしく。 中略 > 基本情報セクションの確認・修正依頼： 抜け漏れ・曖昧な点： • 作成者名が未記入 • 利用対象者の明記がない • システム規模の想定が不明 追加ヒアリング： 1. 作成者名を教えてください 2. 利用対象者は？（個人利用/小規模チーム/大規模組織） 3. 想定同時利用者数は？ 4. 開発完了予定時期はありますか？ これらの情報をお聞かせください。情報が揃い次第、基本情報を更新して次のセクション（背景・目的）のレビューに進みます。 または、現在の内容で問題なければ「次へ」とお答えください。
真っ当なレビューコメントが返ってきました。ただ今回は検証目的なので、修正せずに次へ進みます。
機能要件のレビューにて、以下のように期限を過ぎたタスクの扱いについて指摘されたので、ドキュメント更新を指示しました。
@require 回答します。期限が過ぎたタスクは、カードの色を変えて目立つようにしてください。
するとエージェントからは...
中略 > 要件定義・業務分析のエキスパートとして対応します。 継続して非機能要件のレビューを実施していきます。 ・・・
何度か頼みましたが、記載の修正に応じてくれません。。。 requireプロンプトの「作成とレビューを行う」という指示を遵守している挙動のようです。以下のようにプロンプトを一部修正しましたが、それでもレビューを頑なに中断してくれません😖
# 修正前 ドラフト生成後、ユーザーへレビューを促してください。 # 修正後 - ドラフト生成後、レビューをユーザーへ促してください。 - レビューは各セクションごとに行い、以下の「レビュー・追記のポイント」に記載するポイントを押さえて作業してください。 - 各セクションのレビューに対して、ユーザーからの返答・修正指示があった場合、次セクションのレビューへ、絶対に進まないでください。（中断してください。） - レビューの代わりに、ドラフトに対して修正を行い、修正内容をユーザーに確認するように促してください。 - 確認して問題ない返答をユーザーから受け取った後で、次セクションのレビューを再開してください。それまでは絶対に次セクションのレビューへ進まないでください。
結果的に、プロンプトなしでエージェントに指示することで、期待通りに要件定義書を以下のように更新してもらいました。
#### 4.1.7 期限切れタスク表示 - WHEN タスクの期限日が現在日時を過ぎている THEN タスクカードの色が変更されて表示される - IF タスクに期限が設定されていない THEN 通常の色で表示される
レビューを通して要件定義書を更新・仕上げるのに並列して、レビュー指摘を踏まえてプロンプト自体も修正しておきました。（これで次回に要件定義書を新規作成する時には、よりハイレベルなアウトプットを得られそうです！）
同じように、プロンプト実行、レビュー、エージェントに直接指示してドキュメント更新して、仕様書と設計書も仕上げました。
以上でドキュメント作成は完了です。
また、設計書を元にWebアプリの構成図を書くと、以下のようになります。
実装計画の作成、実装
次は作成したドキュメントを参照ながら、実装計画を作成し、それをもとに実装を進めます。
@impl-plan docsフォルダの仕様と設計をもとに、実装計画を作成してください。まずはバックエンドからお願いします
実行すると.amazonq/cli-todo-listsにJSONファイルが作成されてToDo形式で実装計画が作成されます。以降の実装作業はこのJSONファイルでToDo管理することによって、エージェントが進捗やゴールを見失うのを防ぎます。
実装計画をもとに、実装します。
@impl 実装を始めてください。
ここまでのドキュメントのレビュー・更新のおかげで、自分が望んだ構成や品質のソースコードがもの凄いスピードで生成されていきます。
実装計画を途中経過を見ると、以下のように表示されています。こうやってタスク進捗が明確に見えると、ユーザー自身も実業務で使う時も安心できますね。
テスト作成、実行
👆の実装ステータスで、まだ実装タスクは完了してませんが、既に出来上がったユーティリティ実装を対象にテストをしてみます。
@test 実装をもとにテストを作成・実行してください。
いいですね、プロンプト通りにテストを作成・実行してくれました。プロンプトの指示通りに異常系のテスト作成やレポート作成まで行ってくれました。ここまでやってくれると、実案件でも十分有用に感じます。
レポートも期待するようにHTMLファイルで出力してくれました。
実装プロンプトとテストプロンプトを繰り返し実行しながら、開発を仕上げます。 フロンエンドも同様に、まず実装計画を作成して、実装とテストを進めます。（最終的に、バックエンドで115件とフロントエンドで45件のテストケースを作成しました。）
デプロイ、動作の確認
このステップは手動で進めます。作業しやすいように、作成したIaCファイルを指定して、環境変数の指定やデプロイ手順などの一連の手順書をエージェントに作成してもらいました。
先にバックエンドをデプロイして、作成したAPI Gatewayのエンドポイントをフロントエンドの環境変数に設定してフロントエンドをデプロイします。なおデプロイでのエラーは、template.yamlのバケットポリシーが1箇所誤っていたのみで、他はすべて問題なくデプロイできました。
作成したCloudFrontディストリビューションにアクセスすると、以下のように画面が表示されました。画面イメージなく初手でここまで作成できるのはかなり嬉しいですね。
右上の"+新規タスク作成"を押すと、作成フォームが開きます。ステータスは、要望通りのステータスを選ぶことができました。
また、カレンダーから日付選択もできます。これは仕様として定義してなかったですが、この方が良いので仕様書を更新しておきました。（実業務ならドキュメントのレビュー段階で気づくべきですね）
作成すると、指定したステータスのスイムレーンにタスクが表示されました。
途中に期限を切れたタスクの仕様も加えましたが、仕様通りにカラー変更して目立つように表示されました。
DynamoDBテーブルからも、作成したタスクを確認できました。
タスクを別のスイムレーンに移動する更新処理や、削除ボタンからの削除処理はエラーしてしまいましたが、エラー内容をエージェントに伝えることで、実装&テストを修正して、正常に動くようになりました。
ラフな要望から、手軽でありながら、ドキュメントやテストケースを充実させつつ、仕様駆動開発によってWebアプリケーションを作成ことができました。
考察
ここまでのふり返りです。
よかった点
①実業務で必要な成果物一式を作成でき、手堅く開発できる
仕様駆動開発の醍醐味と言えますが、要件や仕様書、設計書を生成して、それを元に実装・テストを実施して、Webアプリを完成させました。
現場に即したプロセスの中で、エージェントやプロンプトを活用することで、ドキュメントやテストを揃えた手堅い開発をハイスピードで実践することができました。
案件やチームによってはいきなり全プロセスをエージェント・プロンプトで進めるのは難しいかもしれませんが、まずはテストのみ導入してみるなど、適用しやすいところから始めて、コーディングエージェントや仕様駆動開発の効果を実体験するのがオススメです。
②エージェント・プロンプトを育てることで、作業効率と品質をさらにアップできる
今回の検証における、私の作業時間は大まかに以下の割合になりました。
| 作業 | 割合 |
|---|---|
| エージェント・プロンプトの設定・更新 | 50% |
| ドキュメントのレビュー・修正 | 30% |
| 実装・テスト | 0% |
| デプロイ・動作の確認 | 20% |
作業時間の半分はエージェント・プロンプトの設定・更新ですが、これらは次回以降の開発でも流用できます。なぜならば、あくまで今回の要件はbasement.mdにのみ存在して、エージェントとプロンプトは要件に依存しない仕様策定や実装のスタンスやルールなどを定義しています。
そのため、次回の開発ではエージェント・プロンプトの設定・更新はもっと短時間で済みますし、エージェント・プロンプトはブラッシュアップを重ねていくことで更に高い品質のアウトプットを生成してくれます。
注意点
①AIの成果物を過信しない
今回の検証に限った話でありませんが、AIが生成した結果には誤りも含まれます。そのため、プロンプトで指定や制約を与えている場合も、必ずチェックを行いましょう。
とはいえ、ただ愚直にレビューを行っていると、AIのアウトプットの多さに人間が疲弊してしまうので、レビュー専用のプロンプトを用意して負担を減らすことや、レポートを作成するなど既存の開発スタイルの知見を活用することが非常に重要です。
また精度や品質の観点としては、今回は使用しなかったMCPサーバーをエージェントに設定することも有効です。
②コンテキストウィンドウのオーバーフロー後の挙動が不安定
実装途中にコンテキストウィンドウがオーバーフローして以降、エージェントが英語で質問や回答してきたりと、指示通りに動かなくなる時がありました。
Qdevでの上記への対処としては、コンテキストウィンドウの利用状況を /usage コマンドでチェックして、必要に応じて /compact コマンドを実行することで会話をサマリしてして空きスペースを増やす対応も可能です。ただ、集中して開発するのに加えて、コンテキストウィンドウまでお世話するのは面倒くさい...
また、どうやら既知の事象でIssue発行済みのようですので、早めの改善を期待します！
仕様駆動開発におけるQdev利用のススメ
主観的なコメントでもありますが、Qdevに設定したプロンプトは従順過ぎるほどに忠実に動いてくれる一方で、柔軟さに欠けるように感じます。そのため、プロンプト中で禁止を指示するだけでなく、プロンプトを分割してシングルタスクに集中させることが重要です。
※また今回は使わなかった.amazonq/rulesを使って、ルールや制約をプロンプトと分離すれば、もっと快適にドキュメンテーション・開発できるかもしれません。
また従順さゆえに、プロンプトの質がプロダクトの品質に直結するため、プロンプトを多くのプロダクト開発に利用しながら育てていくスタンスはやはり重要です。
従順さにアピールしてしまいましたが、裏を返すと、業務で使いたい仕様駆動開発においてはQdevはコントロールが効きやすくて非常に使いやすいAIエージェントだと思いました。これからエージェントとプロンプトを育てるのがますます楽しみになってきました！
まとめ
Amazon Q Developerのカスタマイズしたエージェントとプロンプトを使って、仕様駆動開発を実践してみました。
今回の検証を通して、30行の要望から、要件定義書からテストまでを一式揃えて、バックエンドとフロントエンド、インフラまで全て用意してWebアプリケーションをデプロイして、仕様駆動開発が現場でも有用であることが確認できました。
より自分の求める高い品質のアウトプットを生成するために、エージェントとプロンプトをブラッシュアップし続けることが重要なので、今後の開発でも積極的にQdevを活用していきたいと思います。
以上、フォージビジョンの藤岡でした！
