Claude Code 상세 사용법 45: Hooks로 자동화 가드레일 만들기 | DAKER 커뮤니티

Claude Code 상세 사용법 45: Hooks로 자동화 가드레일 만들기

Claude Code Hooks는 특정 생명주기 지점에서 자동 실행되는 shell command, HTTP endpoint, MCP tool, prompt, agent입니다. 공식 reference 기준으로 hook은 JSON 컨텍스트를 받아 검사하고, 필요하면 작업을 막거나 Claude에게 추가 정보를 돌려줄 수 있습니다.

언제 쓰나

Hooks는 “Claude에게 잘 부탁하기”보다 강한 장치가 필요할 때 씁니다.

- Bash(git push *) 전에 보호 브랜치 여부 확인
- Edit(*.ts) 뒤에 formatter 또는 타입체크 실행
- UserPromptSubmit에서 회사 티켓 번호 누락 경고
- Stop 시 테스트 로그와 변경 파일 요약 생성

설정 예시

아래는 위험한 push를 막는 최소 예시입니다. 실제 팀에서는 스크립트를 파일로 분리하고 테스트하세요.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git push *)",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Push requires human review' >&2; exit 2"
          }
        ]
      }
    ]
  }
}

문서에 따르면 command hook은 이벤트 JSON을 stdin으로 받습니다. HTTP hook은 POST body로 받습니다. MCP tool hook은 연결된 MCP 서버 도구를 호출하고, prompt hook은 단일 판단을, agent hook은 도구를 써서 더 깊은 검증을 수행할 수 있습니다.

타입 선택

로컬 파일 검사, lint, secret scan은 command가 단순합니다. 조직 공통 정책 서버나 감사 로그는 HTTP가 낫습니다. 이미 연결한 Jira, GitHub, 내부 MCP가 판단에 필요하면 MCP tool을 씁니다. “이 요청이 릴리스 변경인가?”처럼 의미 판단은 prompt hook 후보입니다. 여러 파일을 읽어야 하면 agent hook이 맞지만 실험적 성격을 고려해야 합니다.

실패 모드

첫 번째 실패는 hook이 너무 무거운 경우입니다. 모든 tool call마다 긴 테스트를 돌리면 Claude Code 사용감이 무너집니다. 빠른 차단은 동기 hook, 긴 검증은 async hook이나 CI로 보내세요.

두 번째는 shell quoting입니다. 경로와 인자가 복잡하면 command 문자열보다 args를 쓰는 exec form이 안전합니다. 세 번째는 비밀 노출입니다. hook stdout, stderr, HTTP 로그에 토큰이 찍히지 않게 해야 합니다.

선임 엔지니어 관점

Hooks는 agentic coding을 팀 규칙 안에 넣는 접착제입니다. 하지만 모든 규칙을 hook으로 만들 필요는 없습니다. 사람에게 설명할 관례는 CLAUDE.md, 반드시 막아야 하는 위험은 PreToolUse, 완료 증거는 Stop이나 CI에 배치하세요. 좋은 hook은 짧고 빠르며, 실패했을 때 왜 막았는지 명확합니다.

참고: Claude Code 공식 문서의 Hooks reference, Automate workflows with hooks, Settings 문서를 기준으로 작성했습니다.