CLAUDE.md에 규칙을 많이 넣으면 좋을까? — YES와 NO 사이의 정답
규칙이 많을수록 품질은 올라가지만, 토큰 낭비와 충돌도 늘어난다. 100~200줄이 최적점인 이유.
한 줄 요약: 규칙이 많을수록 Claude의 출력 품질은 올라가지만, 일정 수준을 넘으면 토큰 낭비와 규칙 간 충돌이 발생한다. 정답은 '적정량'이다 — 보통 100~200줄이 최적점이다.
CLAUDE.md에 모든 규칙을 몰아넣고 싶은 충동은 자연스럽다. 더 많이 알려줄수록 더 잘 할 것 같다. 실제로 어느 수준까지는 맞다. 그런데 500줄을 넘기 시작하면 이야기가 달라진다. 이 글에서는 규칙을 늘리는 것이 언제 득이 되고 언제 독이 되는지, 데이터와 구조 분석으로 따져본다.
YES — 규칙이 많을 때의 장점
CLAUDE.md에 구체적인 규칙을 많이 넣으면 실질적인 이득이 있다. 특히 팀 단위 프로젝트나 반복 작업이 많은 환경에서 효과가 뚜렷하다.
일관성 향상
동일한 프로젝트에서 10번의 세션을 돌려도 코드 스타일, 파일 명명 규칙, 커밋 메시지 형식이 흔들리지 않는다. '이번 세션에서는 왜 다르게 했지?'라는 상황이 줄어든다.
실수 감소
금지사항이 명시되어 있으면 Claude가 그 패턴을 피한다. console.log 커밋 금지, any 타입 사용 금지처럼 구체적인 규칙이 있으면 리뷰에서 잡아야 할 항목이 줄어든다.
반복 지시 불필요
매 세션마다 같은 말을 반복하지 않아도 된다. 기술 스택, 배포 환경, 사용 금지 패키지를 한 번 써두면 세션마다 설명하는 비용이 사라진다.
팀 표준화
팀원이 여러 명이고 각자 Claude Code를 쓸 때, CLAUDE.md 하나가 팀 전체의 사실상 코딩 가이드라인 역할을 한다. 온보딩 문서와 실행 규칙이 같은 파일에 담긴다.
NO — 규칙이 많을 때의 단점
규칙을 늘리는 데는 명확한 비용이 따른다. 이 비용은 규칙 수가 선형으로 늘어도 문제가 지수적으로 커질 수 있다는 점에서 주의가 필요하다.
토큰 비용
CLAUDE.md는 매 세션마다 컨텍스트 창에 로드된다. 500줄짜리 CLAUDE.md는 세션이 시작되기도 전에 상당한 토큰을 소모한다. API 키 기반으로 비용을 직접 지불하는 경우라면 이 비용은 무시할 수 없다.
규칙 간 충돌 가능성
규칙이 늘어날수록 서로 모순되는 지시가 생길 확률이 높아진다. Claude는 두 규칙이 충돌할 때 자체적으로 판단하지만, 그 판단이 항상 의도에 맞지는 않는다.
중요도 희석
Claude는 CLAUDE.md의 모든 내용을 동일한 무게로 처리한다. 핵심 보안 규칙과 코드 스타일 권고가 같은 위계에 있으면, 중요한 것이 묻힌다. 규칙이 50개면 각 규칙의 실질적 영향력은 줄어든다.
유지보수 부담
프로젝트가 진화하면 규칙도 갱신해야 한다. 규칙이 많을수록 오래된 규칙이 남아있을 가능성이 높다. 현재 실제와 다른 규칙이 CLAUDE.md에 있으면 Claude는 잘못된 컨텍스트로 작업한다.
토큰 비용 분석
CLAUDE.md의 토큰 비용을 구체적으로 따져보자. 영문 기준으로 1토큰 ≈ 4자, 한국어 기준으로는 1토큰 ≈ 1~2자 수준이다(한글은 토큰 효율이 낮다). 아래 추정은 한국어 혼용 CLAUDE.md 기준이다.
| CLAUDE.md 규모 | 대략 줄 수 | 추정 토큰 | 세션 100회 시 총 토큰 |
|---|---|---|---|
| 최소형 | 30~50줄 | 약 400~700 토큰 | 약 50,000~70,000 |
| 표준형 | 100~200줄 | 약 1,500~3,000 토큰 | 약 150,000~300,000 |
| 과다형 | 500줄 이상 | 약 7,000~10,000 토큰 | 약 700,000~1,000,000 |
※ Claude의 컨텍스트 창은 200K 토큰이다. CLAUDE.md 자체가 크다면 실제 작업에 쓸 수 있는 컨텍스트가 그만큼 줄어든다. 구독 플랜(Pro/Max)에서는 직접적인 비용보다 컨텍스트 낭비가 더 큰 문제다.
API 직접 과금 환경(Anthropic Console)에서는 토큰 비용이 실제 청구액에 반영된다. Claude Sonnet 4.5 기준 입력 토큰은 $3/1M 토큰이므로, 500줄짜리 CLAUDE.md를 하루 50세션 돌리면 월간 CLAUDE.md 로딩 비용만 $3~5 수준이다. 규모가 크다면 무시 못할 금액이다.
규칙 간 충돌 문제
규칙이 늘어날수록 서로 충돌하는 지시가 생긴다. Claude는 모순된 규칙을 받으면 자체 판단으로 하나를 택하는데, 그 선택이 항상 작성자 의도와 같지는 않다.
충돌 예시
| 규칙 A | 규칙 B | Claude의 딜레마 |
|---|---|---|
| 코드를 간결하게 작성해 | 모든 함수에 JSDoc을 넣어 | JSDoc이 길어지면 간결함이 깨짐 |
| 한국어로 주석을 작성해 | 오픈소스 기여를 위해 영어를 써 | 언어 선택 기준이 없음 |
| 함수는 30줄 이내로 | 에러 처리를 모든 케이스에 넣어 | 에러 핸들링이 줄 수를 초과시킬 수 있음 |
우선순위 부여 방법
충돌 가능성을 줄이려면 규칙에 명시적 우선순위를 붙이거나, 규칙 간 관계를 서술해야 한다.
- 명시적 우선순위:
보안 규칙은 스타일 규칙보다 항상 우선한다처럼 메타 규칙을 추가 - 조건부 규칙:
오픈소스 기여 파일에서만 영어 주석 사용, 내부 파일은 한국어처럼 맥락을 명시 - 예외 명시:
에러 처리가 필요한 경우 30줄 제한 예외 허용처럼 예외 조건을 규칙 옆에 기록
최적의 CLAUDE.md 구조
규칙의 양보다 구조가 더 중요하다. 같은 50개의 규칙도 구조화가 잘 되어 있으면 충돌이 줄고 Claude가 올바른 우선순위를 적용한다. 3단계 분리 구조를 권장한다.
- 핵심 규칙 (MUST): 반드시 지켜야 하는 것. 보안, 데이터 안전, 배포 관련. 위반 시 프로젝트에 직접 손상이 가는 규칙만 포함.
- 선호 규칙 (PREFER): 가능하면 따르지만 상황에 따라 예외 허용. 스타일, 네이밍, 주석 수준.
- 참고 정보 (CONTEXT): Claude가 프로젝트를 이해하기 위한 배경 정보. 기술 스택, 디렉토리 구조, 외부 연동 목록.
3단계 분리 구조 CLAUDE.md 예시# CLAUDE.md ## [MUST] 핵심 규칙 — 예외 없이 적용 - node --check {파일}로 JS 구문 검사 후 커밋 - .env 파일 커밋 절대 금지 - SQL 쿼리에 사용자 입력을 직접 삽입 금지 (파라미터 바인딩 사용) - 프로덕션 DB에 직접 쓰기 금지 ## [PREFER] 선호 규칙 — 가능하면 따름 - 함수 길이 30줄 이내 (에러 처리 포함 시 40줄까지 허용) - TypeScript strict 모드 유지 - 주석은 한국어 (오픈소스 파일은 영어) - 커밋 메시지: [타입]: 설명 형식 ## [CONTEXT] 프로젝트 배경 - 스택: Next.js 14 (Pages Router), Vercel, PostgreSQL - 배포: main 브랜치 push 시 Vercel 자동 배포 - 상세 규칙: RULE.md 참조 - 아키텍처: ARCHITECTURE.md 참조
규칙을 줄이는 실전 기법
CLAUDE.md를 가볍게 유지하면서 규칙의 실효성은 높이는 방법이 있다. 핵심은 CLAUDE.md를 '인덱스'로 쓰고, 세부 내용은 보조 파일로 분리하는 것이다.
보조 파일 분리
세부 규칙을 RULE.md, SKILL.md, ARCHITECTURE.md 같은 별도 파일에 두고, CLAUDE.md에서 참조하게 한다. Claude Code는 CLAUDE.md에서 지시하는 파일을 세션 시작 시 함께 읽는다.
- RULE.md: 코딩 컨벤션 세부 사항, 금지 패턴 목록
- SKILL.md: 자주 쓰는 작업 패턴, 명령어 템플릿
- ARCHITECTURE.md: 시스템 구조, 데이터 흐름, 외부 연동
사용 빈도 기준 정리
지난 1~2개월 세션을 돌아봤을 때 한 번도 연관된 적 없는 규칙은 삭제 대상이다. 규칙이 있어도 실제로 관련 작업을 안 하면 그 규칙은 토큰만 잡아먹는다.
주기적 리뷰
월 1회 CLAUDE.md를 검토해서 현재 프로젝트 상태와 맞지 않는 규칙을 정리한다. 기술 스택이 바뀌었거나 특정 패턴을 더 이상 쓰지 않는다면 관련 규칙을 제거한다.
일반 규칙보다 구체적 예시
'좋은 코드를 작성해'는 아무런 실질적 지시가 아니다. 같은 의도라면 '함수 30줄 이내, 파라미터 4개 이하, 중첩 if 3단계 이하'처럼 측정 가능한 형태로 쓰는 것이 낫다. 구체적인 규칙 10개가 모호한 규칙 50개보다 효과적이다.
결론 — 적정량을 유지하는 3가지 원칙
CLAUDE.md는 많을수록 좋은 것도, 적을수록 좋은 것도 아니다. 적절한 밀도를 유지하는 세 가지 원칙이다.
- 100~200줄을 목표 상한으로 유지한다. 이 범위 안에서 핵심 규칙, 선호 규칙, 프로젝트 배경을 모두 담을 수 있다. 이 이상이라면 보조 파일 분리를 검토한다.
- 월 1회 리뷰를 습관화한다. 프로젝트는 변한다. CLAUDE.md도 함께 변해야 한다. 오래된 규칙, 더 이상 쓰지 않는 패턴, 실제와 다른 스택 정보를 정기적으로 제거한다.
- 보조 파일을 적극 활용한다. CLAUDE.md에 모든 것을 담으려 하지 말고, 세부 규칙은 RULE.md, 작업 패턴은 SKILL.md로 분리하고 CLAUDE.md에서 참조하게 한다. Claude Code는 참조된 파일도 읽는다.
규칙을 잘 만드는 것만큼, 규칙을 잘 정리하는 것도 엔지니어링이다.