에이전트가 내 말을 안 듣는다면 — CLAUDE.md·스킬·커맨드·훅 4레버로 신뢰도 100% 만들기

누락이 모델 탓이 아닌 이유, 그리고 4가지 컨트롤 레버의 신뢰도 차이를 직접 써보고 정리한 방법론

오프닝: “CLAUDE.md에 다 써뒀는데 왜 안 지켜지죠?”

저도 한동안 이 질문을 달고 살았습니다. CLAUDE.md에 규칙을 20개쯤 빼곡하게 써뒀는데, 실제로 지켜지는 건 절반도 안 됐거든요. 모델이 멍청한 건지, 제가 프롬프트를 못 쓰는 건지 헷갈렸습니다.

지금은 답이 명확합니다. 문제는 모델도, 프롬프트도 아니었어요. 컨트롤 레버를 잘못 선택한 것이었습니다.

Claude Code에는 에이전트 행동을 빚는 4개의 컨트롤 표면이 있고, 각각 신뢰도와 비용이 완전히 다릅니다. 이걸 구분하지 않고 죄다 CLAUDE.md에 때려넣으면 누락은 구조적으로 피할 수 없습니다.

레버 1: CLAUDE.md — 항상 켜져 있지만, 그래서 위험한

CLAUDE.md의 가장 큰 특징은 항상 로드된다는 거예요. 매 세션, 매 메시지마다 모델이 읽습니다. 즉 거기 쓴 모든 글자가 세션 내내 매 요청 비용에 얹힙니다.

문제는 내용이 길어질수록 개별 규칙 준수율이 떨어진다는 점입니다. 모델의 attention이 늘어난 컨텍스트 전체에 퍼지면서, 특정 규칙이 우선순위에서 밀려납니다. “있긴 한데 무시됨”이 CLAUDE.md 과적재의 전형적인 증상이에요.

판단 기준은 하나입니다. “이 내용을 매 메시지마다 들고 다닐 가치가 있나?” 있으면 CLAUDE.md, 없으면 다른 레버로 빼야 합니다. 패키지 매니저 설정, 코드 스타일, 상시 적용 규칙 — 이런 것들만 남기는 게 맞습니다.

레버 2: 스킬 — 발동 전까지는 거의 공짜

스킬은 .claude/skills/<이름>/SKILL.md 구조로 만들어두면, 평소엔 description만 떠 있고 본문은 발동 시점에 로드됩니다. 발동 안 하면 비용이 거의 없어요.

이걸 알고 나서 CLAUDE.md에 있던 무거운 절차들을 스킬로 분리했더니 두 가지가 동시에 좋아졌습니다. 분리한 절차는 스킬이 또렷하게 챙기고, 남은 CLAUDE.md 규칙들도 희석이 줄어서 준수율이 올라갔습니다. 의외로 큰 이득이었어요.

스킬에서 제일 중요한 건 description입니다. “언제 발동할지” 조건이 구체적이지 않으면 정작 필요할 때 안 나옵니다. “주식 관련”보다 “P&L 계산이나 손익 관련 로직을 작성·수정할 때” 처럼 써야 Claude가 맥락을 맞출 수 있어요.

스킬 고유의 실패 모드도 하나 있습니다. CLAUDE.md는 희석돼도 적어도 떠는 있는데, 스킬은 발동 못 하면 아예 통째로 안 나옵니다. 그래서 description 품질이 곧 누락률입니다.

레버 3: 커맨드 — 수동이라서 신뢰도 100%

커맨드는 /이름을 직접 쳐야 발동합니다. 모델 판단 없이 사람이 의도적으로 실행하는 구조라 신뢰도는 100%입니다.

스킬로 만들기 전에 프로세스를 테스트하거나, 자동 발동이 오히려 방해가 되는 작업에 적합합니다. /review, /simplify 같은 것들 — 잘 만든 프롬프트를 한 단어로 호출하는 편의 도구입니다.

레버 4: 훅 — 모델 판단을 아예 안 거친다

훅은 성격이 완전히 다릅니다. 모델이 “할지 말지” 판단하는 과정 자체가 없습니다. 툴 호출 주변 이벤트에 박힌 쉘 명령어가 결정론적으로 실행됩니다.

settings.json의 hooks 키 아래 이벤트 → matcher → 핸들러 구조로 정의합니다. 핵심 이벤트는 세 가지입니다.

• PreToolUse: 툴 실행 전 가로채기. exit code 2면 차단, 0이면 허용
• PostToolUse: 툴 실행 후 뒷정리
• Stop: Claude가 끝내려 할 때 게이트

제가 직접 확인한 가장 인상적인 장면은 PreToolUse로 시크릿 스캔을 걸었을 때였습니다. sk-ant-, ghp_ 같은 고신뢰 패턴이 감지되면 exit 2로 차단 — 모델이 판단하기도 전에 막힙니다. “아, 이건 진짜 누락이 없구나”를 체감한 순간이었어요.

Stop 훅으로 테스트를 강제하는 것도 강력합니다. Claude가 끝내려 할 때 테스트를 돌려서 실패하면 exit 2로 못 끝내게 막는 구조. tester 에이전트는 모델 판단이지만 Stop 훅은 결정론적 게이트입니다.

4레버 판단 트리

4개를 어떻게 배분할지 실제로 쓰는 기준입니다.

정리하면 이렇습니다. “이 행동은 항상 필요한가 / 자동으로 떠야 하나 / 절대 빠지면 안 되나” — 이 세 질문만 구분되면 레버 선택이 거의 자동으로 따라옵니다.

행동으로 이어지는 결말

지금 CLAUDE.md를 열어서 규칙 목록을 훑어보세요. 그 중에서 “딱 한 번만 쓰는 것”과 “반드시 지켜야 하는 것”을 분리해 보면 됩니다.

전자는 커맨드로 옮기고, 후자는 훅으로 빼세요. CLAUDE.md가 절반으로 줄고, 남은 규칙의 준수율이 올라갑니다. 이게 컨트롤 레버를 이해한 뒤에 바뀐 실제 경험입니다.

스킬과 Claude Code의 세계가 더 궁금하다면 스킬의-비밀-자연어가-로직이-되는-순간과 빌드플랜-스킬로-개발시간-단축도 이어서 보시면 맥락이 잘 연결됩니다.