Zenn
😊

Kiro Hooks 完全ドキュメントガイド

に公開
Kiro
tech

序章とコアコンセプト

Kiro Hooksは、IDE内で特定のイベントが発生したときに事前定義されたエージェントアクションを自動的に実行することで、開発ワークフローを効率化する強力な自動化ツールです。Hookを使用することで、ルーチンタスクを手動でリクエストする必要がなくなり、コードベース全体で一貫性を確保できます。

Agent Hooksとは？

Agent Hooksは、IDE内で特定のイベントが発生したときに事前定義されたエージェントアクションを実行する自動トリガーです。ルーチンタスクを手動で実行するのではなく、Hooksは以下のようなイベントに対する自動応答を設定します：

  • ファイルの保存
  • 新しいファイルの作成
  • ファイルの削除

Agent Hooksのメリット

Agent Hooksは、インテリジェントな自動化によって開発ワークフローを変革します。一般的なタスクにHooksを設定することで、以下のことが可能になります：

  • 一貫したコード品質を維持
  • セキュリティ脆弱性を防止
  • 手動作業の負担を軽減
  • チームプロセスを標準化
  • 開発サイクルを高速化

Agent Hooksの仕組み

Agent Hooksシステムは単純な3段階のプロセスに従います：

  1. イベント検出：システムはIDE内の特定のイベント（ファイルの保存/作成/削除など）を監視
  2. プロンプト実行：イベントが発生すると、事前定義されたプロンプトがエージェントに送信される
  3. 自動アクション：エージェントがプロンプトを処理し、要求されたアクションを実行

Hookの種類とトリガー

Agent Hooksはさまざまなトリガータイプをサポートしており、それぞれ特定の自動化シナリオに設計されています：

  1. ファイル作成時（On File Create）

    • トリガー：ワークスペース内に特定のパターンに一致する新しいファイルが作成されたとき
    • ユースケース：
      • 新しいコンポーネントのボイラープレートコードを生成
      • 新しいファイルにライセンスヘッダーを追加
      • 実装ファイルを作成するときにテストファイルを設定

  2. ファイル保存時（On File Save）

    • トリガー：特定のパターンに一致するファイルが保存されたとき
    • ユースケース：
      • リンティングとフォーマットを実行
      • 関連ファイルを更新
      • ドキュメントを生成
      • 変更されたファイルのテストを実行

  3. ファイル削除時（On File Delete）

    • トリガー：特定のパターンに一致するファイルが削除されたとき
    • ユースケース：
      • 関連ファイルをクリーンアップ
      • 他のファイルのインポート参照を更新
      • プロジェクトの整合性を維持

  4. 手動トリガー（Manual Trigger）

    • トリガー：手動でHookを実行
    • ユースケース：
      • オンデマンドのコードレビュー
      • ドキュメント生成
      • セキュリティスキャン
      • パフォーマンス最適化

Hookの管理と設定

Agent Hooksの設定

Hookの作成と管理は簡単です：

  • エクスプローラービューを使用

    1. Kiroパネルの「Agent Hooks」セクションに移動
    2. 「+」ボタンをクリックして新しいHookを作成
    3. 入力フィールドに自然言語でHookワークフローを定義
    4. Enterキーを押すか「Submit」をクリックして続行
    5. Hook設定を構成して保存

  • コマンドパレットを使用

    1. コマンドパレットを開く（Mac：Cmd + Shift + P、Windows/Linux：Ctrl + Shift + P）
    2. Kiro: Open Kiro Hook UIと入力
    3. 画面の指示に従ってHookを作成

Hooksの管理

すべてのHooksはKiroパネルの「Agent Hooks」セクションからアクセスできます。

Hookの有効化/無効化
Hooksを削除することなく、有効化または無効化する方法：

  • クイックトグル：Agent HooksパネルのHookの横にある「アイコン」をクリック
  • Hookビューから：Hookを選択し、右上の「Hook Enabled」スイッチを使用

既存Hooksの編集
Agent HooksパネルでHookを選択し、トリガー、ファイルパターン、指示、説明などの設定を変更。変更は即座に適用されます。

Hooksの削除
Agent HooksパネルでHookを選択し、下部ビューにある「Delete Hook」をクリックし、次に「delete」をクリック。この操作は元に戻せません。

手動トリガーHookの実行

  • クイック実行：Agent HooksパネルのHook名の横にある「再生ボタン（▷）」をクリック
  • Hookビューから：Hookを選択し、右上の「Start Hook」をクリック

ベストプラクティスとガイドライン

以下のベストプラクティスに従うことで、信頼性が高く、効率的で、保守可能なHooksを作成し、開発ワークフローを強化できます。

Hook設計

  • 具体的かつ明確にする

    • 詳細で明確な指示を記述
    • Hookごとに1つの特定のタスクに焦点を当てる
    • 複雑な操作には番号付きの手順を使用

  • 徹底的にテストする

    • デプロイする前にサンプルファイルでHooksをテスト
    • エッジケースでHooksが機能することを確認
    • 拡張する前に限られたファイルパターンから始める

  • パフォーマンスを監視する

    • Hooksがワークフローを遅くしないようにする
    • トリガーイベントの頻度を考慮する
    • 効率化のためにプロンプトを最適化する

セキュリティに関する考慮事項

  • 入力を検証する

    • Hooksが予期しないファイルコンテンツを適切に処理するようにする
    • ファイル形式の潜在的なエッジケースを考慮する
    • 不正な形式の入力や予期しない入力でテストする

  • 範囲を制限する

    • 可能な場合は特定のファイルタイプまたはディレクトリを対象にする
    • 不要な実行を避けるために正確なファイルパターンを使用する
    • Hooksがコードベース全体に与える影響を考慮する

  • 定期的にレビューする

    • プロジェクトの進化に伴ってHookロジックを更新する
    • 不要になったHooksを削除する
    • 実際の結果に基づいてプロンプトを改良する

チームコラボレーション

  • Hooksを文書化する

    • Hookの目的に関する明確なドキュメントを維持する
    • 期待される動作の例を含める
    • 制限事項やエッジケースを文書化する

  • ワークフローを標準化する

    • チームメンバー間で一貫したHooksを使用する
    • Hook設定をバージョン管理に保存する
    • 一般的なチームワークフローのための標準Hooksを作成する

  • バージョン管理との統合

    • バージョン管理システムと統合するHooksを検討する
    • コードレビューワークフローのためのHooksを作成する
    • チーム標準を強制するためにHooksを使用する

実践的なユースケースと例

これらの例は、実世界のHook実装を示しており、自分のプロジェクトに適応させることができます。

  1. セキュリティプリコミットスキャナー
    トリガータイプ：ファイル保存

    対象：**/*
    このHookは、コミットされる前にファイルをスキャンすることで、セキュリティ漏洩を防ぐのに役立ちます。

    Hook指示：

     このファイルを以下の潜在的なセキュリティ問題についてスキャンしてください：
     - APIキー、パスワード、シークレット
     - ハードコードされた認証情報
     - 潜在的なSQLインジェクション脆弱性
     - XSS脆弱性
     - 安全でない設定
     問題が見つかった場合は、修正に関する具体的な推奨事項を提供してください。
  1. 国際化ヘルパー
    • トリガータイプ：ファイル保存
    • 対象：src/locales/en/*.json
    • このHookは、主要言語ファイルのテキストを更新するときに、翻訳が同期された状態を維持するのに役立ちます。
    • Hook指示：
     この英語ロケールファイルに、他の言語ファイルに存在しない新しいキーがないか確認してください。
     不足しているキーがある場合は、翻訳が必要であることを示すプレースホルダーテキストを対応するファイルに追加してください。
  1. ドキュメントジェネレーター
    • トリガータイプ：手動トリガー
    • このHookは、コードが変更されたときに自動的にドキュメントを更新します。
    • Hook指示：
     現在のプロジェクトの包括的なドキュメントを生成してください。以下を含めてください：
     - すべてのパブリック関数のAPIドキュメント
     - 使用例
     - インストール手順
     - 設定オプション
     README.mdファイルを最新情報で更新してください。
  1. テストカバレッジメンテナー
    • トリガータイプ：ファイル保存
    • 対象：src/**/*.{js,ts,jsx,tsx}
    • このHookは、コードが進化するにつれてテストカバレッジが高い状態を維持するのに役立ちます。
    • Hook指示：
     このファイルを分析し、対応するテストファイルが存在するか確認してください。
     テストが不足している場合または不完全な場合は：
     - テストファイルを作成または更新する
     - すべてのパブリック関数がテストされていることを確認する
     - 該当する場合、エッジケースのテストを追加する

MCPとの統合

Agent Hooksは、Model Context Protocol（MCP）機能を強化することで機能を拡張できます：

  1. 外部ツールへのアクセス：HooksはMCPサーバーを利用して専門的なツールやAPIにアクセスできます
  2. 強化されたコンテキスト：MCPは、よりインテリジェントなHookアクションのための追加コンテキストを提供します
  3. ドメイン固有の知識：専門的なMCPサーバーはドメインの専門知識を提供できます

例：Figmaデザインの検証

  • トリガータイプ：ファイル保存Hook
  • 対象：*.css *.html
  • Hook指示：
  Figma MCPを使用して、このファイルのHTMLとCSSの変更がデザインシステムの仕様に準拠しているか検証してください。以下を確認してください：
  - デザイントークンとの色の一貫性
  - スタイルガイドとのタイポグラフィの一致
  - グリッドシステムに対する間隔とレイアウトの準拠
  偏差がある場合は、具体的なフィードバックを提供してください。

トラブルシューティングと一般的な問題

提供された情報ではトラブルシューティングページの内容が完全には入手できませんでしたが、以下にKiro Hooksの一般的なトラブルシューティング方法を示します：

一般的な問題

  • Hookがトリガーされない

    • ファイルパターンが対象ファイルと一致しているか確認
    • Agent HooksパネルでHookが有効になっているか確認
    • トリガーイベントが予期されたとおりに発生しているか確認

  • パフォーマンスの問題

    • Hookの頻度と範囲を確認
    • プロンプトの複雑さを最適化
    • 不要な実行を減らすためにファイルパターンを制限することを考慮

  • 予期しない結果

    • 明確性のためにHookの指示を確認して改良
    • 本番環境にデプロイする前にサンプルファイルでテスト
    • ファイルパターンのエッジケースを確認

デバッグ手順

  1. Hook状態の確認：Hookが有効になっていて正しく構成されているか確認
  2. ファイルパターンのテスト：対象パターンが意図したファイルと一致しているか確認
  3. ログの確認：エラーメッセージや警告がないか確認
  4. 指示の簡略化：基本的な指示から始め、徐々に複雑さを追加
  5. 段階的なテスト：広く適用する前に、小さなファイルセットでHooksをテスト

トラブルシューティングのベストプラクティス

  • Hook設定の詳細なドキュメントを保持する
  • 可能な場合はHook設定をバージョン管理に使用する
  • 本番環境の前に開発環境でHooksをテストする
  • Hookのパフォーマンスを監視し、必要に応じて調整する
  • プロジェクトが進化するにつれて、定期的にHookロジックを確認して更新する

Kiro Hooks Guide

Discussion