저는 수십 가지의 Claude Code 구성을 테스트했습니다.
실제로 결과물을 바꾼 유일한 것은 CLAUDE.md 라는 60줄짜리 파일이었습니다.
이 글을 북마크해두세요 🔖
작동 방식, 대부분의 사람들이 완전히 놓치는 이유, 그리고 오늘 바로 복사할 수 있는 전체 템플릿을 알려드립니다.
아무도 알려주지 않는 Claude Code의 진실
첫 프롬프트 전에. 코드 한 줄도 작성하기 전에. 세션에서 어떤 일이 일어나기도 전에.
Claude는 단 하나의 파일을 읽습니다. 오직 하나만.
CLAUDE.md.
그리고 이 파일을 전체 세션 내내 절대적인 진리로 취급합니다. 제안이 아닙니다. 여러 컨텍스트 중 하나도 아닙니다. 앞으로 내릴 모든 결정의 틀을 잡는 결정적인 브리핑입니다.
그래서 이 파일이 전체 Claude Code 스택에서 가장 과소평가된 변수인 이유입니다.
대부분의 사람들은 이 파일을 전혀 가지고 있지 않습니다. 가지고 있는 사람들도 두 가지 실수 중 하나를 저지릅니다: 파일에 내용이 전혀 없거나, "단계별로 생각하는 경험 많은 시니어 엔지니어가 되어라"라는 내용이 300줄이나 적혀 있는 경우입니다.
둘 다 쓸모없습니다. 각각 다른 이유로.
대부분의 CLAUDE.md 파일이 작동하지 않는 이유: 실제 3가지 이유
이유 1: 너무 길다
Claude는 세션당 약 150~200개의 지침을 안정적으로 따를 수 있습니다. 이는 구조적 제약이지, 의지의 문제가 아닙니다.
문제: Claude Code의 내부 시스템 프롬프트에는 이미 약 50개의 지침이 포함되어 있습니다. 즉, Claude가 지침을 놓치기 시작하기 전까지 실제로 CLAUDE.md 에 사용할 수 있는 슬롯은 100~150개입니다.
파일이 200줄이라면, Claude는 의도적으로 규칙을 무시하는 것이 아닙니다. 기계적으로 잊어버리는 것입니다. 순응 문제가 아니라 주의 예산 문제입니다.
이유 2: 콘텐츠가 나쁘다
대부분의 CLAUDE.md 파일은 Claude가 스스로 추론할 수 있거나 행동을 측정 가능한 방식으로 바꾸지 않는 내용으로 가득 차 있습니다.
"시니어 엔지니어처럼 행동하라." → Claude는 이미 그 의미를 알고 있으며 특정 행동을 고정하지 않습니다. "단계별로 생각하라." → 그것은 이미 학습된 내용입니다. 한 줄을 낭비하는 것입니다. "깨끗하고 유지보수 가능한 코드를 작성하라." → 구체적인 기준이 없습니다. Claude는 여러분의 특정 맥락에서 "깨끗함"이 무엇을 의미하는지 모릅니다.
특정하고 구체적인 오류를 방지하지 못하는 모든 줄은 실제로 중요한 지침에서 도난당한 줄입니다. 테스트는 간단합니다: 이 줄을 삭제하면 Claude가 특정한 실수를 할까요? 대답이 '아니오'라면 그 줄은 있으면 안 됩니다.
이유 3: 계층 구조가 전혀 없다
대부분의 사람들은 Claude Code에 세 가지 수준의 지침이 있다는 것을 무시하고 모든 것을 같은 곳에 밀어 넣습니다.
~/.claude/CLAUDE.md → 글로벌 (모든 프로젝트에 적용)
.claude/CLAUDE.md → 프로젝트 (팀과 공유, git에 포함)
./CLAUDE.local.md → 로컬 (개인 오버라이드, gitignore)
글로벌 수준은 모든 프로젝트에서 반복할 규칙을 위한 것입니다. 프로젝트 수준은 스택과 팀에 특화된 컨텍스트를 위한 것입니다. 로컬 수준은 공유할 필요가 없는 개인적 선호도를 위한 것입니다.
세 수준을 올바르게 사용하는 것이 각 파일을 짧고, 집중적이며, 진정으로 효과적으로 유지하는 방법입니다. 모든 것을 하나의 파일에 넣는 것은 중요한 규칙을 잡음 아래에 빠뜨리는 깔때기를 만드는 것과 같습니다.
효과적인 CLAUDE.md를 구성하는 5가지 섹션
프로덕션 환경의 수십 개 CLAUDE.md 파일(오픈소스 프로젝트, 공식 Anthropic 문서, 커뮤니티 모범 사례 저장소)을 샅샅이 조사한 후, 효과적인 모든 파일이 공통으로 가지고 있는 5가지 섹션은 다음과 같습니다:
섹션 1: 중요 명령어
Claude는 매 세션마다 프로젝트를 빌드하는 방법, 테스트를 실행하는 방법, 린트 오류를 수정하는 방법을 모른 채 시작합니다. 추측할 것입니다. 그리고 그 추측은 여러분의 턴을 소모하게 만듭니다.
정확히 무엇을 입력해야 하는지 알려주세요:
Commands
- Build:
npm run build - Dev:
npm run dev - Test single file:
npm test -- path/to/file - Full test:
npm test - Lint + fix:
npm run lint:fix - Type check:
npx tsc --noEmit
짧고, 정확하며, 직접 사용할 수 있습니다.
이 섹션이 없으면, 프로젝트가 pnpm vitest로 실행되는데 Claude는 npm test를 시도할 것입니다. 절대 작동하지 않을 명령어 문제를 디버깅하는 데 세 턴을 소비하게 됩니다. 실제 작업에 사용할 수 있었던 세 턴을 말입니다.
섹션 2: 아키텍처 맵
Claude는 매 세션마다 코드베이스에 대한 지식이 전혀 없는 상태로 시작합니다. 전혀요. 비즈니스 로직이 어디에 있는지 모릅니다. 컴포넌트가 상태 비저장(stateless)이어야 하는지 모릅니다. API 라우트에 비즈니스 로직이 포함되어서는 안 된다는 것을 모릅니다.
맵을 제공하세요:
Architecture
- src/lib/services/ → 모든 비즈니스 로직
- src/components/ → 상태 비저장 UI 컴포넌트만
- src/lib/store/ → 전역 상태 (Zustand)
- src/app/api/ → API 라우트, 여기에는 비즈니스 로직 없음
- DB 접근은 Server Actions 또는 API 라우트를 통해서만
트리 구조의 전체 목록이 아닙니다. Claude가 무엇이 어디에 있는지, 그리고 더 중요하게는 어디에 있어서는 안 되는지 알 수 있을 정도면 충분합니다.
이 차이... 어디에 있는지 vs. 어디에 없어야 하는지...가 가장 빈번한 아키텍처 오류를 방지합니다.
섹션 3: 하드 규칙
이것은 전체 파일에서 가장 중요한 섹션입니다. 예외 없습니다.
여기의 모든 규칙은 단 하나의 질문에 답해야 합니다: "이 줄을 삭제하면 Claude가 구체적인 오류를 만들까요?"
예 → 규칙 유지. 아니오 → 거기에 있을 필요가 없습니다.
가치 있는 규칙의 예:
Rules
- 절대 .env 파일이나 시크릿을 커밋하지 마세요
- 모든 비동기 호출은 try/catch로 감싸야 함
- 함수형 컴포넌트만 사용, 클래스 컴포넌트는 제로
- 필수 커밋 접두사: feat:, fix:, docs:, refactor:
- 모든 PR은 머지 전에
npm run verify를 통과해야 함 - 정적 내보내기만, SSR 금지 (S3에 배포)
- 중요: 모든 코드 수정 후 타입 체크를 실행하세요
이 목록에 대해 주목할 두 가지 사항이 있습니다.
첫째, 부정적인 규칙은 긍정적인 규칙만큼 중요합니다. "절대 .env 파일을 커밋하지 마세요"는 Claude가 그렇게 하는 날까지는 당연해 보이는 규칙입니다. 넣어두세요.
둘째, 중요 또는 반드시와 같은 강조 표시는 실제로 효과가 있습니다.
이는 일화가 아닙니다. Anthropic이 자체 문서에서 확인했습니다: 규칙 앞에 중요 또는 반드시를 추가하면 Claude가 해당 규칙을 따르는 것이 측정 가능하게 개선됩니다.
아껴서 사용하세요: 무시했을 때 가장 심각한 결과를 초래하는 규칙을 위해 남겨두세요.
이 섹션의 규칙은 15개 미만으로 유지하세요. 그 이상이면 중요한 규칙에 대한 주의가 분산됩니다.
섹션 4: 워크플로우 선호도
이런 경험 해보셨을 겁니다. Claude에게 한 줄만 고쳐달라고 했는데, 세 개의 파일을 다시 쓰고, 함수 이름을 바꾸고, 요청과 전혀 상관없는 클래스를 리팩터링합니다.
이 섹션이 그런 일을 방지합니다:
Workflow
- 복잡한 작업을 시작하기 전에 명확하게 질문하세요
- 최소한의 변경만 하고, 관련 없는 코드는 리팩터링하지 마세요
- 모든 변경 후 테스트를 실행하고, 실패를 고친 후 계속 진행하세요
- 논리적 변경마다 별도의 커밋을 만들고, 하나의 거대한 커밋은 만들지 마세요
- 두 가지 접근 방식 사이에 불확실성이 있다면, 둘 다 설명하고 제가 선택하도록 하세요
여기의 모든 줄은 구체적인 고통 지점을 해결합니다. 47개 파일의 거대한 커밋. 요청하지 않은 완전한 재작성. Claude가 물어봤어야 할 때 혼자 내리는 아키텍처 결정.
섹션 5: CLAUDE.md에 넣지 말아야 할 것
이 섹션은 다른 섹션만큼 중요합니다. 어쩌면 더 중요할 수도 있습니다.
넣지 마세요:
- 성격 지침 ("시니어 엔지니어가 되어라")
- 린터가 이미 처리하는 포맷팅 규칙
- 모든 세션에 전체 문서를 가져오는 @ 임포트
- 중복 규칙 (글로벌이 "테스트 실행"이라고 하면 프로젝트에서 반복하지 않음)
- Claude가 자동 메모리를 통해 스스로 학습하는 모든 것
마지막 점은 널리 과소평가되고 있습니다.
Claude는 ~/.claude/projects/<project>/memory/에 자체 노트를 유지합니다. 세션에서 /memory를 실행하여 프로젝트에 대해 이미 학습한 내용을 확인하세요. 몇 번의 세션 후에는 Claude가 수동으로 CLAUDE.md 에 작성하려고 했던 정보를 이미 포착했다는 것을 종종 알게 될 것입니다.
Claude가 스스로 기억한 것에 제한된 지침을 낭비하지 마세요.
60줄 미만의 완전한 템플릿, 바로 사용 가능
프로젝트에 해당하지 않는 섹션은 삭제하세요. 모든 것을 채우는 것이 목표가 아닙니다. Claude의 행동을 측정 가능한 방식으로 바꾸는 것만 유지하는 것이 목표입니다.
결과물에 가장 큰 영향을 미친 줄: 구체적인 결과
수십 가지 구성을 테스트한 후, 가장 가시적인 차이를 만든 다섯 줄은 다음과 같습니다:
중요: 모든 코드 수정 후 타입 체크 실행 → Claude가 명시적으로 확인하라는 프롬프트 없이는 감지하지 못하는 타입이 깨진 코드를 전달하는 것을 방지합니다.
최소한의 변경만 하고, 관련 없는 코드는 리팩터링하지 마세요 → 완전하고 요청되지 않은 파일 재작성을 방지합니다.
논리적 변경마다 별도의 커밋을 만들고, 하나의 거대한 커밋은 만들지 마세요 → 47개 파일이 섞인 읽을 수 없는 괴물 커밋을 방지합니다.
두 가지 접근 방식 사이에 불확실성이 있다면, 둘 다 설명하고 제가 선택하도록 하세요 → Claude가 혼자서 내렸어야 할 아키텍처 결정을 내리는 것을 방지합니다.
정적 내보내기만, SSR 금지 → S3에 정적으로 배포된 프로젝트에 Claude가 서버 코드를 추가하는 것을 방지합니다.
이 다섯 줄의 공통점: 각각은 디버그 시간에 특정하고 빈번하며 비용이 많이 드는 오류를 방지합니다.
이것이 CLAUDE.md 의 모든 줄에 대한 궁극적인 테스트입니다.
근본적인 오류와 그렇게 널리 퍼진 이유
사람들은 자신의 CLAUDE.md 를 소원 목록이나 성격 프롬프트처럼 취급합니다.
"시니어가 되어라." "철저해져라." "전문가처럼 생각하라."
이것은 브리핑이 아닙니다. 마법적인 사고입니다.
CLAUDE.md 는 동기 부여 연설이 아닌 기술 문서여야 합니다. 스택, 명령어, 아키텍처, 구체적인 규칙, 워크플로우. 다른 모든 것은 실제로 중요한 지침과 경쟁하는 잡음입니다.
파일을 80줄 미만으로 유지하세요. Claude가 예방할 수 있었던 오류를 만들 때마다 수정하세요.
그리고 무엇보다도: 이 파일이 시간이 지남에 따라 무엇이 되는지 이해하세요.
첫 달에 좋은 CLAUDE.md 는 매 세션마다 시간을 절약해 줍니다. 세 번째 달이 되면 규칙과 스택을 충분히 정확하게 포착하여 Claude가 거의 팀원처럼 작업하게 됩니다.
여섯 번째 달이 되면 이 프로젝트에서 Claude가 저지른 모든 오류를 포함하고 자동으로 방지합니다.
파일은 축적됩니다. 모든 수정과 함께 개선됩니다. 점차 여러분이 작성한 최고의 온보딩 브리핑이 됩니다.
Claude를 위한 것이 아닙니다. 여러분을 위한 것입니다.
