CLAUDE.md 실전 가이드

문제

CLAUDE.md에 규칙을 적어 넣었습니다. 몇 주 뒤 확인해 보면 그 규칙이 지켜진 적이 있는지 확신이 서지 않습니다.

이유

CLAUDE.md에 “이 표현이 프롬프트에 있으면 이 도구·스킬을 써라”는 형태의 트리거를 정의해두는 경우가 있습니다. 이런 규칙은 권고이지 강제가 아닙니다. 모델은 프롬프트와 CLAUDE.md 사이에서 매칭을 스스로 판단해야 하고, 판단할 동기가 없으면 조용히 건너뜁니다. CLAUDE.md에 규칙을 쓴다고 그 규칙이 습관이 되지는 않습니다.

강제되는 형태는 다릅니다. 훅으로 판정하거나 스킬 게이트로 막아둔 규칙은 판단이 개입할 여지가 없으므로 계속 발동합니다. 차이는 트리거의 정교함이 아니라 판정 방식에 있습니다. 자연어 판정인지 기계 판정인지가 결과를 가릅니다.

구조적인 실패 유형이 하나 더 있습니다. CLAUDE.md에 “낯선 패턴을 만나면 X를 참조하라”처럼 선택적으로 적용되는 지침을 적으면, 에이전트는 동기가 없으면 건너뜁니다. 더 나쁜 경우는 그 지침이 가리키는 도구 자체를 모델이 볼 수 없는 경우입니다. CLAUDE.md에 “예외 없이 /x를 실행한다”라고 적어 두고 x의 skillOverrides 값이 user-invocable-only라면, 그 스킬은 모델의 스킬 목록에서 애초에 숨겨져 있습니다. 모델 입장에서는 존재하지 않는 도구를 “예외 없이” 실행하라는 지시를 받은 셈입니다. 이 문장은 구조적으로 실행될 수 없는 죽은 코드입니다. 문서만 읽으면 아무 문제 없어 보이기 때문에 발견하기도 어렵습니다. 지침을 쓸 때는 그 지침이 참조하는 도구가 모델에게 실제로 보이는지를 함께 확인해야 합니다.

예시

아래는 구성한 예시입니다. /design-review는 실제로 등록된 스킬이 아니라, 조건부 트리거가 왜 막히는지 보여주기 위해 만든 이름입니다.

지켜지지 않는 CLAUDE.md

브라우저 자동화가 필요하면 프롬프트에 `$browser`를 붙여라.
새 컴포넌트를 만들 때는 예외 없이 `/design-review`를 실행한다.

$browser는 모델이 자율로 판단해 매칭해야 하는 자연어 트리거입니다. 동기가 없으면 건너뜁니다. /design-review는 skillOverrides가 user-invocable-only라면 모델의 스킬 목록에 아예 없습니다. 모델은 이 규칙을 지킬 방법이 없습니다.

강제되는 CLAUDE.md

브라우저 도구 라우팅은 실행 시점에 자동 판정한다 (참조: PreToolUse 훅).
CLAUDE.md는 라우팅 기준만 요약하고, 강제는 훅이 한다.

새 컴포넌트 작업 스킬의 SKILL.md 맨 앞에 “착수 전 읽을 것” 목록을 고정으로 박아둡니다. 그 스킬은 해당 작업일 때 무조건 로드되므로 판단이 개입할 자리가 없습니다. 사람이 명시적으로만 불러야 하는 도구는 CLAUDE.md에서 “모델이 자동으로 실행한다”고 적지 않습니다.

CLAUDE.md에 새 규칙을 적었다면, 다음 점검을 합니다.

이 규칙이 가리키는 도구는 모델의 스킬 목록에 보이는가?
├─ 아니오 (user-invocable-only, off) → CLAUDE.md 문구를 지우거나 사람 호출로 명시한다
└─ 예 → 자연어 트리거로 충분한가, 훅·고정 목록으로 강제해야 하는가를 판단한다

하지 말 것

트리거를 CLAUDE.md에 적어놓고 실제로 쓰이는지 확인하지 않기. 문서에 적어둔 자연어 트리거는 한 번도 입력되지 않은 채 방치되기 쉽습니다. 프롬프트 로그를 직접 훑기 전에는 그 사실을 알기 어렵습니다.

모델에게 보이지 않는 스킬을 “예외 없이 실행한다”고 적기. user-invocable-only나 off인 스킬을 CLAUDE.md에서 모델이 자동으로 실행할 것처럼 적으면, 그 문장은 실행되지 않는 죽은 코드입니다.

공식 include/exclude 기준을 지켰다는 이유로 규칙이 지켜진다고 믿기. 무엇을 CLAUDE.md에 넣을지 기준을 지키는 것과, 넣은 규칙이 실제로 발동하는 것은 별개 문제입니다.

CLAUDE.md 실전 가이드

문제

추천

이유

예시

하지 말 것