{"meta":{"title":"후크를 사용하여 에이전트 워크플로 사용자 지정","intro":"에이전트 실행 중 핵심 지점에서 Linting, 형식 지정 또는 보안 검사와 같은 자동화된 검사를 실행하여 품질 표준을 적용합니다.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ko/copilot","title":"GitHub Copilot"},{"href":"/ko/copilot/how-tos","title":"방법"},{"href":"/ko/copilot/how-tos/copilot-on-github","title":"Copilot 에 GitHub"},{"href":"/ko/copilot/how-tos/copilot-on-github/customize-copilot","title":"사용자 지정 Copilot"},{"href":"/ko/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent","title":"맞춤 설정 cloud agent"},{"href":"/ko/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks","title":"후크 사용"}],"documentType":"article"},"body":"# 후크를 사용하여 에이전트 워크플로 사용자 지정\n\n에이전트 실행 중 핵심 지점에서 Linting, 형식 지정 또는 보안 검사와 같은 자동화된 검사를 실행하여 품질 표준을 적용합니다.\n\n후크를 사용하면 에이전트를 실행하는 동안 키 지점에서 사용자 지정 셸 명령을 실행하여 에이전트의 GitHub Copilot 동작을 확장하고 사용자 지정할 수 있습니다. 사용 가능한 후크 트리거의 세부 정보를 포함하여 후크의 개념적 개요는 [후크에 대한 정보 GitHub Copilot](/ko/copilot/concepts/agents/hooks)을 참조하세요.\n\n## 리포지토리에서 후크 만들기 GitHub\n\n1. 리포지토리의 `NAME.json` 폴더에 새 `NAME` 파일(`.github/hooks/`는 파일의 용도를 설명함)을 만듭니다.\n\n   > \\[!IMPORTANT]\n   > 후크 구성 파일은 \\*\\*\\*\\* 에서 사용되기 위해 리포지토리의 기본 분기에 반드시 Copilot cloud agent존재해야 합니다.\n\n2. 텍스트 편집기에서 다음 후크 템플릿을 복사하여 붙여넣습니다. 사용하지 않을 계획인 후크를 `hooks` 배열에서 제거합니다.\n\n   ```json copy\n   {\n     \"version\": 1,\n     \"hooks\": {\n       \"sessionStart\": [...],\n       \"sessionEnd\": [...],\n       \"userPromptSubmitted\": [...],\n       \"preToolUse\": [...],\n       \"postToolUse\": [...],\n       \"errorOccurred\": [...]\n     }\n   }\n   ```\n\n3. `bash` 및 `powershell` 키에서 후크 구문을 구성하거나 직접 만든 스크립트 파일을 참조하세요.\n\n   > \\[!NOTE]\n   > 세 운영 체제에서 후크를 실행할 수 있도록 `bash` 키(Linux 및 macOS용 스크립트 포함)와 `powershell` 키(Windows 스크립트용)를 모두 포함합니다.\n   > Copilot 는 사용자의 운영 체제에 따라 적절한 키를 사용합니다.\n\n   * 이 예제에서는 후크를 사용하여 세션의 시작 날짜를 로그 파일에 출력하는 스크립트를 `sessionStart` 실행합니다.\n\n     ```json copy\n     \"sessionStart\": [\n       {\n         \"type\": \"command\",\n         \"bash\": \"echo \\\"Session started: $(date)\\\" >> logs/session.log\",\n         \"powershell\": \"Add-Content -Path logs/session.log -Value \\\"Session started: $(Get-Date)\\\"\",\n         \"cwd\": \".\",\n         \"timeoutSec\": 10\n       }\n     ],\n     ```\n\n   * 이 예제에서는 외부 `log-prompt` 스크립트를 호출합니다.\n\n     ```json copy\n     \"userPromptSubmitted\": [\n       {\n         \"type\": \"command\",\n         \"bash\": \"./scripts/log-prompt.sh\",\n         \"powershell\": \"./scripts/log-prompt.ps1\",\n         \"cwd\": \"scripts\",\n         \"env\": {\n           \"LOG_LEVEL\": \"INFO\"\n         }\n       }\n     ],\n     ```\n\n     샘플 스크립트와 함께 에이전트 세션의 입력 JSON에 대한 전체 참조는 [GitHub Copilot 후크 참조](/ko/copilot/reference/hooks-reference)을 참조하세요.\n\n4. 파일을 리포지토리에 커밋하고 기본 분기에 병합합니다. 이제 에이전트 세션 동안 후크가 실행됩니다.\n\n## Troubleshooting\n\n후크를 사용하여 문제가 발생하면 다음 표를 사용하여 문제를 해결합니다.\n\n| Issue                                                                                                                                                                          | 조치                                                                                                                                                                             |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| 후크가 실행되고 있지 않습니다.                                                                                                                                                              | <ul><li>JSON 파일이 디렉터리에 있는지 `.github/hooks/` 확인합니다.</li><li>유효한 JSON 구문(예: `jq .  hooks.json`)을 확인합니다.</li><li>                                                                 |\n| `version: 1`이 당신의 `hooks.json` 파일에 지정되어 있는지 확인하십시오.</li><li>후크에서 호출하는 스크립트가 실행 파일인지 확인(`chmod +x script.sh`)</li><li>스크립트에 적절한 shebang이 있는지 확인합니다(예: `#!/bin/bash`).</li></ul> |                                                                                                                                                                                |\n| 후크가 시간 초과되고 있습니다                                                                                                                                                               | <ul><li>기본 제한 시간은 30초입니다. 필요한 경우 `timeoutSec`을(를) 구성에 추가하십시오.</li><li>불필요한 작업을 방지하여 스크립트 성능을 최적화합니다.</li></ul>                                                                 |\n| 잘못된 JSON 출력                                                                                                                                                                    | <ul><li>출력이 한 줄에 있는지 확인합니다.</li><li>Unix에서 JSON 출력을 압축하고 유효성을 검사하는 데 사용합니다 `jq -c` .</li><li>Windows PowerShell에서 `ConvertTo-Json -Compress` 명령을 사용하여 동일한 작업을 수행합니다.</li></ul> |\n\n## 디버깅\n\n다음 메서드를 사용하여 후크를 디버그할 수 있습니다.\n\n* **스크립트에서 상세 로깅을 활성화하여** 입력 데이터를 점검하고 스크립트 실행을 추적합니다.\n\n  ```shell copy\n  #!/bin/bash\n  set -x  # Enable bash debug mode\n  INPUT=$(cat)\n  echo \"DEBUG: Received input\" >&2\n  echo \"$INPUT\" >&2\n  # ... rest of script\n  ```\n\n* 테스트 입력을 후크에 파이핑하여 **로컬로 후크를 테스트**하여 해당 동작의 유효성을 검사합니다.\n\n  ```shell copy\n  # Create test input\n  echo '{\"timestamp\":1704614400000,\"cwd\":\"/tmp\",\"toolName\":\"bash\",\"toolArgs\":\"{\\\"command\\\":\\\"ls\\\"}\"}' | ./my-hook.sh\n\n  # Check exit code\n  echo $?\n\n  # Validate output is valid JSON\n  ./my-hook.sh | jq .\n  ```\n\n## 추가 읽기\n\n* [GitHub Copilot 후크 참조](/ko/copilot/reference/hooks-reference)\n* [GitHub Copilot 클라우드 에이전트 정보](/ko/copilot/concepts/agents/cloud-agent/about-cloud-agent)\n* [GitHub Copilot CLI 정보](/ko/copilot/concepts/agents/copilot-cli/about-copilot-cli)\n* [개발 환경 구성](/ko/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)"}