오랜만에 하네스 이야기를 할게요.
마지막에 작성했던게 스킬을 테스트하는 내용이었는데요. 구조를 만들고, 잘 작동하는지 검증하기까지를 다뤘었습니다.
그 다음 문제를 다뤄볼까 해요. "아무리 잘 가르쳐도 Claude가 안 따르는 경우에 대해서"죠.
대부분의 경우 Claude에게 코드를 맡기기 전에 계획서를 먼저 만드는데요.
이슈를 분석하고, 순서를 정하고, 검토를 거쳐 확정하는 구조입니다.
계획서는 기본적으로 구현부터 Side-Effect까지를 다 다루게 되고, 필요하다면 심층 인터뷰를 통해 에이전트와 여러번 검토하고 결정되기 때문에, 저는 한번 확정된 계획서는 수정하지 않습니다.
그래서 프롬프트나 규칙으로 "계획서는 승인된 계약서입니다. 절대 수정하지 마세요"라고 적어두게 되는데요.
평소에는 잘 따릅니다. 그런데 실행하다가 막히면 "계획을 약간 조정하면 될 것 같은데요" 하면서 슬그머니 계획서를 고쳐버리더라구요.
프롬프트나 규칙은 결국 해석의 영역입니다.
Claude가 "이 상황에서는 예외가 합리적이다"라고 판단하면 뚫리게 됩니다. 스킬로 단계와 역할을 구조화해도 마찬가지구요. "어차피 고쳐야 하는 건데 미리 하는 게 효율적이잖아"라는 합리화 앞에서는 구조도 우회됩니다.
비유하자면, 프롬프트는 표지판(무시 가능), 스킬은 매뉴얼(우회 가능)입니다.
그래서 세 번째 방법인 잠긴 문. 훅(Hook)이 필요하게 된거죠.
훅의 동작 원리
훅은 Claude가 도구를 사용하거나 응답을 완료하는 시점에 자동으로 실행되는 스크립트입니다.
Claude가 아니라 시스템이 실행하기 때문에, Claude의 판단이 개입할 여지가 없습니다. 조건에 맞으면 차단, 아니면 통과. 그게 전부인거에요.
설정은 settings.json에 작성합니다.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "bash .claude/hooks/plan-guard.sh"
}
]
}
]
}
}구조는 세 가지입니다. 언제(이벤트 타입), 어떤 도구에(matcher), 무엇을(command).
이벤트 타입은 용도에 따라 나뉩니다.
PreToolUse: Claude가 도구를 쓰기 직전. 파일 수정이나 명령 실행을 가로챌 수 있습니다.
Stop: Claude가 응답을 마친 직후. 결과를 검사하거나 경고를 줄 수 있습니다.
UserPromptSubmit: 사용자가 메시지를 보낼 때. Claude에게 추가 맥락을 주입할 수 있습니다.
PreCompact: 대화 맥락이 압축되기 직전. 상태를 저장할 수 있습니다.
훅 스크립트는 stdin으로 JSON을 받습니다. 어떤 도구를 쓰려 하는지, 어떤 파일을 건드리려 하는지가 들어있구요. 스크립트의 종료 코드로 결과를 전달합니다.
exit 0: 허용. stdout에 메시지를 출력하면 Claude에게 전달됩니다.
exit 2: 차단. Claude에게 차단 사유가 전달되고, 해당 행동은 실행되지 않습니다.
이제 패턴을 보겠습니다.
패턴 1: 차단
가장 기본적인 패턴입니다. 계획서 보호 훅의 핵심은 이렇습니다.
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
if [[ "$FILE_PATH" =~ PLAN\.md$ ]] && [[ -f ...
