Claude Code를 단순 채팅형 코딩 도구로만 쓰면 개인 생산성 도구에 머뭅니다. 팀에서 제대로 쓰려면 에이전트가 파일을 읽고, 명령을 실행하고, PR을 만들기 전후에 조직 규칙을 통과하도록 만들어야 합니다. 이때 필요한 기능이 Hooks입니다. Hooks는 Claude Code 세션의 특정 이벤트에서 shell command, HTTP endpoint, LLM prompt를 실행하게 해주는 장치입니다.
중요한 점은 Hooks가 “자동화 편의 기능”이 아니라 “AI 에이전트 운영 제어면”이라는 것입니다. 사람이 IDE에서 코드를 고칠 때는 팀 규칙을 습관으로 지킵니다. 하지만 에이전트는 한 번에 여러 파일을 바꾸고, 테스트를 돌리고, 외부 도구를 호출합니다. 이 흐름에 검증 지점을 넣지 않으면 작은 실수가 큰 변경으로 번집니다.
Claude Code Hooks는 세션 시작과 종료, 사용자 프롬프트 제출, 도구 사용 전후, 권한 요청, 서브에이전트 시작과 종료 같은 지점에서 실행됩니다. 문서에는 SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PermissionRequest, SubagentStart, TaskCompleted, Stop 같은 이벤트가 정리되어 있습니다. 실무 설계에서는 이 이벤트를 “어디서 막고, 어디서 기록하고, 어디서 알릴 것인가”로 나눠 보면 쉽습니다.
PreToolUse는 방화벽에 가깝습니다. 위험한 명령, 금지된 경로 수정, 민감 파일 접근을 도구 실행 전에 차단할 수 있습니다. 예를 들어 .env, production credential, 결제 관련 설정 파일은 읽기·쓰기 정책을 분리해야 합니다. AI가 실수로 파일을 열람하거나 수정하려 할 때, 모델이 알아서 조심하리라고 기대하는 것보다 hook에서 명시적으로 막는 편이 안전합니다.
PostToolUse는 감사 로그와 품질 게이트에 적합합니다. 파일이 변경된 뒤 lint 대상인지, 테스트가 필요한지, 변경 파일 목록을 기록해야 하는지 판단할 수 있습니다. Stop 이벤트는 세션이 끝날 때 요약, 작업 로그, 다음 액션을 남기는 데 유용합니다. 사람이 이어받아야 하는 작업이라면 종료 시점 로그가 특히 중요합니다.
첫 번째는 위험 명령 차단 hook입니다. rm -rf, production DB 접속, 배포 명령, secret 출력 명령처럼 사고 비용이 큰 작업은 기본 차단해야 합니다. 승인 기반으로 풀더라도 “무조건 허용”보다 명령 패턴을 검사하는 편이 낫습니다. 이 hook은 복잡할 필요가 없습니다. stdin으로 들어온 도구 실행 정보를 읽고, 명령 문자열에 금지 패턴이 있는지 확인한 뒤 차단 결정을 반환하면 됩니다.
두 번째는 변경 파일 감사 hook입니다. 에이전트가 수정한 파일 목록, 변경량, 테스트 실행 여부를 세션 로그로 남깁니다. 나중에 문제가 생겼을 때 “AI가 어디를 건드렸는지”를 바로 확인할 수 있어야 합니다. 특히 monorepo에서는 앱, 웹, 인프라, 문서가 한 저장소에 섞여 있어 변경 범위를 놓치기 쉽습니다.
세 번째는 테스트 유도 hook입니다. 특정 파일 패턴이 바뀌면 관련 테스트 명령을 안내하거나 자동 실행 후보로 표시합니다. 예를 들어 src/api/**가 바뀌면 API 테스트, schema/**가 바뀌면 migration 검증, components/**가 바뀌면 Storybook 또는 UI snapshot 확인을 요구합니다. 핵심은 모든 변경에 같은 테스트를 돌리는 것이 아니라 변경 유형별 최소 검증을 연결하는 것입니다.
Claude Code settings는 scope 개념을 갖고 있습니다. Managed, User, Project, Local처럼 설정 위치와 우선순위가 다릅니다. 팀에서 공유해야 하는 hook은 프로젝트 설정에 두고, 개인 취향이나 로컬 실험은 local 설정에 둬야 합니다. 회사 보안 정책처럼 반드시 강제해야 하는 항목은 managed scope가 맞습니다.
여기서 흔한 실수는 모든 설정을 개인 디렉터리에 넣는 것입니다. 그러면 한 명의 환경에서는 잘 작동하지만 팀원이나 CI, 신규 장비에서는 같은 규칙이 적용되지 않습니다. 반대로 개인 API 키나 로컬 경로를 프로젝트 설정에 넣으면 보안과 재현성이 모두 깨집니다. 설정 scope를 설계하지 않은 hook은 시간이 지나면 “내 컴퓨터에서는 되는데요” 문제가 됩니다.
추천 구조는 단순합니다. 팀 공통 hook, 금지 명령, 프로젝트별 테스트 매핑은 repository의 .claude 설정에 둡니다. 개인 알림, 로컬 에디터 연동, 실험적 hook은 local 설정으로 둡니다. 조직 보안 정책은 managed 설정으로 배포합니다. 이 기준만 지켜도 협업 안정성이 크게 올라갑니다.
AI 에이전트 작업의 리스크는 일반 자동화와 다릅니다. 스크립트는 정해진 일을 반복하지만, 에이전트는 상황에 따라 다음 행동을 선택합니다. 그래서 hook은 단순 후처리보다 “행동 경계” 역할을 해야 합니다.
예를 들어 에이전트가 테스트 실패를 고치기 위해 의존성을 업그레이드할 수 있습니다. 작은 수정 요청이 패키지 버전 변경으로 번질 수 있다는 뜻입니다. package.json, lockfile, migration 파일, CI 설정 파일 변경은 별도 알림을 띄우거나 승인 요구 대상으로 분리하는 게 좋습니다. 또 외부 HTTP 호출이나 배포 명령은 dry-run과 실제 실행을 명확히 구분해야 합니다.
리뷰 관점에서는 hook 로그가 중요합니다. “모델이 왜 이 파일을 바꿨는가”는 대화 기록에 남을 수 있지만, 운영 감사에는 구조화된 로그가 필요합니다. 최소한 세션 ID, 사용자 요청, 변경 파일, 실행 명령, 실패한 명령, 최종 상태는 남겨야 합니다.
처음부터 완벽한 정책을 만들 필요는 없습니다. 1주차에는 위험 명령 차단과 변경 파일 로그만 넣으세요. 2주차에는 변경 파일 패턴별 테스트 안내를 추가합니다. 3주차에는 PR 템플릿과 연결해 에이전트가 작업 요약을 자동으로 남기게 합니다. 4주차에는 실제 사고나 불편 사례를 모아 정책을 다듬습니다.
중요한 것은 hook을 너무 시끄럽게 만들지 않는 것입니다. 모든 도구 호출마다 긴 알림이 뜨면 개발자는 hook을 끄고 싶어집니다. 좋은 hook은 평소에는 조용하고, 위험할 때만 강하게 개입합니다. 에이전트의 속도를 죽이는 규칙이 아니라, 사고 가능성이 높은 순간만 잡는 안전벨트가 되어야 합니다.
PreToolUse에서 금지 명령과 민감 파일 접근을 차단한다.PostToolUse에서 변경 파일, 실행 명령, 실패 결과를 구조화 로그로 남긴다.Stop 이벤트에서 작업 요약과 다음 액션을 자동 생성한다.package.json, lockfile, migration, CI 설정 변경은 별도 승인 대상으로 둔다.Claude Code Hooks는 AI에게 일을 더 많이 시키는 기능이 아닙니다. AI가 팀의 작업 방식 안에서 움직이게 만드는 운영 장치입니다. 에이전트 사용량이 늘어날수록 “잘 프롬프트하기”보다 “안전하게 실행되게 만들기”가 더 중요해집니다.