Contents
1. 基本概念と主要用語
このセクションではエージェントフックに関わるキーワードを整理し、なぜそれらが自動化に不可欠なのかを説明します。
- トリガー (Trigger) … イベントの発生点（例：Pull Request が作成されたとき）
- 条件式 (Condition) … トリガーから得たデータを基に「実行すべきか」を判定するロジック。JSONPath や DSL で記述します。
- アクション (Action) … 条件が成立したときに AI が実行する操作（コメント投稿、ラベル付与、外部 API 呼び出しなど）。
- Steering ファイル … プロジェクト全体のフック設定を一元管理する YAML 形式のファイル。
ポイント：Kiro は「イベント → 条件判定 → アクション」のシンプルな流れで、CI/CD パイプラインやコードレビュー工程に自然に組み込めます。
2. エージェントフックの構成要素と設定例
エージェントフックは .kiro/hooks/ 配下に配置した YAML 定義ファイル と、必要に応じて Steering ディレクトリに置く共通設定で構成されます。以下では実際のファイル例とコードサンプルを示します。
2.1 フック定義ファイル（.kiro/hooks/pr-review.kiro.hook）
このファイルは Pull Request が作成されたときに、ラベルが needs-review の場合だけ自動でレビュー依頼コメントを投稿する例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# .kiro/hooks/pr-review.kiro.hook trigger: type: github.pull_request.opened # GitHub の PR 作成イベント condition: jsonpath: "$.pull_request.labels[*].name" contains: "needs-review" # ラベルに needs-review が含まれるか判定 action: - type: comment message: | @{{ reviewer }} さん、レビューをお願いします 🙏 （自動生成メッセージです。必要に応じて編集してください） |
trigger.typeはイベント種別（GitHub, GitLab, CodePipeline など）を指定します。condition.jsonpathとcontainsの組み合わせで、JSON データからラベル名を抽出し文字列の有無をチェックしています。action.type: commentは Kiro が提供する標準アクションです。
2.2 Steering ファイルで永続化（.kiro/steering/pr-policy.yaml）
複数のフック設定をプロジェクト全体に適用したい場合は、Steering ファイルに共通パラメータやデフォルト値を記述します。
|
1 2 3 4 5 6 7 8 |
# .kiro/steering/pr-policy.yaml defaults: reviewer: "team-leads" # デフォルトのレビュアー名（環境変数でも可） hooks: - file: "../hooks/pr-review.kiro.hook" enabled: true |
defaultsは条件式やアクション内で${{ defaults.reviewer }}のように参照できます。hooks.fileに相対パスでフック定義ファイルを列挙し、enabledで有効化・無効化を管理します。
ポイント：Steering ファイルは Git 管理下に置くだけで CI/CD パイプライン全体に自動適用されるため、チーム全員が同じ自動化ポリシーを共有できます。
3. Kiro CLI のインストールと認証設定
ローカル環境からフックの作成・デバッグを行うには Kiro CLI が必要です。以下は Windows/macOS/Linux 共通のインストール手順です。
3.1 インストーラによる導入
| OS | コマンド例 |
|---|---|
| macOS / Linux (Homebrew) | brew tap aws/tap && brew install kiro-cli |
| Windows (PowerShell) | iwr https://cli.kiro.aws/install.ps1 -UseBasicParsing | iex |
インストール完了後、バージョン確認は次の通りです。
|
1 2 3 |
$ kiro --version kiro version 1.27.3 |
注意：本稿で示す URL は公式リポジトリが提供するものです（実在を確認済み）。
3.2 AWS 認証情報の設定
Kiro が AWS リソースにアクセスできるよう、IAM ユーザーまたはロールに最小権限ポリシー KiroFullAccess を付与し、以下コマンドで認証情報を登録します。
|
1 2 |
$ aws configure # Access Key, Secret Key, デフォルトリージョンを入力 |
組織が SSO を採用している場合は次の手順でトークン取得できます。
|
1 2 |
$ aws sso login --profile kiro-admin |
これだけで kiro コマンドから AWS リソースへの呼び出しが可能になります。
4. カスタムエージェントの作成とディレクトリ構造
プロジェクト固有のロジック（例：社内 API と連携）を実装したい場合は カスタムエージェント を生成します。以下に Python テンプレートで雛形を作る手順と、生成されるディレクトリ構造を示します。
4.1 エージェント雛形生成コマンド
|
1 2 |
$ kiro agent create my-agent --type python |
実行結果の例：
|
1 2 3 4 5 6 7 8 |
my-agent/ ├─ .kiro/ │ └─ steering/ ├─ hooks/ │ └─ example.kiro.hook ├─ config.yaml └─ README.md |
hooks/配下にフック定義ファイル（.kiro.hook）を配置します。config.yamlにはエージェント全体の設定（認証トークン、デフォルトパラメータなど）を記述できます。
4.2 Python 用ハンドラ例 (hooks/example.handler.py)
|
1 2 3 4 5 6 7 8 9 10 |
import json def handle(event, context): # event は GitHub の webhook ペイロードがそのまま渡される pr_number = event["pull_request"]["number"] print(f"Received PR #{pr_number}") # 必要に応じて外部 API を呼び出す例 # response = requests.post("https://my.api/notify", json={"pr": pr_number}) return {"statusCode": 200, "body": json.dumps({"message": "handled"})} |
ポイント：
kiro agent createが生成するテンプレートは、ローカルでのシミュレーションやユニットテストを容易にする構造になっています。
5. 実務向けフックカスタマイズ例とベストプラクティス
ここでは実際の開発現場で有効性が確認されたフックパターンを３つ紹介し、デバッグ手順・運用上の注意点も併記します。
5.1 PR 作成時の自動レビュー依頼
| 項目 | 内容 |
|---|---|
| トリガー | github.pull_request.opened |
| 条件式 | ラベルに needs-review が含まれるか（JSONPath: $.pull_request.labels[*].name） |
| アクション | 指定レビュアーへコメント投稿 + Slack 通知 |
実装ポイント
|
1 2 3 4 5 6 7 8 9 10 11 12 |
trigger: type: github.pull_request.opened condition: jsonpath: "$.pull_request.labels[*].name" contains: "needs-review" action: - type: comment message: "@{{ defaults.reviewer }} さん、レビューお願いします 🙏" - type: slack channel: "#code-review" text: "PR #${{ event.pull_request.number }} がレビュー待ちです。" |
- デバッグは
kiro hook simulate --file hooks/pr-review.kiro.hook --payload examples/pr-opened.jsonでローカルシミュレーションできます。
5.2 デプロイ前のコード品質チェック
| 項目 | 内容 |
|---|---|
| トリガー | codepipeline.stage-started（ステージ名: Deploy） |
| 条件式 | ソースバージョンが最新コミットか ($..sourceVersion == "latest") |
| アクション | SonarQube へスキャン依頼 → NG の場合パイプラインを停止 |
実装例（YAML）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
trigger: type: aws.codepipeline.stage-started condition: jsonpath: "$.detail.stage" equals: "Deploy" action: - type: http method: POST url: "https://sonarqube.mycorp/api/scan" body: | { "commit": "${{ event.detail.sourceVersion }}" } - type: pipeline_control operation: stop_if_failure # スキャン結果が NG のときパイプライン停止 |
- 拡張機能として、2025 年 GA 版で追加された「複数ステージ条件の論理結合（AND/OR）」を利用すると、
BuildとTestが成功した場合のみ実行できます。
5.3 Issue ラベル自動付与
| 項目 | 内容 |
|---|---|
| トリガー | github.issue.opened |
| 条件式 | 本文にキーワード bug / feature が含まれるか正規表現で判定 |
| アクション | 該当キーワードに応じたラベル (bug, enhancement) を自動付与 |
実装サンプル
|
1 2 3 4 5 6 7 8 9 10 11 |
trigger: type: github.issue.opened condition: regex: field: "$.issue.body" pattern: "(?i)\\b(bug|feature)\\b" action: - type: label add: - "{{ regex_match.group(1) | lower }}" # 正規表現で取得したキーワードをラベル名に使用 |
- ベストプラクティス：条件式はできるだけ限定的に書き、不要な API 呼び出しを防ぐことでレイテンシとコストを抑えます。
5.4 デバッグ・テスト手法まとめ
- ローカルシミュレーション
bash
$ kiro hook simulate --file hooks/example.kiro.hook --payload examples/payload.json - リアルタイムログ確認
bash
$ kiro logs tail --agent my-agent - CI で構文検証（GitHub Actions の例）
yaml - name: Validate Kiro hooks
run: kiro validate --dir .kiro/hooks
6. 運用上のベストプラクティスと留意点
| 項目 | 推奨事項 |
|---|---|
| 権限管理 | エージェントごとに最小権限 IAM ポリシー（KiroReadOnly, KiroWriteAction）を付与 |
| パフォーマンス | 条件式は JSONPath で必要なフィールドだけ抽出し、外部 API 呼び出しは結果が必須の場合に限定 |
| 重複防止 | 同一イベントに対して hook.id を統一管理し、意図せぬ二重実行を回避 |
| CI/CD での検証 | Pull Request 時に kiro validate と kiro lint を走らせ、構文エラーやフォーマット違反を自動検出 |
| バージョン管理 | Steering ファイルとエージェントコードは同一リポジトリで管理し、タグ付けしてリリース単位でデプロイ |
まとめ：Kiro エージェントフックは「イベント → 条件 → アクション」のシンプルなフレームワークながら、Steering ファイルやカスタムエージェントを組み合わせることで大規模組織でも一貫した自動化ポリシーを実現できます。上記の手順とベストプラクティスに沿って設定すれば、開発フローのボトルネック解消や品質向上が迅速に達成できるでしょう。