Rules

문제

지침을 CLAUDE.md에 둘지, 훅으로 강제할지, 스킬로 내릴지 매번 헷갈립니다. 셋 다 “규칙을 지키게 만드는” 방법처럼 보입니다.

추천

회수·주입 정책은 얼마나 자주 훑어야 하는지로 고릅니다. 기본은 스킬 description 기반 조건부 호출이고, 도구가 실패했을 때만 반응하면 되면 PostToolUseFailure, 모든 프롬프트를 빠짐없이 훑어야 할 때만 UserPromptSubmit을 씁니다. 매 프롬프트를 훑는 쪽으로 올라갈수록 비용이 커지므로, 더 좁은 단계로 해결되는지부터 확인합니다.

이유

세 단계는 이렇게 나뉩니다.

1. 스킬 description 기반 조건부 호출이 기본값입니다. 모델이 요청 내용과 description을 대조해 스스로 판단합니다. 비용은 목록에 올라간 description만큼입니다.
2. PostToolUseFailure는 도구 실패에만 발동합니다. 성공한 작업이나 일반 프롬프트에는 전혀 실행되지 않으므로, “실패했을 때만 관련 지식을 주입한다” 같은 규칙에 맞습니다.
3. UserPromptSubmit은 모든 프롬프트를 훑어야 할 때만 씁니다. 실패 여부와 무관하게 항상 도는 유일한 단계라 비용도 가장 큽니다.

같은 프로세스 안에서 매칭 함수 자체만 재면 비용이 작아 보입니다. 실제로는 매 호출마다 새 프로세스를 띄우는 비용이 따로 붙습니다. 훅 성능은 프로세스 기동을 포함해서 재야 합니다. 함수 단위 벤치마크만 보고 “가벼우니 모든 이벤트에 걸어도 된다”고 판단하면 실제 체감 지연을 과소평가합니다.

회수 품질을 좌우하는 것은 매칭 로직보다 사전입니다. 문서를 찾아냈는데 실제 증상 표현이 검색 키워드 목록에 없었다면 그 표현을 추가합니다. 사전에 없는 어휘는 매칭기를 아무리 정교하게 짜도 잡히지 않습니다.

예시

새 규칙을 어디에 둘지는 이 순서로 판단합니다.

이 규칙을 언제 지켜야 하는가?
├─ 항상 사실이고 분량이 작다 → CLAUDE.md
├─ 특정 작업에서만 필요하고 모델이 스스로 판단해도 된다 → 스킬 description
├─ 도구가 실패했을 때만 필요하다 → PostToolUseFailure 훅
└─ 모든 프롬프트를 예외 없이 훑어야 한다 → UserPromptSubmit 훅

UserPromptSubmit을 선택했다면 실제 지연(프로세스 기동 포함)을 직접 측정해보고 그 비용을 감수할 가치가 있는지 확인합니다. PostToolUseFailure로 충분한 규칙을 UserPromptSubmit으로 올리면 매 프롬프트가 그 비용을 뭅니다.

회수가 안 될 때는 매칭 로직보다 사전을 먼저 의심합니다. 실제로 겪은 증상을 표현한 그대로 검색 키워드에 추가했는지부터 확인합니다.

하지 말 것

훅 성능을 같은 프로세스 안의 매칭 함수만으로 재고 판단하기. 프로세스 기동을 포함하지 않은 벤치마크는 실제 지연의 일부만 잽니다. 벤치마크가 실제 지연을 과소평가하면 그 위에서 내린 판단(예: “가벼우니 모든 이벤트에 걸어도 된다”)이 틀립니다.

UserPromptSubmit을 기본값으로 쓰기. 도구 실패에만 반응하면 되는 규칙까지 매 프롬프트를 훑게 만들면, 필요 없는 비용을 세션 내내 반복해서 뭅니다.

매칭이 안 될 때 로직부터 고치기. 회수 실패의 상당수는 로직이 아니라 사전에 그 증상의 표현이 없어서입니다. 로직을 정교하게 다듬기 전에 어휘부터 채웁니다.