Kiro Hooksで品質ゲートを構築する

1.     はじめに
2.     postTaskExecutionとは
3.     実践：タスク完了時にテストを自動実行する
4.     IaC版：cfn-nagによるセキュリティチェック
5.     使い分けの指針：postTaskExecution vs userTriggered
6.     複数のrunCommandを組み合わせる
7.     まとめ

前回の記事「Kiro Hooksで命名規約の逸脱を即座に検出する」では、ファイルが作成された瞬間にエージェントが規約違反を検出し、リネームまで自動でやる仕組みを構築しました。
今回はpostTaskExecution Hookを使って、「Specのタスクが完了した瞬間にテストを強制実行する」仕組みを作ります。テストが通るまで先に進めない — そういうガードレールになります。

Kiro Specsでは、タスクにステータスがあります。

not_started → in_progress → completed (この瞬間に Hook が発火)

postTaskExecutionは、タスクのステータスがcompletedに変わった直後に発火するイベントです。「実装が終わった」とエージェントが判断した瞬間、自動的にチェックが走ります。

前回はaskAgentを使いました。命名規約の判断はエージェントに「考えさせる」必要があったからです。ファイル名がルールに合致するかはコンテキスト依存で、機械的なパターンマッチだけでは判定しきれません。
今回はrunCommandを使います。テスト実行に判断は不要です。mvn testを走らせて、通るか通らないか。結果は0か1です。

runCommandはローカルでコマンドを実行するだけなので、クレジットを消費しません。Hookを10個付けてもテストが全部通ればコスト増はゼロです。一方askAgentは毎回LLMを呼び出すため、発火するたびにクレジットが消費されます。
ただし、runCommandの出力結果をもとにエージェントが修正を試みる場合（テスト失敗→自動修正ループ）、その修正作業ではクレジットが消費されます。コマンド実行自体は無料でも、失敗が頻発すると修正ループでクレジットが消費される点は意識しておいてください。
なお、Kiro IDE版にはエージェントの最大試行回数を設定する機能はありません（Kiro CLIの/goal --maxとは別）。テスト失敗→修正→再テストのループが収束しない場合は、Supervisedモードに切り替えるか、チャットで中断してください。実際には2〜3回修正を試みて解決しない場合、エージェントは自発的にユーザーへ報告する傾向があります。
runCommandの出力結果はエージェントに自動的に返されます。テストが失敗すれば失敗内容がそのまま伝わるため、エージェントは自力で修正を試みます。

.kiro/hooks/run-tests-after-task.kiro.hook に以下を配置します。

定義はこれだけです。when.typeがpostTaskExecutionなので、Specタスクが完了するたびにmvn test -qが走ります。
-q（quiet）オプションをつけているのは、テスト成功時の大量ログをチャットに流さないためです。失敗時はエラー内容が表示されるので問題ありません。
注意: postTaskExecutionにはファイルパターン（patterns）の指定は不要です。タスクレベルのイベントなので、ファイルではなくタスク全体に対して発火します。

実際のプロジェクトでは、グローバルのmvnコマンドではなくMaven Wrapper（mvnw / mvnw.cmd）を使うケースが多いです。Kiroのターミナル環境でPATHにmvnが通っていないとcommand not foundになります。
プロジェクトにMaven Wrapperが含まれている場合は、コマンドを以下のように変更してください。

Windows環境の場合は mvnw.cmd test -q です。Gradle Wrapperの場合も同様に ./gradlew test としてください。Hookのコマンドはプロジェクトルートから実行されるため、Wrapperのパスは相対パスで指定できます。

1. エージェントがSpecタスクの実装を完了
   ↓
2. タスクステータスが「completed」に変更
   ↓
3. postTaskExecution Hook が発火
   ↓
4. mvn test -q が実行される
   ↓
5. テスト全件合格 → 「BUILD SUCCESS」がエージェントに返る
   ↓
6. エージェントは次のタスクへ進む

成功した場合はスムーズに次のタスクに移ります。テスト実行のオーバーヘッドはありますが、品質が保証されるなら許容範囲です。
筆者のFileUploaderプロジェクト（jqwikプロパティテスト27件）で計測したところ、テスト実行時間は約7秒でした。タスク完了のたびに7秒待つ程度なので、実用上の問題にはなりません。

1. エージェントがSpecタスクの実装を完了
   ↓
2. タスクステータスが「completed」に変更
   ↓
3. postTaskExecution Hook が発火
   ↓
4. mvn test -q が実行される
   ↓
5. テスト失敗 → 失敗内容がエージェントに返る
   例: "FileUploadServiceTest.testUploadEmptyFile: expected 400 but was 500"
   ↓
6. エージェントがエラーを分析し、コードを修正
   ↓
7. エージェントが再度テストを実行し、合格を確認

ポイント: テスト失敗の結果はrunCommandの出力としてエージェントに戻ります。エージェントは何が壊れたかを把握できるため、自動的に修正を試みます。人間が「テスト通らないよ」と教える必要はありません。
「完了です」→「テスト落ちてます」→「修正しました」が全部自動で回ります。人間が介入する必要がないのがこの仕組みの利点です。

同じ仕組みはインフラコードにも応用できます。CloudFormationテンプレートのセキュリティスキャンを自動実行する例です。

cfn-nagはCloudFormationテンプレートのセキュリティ問題を検出するツールです。S3バケットのパブリックアクセス設定、セキュリティグループの0.0.0.0/0許可、暗号化未設定など、よくある脆弱パターンを指摘してくれます。
テスト実行と同じ考え方です。エージェントが「インフラ定義を書きました、完了です」と言った瞬間にセキュリティスキャンが走ります。脆弱性があれば修正を試みるので、人間がレビューで指摘する前に解決されていることが多いです。
「実践編：ステアリングファイルとKiro Powerで実現するIaC品質管理」で構築したIaC Validator Power（Kiro Powerによるセキュリティ検証）と組み合わせれば、さらに強固なチェックが可能です。Powerは「エージェントの能力拡張」、Hookは「自動実行の仕組み」— 役割が異なるので併用が効果的です。

postTaskExecutionはSpecsの各タスク（チェックボックス1つ）が完了するたびに発火します。タスクが10個あれば10回テストが走る。これが適切かどうかは、Specのタスク構成とプロジェクトの状況によります

- [ ] Task 1: FileUploadServiceの実装とテスト
- [ ] Task 2: FileUploadControllerの実装とテスト
- [ ] Task 3: エラーハンドリングの実装とテスト

各タスクが「実装＋そのテスト」をワンセットで含みます。Kiroが自動生成するSpecは、たいていこのパターンになります。

- [ ] Task 1: FileUploadServiceの実装
- [ ] Task 2: FileUploadControllerの実装
- [ ] Task 3: エラーハンドリングの実装
- [ ] Task 4: 全テストの作成
Task 1〜3完了時点ではテストが存在しない。postTaskExecutionで走らせても「テストが0件」で素通りするか、ビルドエラーになる。

- [ ] Task 1: FileUploadServiceのテスト作成
- [ ] Task 2: FileUploadServiceの実装
- [ ] Task 3: FileUploadControllerのテスト作成
- [ ] Task 4: FileUploadControllerの実装
Task 1完了時点ではテストだけあって実装がない。テストは当然失敗する。実装が来るまで失敗し続けるのは想定通りであり、ノイズになる。

両方のHookを.kiro/hooks/に置いておき、プロジェクトのフェーズやSpecの構成に応じて使い分けるのが現実的です。

実際のプロジェクトでは、テストだけでなくリント・ビルド・静的解析もまとめて走らせたいケースがあります。Hookは複数定義できるので、それぞれ個別に作成できます。

同じpostTaskExecutionイベントに複数のHookを紐づけると、すべてが実行されます。1つでも失敗すればエージェントにフィードバックが返るため、品質ゲートとして機能します。

複数のHookファイルを定義した場合、実行順序は保証されません。「リントを通してからテストを走らせたい」のように順序が重要な場合は、1つのHookにコマンドを && で連結します。

&& で繋ぐと、前のコマンドが失敗した時点で後続は実行されません。軽いチェック（リント）を先に置くことで、コードスタイルが壊れている段階でテスト実行を省けます。
より複雑な制御（条件分岐、ログ集約）が必要な場合は、シェルスクリプトにまとめて "command": "./scripts/quality-gate.sh" とするのも有効です。

•    ✅ postTaskExecution Hook（タスク完了時テスト自動実行）
•    ✅ runCommandによる品質ゲート（テスト・リント・セキュリティスキャン）
•    ✅ 「テストが通るまで完了にさせない」仕組み

Steeringで「こう書いてね」、Hooksで「守ってなかったら止める」。前回はファイル単位の品質（命名）、今回はタスク単位の品質（テスト）。レイヤーの異なるガードレールを重ねることで、品質の穴を塞いでいきます。

2026年6月にAWS Security AgentがKiro Powerに追加されました。次回はAWS Security AgentをKiroのSpecsと組み合わせて、設計段階のセキュリティチェックを行います。

• Kiro Hooksで命名規約の逸脱を即座に検出する（第7回）
• AI開発の品質をルールで担保する — ステアリングファイル実践ガイド（第6回）

• Kiro公式ドキュメント - Hooks: https://kiro.dev/docs/hooks/
• Anthropic: Building effective agents: https://www.anthropic.com/research/building-effective-agents
• OpenAI: Harness Engineering Blog: https://openai.com/index/harness-engineering/