Claude의 CLAUDE.md 사용법 완전 정리
CLAUDE.md 개념과 역할
CLAUDE.md는 Claude Code가 프로젝트를 이해하고 행동할 때 가장 먼저 참고하는 "헌법" 같은 파일이다.1
대부분의 상황에서 Claude가 코드를 읽기 전에 CLAUDE.md부터 불러오기 때문에, 이 파일에 무엇을 적어두느냐가 곧 Claude의 실력과 실수 빈도를 결정한다고 생각하면 된다.14
프로젝트별 규칙, 개발 흐름, 도구 사용법, 테스트 전략, 주의사항 같은 것을 사람에게 설명하듯 명확하게 적어두면, 매 세션마다 장황하게 설명하지 않아도 Claude가 일관된 방식으로 움직인다.
CLAUDE.md는 "전체 설명서"가 아니라 "Claude를 위한 최소 지침서 + 중요 참고 링크 모음"에 가깝게 설계하는 것이 좋다.4
CLAUDE.md가 자동으로 불리는 위치
Claude Code는 특정 경로에 있는 CLAUDE.md를 자동으로 읽어들인다.1
실제로는 다음 네 가지 레이어를 겹쳐서 쓰게 된다.
프로젝트 루트나 claude를 실행하는 디렉터리 근처에 둔 CLAUDE.md 상위 디렉터리에 있는 CLAUDE.md (모노레포 공통 규칙 등)1 하위 디렉터리의 CLAUDE.md (특정 패키지·서비스 전용 규칙)1 홈 폴더의 ~/.claude/CLAUDE.md (모든 프로젝트에 공통 적용되는 개인 규칙)1
Claude를 모노레포에서 쓸 때는 루트 CLAUDE.md에 조직 공통 규칙을 쓰고, 각 패키지 폴더에 별도의 CLAUDE.md를 두어 로컬 규칙을 정의하는 패턴이 많이 쓰인다.14
/init와 CLAUDE.md 초기 생성
기존 프로젝트에 Claude Code를 처음 붙일 때는 /init를 한 번 실행해 두는 편이 좋다.2
Claude는 현재 코드베이스를 훑어보고 기본적인 CLAUDE.md를 자동으로 생성한다.12 이 파일은 "완성본"이라기보다 초안에 가깝기 때문에, 이후 수동으로 다듬거나 Claude에게 "이 부분을 이렇게 수정해 달라"고 지시해가며 점진적으로 개선하는 것이 자연스러운 흐름이다.
이미 있는 프로젝트라면 /init로 자동 생성된 내용을 기반으로, 실제 팀 규칙과 도구, 워크플로에 맞게 정리하면서 "우리 팀 전용 CLAUDE.md"로 재구성하는 것이 좋다.2
CLAUDE.md에 어떤 내용을 넣을지
좋은 CLAUDE.md는 "Claude가 매일 헷갈리는 것"을 중심으로 작성된다.14
실무에서 자주 들어가는 내용은 대체로 다음과 같다.
프로젝트를 빌드·테스트·런칭하는 핵심 명령
코딩 스타일 규칙과 포맷터·린터 사용법
도메인·서비스별 주요 진입점 파일과 유틸리티 위치
테스트 전략과 필수로 돌려야 하는 테스트 세트
Git 브랜치 전략과 커밋·PR 규칙
보안·성능 관련 중요한 금지/주의 사항
핵심은 "Claude가 이렇게만 알고 있으면, 대부분의 작업을 스스로 계획하고 수행할 수 있다" 수준까지만 적는 것이다.4
세부적인 튜토리얼이나 장문의 설계 문서는 그대로 넣기보다, 경로와 함께 "언제 이 문서를 읽어야 하는지"를 설명하는 쪽이 좋다.4
예를 들어 다음처럼 쓰는 식이다.
복잡한 배포 시나리오나 에러 대응 절차는 docs/deploy.md에 정리되어 있다. 배포 관련 작업을 수행할 때나 배포 에러를 다룰 때 이 파일을 읽고 지침을 따른다.
CLAUDE.md 작성 스타일과 토큰 최적화
Claude.md에 무엇을 쓰느냐 못지않게, 어떻게 쓰느냐도 중요하다.14
첫째, 간결성. CLAUDE.md는 Claude의 매 요청마다 프롬프트에 포함되므로, 쓸데없이 길면 곧바로 토큰 낭비와 성능 저하로 이어진다.4 각 규칙·도구·워크플로 설명은 "핵심 문장 몇 줄 + 언제 쓰는지" 정도로 최소화하는 편이 좋다.
둘째, Guardrail 중심. 처음부터 모든 것을 설명하려 하기보다, Claude가 실제로 실수한 부분이나 반복적으로 오해한 지점부터 규칙을 추가해 나가는 방식이 효과적이다.4 실수를 발견할 때마다 "이 상황에서는 이렇게 해라"는 문장을 CLAUDE.md에 추가하며, 점진적으로 정교해지는 구조다.
셋째, "절대 하지 마라" 단독 규칙은 피하기. 예를 들어 "절대 foo-bar 플래그를 쓰지 마라"만 적어두면, Claude가 그 플래그를 사용해야 할 것처럼 느끼는 상황에서 멍해지는 경우가 있다.4 항상 "대신 무엇을 해야 하는지"를 함께 적어야 한다. 예) foo-bar 플래그 대신, 항상 foo-safe 플래그를 사용하고 필요한 옵션은 ... 로 조정한다.
넷째, 다른 문서를 그대로 인용하지 않기. 다른 마크다운 문서를 통째로 @-참조해서 매번 전체 내용을 프롬프트에 집어넣으면, 토큰 창을 금방 채워버린다.4 해당 문서를 언급하되, "언제 이 문서를 읽어야 하는지"를 명시하고, 실제 내용은 Claude가 필요할 때 직접 열어 읽도록 맡기는 쪽이 낫다.4
CLAUDE.md를 프로젝트 구조와 맞추기
CLAUDE.md는 코드 구조와 도구 구조를 단순화하는 방향으로 사용하는 것이 이상적이다.4
명령이 지나치게 복잡한 내부 CLI가 있다면, CLAUDE.md에 장문의 설명을 쓰는 대신, 사람이 쓰기 쉬운 래퍼 스크립트를 만들고 그 간단한 명령만 문서화하는 편이 좋다. 이렇게 하면 사람과 Claude 모두가 해당 스크립트를 표준 진입점으로 사용하게 되고, 도구 사용성 자체가 개선된다.4
실제 대규모 조직에서는 CLAUDE.md 안에서 각 내부 도구·CLI에게 "할당 가능한 토큰 예산"을 고려하는 식으로 관리하기도 한다.4 즉, CLAUDE.md를 짧게 유지하기 위해 각 팀이 자신의 도구를 간결하게 설명하도록 강제하는 구조를 만든다.
Claude Code 이외의 AI IDE와도 함께 쓰고 싶다면, 동일한 내용을 AGENTS.md처럼 별도의 파일로 동기화하는 패턴도 있다.4
CLAUDE.md와 컨텍스트 관리(/context, /clear)
Claude Code는 매우 큰 컨텍스트 윈도우를 가지고 있지만, 그 공간이 무한한 것은 아니다.4 CLAUDE.md가 항상 포함되고, 여기에 대화 내역, 변경된 파일 내용 등이 계속 쌓이면 언젠가 공간이 꽉 찬다.
이때 /context를 사용하면 현재 세션의 컨텍스트 사용 현황을 확인할 수 있다.4 어떤 문서·대화가 얼마만큼의 토큰을 쓰고 있는지 파악해, 어디를 정리해야 할지 감이 잡힌다.
자동 요약(/compact)에만 의존하면 요약 품질이나 보존 정보가 불투명해져, 특히 큰 작업을 할 때는 문제가 발생할 수 있다.4 많은 사용자들이 /compact 사용을 최소화하고, 대신 다음 두 가지 패턴을 쓴다.
심플 리스타트. 먼저 /clear로 대화 기록을 날리고, /catchup 같은 커스텀 명령으로 "현재 브랜치에서 변경된 파일을 다시 읽어"라고 시킨다.4 CLAUDE.md와 실제 코드만 다시 로드해 작업을 이어가는 방식이다.
문서화 후 리스타트. 복잡한 장기 작업에서는, 지금까지의 계획과 진행 상황, 남은 할 일을 하나의 .md 파일로 정리하도록 Claude에 시킨 뒤 /clear로 세션을 초기화하고, 새 세션에서 그 .md를 읽고 이어서 작업하게 한다.4 이때 CLAUDE.md는 변하지 않지만, "현재 작업 상태"는 별도의 문서로 관리되는 셈이다.
CLAUDE.md는 항상 프롬프트에 포함되므로, 컨텍스트가 부족할수록 CLAUDE.md의 중요성이 더 커진다고 볼 수 있다. "그때그때 대화 기록에 의존하기보다, CLAUDE.md를 잘 쓰고 /clear로 자주 초기화하라"는 패턴이 자연스럽게 자리 잡는다.34
CLAUDE.md와 서브에이전트·서브태스크
Claude Code에는 서브에이전트·Task/Explore 같은 기능이 있다.35
많은 사용자가 처음에는 "특화 서브에이전트"를 만들어 PythonTests, FrontendLinter 같은 역할을 분리하려 하지만, 이는 몇 가지 부작용을 만든다.5
테스트 관련 컨텍스트를 서브에이전트로만 숨겨두면, 메인 에이전트가 전체 코드를 일관되게 추론하기 어려워진다. 사람이 미리 짠 워크플로에 Claude를 끼워 맞추게 되어, 에이전트의 자율성이 떨어진다.5
대안으로 "마스터-복제(Master-Clone)" 방식이 제안된다.5 핵심 규칙과 도구 설명, 테스트 방식 등은 모두 CLAUDE.md에 두고, 메인 에이전트가 필요한 순간에 스스로 Task(...)를 호출해 자기 복제본을 띄워 병렬 작업을 진행하는 방식이다. 이렇게 하면 컨텍스트 관리 이점은 유지하면서, 전체 규칙은 여전히 하나의 CLAUDE.md에 모으는 구조를 유지할 수 있다.5
이 접근의 전제 조건은 "CLAUDE.md가 충분히 잘 설계되어 있다"는 것이다. 그래야 메인 에이전트든 복제된 태스크든, 동일한 규칙과 도구 사용법을 공유한 상태에서 움직일 수 있다.
CLAUDE.md와 권한·툴 사용 전략
Claude Code는 기본적으로 보수적인 권한 시스템을 사용해, 파일 수정·bash 실행·MCP 툴 호출 등에서 매번 승인을 요청한다.13
실무에서는 이 권한 정책도 CLAUDE.md와 함께 설계할 필요가 있다.
팀 차원에서 "항상 허용해도 되는 명령"과 "반드시 승인 받아야 하는 명령"을 합의하고, /permissions, 설정 파일(.claude/settings.json), CLI 플래그(--allowedTools, --dangerously-skip-permissions 등)를 적절히 조합한다.13 중요한 보안 규칙은 CLAUDE.md 상단에 명확히 강조해, 코드 작성 중에도 모델이 임의로 위험한 경로로 빠지지 않도록 한다.
개인 프로젝트라면 --dangerously-skip-permissions로 완전 자동 모드 "vibe coding"을 쓰는 경우도 많다.25 다만 이런 모드를 쓸수록 git으로 변경사항을 잘 쌓고, 포맷터·테스트·CI를 Hook·스크립트로 강제하는 전략이 중요해진다.4
CLAUDE.md 개선을 위한 피드백 루프
CLAUDE.md는 한 번 쓰고 끝나는 문서가 아니라, 에이전트와 함께 진화하는 문서다.14
Claude가 자주 틀리거나 헷갈리는 내용을 발견하면, 그때마다 해당 상황을 CLAUDE.md에 규칙으로 승격시키는 식으로 운영하는 것이 좋다. Claude Code는 # 키로 CLAUDE.md에 자동으로 내용을 추가하는 기능도 제공하므로, 작업 중 떠오르는 규칙을 바로 기록하는 습관을 들이면 좋다.1
Anthropic 내부 팀은 CLAUDE.md를 "프롬프트 개선기(prompt improver)"로 가끔 돌려, 문장을 더 명확하게 다듬거나 중요도 표현(IMPORTANT, YOU MUST 등)을 조정해 모델의 준수율을 높인다고 한다.1
조직 차원에서는 CLAUDE.md 변경을 일반 코드와 동일하게 PR로 관리하고 코드리뷰를 붙이는 것도 추천된다. CLAUDE.md가 바뀌면 에이전트의 행동이 바뀌므로, 사실상 "인프라 변경"과 비슷한 무게를 갖기 때문이다.4
CLAUDE.md를 잘 만들었을 때 얻는 효과
CLAUDE.md를 전략적으로 설계하고 꾸준히 다듬으면 다음과 같은 효과를 기대할 수 있다.
에이전트가 복잡한 모노레포·대형 파일에서도 더 안정적으로 코드를 수정하고, 스스로 계획을 세워 실행할 수 있다.23 새로운 팀원이 프로젝트에 합류했을 때, CLAUDE.md에 의존해 더 빠르게 온보딩할 수 있다. Slash 명령이나 서브에이전트에 과도하게 의존하지 않고, "그냥 자연어로 시키면 되는" 사용 경험을 유지할 수 있다.5 컨텍스트 관리(/context, /clear, /catchup 등)와 결합해, 긴 세션에서도 에이전트의 집중력을 유지할 수 있다.4
결국 CLAUDE.md는 "문서"이자 "시스템 프롬프트"이자 "조직의 개발 문화 스냅샷"이다. Claude Code를 단순한 자동완성 도구가 아니라 "실제 개발 파트너"로 쓰고 싶다면, 코드만큼이나 CLAUDE.md 설계에 시간을 투자할 가치가 충분하다.24
참고
2Cooking with Claude Code: The Complete Guide
3How I use Claude Code (+ my best tips)