Hook Troubleshooting

Hook이 의도한 대로 동작하지 않을 때 가장 먼저 점검해야 할 항목들과, 성능 저하·예기치 못한 동작을 줄이기 위한 진단 절차를 정리했습니다.

자주 발생하는 문제

Hook은 파일 변경, 저장, 사용자 명령 등 다양한 이벤트에 반응하는 자동화 장치입니다. 문제가 생겼다면 보통 트리거 조건, 동작 정의, 실행 환경 셋 중 하나에 원인이 있습니다. 아래 체크리스트를 위에서 아래로 따라가며 좁혀 보세요.

Hook이 아예 트리거되지 않을 때

가장 흔한 사례입니다. Hook을 만들었는데도 작업 흐름에서 발화하지 않는다면 다음을 차례대로 확인합니다.

1. 파일 기반 Hook이라면 설정한 file pattern(예: **/*.ts, src/**/*.test.tsx)이 실제로 대상 파일을 포함하는지 확인합니다. 너무 좁거나, 잘못된 glob 문법으로 적힌 경우가 많습니다.
2. Hook 자체가 활성화(enabled) 상태인지 확인합니다. 비활성화된 Hook은 조건이 맞아도 실행되지 않습니다.
3. 이벤트 타입(예: On file save, On file create, Manual)이 의도한 트리거와 일치하는지 다시 점검합니다. 저장 이벤트로 만들어 놓고 생성 이벤트에서 동작하길 기대하는 식의 혼동이 흔합니다.

예상과 다른 방식으로 동작할 때

Hook은 실행되지만 결과가 의도와 어긋나는 경우입니다. 대개 지시문이 모호하거나, 다른 Hook과 작업이 충돌하고 있습니다.

1. Hook의 instructions를 다시 읽고, 모호한 표현이나 해석의 여지가 있는 문장을 구체적으로 다듬습니다. "필요한 경우 정리"보다 "변경된 파일에 대해서만 import 정렬을 수행"처럼 명확하게 적습니다.
2. 같은 이벤트나 같은 파일 패턴을 공유하는 다른 Hook이 없는지 확인합니다. 두 Hook이 동일 파일을 동시에 수정하면 결과가 비결정적으로 보일 수 있습니다.
3. file pattern이 지나치게 광범위하지 않은지 점검합니다. 의도하지 않은 디렉터리(예: node_modules, 빌드 산출물)까지 매칭되면 부수 효과가 발생합니다.

성능이 느리거나 IDE가 무거워질 때

Hook은 편집 흐름과 함께 자주 실행되므로, 무거운 작업이 묶이면 체감 속도가 빠르게 떨어집니다.

1. 파일 기반 Hook은 file pattern을 더 구체적으로 좁혀 매칭되는 파일 수를 줄입니다.
2. agent prompt를 사용하는 Hook이라면 지시를 간결하게 만들고, 한 번에 너무 많은 작업을 시키지 않습니다. 작업을 나누거나 조건을 추가해 호출 빈도를 낮추는 것이 효과적입니다.
3. shell command 액션은 가능한 한 짧게 끝나도록 작성합니다. 장시간 실행되는 명령은 백그라운드 작업으로 분리하거나, 캐시·증분 처리를 도입합니다.
4. 트리거 이벤트가 너무 자주 발생하지 않도록 조건을 보강합니다. 예를 들어 모든 저장이 아니라 특정 디렉터리의 저장에서만 동작하도록 좁힐 수 있습니다.

여전히 해결되지 않는다면

위 항목으로도 원인을 좁히지 못했다면 일반 문제 해결 가이드인 /docs/troubleshooting을 참고합니다. IDE 전반의 로그 확인 방법, Agent 동작 점검 절차, 환경 진단 도구 등이 정리되어 있어 Hook 외부 요인까지 살펴볼 때 도움이 됩니다.