Anthropic 공식 플러그인 「hookify」로 Claude Code의 후크를 자연어로 만들기

서론

Claude Code의 후크 (Hook) 기능은 강력합니다. 파일 편집 전에 확인 과정을 거치거나, 위험한 명령어를 차단하거나, .env 파일에 대한 쓰기를 방지할 수 있습니다.

하지만 실제로 설정하려고 하면, settings.json에 JSON을 직접 작성해야 하며, 형식을 찾아보며 시행착오를 겪는 사이에 포기해 버린 경험이 있는 사람도 적지 않을 것입니다.

hookify는 그 장벽을 거의 제로로 만드는 플러그인입니다. 자연어로 하고 싶은 내용을 전달하는 것만으로 후크가 생성되며, 재시작 없이 즉시 유효해집니다.

hookify란

hookify는 claude-plugins-official에서 공개된 Anthropic의 공식 플러그인입니다.

후크의 정의를 settings.json의 복잡한 JSON으로 쓰는 대신, 마크다운 (Markdown) 파일로 쓸 수 있게 해줍니다. 그 마크다운 생성을 자연어 지시로부터 자동으로 수행하는 것이 /hookify:hookify 명령어입니다.

공식 README.md에는 /hookify 명령어로 적혀 있지만, 이렇게 입력하면 에러가 발생하므로 주의가 필요합니다.

주요 특징은 다음과 같습니다:

• 자연어 지시로부터 규칙 파일을 자동 생성
• 대화 이력을 분석하여 "반복적으로 수정된 패턴"을 자동으로 검출
• JSON을 전혀 쓰지 않고 완결
• warn (경고만)과 block (실행 저지)을 선택 가능
• 변경 즉시 반영 (재시작 불필요)

설치

/plugin install hookify@claude-plugins-official
/reload-plugins

이전의 claude-code-setup과 마찬가지로, 마켓플레이스에서 한 줄로 설치할 수 있습니다.

이전 기사는 여기로

기본적인 사용법

지시를 전달하여 사용하기

하고 싶은 일을 인자 (Argument)로 전달합니다:

/hookify:hookify rm -rf 를 실행할 때는 경고해줘

Claude가 다음을 수행합니다:

• 지시를 분석하여 규칙을 설계
• warn인지 block인지 확인
• .claude/hookify.warn-rm.local.md를 생성
• "즉시 유효합니다"라고 통지

실행 결과

❯ /hookify:hookify rm -rf 를 실행할 때는 경고해줘
⏺ Skill(hookify:writing-rules)
⎿ Successfully loaded skill
...

인자 없이 사용하기 (대화 분석 모드)

/hookify:hookify

인자 없이 실행하면, 최근의 대화를 분석하여 "반복적인 수정이 발생한 패턴"이나 "사용자가 명시적으로 부정적으로 언급한 조작"을 자동으로 검출하여, 후크화 후보를 제시합니다.

예를 들어 다음과 같은 발언이 과거 대화에 있었을 경우:

왜 console.log 를 추가했나요? 삭제해 주세요

이를 검출하여 "TypeScript 파일에 console.log 추가를 경고하는 후크"를 후보로서 제시해 줍니다.

헬퍼 명령어 (Helper Command)

명령어	설명
/hookify:list	설정된 규칙 목록 표시
/hookify:configure	규칙의 활성/비활성을 대화형으로 전환
/hookify:help	문서 표시

규칙 파일의 구조

생성되는 파일은 .claude/hookify.{rule-name}.local.md라는 이름으로, 프로젝트 루트의 .claude/에 위치합니다. 포맷은 심플합니다.

기본형 (단일 패턴)

---
name: warn-dangerous-rm
enabled: true
...

복수 조건의 조합

---
name: warn-hardcoded-api-key
enabled: true
...

conditions를 사용하면 "파일 경로"와 "추가되는 텍스트"를 동시에 평가할 수 있습니다. 모든 조건이 일치할 때만 규칙이 발화합니다.

이벤트 타입

event	대상 도구	용도 예시
bash	Bash	위험한 명령의 차단 및 경고
file	Edit / Write / MultiEdit	특정 파일에 대한 쓰기 제어
stop	세션 중지	테스트 미실행 상태로 종료되는 것을 방지
prompt	사용자 입력	특정 지시 패턴에 반응
all	전체	횡단적인 규칙

warn と block の違い (warn과 block의 차이)

action	동작
warn	경고 메시지를 표시하지만 작업은 계속됨
block	작업을 차단함 (bash / file에서는 실행 중지, stop에서는 세션 종료를 방지)

고민된다면 warn부터 시작하여, 문제가 반복된다면 block으로 전환하는 운영 방식이 안전합니다.

実用的なルール例 (실용적인 규칙 예시)

다음 규칙들은 공식 examples 디렉토리에 수록된 샘플을 바탕으로 하고 있습니다. 일부 수정을 가했지만, 실제 파일도 참고해 주세요.

1. .env 파일에 대한 쓰기 차단

---
name: block-env-edit
enabled: true
...

2. 디버그 코드 혼입 경고

---
name: warn-debug-code
enabled: true
...

3. 테스트 미실행 상태로 세션 종료 방지

공식 샘플에는 다음과 같이 작성되어 있습니다.

---
name: require-tests-before-stop
enabled: false
...

단, not_contains의 구현은 Python의 단순한 부분 문자열 체크(pattern not in text)입니다. |는 정규 표현식의 OR가 아니라 리터럴 문자로 취급되기 때문에, 위 설정은 "npm test|pytest|cargo test라는 문자열이 트랜스크립트(transcript)에 포함되지 않을 경우 발화"하는 동작이 됩니다. 이 문자열이 트랜스크립트에 나타날 일은 거의 없기 때문에, 테스트를 실행하고 있더라도 항상 block이 발화하게 됩니다.

올바르게 동작시키려면 조건을 하나씩 분리해야 합니다 (조건은 AND로 평가되므로 "어느 것도 포함되지 않을 경우 발화"하게 됩니다).

---
name: require-tests-before-stop
enabled: false
...

테스트 필수 체크는 너무 엄격한 상황도 있을 수 있으므로, 기본값을 enabled: false로 설정해 두고 필요한 프로젝트에서만 활성화하는 것을 추천합니다.

settings.json との比較 (settings.json과의 비교)

기존의 후크 설정과 hookify를 비교합니다.

기존 (settings.json을 수동 작성):

{
"hooks": {
"PreToolUse": [
...

hookify:

---
name: block-dangerous-rm
enabled: true
...

후크의 의도를 읽기 쉽고 메시지를 자유롭게 쓸 수 있는 것이 hookify의 강점입니다. 또한 JSON 형식 오류로 인해 조용히(silently) 작동하지 않게 될 리스크도 없습니다.

注意点 (주의사항)

• 규칙 파일은 .local.md라는 이름이므로, .gitignore에서 버전 관리 대상에서 제외할지 여부를 의식해야 합니다. 팀과 공유하고 싶다면 파일 이름 명명 규칙을 검토하세요.
• 패턴은 Python의 정규 표현식(Regular Expression) 구문입니다. 복잡한 패턴은 python3 -c "import re; print(re.search(r'pattern', 'test'))"로 사전에 확인할 수 있습니다.
• stop 이벤트의 block은 강력하기 때문에, 의도치 않게 세션이 종료되지 못하는 경우가 발생할 수 있습니다. 사용할 때는 enabled: false를 초기값으로 설정해 두는 것을 권장합니다.

まとめ (요약)

hookify는 Claude Code의 후크 기능을 "알고는 있지만 설정이 번거로워 사용하지 못하는" 상태에서 "자연어로 즉시 설정할 수 있는" 상태로 바꿔주는 플러그인입니다.

자신이 반복해서 수정하던 작업을 /hookify:hookify

（인수 없음）으로 해석하여 규칙화하는 것만으로도, 일상적인 작업을 크게 개선할 수 있습니다.

참고 링크