CoreCode 제대로 쓰기

CLAUDE.md 작성법

최종 업데이트: 2026년 10월 27일

CLAUDE.md는 Claude Code가 세션을 시작할 때마다 읽는 프로젝트 브리핑입니다. 잘 쓰면 Claude가 같은 실수를 반복하지 않고, 길고 어수선하면 매 턴 컨텍스트를 낭비합니다. 이 페이지는 Anthropic의 공식 가이드를 따르며, 요금에 미치는 영향도 함께 다룹니다.

CLAUDE.md란

이 프로젝트에서 Claude가 알아야 할 내용을 적은 평범한 Markdown 파일입니다. 빌드와 테스트 방법, 코드 컨벤션, 구조, "항상 X를 하라" 같은 규칙이 들어갑니다. Claude Code는 세션을 시작할 때마다 이 파일을 컨텍스트로 읽습니다.

강제 설정은 아닙니다. 규칙이 구체적이고 간결할수록 Claude가 일관되게 따릅니다. 보호된 디렉터리를 수정하는 것처럼 절대 일어나면 안 되는 일에는 PreToolUse 훅을 쓰세요.

Claude Code에는 자동 메모리도 있습니다. 사용자가 준 교정 내용은 ~/.claude/projects/<project>/memory/에 저장됩니다. CLAUDE.md에는 사용자가 쓴 규칙이, 자동 메모리에는 Claude가 배운 내용이 들어가며, 둘 다 매 세션 로드됩니다.

어디에 두나

Claude Code는 시작할 때 작업 디렉터리와 그 위의 모든 디렉터리에서 CLAUDE.md를 읽어 위에서 아래로 이어 붙입니다. 그래서 시작한 위치에 가장 가까운 파일이 마지막에 읽힙니다. 하위 디렉터리의 CLAUDE.md는 Claude가 그 하위 디렉터리의 파일을 읽거나 수정할 때 나중에 로드됩니다.

시작하는 법

프로젝트에서 /init을 실행하세요. Claude가 코드베이스를 분석해 찾아낸 빌드 명령, 테스트 방법, 컨벤션을 담은 CLAUDE.md를 만들어 줍니다. 이미 있으면 덮어쓰지 않고 개선안을 제안합니다. 그다음 Claude가 스스로 알아낼 수 없던 내용을 덧붙이세요.

무엇을 담을까

매번 다시 설명하게 될 내용을 적어 두는 곳이라고 생각하세요. 다음 경우에 한 줄을 추가합니다.

• Claude가 같은 실수를 두 번째 반복했을 때
• 코드 리뷰에서 Claude가 알았어야 할 컨벤션이 지적되었을 때
• 지난 세션에서 입력한 것과 같은 교정을 또 입력하고 있을 때
• 새 팀원도 같은 컨텍스트가 필요할 때

모든 세션에 필요한 사실만 담으세요. 여러 단계로 된 절차는 필요할 때 로드되는 스킬로 쓰고, 코드베이스 한 부분에 대한 규칙은 .claude/rules에 두세요.

효과 있는 규칙 쓰는 법

막연한 바람이 아니라 확인할 수 있는 규칙을 쓰세요.

• 짧게. CLAUDE.md 하나는 200줄 이내로 유지하세요. 길어지면 컨텍스트를 더 쓰고 규칙이 덜 지켜집니다.
• 구조적으로. 관련 규칙은 제목 아래 글머리 기호로 묶고, 빽빽한 문단으로 쓰지 마세요.
• 일관되게. 두 규칙이 충돌하면 Claude는 어느 쪽이든 고를 수 있습니다. 오래된 항목은 정리하세요. Claude Code v2.1.283부터 /doctor prompt-audit가 오래되었거나 충돌하는 항목, 존재하지 않는 파일에 대한 참조를 찾아 줍니다.
• 사람을 위한 메모는 HTML 주석으로. CLAUDE.md의 <!-- note -->는 컨텍스트에 들어가기 전에 제거되므로 토큰이 들지 않습니다.

짧은 예시입니다.

# Project

## Commands
- Install: pnpm install (not npm)
- Test: pnpm test, must pass before committing
- Run locally: pnpm dev, port 3000

## Conventions
- TypeScript strict mode, no any
- API handlers in src/api/handlers/, one route per file
- Schema changes only through prisma migrate

다른 파일 가져오기

@path로 다른 파일을 가져올 수 있습니다. 예: See @README and @docs/git-instructions.md. 상대 경로는 그것을 포함한 CLAUDE.md를 기준으로 해석되며, 가져오기는 최대 4단계까지 중첩됩니다. 백틱 안의 `@README`는 가져오지 않습니다.

가져오기는 파일을 정리해 줄 뿐 컨텍스트 비용을 줄이지는 않습니다. 가져온 내용도 매번 로드됩니다. 프로젝트가 자기 디렉터리 밖의 파일을 처음 가져올 때 Claude Code가 승인을 요청합니다.

.claude/rules로 범위별 분리

큰 프로젝트에서는 지침을 .claude/rules/ 아래의 testing.md, api-design.md 같은 주제별 파일로 나누세요. paths가 없는 규칙은 CLAUDE.md처럼 시작할 때 로드되고, paths가 있는 규칙은 Claude가 일치하는 파일을 다룰 때만 로드됩니다.

---
paths:
  - "src/api/**/*.ts"
---
# API rules
- Validate every endpoint's input
- Return errors as ApiError

CLAUDE.md의 한 섹션이 여러 단계의 절차로 커졌다면 스킬로 만들 수 있습니다. 스킬은 사용할 때만 로드됩니다. 스킬 가이드를 참고하세요.

이미 AGENTS.md가 있다면

Claude Code v2.1.277부터 Claude는 AGENTS.md를 직접 읽습니다. CLAUDE.md가 없으면 AGENTS.md를 읽고, 있으면 CLAUDE.md만 읽습니다. 여러 코딩 도구가 한 파일을 공유하게 하려면 CLAUDE.md에 @AGENTS.md 한 줄을 추가하세요.

비용과 캐시

• 매 턴 전송됩니다. CLAUDE.md, 자동 메모리, paths가 없는 규칙은 모든 요청과 함께 나갑니다. 캐시 적중 시에는 캐시 읽기 가격이 들지만, 길수록 미스가 났을 때 다시 쓰는 비용이 커집니다. 짧게 유지해야 할 또 하나의 이유입니다.
• 세션 도중의 수정은 나중에 반영됩니다. 실행 중인 세션은 /clear, /compact 또는 재시작 전까지 수정된 CLAUDE.md를 보지 못합니다(Anthropic의 Claude Code 캐싱 가이드 참고). 그 대신 수정해도 세션의 캐시가 무효화되지 않습니다.

더 절약하는 방법은 Claude Code 비용 절감 가이드에 있습니다.

로드되었는지 확인하는 법

• /context를 실행해 Memory files 아래를 보세요. 거기 없는 파일은 Claude에게 보이지 않습니다.
• /memory는 각 CLAUDE.md를 나열하고 열고 편집하며, 자동 메모리를 켜고 끕니다.

FAQ