CLAUDE.md

어떻게 동작하나

Claude Code는 새 세션마다 빈 컨텍스트에서 시작합니다. CLAUDE.md는 그 컨텍스트에 처음부터 들어가는 지침입니다. 공식 문서는 이 파일을 강제 설정이 아니라 "컨텍스트"로 취급한다고 설명합니다. 지침이 구체적이고 짧을수록 더 일관되게 따릅니다.

현재 작업 폴더와 그 상위 폴더에 있는 CLAUDE.md가 시작할 때 모두 읽히고, 이어 붙여지는 방식입니다. 파일시스템 루트에서 작업 폴더 쪽으로 내려오는 순서로 배치됩니다. 하위 폴더의 CLAUDE.md는 시작할 때가 아니라, Claude가 그 폴더의 파일을 읽거나 고칠 때 불러옵니다.

• 프로젝트: ./CLAUDE.md 또는 ./.claude/CLAUDE.md (팀과 공유, 버전 관리에 포함)
• 개인 전체: ~/.claude/CLAUDE.md (모든 프로젝트에 적용)
• 개인 프로젝트용: ./CLAUDE.local.md (공식 문서는 .gitignore에 넣으라고 안내)
• 조직 정책: 운영체제별 관리자 경로에 두는 관리형 CLAUDE.md

무엇을 넣고 무엇을 빼나

공식 문서의 기준은 "매번 다시 설명하게 되는 것"입니다. Claude가 같은 실수를 두 번 했을 때, 코드 리뷰에서 코드베이스 규칙을 놓쳤다고 지적받았을 때, 지난 세션에 쓴 교정 문장을 또 쓰고 있을 때가 추가할 시점입니다.

넣을 것은 빌드·테스트 명령, 코딩 규칙, 프로젝트 구조, "항상 X를 한다" 규칙입니다. 여러 단계로 된 절차나 코드베이스 일부에만 해당하는 내용은 스킬이나 경로별 규칙(.claude/rules/)으로 옮기라고 안내합니다.

문장은 확인할 수 있을 만큼 구체적으로 씁니다. "코드를 깔끔하게 정리해" 대신 "들여쓰기는 2칸", "커밋 전에 npm test를 실행한다", "API 핸들러는 src/api/handlers/에 둔다"처럼 씁니다.

# 빌드와 테스트
- 개발 서버: npm run dev
- 커밋 전에 npm test 와 npm run lint 를 실행한다

# 규칙
- 들여쓰기는 2칸
- API 핸들러는 src/api/handlers/ 에 둔다

# 참고
See @README.md for project overview

길이와 구조

파일 하나당 200줄 이내를 목표로 하라는 것이 공식 권장입니다. 길수록 컨텍스트를 더 쓰고 지침을 덜 따릅니다. 관련 지침은 제목과 글머리표로 묶고, 서로 모순되는 지침은 정기적으로 걷어냅니다. 모순이 있으면 Claude가 임의로 하나를 고를 수 있다고 문서에 나옵니다.

@경로 문법으로 다른 파일을 가져올 수 있습니다. 상대 경로는 그 파일 기준이고, 가져온 파일이 다시 가져오는 것은 최대 4단계까지입니다. 다만 가져온 파일도 같이 컨텍스트에 올라가므로 정리용일 뿐 컨텍스트를 줄여 주지는 않습니다. 경로를 문장 안에서 그대로 언급하고 싶으면 백틱으로 감쌉니다.

블록 수준 HTML 주석(<!-- 메모 -->)은 Claude에게 주입되기 전에 제거됩니다. 사람용 메모를 토큰 걱정 없이 남길 수 있습니다.

이웃 기능과의 관계

• /init: CLAUDE.md 초안을 만들어 줍니다. 이미 파일이 있으면 덮어쓰지 않고 개선안을 제안합니다.
• /memory: CLAUDE.md와 자동 메모(auto memory)를 열어 편집하고, 자동 메모를 켜고 끕니다.
• 자동 메모: CLAUDE.md는 내가 쓰는 지침, 자동 메모는 Claude가 교정 내용에서 스스로 적는 메모입니다.
• /context: 로드된 파일은 Memory files 목록에서 확인합니다. 목록에 없으면 Claude에게 보이지 않는 것입니다.
• AGENTS.md: CLAUDE.md가 없을 때만 기본으로 읽습니다. 둘 다 쓰려면 CLAUDE.md에서 @AGENTS.md로 가져옵니다.
• /compact 이후: 프로젝트 루트의 CLAUDE.md는 디스크에서 다시 주입됩니다. 대화 중에만 말한 지침은 사라질 수 있습니다.

실제 예시

프로젝트 루트에 CLAUDE.md를 만들고 "# 빌드와 테스트 / 커밋 전에 npm test 를 실행한다"를 적은 뒤 새 세션에서 /context 실행

PR 리뷰 절차와 DB 마이그레이션 절차를 CLAUDE.md에서 빼서 스킬로 옮기고, 프론트엔드 규칙은 .claude/rules/ 아래 파일로 분리한 뒤 CLAUDE.md는 공통 규칙만 남김

프로젝트 루트에 CLAUDE.local.md를 만들어 개인 주소를 적고, .gitignore에 CLAUDE.local.md를 추가

흔한 실수와 쓰지 말아야 할 때

• 모든 것을 다 적으려는 것. 길어질수록 컨텍스트 비용이 늘고 지침 준수율은 떨어집니다. 200줄 안팎을 넘기면 스킬이나 경로별 규칙으로 쪼개세요.
• "깔끔하게", "잘" 같은 모호한 문장. 확인할 수 있는 문장으로 바꿔야 효과가 있습니다.
• CLAUDE.md를 강제 수단으로 믿는 것. 공식 문서는 컨텍스트일 뿐 강제 설정이 아니라고 말합니다. 특정 동작을 반드시 막아야 하면 PreToolUse hook이나 권한 설정을 쓰세요.
• @import로 길이 문제를 해결했다고 생각하는 것. 가져온 파일도 함께 컨텍스트에 들어갑니다.
• 프로젝트 방향이 바뀌었는데 예전 규칙을 그대로 두는 것. 서로 충돌하는 지침은 Claude가 임의로 고를 수 있습니다.

자주 묻는 질문