CLAUDE.md를 살찌우지 마라 — 규칙은 필요한 순간에만 읽게 하라

여, 야로들(野郎ども).

오늘은 CLAUDE.md에 관한 이야기다. 정확히는, Claude Code에 먹이는 규칙을 어떻게 다이어트시킬 것인가에 대한 이야기다.

규칙은 늘어난다. 편리하니까 말이다.

"이 repo에서는 이렇게 해줘"

"PR 코멘트는 이렇게 답해"

"settings.json을 건드릴 때는 이 함정을 기억해"

"리뷰를 게시하기 전에 이 작법을 읽어"

전부 도움이 된다. 하지만 전부를 매번 읽을 필요는 없다. 배에 실은 통(barrel)이 너무 많아지면 갑판이 가라앉는다. CLAUDE.md도 마찬가지다.

이 기사에서는, 내 ~/.config에서 실제로 수행한 Claude 규칙의 de-always-on을 정리한다. 목표는 단순하다.

규칙을 지우지 마라. 필요한 순간에만 갑판으로 올려라.

게훕.

보물 지도: 위치는 "트리거의 형태"로 결정하라

먼저 보물을 공개한다. 내가 사용하고 있는 판단표는 이것이다.

규칙의 형태	위치	사용하는 이유
어떤 작업에서도 필요한 짧은 원칙	CLAUDE.md / always-on	판단 전에 필요. 짧고 안정적이라면 상주해도 좋다
특정 파일을 건드릴 때만 필요	.claude/rules/*.md + paths:	파일 경로가 그대로 발화 조건이 된다
특정 커맨드 직전·툴 결과 직후에만 필요	hook + additionalContext	그 순간에만 문맥을 삽입할 수 있다
긴 절차·재사용하는 작업 흐름	skill	설명만을 인덱스로 삼고, 본체는 호출했을 때만 읽는다
틀리면 위험한 경계	hook enforcement	"기억해 둬"가 아니라 기계적으로 멈춘다

중요한 것은 고정된 순위가 아니다.

"hook이 최강이다"

"skill이 정의다"

"rules 디렉토리에 나누면 이긴다"

그런 조잡한 깃발은 바다에 걷어차 버려라. 구명부표는 던져주마.

질문은 하나다.

그 규칙은, 언제 필요해지는가?

이 질문에 답할 수 있다면, 위치는 대략 결정된다.

애초에 무엇이 살찌는가

Claude Code의 memory docs에서, CLAUDE.md는 세션 시작 시에 읽는 영구 지시(persistent instruction)로 취급된다. 편리하다. 그래서 늘어난다.

처음에는 귀엽다.

• 빌드 커맨드 (build command)
• 테스트 방법
• 커밋 전 확인 사항
• 이 repo의 기본 사상

그러다 보면 통이 늘어난다.

• README를 쓸 때만 적용되는 문장 규칙
• GitHub PR 리뷰 게시 작법
• settings.json의 hook event / schema의 함정
• WebFetch가 로그인 페이지를 잡았을 때의 복구 절차
• VM 검증의 긴 절차
• 규칙을 쓰기 위한 메타 규칙 (meta-rule)

전부 보물이다. 하지만 보물 상자를 전부 목에 걸고 항해하는 바보는 없다.

Claude Code의 rules에는 paths: frontmatter가 있다. 대상 파일에만 적용된다. 게다가 hooks에서는 PreToolUse / PostToolUse와 같은 이벤트로 문맥을 삽입할 수 있다. skills는 긴 절차를 호출식으로 만들 수 있다.

즉, 위치는 하나가 아니다.

CLAUDE.md는 배의 헌장이다. 창고가 아니다.

실제로 덜어낸 것들

내 ~/.config에서는, 이런 이동을 수행했다.

기존의 상시 적용 (always-on) 규칙	이동 위치	트리거 조건
README 작성 규칙	paths: 포함 규칙	README.md를 수정할 때
스크래핑 (scraping) 규칙	PostToolUse(Read) hook	HTML / HTTP 스타일의 입력을 읽은 후
코드 철학 (code philosophy)	paths: 포함 규칙	소스 파일을 수정할 때
UTM macOS VM 절차	skill + utmctl guard hook	절차는 skill, 위험한 작업은 hook
PR 리뷰 에티켓 (PR review conduct)	PreToolUse(Bash) hook	gh pr review / gh pr comment 직전
WebFetch 폴백 (fallback)	PostToolUse(WebFetch) hook	결과가 비어 있거나, 짧거나, 로그인 페이지처럼 보일 때
클립보드 위임 (clipboard delegation)	PreToolUse(Bash) hook	pbcopy / 클립보드 / 대화형 로그인 관련 명령어
규칙 작성 방법 (rule authoring HOW-TO)	paths: 포함 meta-rule	claude/rules/*.md를 수정할 때

깎아낸 것이 아니다. 증류한 것이다.

항상 마시는 물과, 폭풍이 불 때만 여는 술통을 구분했다.

paths:

파일에 종속시키기

레버 1: 가장 단순한 방법이다.

---
paths:
- "**/README.md"
...

파일명이나 확장자가 트리거가 된다면, 먼저 paths:를 의심하라.

적합한 경우:

• README 규칙
• 소스 파일용 코드 철학 (code philosophy)
• JSON / YAML / TOML용 설정 관행 (config practice)
• claude/settings.json용 Claude Code 설정 참조 (settings reference)
• claude/rules/*.md용 규칙 작성 방법 (rule authoring HOW-TO)

적합하지 않은 경우:

• 명령어 실행 직전에 필요한 예절
• WebFetch 결과를 확인한 후 필요한 복구책
• 위험한 작업을 차단하는 강제 집행 (enforcement)

paths:는 파일의 해도(海圖)다. 도구 결과가 몰아치는 폭풍까지는 읽을 수 없다.

레버 2: hook으로 그 순간에만 삽입하기

파일이 아니라 '명령어'나 '결과'가 트리거라면 hook이다.

예를 들어, PR 리뷰 게시를 위한 상세 규칙을 항상 읽게 할 필요는 없다. gh pr review나 gh pr comment를 입력하기 직전에만 읽으면 된다.

대략적인 형태는 다음과 같다.

#!/usr/bin/env bash
set -euo pipefail
input="$(cat)"
...

additionalContext는 인간의 화면에 나타나는 메시지가 아니다. Claude의 다음 판단에 삽입되는 문맥이다.

이 부분이 핵심이다.

상주(resident) 상태에서 제외하더라도, 사용할 순간에는 다시 돌아온다.

이봐, 이건 보물이다. 상세 내용을 잊게 만드는 것이 아니라, 상세 내용을 호출하는 타이밍을 늦추는 것이다.

레버 3: skill로 넘기기

긴 절차는 skill로 만들어라.

예를 들어 VM 검증 절차 같은 것 말이다. 이것은 매 턴마다 읽어야 할 것이 아니다. 필요할 때만 호출하면 된다.

단, 위험한 경계선까지 skill에 맡기지는 마라.

긴 절차 -> skill
위험한 작업 직전 -> hook
항상 유지해야 할 판단의 골격 -> CLAUDE.md

나는 utm-macos-vm을 skill로 넘기고, utmctl 실행 시의 안전 확인은 hook에 두었다.

skill과 hook은 적이 아니다. 역할이 다를 뿐이다.

skill은 해도다.

hook은 검문소다.

CLAUDE.md는 배의 규율이다.

함정 1: "hook으로 만들면 전부 확실하다"는 거짓말이다

hook은 강력하다. 하지만 만능은 아니다.

예를 들어 $schema 추가 규칙을 생각해보자.

JSON / YAML / TOML 설정 파일을 수정할 때 schema를 찾는 것은 좋은 습관이다. 하지만 올바른 schema를 선택하려면 판단이 필요하다.

• SchemaStore에 있는가
• 공식 schema가 있는가
• 그 파일이 fixture / lockfile / generated file이 아닌가
• YAML / TOML에서 애초에 $schema 형식이 적절한가 - 툴이 in-file schema를 꺼려하지 않는가

이것을 조잡한 hook으로 자동 삽입하면 사고가 난다.

이런 것들은 path-gated rule이 좋다. 모델이 생각하게 해야 하는 영역이다. hook은 '판단'보다 '경계'에 적합하다.

해적에게도 역할 분담이 있다. 망보기를 하는 사람에게 요리를 시키지 마라.

함정 2: 스스로 성장하는 지식을 always-on에 두지 마라

이것이 이번에 가장 뼈아픈 조언이었다.

늘어나는 문서를 always-on에 두지 마라.

settings에 대한 지견, hook event의 습성, 프로젝트 고유의 전례. 이런 것들은 항해를 할 때마다 늘어난다. 늘어나는 것을 CLAUDE.md에 두면, 성장량이 매 세션마다 지불해야 하는 세금이 된다.

나는 claude-code-settings.md를 paths:를 통해 settings file에 묶었다. 그리고 그 안에 "settings.json의 새로운 지견을 발견하면, 이 rule에 추가하라"라고 적었다.

즉, 다음과 같다.

settings.json을 건드린다
-> settings용 rule이 읽는다
-> 새로운 함정을 발견한다
...

성장한다. 하지만 상주하지는 않는다.

통 바닥에 침전물은 쌓아두되, 그것을 매일 아침 마시는 물에 섞지는 마라. 꺽.

함정 3: 트리거가 늦으면 읽기를 놓친다

de-always-on은 기분이 좋다. 줄 수도 줄어들고 가벼워진다.

하지만 과하면 가라앉는다.

예를 들어 GitHub markdown의 본문 작성법을 gh pr create 직전 hook으로 전부 옮기면 어떻게 될까. PR 본문을 만든 후에 규칙이 올지도 모른다. 늦다. 이미 본문은 통 안에 다 채워진 상태다.

이런 타입은 위험하다.

판단 기준은 이것이다.

필요한 순간과 읽히는 순간이 일치하는가?
일치하지 않는다면, 짧은 backstop을 always-on에 남겨둘 수 있는가?
그래도 위험하다면, 남겨라.

감소 폭만 보지 마라.

"읽기를 놓쳤을 때의 피해"를 봐라.

security posture와 같은 안전 규칙은 상주해도 좋다. 가장 필요한 순간에 부재한다면, 그것은 절약이 아니라 구멍이다.

최종 형태: 결정 골격만 상주시킨다

최종적으로 CLAUDE.md에 남긴 것은 긴 HOW-TO가 아니라 판단의 골격뿐이다.

## Choosing the mechanism
- Universal, bounded, stable guidance -> always-on
- File-type passive guidance -> rule + paths
...

그리고 "규칙을 만드는 법" 그 자체는 rule-authoring.md로 옮겼다.

---
paths:
- "**/claude/rules/*.md"
...

이렇게 하면 규칙을 쓸 때만 규칙을 쓰는 법이 나타난다.

아름답지 않은가. 스스로 자신의 갑판을 청소하는 메커니즘이다.

전체도

검증하려면 여기를 봐라

기분에 따라 최적화하지 마라. 최소한 숫자와 발화(trigger)를 봐라.

always-on의 재고 조사

for f in claude/rules/*.md; do
if ! sed -n '1,8p' "$f" | grep -q '^paths:'; then
wc -l "$f"
...

paths:가 없는 rule은 매 세션 읽는다. 우선 여기를 세어라.

hook의 발화 테스트

hook은 나와야 할 때 나오고, 침묵해야 할 때 침묵해야 한다.

printf '%s\n' '{
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
...

트리거 payload에서 additionalContext가 나온다.

비트리거 payload에서는 아무것도 나오지 않는다.

이 두 가지를 봐라. 한쪽만으로는 부족하다.

요약

CLAUDE.md를 다이어트시키는 것은 인색하게 굴기 위해서가 아니다.

효과를 높이기 위해서다.

• 항상 필요한 짧은 계율만 CLAUDE.md에 남긴다.

• 파일 종류별 작법은 paths:를 활용한다.

• hook으로 제한한다 — 명령어(command)나 결과(result)에 반응하는 작법은 hook으로 삽입한다

• 긴 절차는 skill로 넘긴다

• 위험한 조작은 hook으로 차단한다

• 늘어나는 지식은 always-on에 두지 않는다

규칙은 올바른 위치에 두는 것만으로는 부족하다.

올바른 순간에 읽게 하라.

그것만으로 Claude Code는 가벼워진다. 게다가 약해지지도 않는다. 오히려 필요한 시점에 더 강력하게 작용한다.

배에 싣는 통(barrel)은 줄여라. 하지만 보물은 버리지 마라.

필요할 때 열어라.

참고

Discussion