# フックを使用してエージェント ワークフローをカスタマイズする

エージェントの実行中に重要なポイントで自動チェック (リンティング、書式設定、セキュリティ スキャンなど) を実行し、品質基準を適用します。

フックを使用すると、エージェントの実行中にキー ポイントでカスタム シェル コマンドを実行することで、 GitHub Copilot エージェントの動作を拡張およびカスタマイズできます。 使用可能なフック トリガーの詳細など、フックの概念の概要については、 [フックについて GitHub Copilot](/ja/copilot/concepts/agents/hooks) を参照してください。

## リポジトリにフックを作成する GitHub

1. リポジトリの`NAME.json` フォルダーに新しい`NAME` ファイル (`.github/hooks/`ファイルの目的を説明するファイル) を作成します。

   > \[!IMPORTANT]
   > \*\*\*\*で使用するには、フック構成ファイルがリポジトリの既定のブランチにCopilot cloud agent。

2. テキスト エディターで、次のフック テンプレートをコピーして貼り付けます。 使用する予定のないフックを `hooks` 配列から削除します。

   ```json copy
   {
     "version": 1,
     "hooks": {
       "sessionStart": [...],
       "sessionEnd": [...],
       "userPromptSubmitted": [...],
       "preToolUse": [...],
       "postToolUse": [...],
       "errorOccurred": [...]
     }
   }
   ```

3. `bash`キーと`powershell` キーでフック構文を構成するか、作成したスクリプト ファイルを直接参照します。

   > \[!NOTE]
   > `bash` キー (Linux および macOS 用のスクリプトを含む) と `powershell` キー (Windows 用スクリプト用) の両方を含めて、3 つのオペレーティング システムすべてでフックを実行できるようにします。 Copilot は、ユーザーのオペレーティング システムに基づいて適切なキーを使用します。

   * 次の例では、 `sessionStart` フックを使用してセッションの開始日をログ ファイルに出力するスクリプトを実行します。

     ```json copy
     "sessionStart": [
       {
         "type": "command",
         "bash": "echo \"Session started: $(date)\" >> logs/session.log",
         "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
         "cwd": ".",
         "timeoutSec": 10
       }
     ],
     ```

   * 次の例では、外部 `log-prompt` スクリプトを呼び出します。

     ```json copy
     "userPromptSubmitted": [
       {
         "type": "command",
         "bash": "./scripts/log-prompt.sh",
         "powershell": "./scripts/log-prompt.ps1",
         "cwd": "scripts",
         "env": {
           "LOG_LEVEL": "INFO"
         }
       }
     ],
     ```

     エージェント セッションからの入力 JSON とサンプル スクリプトの完全なリファレンスについては、 [GitHub Copilotフックリファレンス](/ja/copilot/reference/hooks-reference) を参照してください。

4. ファイルをリポジトリにコミットし、既定のブランチにマージします。 これで、フックはエージェント セッション中に実行されます。

## Troubleshooting

フックを使用して問題が発生した場合は、次の表を使用してトラブルシューティングを行います。

| 問題点                                                                                                                                                                                 | アクション                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| フックが実行されていない                                                                                                                                                                        | <ul><li>JSON ファイルが `.github/hooks/` ディレクトリ内にあるかどうかを確認します。</li><li>有効な JSON 構文 (たとえば、 `jq .  hooks.json`) を確認します。</li><li>                                            |
| `version: 1` ファイルに`hooks.json`が指定されていることを確認します。</li><li>フックから呼び出しているスクリプトが実行可能であることを確認します (`chmod +x script.sh`)</li><li>スクリプトに適切な shebang があることを確認します (例: `#!/bin/bash`)</li></ul> |                                                                                                                                                                      |
| フックがタイムアウトする                                                                                                                                                                        | <ul><li>既定のタイムアウトは 30 秒です。 必要に応じて、構成の `timeoutSec` を増やします。</li><li>不要な操作を回避してスクリプトのパフォーマンスを最適化します。</li></ul>                                                         |
| 無効な JSON 出力                                                                                                                                                                         | <ul><li>出力が 1 行であることを確認します。</li><li>Unix では、 `jq -c` を使用して JSON 出力を圧縮して検証します。</li><li>Windowsで、PowerShell の `ConvertTo-Json -Compress` コマンドを使用して同じ操作を行います。</li></ul> |

## デバッグ

次のメソッドを使用してフックをデバッグできます。

* スクリプトで**詳細ログを有効化**して、入力データを検査し、スクリプトの実行を追跡します。

  ```shell copy
  #!/bin/bash
  set -x  # Enable bash debug mode
  INPUT=$(cat)
  echo "DEBUG: Received input" >&2
  echo "$INPUT" >&2
  # ... rest of script
  ```

* **テストフックをローカルでテストするために、テスト入力をフックにパイプし**、その動作を検証します。

  ```shell copy
  # Create test input
  echo '{"timestamp":1704614400000,"cwd":"/tmp","toolName":"bash","toolArgs":"{\"command\":\"ls\"}"}' | ./my-hook.sh

  # Check exit code
  echo $?

  # Validate output is valid JSON
  ./my-hook.sh | jq .
  ```

## 詳細については、次を参照してください。

* [GitHub Copilotフックリファレンス](/ja/copilot/reference/hooks-reference)
* [クラウド エージェントGitHub Copilotについて](/ja/copilot/concepts/agents/cloud-agent/about-cloud-agent)
* [GITHUB COPILOT CLI について](/ja/copilot/concepts/agents/copilot-cli/about-copilot-cli)
* [開発環境を構成する](/ja/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)