클로드 코드 CLAUDE.md 완벽 가이드: 3배 더 똑똑하게

클로드코드 사용법을 익혔는데도 Claude가 지시를 자꾸 무시한다면, 문제는 코드가 아니라 CLAUDE.md 파일에 있을 가능성이 높습니다. CLAUDE.md를 제대로 작성하면 Anthropic 공식 문서 기준으로 코딩 품질이 2~3배까지 올라갑니다. 이 글에서는 CLAUDE.md의 작동 원리부터 나쁜 패턴, 좋은 패턴, 그리고 Auto Memory 활용법까지 실전 중심으로 정리합니다.

 

CLAUDE.md가 뭔지 알고 계세요? 알고 쓰면 다르다

CLAUDE.md는 프로젝트마다 Claude에게 미리 알려두는 "지시서"입니다. Claude Code를 실행하면 가장 먼저 하는 일이 이 파일을 찾아 통째로 읽는 것입니다. 덕분에 매번 같은 말을 반복하지 않아도, "주석은 한국어로 달아줘"나 "새 파일 만들기 전에 먼저 확인해줘" 같은 규칙이 자동으로 적용됩니다.

 

로딩 순서를 알면 이 파일이 왜 중요한지 더 분명해집니다. Claude Code는 AI의 기본 지침인 시스템 프롬프트 다음, 사용자가 입력한 메시지보다 먼저 CLAUDE.md를 읽습니다. 사전 지시서 역할이라고 보면 됩니다.

 

그런데 여기서 많은 분들이 놓치는 게 있습니다. Anthropic 공식 문서에 따르면, CLAUDE.md는 시스템 프롬프트가 아니라 사용자 메시지로 전달됩니다. 즉 Claude가 읽고 따르려고 하지만, 모호하거나 충돌하는 지시는 엄격하게 따른다는 보장이 없습니다. 맥락이지 강제가 아닌 거죠. "분명히 써놨는데 왜 무시하지?"라는 경험이 있으셨다면, 바로 이 이유입니다.

 

파일 위치는 세 곳을 사용할 수 있습니다. 가장 흔한 건 프로젝트 루트의 CLAUDE.md 또는 .claude/CLAUDE.md이고, 모든 프로젝트에 공통 적용하고 싶다면 홈 폴더의 ~/.claude/CLAUDE.md를 활용합니다. 처음 시작할 때 /init 명령어를 쓰면 Claude가 코드베이스를 분석해서 CLAUDE.md를 자동으로 만들어 주기도 합니다.

 

Anthropic 엔지니어링 블로그에서는 이런 기술을 컨텍스트 엔지니어링이라고 부릅니다. "AI에게 이번 작업에서 알아야 할 정보를 명확히 전달하는 기술"로, CLAUDE.md는 그 출발점입니다.

 

피해야 할 CLAUDE.md 나쁜 패턴 3가지

CLAUDE.md를 만들어 놓고도 Claude가 규칙을 자꾸 어기는 경우, 대부분 아래 세 가지 패턴 중 하나에 해당합니다.

 

1. 너무 긴 파일 (300줄 이상)

Anthropic 공식 문서는 CLAUDE.md를 파일당 200줄 이하로 유지하도록 권장합니다. 파일이 길어지면 중요한 규칙이 노이즈에 묻혀버리기 때문입니다. 공식 문서에 이런 문장이 있습니다. "Claude가 특정 규칙을 계속 어긴다면, 파일이 너무 길어서 그 규칙이 묻혀 있는 것일 가능성이 높다."

 

50페이지짜리 회사 규정집과 한 장짜리 체크리스트 중 어느 쪽을 더 잘 기억하나요? Claude도 마찬가지입니다. 정말 중요한 규칙만 남기고 나머지는 과감히 삭제하는 게 답입니다.

 

2. 모호한 지시 ("깔끔하게 코딩해줘")

혹시 이런 내용을 CLAUDE.md에 써놓으신 적 있으신가요?

# 나쁜 예
깔끔한 코드를 작성해주세요.
테스트를 잘 작성해주세요.

Claude는 "깔끔한"이 정확히 무엇을 의미하는지 모릅니다. 이런 지시는 사실상 무시되는 것과 같습니다. 대신 Claude가 스스로 지켰는지 검증할 수 있는 구체적인 기준을 써야 합니다.

# 좋은 예
변수명은 camelCase를 사용해주세요.
함수 하나는 15줄 이하로 유지해주세요.
새 파일을 만들기 전에 먼저 확인해주세요.
기능 추가 후 `npm test`를 실행해서 모든 테스트가 통과하는지 확인해주세요.

전문 AI 개발 커뮤니티에서 자주 언급되는 원칙이 있습니다. "린터가 할 일을 LLM에게 시키지 말 것." 코드 스타일 가이드(들여쓰기, 따옴표 종류 등)는 실제 린터와 포매터가 훨씬 빠르고 정확하게 처리합니다. CLAUDE.md는 Claude가 추측할 수 없는 맥락, 즉 프로젝트 고유의 규칙에 집중하는 게 좋습니다.

 

3. 프로젝트가 커져도 파일 하나로 버팀

초반에는 하나의 CLAUDE.md로 잘 돌아가던 프로젝트도 규모가 커지면 달라집니다. 분명히 디렉토리 구조를 정의해 놨는데 엉뚱한 위치에 파일을 만들거나, 이미 작성한 코드를 또 쓰기 시작하면 이 신호입니다. 규칙이 늘어났으면 파일도 분리할 때가 된 겁니다. 모듈식 관리는 다음 섹션에서 자세히 다룹니다.

 

클로드 코딩 품질을 2~3배 높이는 좋은 패턴 4가지

Anthropic 공식 문서에서 "투자 대비 효과가 가장 큰 전략"으로 꼽는 것들입니다. 하나씩 적용해 보면 차이가 꽤 분명하게 느껴집니다.

 

1. 검증 가능한 규칙 작성하기

Anthropic 공식 문서에서 밝힌 가장 강력한 전략입니다. Claude가 작업 결과를 스스로 검증할 수 있는 방법을 CLAUDE.md에 써두는 것입니다. Claude Code 개발을 이끈 Boris Cherny도 이 방식을 쓸 때 최종 결과물 품질이 2~3배 향상된다고 직접 밝혔습니다.

 

차이를 보면 이해가 빠릅니다.

# 나쁜 예 (검증 불가)
테스트를 잘 작성해주세요.

# 좋은 예 (검증 가능)
IMPORTANT: 기능 추가 후 반드시 `npm test`를 실행하세요.
모든 테스트가 통과되지 않으면 코드 변경을 완료된 것으로 간주하지 마세요.
실패 시 수정 후 재실행하세요.

이렇게 하면 Claude가 구현 후 자동으로 빌드하고, 오류가 나면 스스로 고치는 루프가 돌아갑니다. 단, IMPORTANT라는 강조 표현은 진짜 중요한 1~2개에만 써야 효과가 있습니다. 모든 항목에 붙이면 효과가 사라집니다.

 

2. 비즈니스 도메인 용어 정의하기

프로젝트에서만 특별한 의미로 쓰는 단어가 있다면 반드시 CLAUDE.md에 정의해 두세요. 예를 들어 배달 앱을 만들 때 "주문 금액을 계산해줘"라고 하면, Claude가 헷갈릴 수 있습니다. "주문"이 고객이 결제하는 전체 묶음을 뜻하는지, 아니면 짜장면 1개 같은 개별 항목을 뜻하는지 맥락 없이는 알 수 없기 때문입니다.

 

## 도메인 용어 정의
- 주문(Order): 고객이 한 번에 결제하는 묶음 전체
- 주문 항목(OrderItem): 주문 안에 포함된 개별 상품 (짜장면, 탕수육 등)
- 수령자(Recipient): 실제 배달을 받는 사람 (주문자와 다를 수 있음)

본인 프로젝트에서 설명 없이 쓰면 헷갈릴 법한 단어들을 한번 떠올려보세요. 그걸 CLAUDE.md에 적어두는 것만으로 버그 하나를 예방할 수 있습니다.

 

3. 모듈식 관리: @참조와 하위 디렉토리

프로젝트가 커지면 200줄 제한이 빡빡해집니다. 이때 쓸 수 있는 방법이 모듈식 관리입니다. .claude/rules/ 디렉토리에 주제별로 파일을 나눠두면, Claude Code가 관련 파일 작업을 할 때만 해당 규칙을 로드합니다. 필요 없는 규칙으로 컨텍스트 창을 낭비하지 않는 거죠.

.claude/
├── CLAUDE.md          ← 핵심 프로젝트 컨텍스트 (200줄 이하)
└── rules/
    ├── testing.md     ← 테스트 관련 규칙
    ├── security.md    ← 보안 규칙
    └── frontend/
        └── react.md   ← React 파일 작업 시에만 로드

또한 @README.md, @package.json 같은 방식으로 프로젝트에 이미 있는 문서를 그대로 참조할 수 있습니다. 최대 5단계 중첩이 가능하고, 전체 메모리 파일 합계는 10,000 토큰 미만으로 유지하는 게 권장 기준입니다.

 

4. Boris Cherny의 황금 조언: 빈 파일로 시작하기

Claude Code 개발을 이끈 Boris Cherny가 직접 공개한 방법입니다. 처음부터 완벽한 CLAUDE.md를 쓰려고 하면 시작도 못 합니다. 그의 조언은 단순합니다. "빈 파일로 시작해서 Claude가 실수할 때마다 한 줄씩 추가한다."

 

Claude Code를 만든 사람도 처음부터 완벽하게 작성하지 않았다는 게 솔직히 좀 위안이 되지 않나요? 실제로 사용하면서 "또 이 실수를 하네"라고 느끼는 순간 한 줄을 추가하면 됩니다. 그렇게 쌓이다 보면 프로젝트에 딱 맞는 파일이 만들어집니다.

 

Auto Memory: Claude가 스스로 적는 업무 일지

Auto Memory는 최근 추가된 기능으로, 아직 잘 알려져 있지 않습니다. CLAUDE.md가 개발자가 직접 쓰는 업무 메뉴얼이라면, Auto Memory는 Claude가 스스로 적는 업무 일지입니다. "이 프로젝트는 React를 쓰는구나", "이 사용자는 한국어 주석을 선호하는구나" 같은 내용을 세션 중에 알아서 기록합니다.

 

두 가지의 차이를 정리하면 이렇습니다.

구분	CLAUDE.md	Auto Memory
작성자	개발자 직접 작성	Claude가 자동 기록
로드 범위	세션 시작 시 전체 로드	처음 200줄만 로드
저장 위치	프로젝트 루트 또는 홈 폴더	~/.claude/projects/<project>/memory/
확인 방법	직접 파일 열기	/memory 명령어

200줄이 넘으면 Claude가 자동으로 별도 파일로 분리해서 관리합니다. /compact 명령어로 컨텍스트를 압축한 뒤에도 CLAUDE.md는 디스크에서 다시 로드되기 때문에, 장기 세션에서도 안정적으로 작동합니다.

 

실용적인 팁을 하나 드리면, /memory를 주기적으로 열어서 Claude가 잘못 기억하거나 오래된 내용이 있는지 확인하고 수정해 주세요. 잘못된 기억이 쌓이면 오히려 방해가 될 수 있습니다.

 

팀에서 쓰면 더 강력해지는 CLAUDE.md 협업 전략

혼자 쓸 때도 좋지만, 팀에서 CLAUDE.md를 활용하면 효과가 배로 커집니다. 핵심은 파일을 Git에 커밋해서 팀 전체가 함께 관리하는 것입니다.

 

Boris Cherny가 팀에서 실제로 쓰는 방식은 이렇습니다. 팀원 누구든 Claude가 실수하는 걸 발견하면 CLAUDE.md에 한 줄을 추가하고 PR을 올립니다. 코드 리뷰 때 이 변경도 함께 검토하고, 머지되면 그 순간부터 팀 전원이 같은 실수를 방지할 수 있게 됩니다. "수정 내용이 영구적으로 누적된다"는 표현처럼, 복리 효과가 생깁니다.

 

혼자 개발하는 분들도 이 섹션에서 챙길 게 있습니다. .claude/settings.json에 자주 쓰는 안전한 명령어를 미리 승인해 두면 매번 확인 창이 뜨지 않습니다. 예를 들어 빌드 명령어나 테스트 실행 명령어를 사전 승인해두면 작업 흐름이 훨씬 부드러워집니다. MCP 설정을 .mcp.json에 커밋해두면 팀원 모두가 같은 환경에서 작업할 수 있습니다.

 

가끔 Claude에게 이렇게 물어보는 것도 좋은 방법입니다. "우리 CLAUDE.md 한번 리뷰해줘. 불필요한 내용이나 빠진 게 있으면 알려줘." Claude가 직접 파일을 읽고 피드백을 줍니다. 이걸 주기적으로 하면 파일이 항상 최적 상태로 유지됩니다.

 

클로드 코드 요금제: 무료로도 쓸 수 있나요?

2026년 3월 기준으로, Claude Code는 Claude Pro($20/월) 이상 플랜에서 사용 가능합니다. 무료 플랜에서는 사용할 수 없습니다. 보다 집중적으로 사용하는 분들을 위한 Claude Max($100/월, $200/월) 플랜도 있습니다. 정확한 요금은 변동될 수 있으므로 Anthropic 공식 사이트에서 최신 정보를 확인하는 것을 권장합니다.

 

비용과 CLAUDE.md는 생각보다 연결고리가 있습니다. 모호한 지시는 Claude가 결과를 맞추기 위해 여러 번 재시도하게 만들고, 그만큼 토큰을 더 씁니다. CLAUDE.md를 구체적이고 짧게 유지하는 것이 곧 비용 절감으로 이어집니다. 잘 쓴 CLAUDE.md 하나가 API 비용을 줄이는 셈입니다.

 

한눈에 보는 CLAUDE.md 작성 체크리스트

지금까지 내용을 실천 항목으로 정리했습니다. 지금 사용 중인 CLAUDE.md와 비교해 보세요.

• 파일 길이 200줄 이하 유지
• 모호한 지시 대신 Claude가 스스로 검증할 수 있는 구체적 규칙 작성
• IMPORTANT는 진짜 중요한 1~2개에만 사용
• 프로젝트 고유 도메인 용어 정의
• 규칙이 많아지면 .claude/rules/로 모듈화
• Git에 커밋해서 팀 공유 (또는 개인 히스토리 관리)
• 빈 파일로 시작, 실수할 때마다 한 줄씩 추가
• /memory 명령어로 Auto Memory 주기적 확인 및 정리
• 코드 스타일은 실제 린터/포매터에게 맡기기
• 전체 메모리 파일 합계 10,000 토큰 미만 유지

 

CLAUDE.md를 제대로 쓰는 것이 컨텍스트 엔지니어링의 첫 걸음입니다. 거창하게 시작할 필요 없습니다. 오늘 당장 CLAUDE.md를 열어서 가장 자주 Claude에게 반복하는 말 하나를 찾아 구체적인 규칙으로 다듬어 보세요. Boris Cherny의 조언처럼, 빈 파일에서 시작해 실수할 때마다 한 줄씩 추가하다 보면 어느새 프로젝트에 딱 맞는 파일이 완성됩니다.