▲

Claude Code가 이제 훅(hooks)을 지원함

 (docs.anthropic.com)
17P by GN⁺ 6일전 | ★ favorite | 댓글 3개
  • Claude Code에 사용자 정의 훅 기능이 도입. LLM의 선택에 의존하지 않고, 앱의 행동을 더욱 정확하고 반복적으로 제어할 수 있음
  • 알림 커스터마이징, 코드 자동 포맷팅, 명령 로그 추적과 같은 다양한 자동화가 가능
  • 명령어 실행 전/후, 알림 발생, 응답 완료 시점 등에서 동작하며, 설정 파일을 통해 프로젝트·사용자·엔터프라이즈 레벨로 관리할 수 있음
  • 설정 파일 구조와 매처(matcher) 방식을 통해, 특정 도구 호출 시점에 특정 훅만 실행할 수 있음
  • 입력은 JSON 포맷으로 전달되고, 출력은 exit code 또는 JSON으로 결과·피드백을 제어함
  • 훅은 셸 명령어를 사용자의 전체 권한으로 자동 실행하므로, 보안 및 안전에 대한 주의 필요함

소개

  • Claude Code의 훅(hook)은 코드 실행 라이프사이클 각 단계에서 자동으로 실행되는 사용자 지정 쉘 명령어
  • 이를 통해 LLM이 선택적으로 실행하는 것 대신 매번 일관된 자동화가 가능해짐

  • 주요 활용 예시

    • 알림: 입력 대기 시 사용자에게 맞춤형 알림 제공
    • 자동 포맷팅: 파일 편집 후 prettier 또는 gofmt 자동 실행
    • 로깅: 실행된 명령을 기록하고 집계하여 추적이나 디버깅에 활용
    • 피드백: 코드베이스 규칙에 맞지 않는 코드 생성 시 자동 피드백 제공
    • 커스텀 권한: 민감 디렉터리나 프로덕션 파일에 대한 변경 차단
  • 프롬프트가 아닌 시스템 코드로 동작하므로, 매번 확정적으로 실행됨 → 자동화의 신뢰성 증가
  • 훅은 사용자 전체 권한으로 셸 명령을 직접 실행하므로, 안전성 검증 필요함.

구성 예제

  • 예: Claude가 Bash 명령 실행 전마다 로그를 남기도록 후크 등록
    1. /hooks 명령어로 후크 설정 메뉴 진입, PreToolUse 이벤트 선택
    2. Bash 매처 추가 (Bash 명령에만 적용)
    3. 후크 커맨드 등록 및 저장 (User settings 위치 선택 시 전체 프로젝트에 적용)
    4. /hooks로 설정 확인 또는 ~/.claude/settings.json에서 파일 직접 확인 가능

설정 구조

  • 후크는 매처(matcher) 기준으로 그룹화하며, 매처별로 여러 후크를 배열로 가질 수 있음
    • 예: 단일 문자열(정확 매칭), 정규식, 비워두면 모든 이벤트에 적용
  • 설정 파일 종류
    • ~/.claude/settings.json: 사용자 전체 설정
    • .claude/settings.json: 프로젝트 설정
    • .claude/settings.local.json: 로컬(비공유) 설정
    • 엔터프라이즈 정책 설정

주요 후크 이벤트

  • PreToolUse: 툴 호출 전 실행, 필요시 실행 차단 가능 (주요 매처: Bash, Write, Edit, Grep 등)
  • PostToolUse: 툴 실행 직후, 동일 매처 지원
  • Notification: 알림 전송 시 실행
  • Stop: 응답 완료 후 실행

매처 예시

  • Task: 에이전트 작업
  • Bash: 셸 명령
  • Glob: 파일 패턴 매칭
  • Grep: 내용 검색
  • Read: 파일 읽기
  • Edit, MultiEdit: 파일 수정
  • Write: 파일 작성
  • WebFetch, WebSearch: 웹 작업

입력 및 출력 형식

  • 입력: stdin으로 JSON 전달 (세션 정보, 이벤트별 데이터 포함)
    • 예: PreToolUse에는 tool_input 포함, PostToolUse에는 tool_response 추가
  • 출력:
    • exit code 0: 정상 실행, stdout은 유저에게 표시
    • exit code 2: 차단, stderr가 Claude에게 피드백으로 전달 (PreToolUse에서는 툴 실행 차단)
    • 기타 코드: 오류, stderr만 유저에게 표시
    • 고급 제어: stdout에 JSON 반환 시, "continue" false나 "decision": "block" 등 세부 흐름 제어 가능

MCP 도구와 통합

  • Model Context Protocol(MCP) 기반 툴도 지원하며, 특수 네이밍 패턴(mcp____)을 통해 선택적으로 타깃팅 가능

보안 권고사항

  • 후크는 시스템 임의 명령 실행의 위험이 있으므로, 입력값 검증, 경로 체크, 민감 파일 제외, 절대 경로 사용 등 안전 규칙 필수
  • 설정 변경 시 즉시 반영되지 않으며, 세션 시작 시 스냅샷을 사용하고 외부 변경 시 경고 표시

실행 환경 및 디버깅

  • 각 후크는 최대 60초 제한, 병렬 실행, 현재 작업 디렉토리·환경에서 동작
  • /hooks에서 설정 확인, 명령 직접 테스트, exit code·출력 체크 등으로 디버깅 가능
  • 실행 과정과 결과는 transcript 모드(Ctrl-R)에서 확인
▲
shakespeare 6일전  [-]

윈도우 버전 좀 만들어주세요 ㅠㅠ

답변달기
▲
nalbam 2일전  [-]

wsl 사용하세요

답변달기
▲
GN⁺ 6일전  [-]
Hacker News 의견

  • Claude Code Opus 4가 파일 끝에 리턴을 붙이지 않는 버릇 탓에 답답함을 느꼈음
    새로운 후크를 테스트할 땐 claude를 재시작해야 하므로, 세션 내에서 계속 편집할 수 있는 스크립트를 활용한 편이 훨씬 효율적임
    이 스크립트는 C 파일과 쉘 스크립트엔 포매터를 적용하고, 기타 파일엔 누락된 리턴만 보정함
    Claude 같은 AI는 문제를 적절히 쪼개는 데 약하고, 이상한 방식으로 일을 시도하기도 해서, 위의 후크 예제처럼 JSON 파일을 디스크에 저장 후 경로만 빼서 다시 저장해두고, 해당 경로를 save-hook.sh로 넘기는 식으로 여러 번 고쳤음
    10분 만에 원하는 걸 해냈지만, 한 번에 큰 스텝을 시키느라 낭비한 시간이 더 많았음

  • AI가 개발자를 대체할 거란 말들을 듣지만, 이런 후크를 누가 설정하고 새 기능을 제안할지는 여전히 사람의 몫임
    이런 툴링과 관련된 작업은 AI가 스스로 이 아이디어를 생각해내서 다른 AI에 적용할 수준으로 진화하기 전까진 계속 존재할 상황임

    • 목공 비유를 빗대자면, 지금은 수공구에서 전동공구 시대로 넘어가는 전환점이라고 봄
      기본기를 이해한 사람이 도구를 잘 다룰 수 있지만, 이제는 손으로 섬세하게 만들던 대신 테이블쏘로 빠르게 작업하는 단계라 효율은 높지만 더 위험할 수도 있다는 이야기임

    • 콤바인 하베스터 같은 농기계가 등장해 농업 일자리를 대체할 거란 주장과 유사함
      모든 인력이 단순히 기계 조작자로 전환될 거란 게 말이 됨?
      자동화 도구든, 그게 농업이든 AI든, 단순 전환만이 가치가 아니라는 시각임

    • 유명한 "거북이 등 위의 지구" 이야기처럼, AI 출현 뒤엔 "그럼 그 AI를 누가 관리하지?"라는 논의로 무한반복할 수 있음
      이미 Claude Code에게 스스로 CLAUDE.md를 업데이트하도록 맡기는 사례도 있어서 자기 후크까지 수정하게 하는 일도 아예 불가능하지 않음
      하지만 쥬라기 공원처럼 "과연 해야 하는가"에 대한 고민이 빠지기 쉽다는 점이 흥미로움

    • AI가 개발 직업을 줄일 거란 의견과, 그럼 누가 후크를 설정하냐는 의문 모두 맞는 말임
      기술 발전이 일자리 수 증감 문제로만 단순화되지 않고, 일자리를 없애면서 동시에 새 일자리를 창출한다는 사실을 강조함

    • 사실 대다수 사람에게 이런 작업은 개발이 아니라 유지관리, DevOps 같은 일이라는 생각임
      SaaS 제품에서도 코드라기보다는 운영과 관련된 작업이 많고, HN 이용자들이 생각하는 본격적 개발과는 차이가 큼

  • 이번 기능 도입이 정말 기대됨
    후크는 에이전트의 맥락 엔지니어링과 런타임 성능 검증에 중요한 역할을 할 전망임
    엔터프라이즈 컴플라이언스나 행위 감시 등 다양한 상황에 확장 가능함
    Anthropic이 깃허브 이슈 제안에서 바로 지원한 것도 인상적임
    관련 이슈 링크

    • 실제로 나는 Claude Code대신 cline.bot이라는 VS Code 익스텐션을 쓰고 있음
      이런 기능은 앞으로 모든 코딩 에이전트에 보급될 필살기라고 생각함

  • 이 기능이 좋다고 느끼는 이유는, CLAUDE.md로 우회하지 않고 바로 복잡한 커맨드 실행 제어룰을 작성할 수 있기 때문임
    예를 들어,
    docker compose exec django python manage.py test
    같은 명령은 허용하고
    docker compose exec django python manage.py makemigrations
    같은 명령은 차단 가능함

    • 이미 .Claude/settings.json에서 이 정도는 구현 가능함

  • 이 기능이 MCP 서버 자체로 동작했다면 더 좋았을 것으로 생각함
    후크를 미리 약속된 이름의 mcp 툴로 만들어두고, 에이전트가 자동으로 후크를 발견해서 내부 구현을 몰라도 mcp 서버를 재사용하거나 다른 에이전트에서 재활용하는 그림을 상상할 수 있음

  • Claude Code가 CLAUDE.md 파일의 지침과 코드베이스의 주요 내용을 자주 까먹어서, 수시로 리마인드 시킬 필요가 있음
    이번 업데이트가 이 문제를 고칠 수 있을지 기대 중임

    • 예를 들면, "void 함수에서 일찍 리턴 쓰지 마! CLAUDE.md에 그런 패턴 금지라고 되어 있잖아!"
      Claude가 CLAUDE.md 읽고 "22초, 2.6k 토큰…"
      "당신 말이 맞음!"이라는 반응임

  • 예제 후크 몇 개 공유
    후크 작성 및 워크플로 자동화 예시 글
    Claude Code가 Cursor와 동등한 수준으로 코드 수정 후 린팅/타입 체크 지원을 갖춘 점이 반가움

  • Cursor에도 이런 기능이 들어갔으면 함
    지금은 임시 방편으로 여러 규칙 조합해서 어느 정도 해결 중임

    • Cursor를 안 쓰는 나로서는 아직도 이걸 쓰는 이유가 있나 궁금함

  • 이번 기능이 그동안 존재하던 큰 기능 격차를 해소한다고 봄
    Claude Code가 커밋을 생성하는 방식 때문에 일반 Git hooks가 대부분 동작하지 않아서, CLAUDE.md를 통해 Qlty CLI로 코드 형식을 자동화하도록 지시하는 편법을 썼는데, Claude가 이를 일관되게 잘 수행하지 못해서 아쉬웠음
    이번 변화로 더 결정적인 결과를 얻을 수 있음
    현재 hook 가능한 이벤트가 제한적이긴 하지만, 앞으로 Git commit과 push 이벤트도 쉽게 훅킹 가능해질지 기대됨
    Qlty CLI GitHub 링크

    • 참고로 Claude는 Java를 매우 잘 다룸
      내 스타일가이드, 들여쓰기 선호까지 정확히 파악해서 자바코드 리포매팅이 필요없는 수준으로 완벽하게 맞춤
      JavaDoc까지 정교하게 잘 맞춰줘서 놀람
      아마도 대형 엔터프라이즈 자바 코드 학습량이 어마어마했던 듯함

    • 일반 git hooks가 왜 claude code에서 제대로 동작하지 않는지 궁금함

    • Husky와 lint-staged는 정상적으로 작동했지만, Pre Commit Hooks는 작동하지 않았음

  • 내 짧은 이해로, 이 기능은 context를 소모하지 않고, MCP처럼 언제 실행할지 Claude가 결정하는 구조가 아니라 각 툴 사용에 대해 사용자가 직접 지정하는 자동 동작 구조임

답변달기