# 후크를 사용하여 에이전트 워크플로 사용자 지정

에이전트 실행 중 핵심 지점에서 Linting, 형식 지정 또는 보안 검사와 같은 자동화된 검사를 실행하여 품질 표준을 적용합니다.

후크를 사용하면 에이전트를 실행하는 동안 키 지점에서 사용자 지정 셸 명령을 실행하여 에이전트의 GitHub Copilot 동작을 확장하고 사용자 지정할 수 있습니다. 사용 가능한 후크 트리거의 세부 정보를 포함하여 후크의 개념적 개요는 [후크에 대한 정보 GitHub Copilot](/ko/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 스크립트용)를 모두 포함합니다.
   > 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 후크 참조](/ko/copilot/reference/hooks-reference)을 참조하세요.

4. 파일을 리포지토리에 커밋하고 기본 분기에 병합합니다. 이제 에이전트 세션 동안 후크가 실행됩니다.

## Troubleshooting

후크를 사용하여 문제가 발생하면 다음 표를 사용하여 문제를 해결합니다.

| Issue                                                                                                                                                                          | 조치                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 후크가 실행되고 있지 않습니다.                                                                                                                                                              | <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>출력이 한 줄에 있는지 확인합니다.</li><li>Unix에서 JSON 출력을 압축하고 유효성을 검사하는 데 사용합니다 `jq -c` .</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 후크 참조](/ko/copilot/reference/hooks-reference)
* [GitHub Copilot 클라우드 에이전트 정보](/ko/copilot/concepts/agents/cloud-agent/about-cloud-agent)
* [GitHub Copilot CLI 정보](/ko/copilot/concepts/agents/copilot-cli/about-copilot-cli)
* [개발 환경 구성](/ko/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)