Amazon Web Services ブログ
バグ修正と既存アプリの上に構築するための新しい Spec タイプ
本記事は「New spec types: fix bugs and build on top of existing apps」を翻訳したものです。
モノリスからマイクロサービスへの移行を進めているとします。アーキテクチャはすでに明確で、イベント駆動、非同期メッセージング、特定のレイテンシ要件があります。必要なのは実装の手助けだけです。あるいは、バグを修正しているとします。何が壊れていて、何をそのままにすべきかはわかっています。外科的な修正が必要です。アプリの他の部分を変更したり、トークンを無駄に消費して堂々巡りすることなく、エージェントと協力してこれらの目標を達成する最善の方法は何でしょうか？
Specs と仕様駆動開発ワークフローをリリースした際、私たちは従来の PM/エンジニアリングのフローに基づいて構築しました。まず要件、次に設計、そしてタスクという流れです。これは多くのプロジェクトでうまく機能し、何十万人もの開発者が新しいものを構築する際にこのアプローチをデフォルトとして採用してきました。
しかし、Kiro ユーザーと話す中で、明確なパターンが見えてきました。すべての人が要件から始めるわけではないということです。特に既存のブラウンフィールドアプリで作業する場合、技術アーキテクチャがすでに決まっている状態で取り組む開発者もいます。バグ修正をしていて、何を変更し何を変更すべきでないかを慎重に定義する必要がある開発者もいます。Specs の構造は手放したくないが、現在のフローではこれらのタイプのタスクに対して十分な柔軟性がありませんでした。
開発者がすでに取り組んでいるプロジェクトへのアプローチを変えるよう求めたくはなかったので、本日、デザインファーストワークフローとバグ修正 の 2 つの新しい Spec をリリースします。
硬直的なワークフローが失敗する理由
Specs を最初に設計した際、私たちは Laurence Tratt が提唱するソフトウェア開発における「循環的仕様問題」と「観察者効果」に動機づけられていました。Tratt は根本的な緊張関係を指摘しています。構築したいソフトウェアを正確に知る唯一の方法は完全に仕様化することだが、完全な仕様はソフトウェア自体を作成するのと少なくとも同じだけの作業量が必要であるということです。これは、ソフトウェアを真に仕様化するためにはソフトウェアを構築しなければならないという鶏卵問題になってしまいます。特に大規模プロジェクトでは、これは希望的観測にすぎません。Tratt が観察するように、ソフトウェアは空想と現実の間の「リミナルな状態」にあり、実際に何かを構築するまで定量化が難しいソフトな制約に満ちています。ソフトウェアを作成する行為自体が仕様化の行為なのです。これは計画なしで作業するということではなく、素早く進捗できるだけの十分な構造を持つ中間地点に到達するということです。
要件ファーストとデザインファーストは同じコインの表と裏であり、この循環的仕様問題の異なる側面に対処しています。
- 要件ファーストは、必要な振る舞いや成果は理解しているが、技術的な道筋が不明確な場合に機能します。「これは何をすべきか？」を「どのように動作すべきか？」の前に探求します。選択肢が開かれている新規プロジェクトに最適なオプションです。
- デザインファーストは、経験、アーキテクチャ上の制約、またはプロトタイピングから技術的なビジョンをすでに持っていて、そのシステムが実際に何を達成するかを逆算して形式化する必要がある場合に機能します。ソリューションをホワイトボードに描いてから「この製品が何をするか」をまとめるようなものです。既存のアプリの上に新しい機能を構築する場合にも適用できます。現在のアーキテクチャと技術スタック内で作業する必要があるからです。
どちらのアプローチもイテレーションとフィードバックを重視しています。どちらもソフトウェアを事前に完璧に仕様化できるとは主張しません。代わりに、あなたの思考の現在地に合わせて、異なる出発点から循環的仕様問題に取り組む手助けをします。
デザインファースト Spec : 技術的アプローチから始める
次のプロンプトを考えてみましょう。
この開発者はすでにスタック（FastAPI と mcp-python）、ハイレベルアーキテクチャ（MCP サーバー）、制約（UI 機能なし）を把握しています。「何を構築すべきか？」ではなく、「すでに設計したこのものを構築する手助けをしてほしい」と求めています。この場合、設計ドキュメントから始める方が理にかなっています。なぜなら、開発者がすでに問題について考えている方法と一致するからです。
そこで、新しい Feature Spec を作成する際、Kiro は選択を求めるようになりました。要件ファーストまたは技術デザインファーストです。技術デザインファーストを選択した場合、詳細レベルを選びます。システム図やコンポーネントのハイレベル設計か、アルゴリズムや関数シグネチャのローレベル設計かです。Kiro はまず設計ドキュメントを生成します。それをイテレーションし、さまざまな技術的アプローチを探求します。満足したら、Kiro は設計から要件を導出し、実現可能性を確保します。残りの Spec ワークフローは同じです。タスク、実装、実装が望んだものと一致するかを確認するプロパティベーステスト。
技術デザインファーストは、事前に定義されたアーキテクチャがある場合、何かが実現可能かどうかを確認するためにプロトタイピングしている場合、または設計の選択肢を制約する厳格な非機能要件がある場合に特にうまく機能します。技術的アプローチが出発点であり、目的地ではない場合に最適です。
バグ修正 Spec : 精密にバグを修正する
バグを修正する際には、異なる制約と目標があります。新しいものを構築するのではなく、既存のものを修正します。影響範囲も異なります。変更しすぎると、正常に動作していたものを壊すリスクがあります。問題を修正する最小限の変更が求められます。
では、エージェントと協力してそれを行う最善の方法は何でしょうか？ Specs を使ってバグ修正に成功した開発者には 2 つの共通点がありました。第一に、エラーメッセージだけでなく、エラーを引き起こした詳細なシナリオを定義していました。第二に、変更すべきでないものを明示的に述べていました。これは経験豊富な開発者がバグ修正について考える方法です。壊れているものを修正し、それ以外には触れません。
バグ修正 Spec を作成すると、Kiro は同様のアプローチに従い、3 つのセクションを持つ構造化されたドキュメントを生成します。
- 現在の振る舞い（Current Behavior）は、現在何が起きているかを記述します。「WHEN ユーザーが特殊文字を含むフォームを送信した場合、 THEN システムはバリデーションエラーでクラッシュする（THEN）」。このステップでより包括的に記述することで、Kiro はバグが発生する条件をより正確に診断できます。
- 期待される振る舞い（Expected Behavior）は、代わりに何が起こるべきかを記述します。「WHEN ユーザーが特殊文字を含むフォームを送信した場合、THEN the system SHALL 入力をサニタイズしてフォームを正常に処理する」。これにより、Kiro は解決された状態がどのようなものかを把握し、実際にバグが修正されたかを後で確認できます。
- 変更されない振る舞い（Unchanged Behavior）は、そのままでなければならないものを記述します。「WHEN ユーザーが有効なフォームを送信した場合、THEN the system SHALL CONTINUE TO 従来通りに処理を継続する」。変更すべきでないものを暗黙的にするのではなく、バグ修正 Spec はそれを明示的に述べます。これにより、Kiro はリグレッションが導入されていないことを確認し、検証するプロパティテストに反映できます。
この構造により、何が変わり何が変わらないかを明示的に考えることが強制され、基盤となるモデルがあなたの意図をより正確に理解する助けになります。Kiro はこれらのセクションを自動的に構築するため、この .md を自分で書く時間を費やす必要はありません。これらの条件をレビューして改善し、その後 Kiro は Feature Spec と同様に design.md と tasks.md の作成に進みますが、外科的な修正に特化した内容になります。
これがうまく機能する理由は、Kiro 独自のテスト方法にあります。Kiro は 3 つのカテゴリすべてに対してプロパティベーステスト（PBT）を生成します。現在の実装にバグがあることを検証するテスト、修正がバグを解決したことを検証するテスト、そして変更されない振る舞いが以前とまったく同じように動作し続けることを検証するテストです。これらの PBT がなければ、エージェントが包括的な条件セットに対して実際にバグを修正したかどうか、そして変更が本当に外科的であったかどうかを確認することは困難です。
バグ修正 Spec は、構造化された問題解決が有効な複雑なバグ、リグレッションリスクが高い状況、または修正のドキュメントが必要な場合に威力を発揮します。
あなたに適応するツール
Specs は、多くの開発者が堅牢なソフトウェアを出荷するための AI 開発へのアプローチを変えました。しかし、既存のアプリ、特に大規模なコードベースで作業する場合、異なるアプローチを好むかもしれません。要件から始める場合もあります。構築したいものが正確にわかっているからです。技術的アプローチがすでに決まっていて、交渉の余地がない場合もあります。バグを修正していて、すべてのユーザーに影響するリグレッションを避けるために外科的な精度が必要な場合もあります。今では Specs は 3 つのユースケースすべてをサポートしています。
ドキュメントで Feature Spec と バグ修正 Spec の詳細をご覧ください。Kiro IDE をダウンロードまたは再起動して、Specs の新しいアプローチをお試しください。