나「말한 거 다 지켜줘? 진짜야?」 Claude 「다 지키라니... 우선순위 정도는 정해줘...」 CLAUDE.md의 계층 설계 도입기

Claude Code를 계속 사용하다 보면, CLAUDE.md에 규칙이 점점 늘어납니다.

"일본어로 출력해줘", "rm은 사용하지 마", "테스트는 반드시 실행해", "심플한 구현을 우선해"….

어느샌가 규칙이 수십 개가 되어, "어라, 이 규칙 지켜지지 않고 있지 않아?" 라는 상황이 늘어납니다.

본 기사에서는 비대해진 CLAUDE.md를 우선순위 라벨이 붙은 계층 구조로 정리했더니, 규칙의 적용이 안정화된 이야기를 소개합니다.

앞으로 여러분이 CLAUDE.md를 키워나갈 때 참고가 된다면 좋겠습니다.

저의 CLAUDE.md도 사용하기 시작할 무렵에는 심플한 불렛 포인트(bullet point) 형식이었습니다.

# CLAUDE.md
- 일본어로 출력할 것
- rm 커맨드는 사용하지 말 것
...

하지만 운용하다 보니 규칙은 계속 늘어만 갑니다.

그리고 늘어남에 따라, "적혀 있는데 지켜지지 않는" 규칙이 생겨났습니다....

CLAUDE.md의 규칙에는 "절대로 지켜야 할 것"과 "상황에 따라 달라지는 것"이 혼재되어 있습니다.

이를 평면적인 불렛 포인트 상태로 늘려가면, Claude는 어떤 것을 우선해야 할지 판단할 수 없습니다...

그래서 P0~P4의 우선순위 라벨을 붙여 계층화하고, 상세 내용은 별도 파일로 분할하여 참조하는 구성으로 만들었습니다.

이것만으로도 규칙끼리 충돌했을 때의 동작이 안정되고, 중요한 규칙을 놓치는 일이 줄어듭니다.

평면적인 불렛 포인트로 운용하면서 세 가지 문제에 부딪혔습니다.

예를 들어, 다음과 같은 두 가지 규칙이 있다고 가정해 봅시다.

사용자가 "이 임시 파일, rm으로 지워줘"라고 말한다면 어떻게 될까요?

평면적인 불렛 포인트에서는 AI가 어느 쪽을 우선해야 할지 판단할 재료가 없습니다.

이는 세션에 따라 동작이 변하는 불안정성의 원인이 되고 있었습니다.

규칙이 50개 나열되어 있으면, "절대로 지켜줬으면 하는 안전 규칙"과 "가급적 따라줬으면 하는 코딩 취향"이 똑같은 모습이 됩니다.

인간의 문서와 마찬가지로, 전부 강조하면 아무것도 강조하지 않는 것과 같습니다...

Claude에게 있어서 "모두 중요하다"는 것은 "우선순위를 모르겠다"와 동의어입니다.

규칙의 배경이나 구체적인 예시까지 전부 CLAUDE.md에 적으면 파일이 수천 줄이 됩니다.

이는 매 세션마다 읽어들이는 컨텍스트 (context)를 규칙만으로 소비한다는 뜻입니다.

본래의 작업에 사용할 수 있는 컨텍스트가 줄어들어, 긴 세션에서는 규칙 자체를 잊어버리기 쉬워지는 본말전도 상황이 발생합니다.

규칙을 5단계 우선순위로 분류하고, 라벨과 적용 조건을 제목에 명기했습니다.

# CLAUDE.md
## Priority Rules (FOLLOW IN ORDER)
### [P0] CRITICAL - 안전 규칙과 기본 동작
...

포인트는 세 가지입니다.

이렇게 하면, 서두의 "rm으로 지워줘" 문제는 **"P0의 안전 규칙이 우선되므로, ~/.Trash/로 이동하는 것으로 대체한다"**라는 안정적인 동작이 됩니다.

규칙의 배경·구체적 예시·코드 예시는 ~/.claude/rules/ 하위의 개별 파일로 옮겼습니다.

CLAUDE.md 본체에는 요약과 참조 링크만 둡니다.

#### Occam's Razor - 가장 심플한 해답을 선택할 것
- 의존성은 0~2개를 우선 (3개 이상은 정당화 필요)
- 함수는 50행 이내, 조건 분기는 5개 이내
...

~/.claude/
├── CLAUDE.md ← 요약 + 우선순위 + 참조 링크
└── rules/
...

포인트는 CLAUDE.md 측에도 판단에 필요한 최소한의 수치 기준은 남겨두는 것입니다.

"상세 내용은 파일 참조"라고만 하면, 참조되지 않았을 때 아무런 효과가 없게 됩니다. 요약만으로 8할은 움직일 수 있는 상태로 만들고, 나머지 2할을 상세 파일에 맡깁니다.

분류와 더불어 효과적이었던 것은, 규칙을 수치로 작성하는 것입니다.

❌ 함수는 짧게 작성할 것
✅ 함수는 5~15행 (이상적으로는 5~10행). 초과 시 분할 검토
❌ 테스트가 통과하는지 확인할 것
...

'짧게', '제대로'와 같은 형용사는 AI에게 있어 해석의 여지가 너무 큰 단어입니다.

수치로 바꾸면 판정이 기계적으로 변하며, 규칙이 지켜졌는지 여부를 AI 스스로 검증할 수 있게 됩니다.

플랫한(Flat) 불렛 포인트 방식과 우선순위 라벨 구성으로 운영이 어떻게 변했는지 나열해 보겠습니다.

관점	Before (플랫한 불렛 포인트)	After (우선순위 라벨 + 분할 참조)
규칙의 충돌	세션마다 동작이 흔들림	P0 > P1 > … 순으로 안정적으로 해결
...

CLAUDE.md는 '쓰면 쓸수록 좋아지는' 것이 아니라, 구조가 없는 상태로 양만 늘리면 오히려 효과가 떨어지는 문서였습니다.

이는 인간 팀의 규칙서(Rulebook)와 같습니다.

신입 사원에게 50개의 규칙을 전달한다면, '반드시 지켜야 할 것'과 '익숙해지면 의식할 것'을 나누어 전달할 것입니다. AI에 대해서도 동일한 배려가 필요했다는 것이 운영하며 느낀 실감입니다.

본 기사의 요점은 다음과 같습니다.

CLAUDE.md는 한 번 쓰고 끝내는 것이 아니라, 운영하면서 구조를 키워나가는 문서입니다.

규칙이 늘어나 효과가 떨어지고 있다고 느껴진다면, 우선 우선순위 라벨을 통한 정리부터 시도해 보세요!

요약