CLAUDE.md는 Claude Code가 프로젝트를 이해할 때 먼저 읽는 핵심 메모리 파일입니다. 이 문서가 잘 설계되면 세션이 바뀌어도 팀 규칙, 기술 스택, 도메인 개념을 일관되게 적용할 수 있고, 반대로 길고 모호하게 작성하면 응답 품질과 토큰 효율이 함께 떨어집니다.
핵심은 모든 정보를 한곳에 몰아넣는 것이 아니라, 항상 필요한 규칙만 상단에 두고 상세 내용은 다른 문서로 분리하는 것입니다. 또한 CLAUDE.md vs AGENTS.md의 차이, 길이 관리, 토큰 관리, 팀 운영 프로세스까지 함께 설계해야 실제 업무에서 효과가 납니다.
목차
- CLAUDE.md란 무엇인가
- Claude Code 메모리 구조 이해하기
- 프로젝트 컨텍스트 설계 전략
- 잘 만든 CLAUDE.md와 잘못 만든 CLAUDE.md 비교
- CLAUDE.md vs AGENTS.md
- CLAUDE.md 길이 관리 전략
- CLAUDE.md 토큰 관리 실무 가이드
- 팀 프로세스에 녹여 넣는 방법
- 핵심 정리와 실천 체크리스트
- 자주 묻는 질문
본문
1. CLAUDE.md란 무엇인가
CLAUDE.md란 Claude Code가 프로젝트를 이해할 때 항상 먼저 읽는 핵심 메모리 파일입니다. 단순한 README가 아니라, 시스템 프롬프트에 가까운 역할 정의, 팀 개발 규칙, 프로젝트 개요, 도메인 지식을 한데 모은 운영 기준 문서라고 보는 편이 정확합니다.
쉽게 말해 새 팀원이 합류했을 때 맨 먼저 설명해 주는 내용을 Claude Code에게도 같은 방식으로 제공하는 문서입니다. 그래서 이 파일이 있으면 세션이 바뀌어도 기술 스택, 금지 규칙, 답변 기준이 더 안정적으로 유지됩니다.
CLAUDE.md는 Claude Code가 프로젝트를 이해할 때 먼저 읽는, 프로젝트 지침과 컨텍스트를 담은 핵심 메모리 파일입니다.
README가 사람을 위한 안내서라면, CLAUDE.md는 Claude Code를 위한 운영 기준서에 가깝습니다. 이 차이를 이해해야 프로젝트 컨텍스트를 왜 별도 설계해야 하는지 명확해집니다.
- 프로젝트 목적과 핵심 기능
- 코딩 스타일, 테스트 규칙, 금지 라이브러리
- 도메인 용어와 상태값 의미
- Claude Code가 맡아야 할 역할과 우선순위
2. Claude Code 메모리 구조 이해하기
Claude Code 메모리 구조를 이해해야 CLAUDE.md에 어디까지 써야 할지 판단할 수 있습니다. 많은 팀이 실패하는 이유는 모든 정보를 한 파일에 다 넣으려 하기 때문입니다. 하지만 실제로는 프로젝트 컨텍스트와 대화 세션 컨텍스트가 함께 작동합니다.
핵심은 레포 전체가 지식 베이스라는 점입니다. 코드, 설정 파일, 문서, 스키마, README, 설계 문서가 모두 컨텍스트가 되며, 그중 CLAUDE.md는 상위 우선순위를 정하는 문서로 작동합니다.
- 프로젝트 컨텍스트: 코드, 문서, 설정,
CLAUDE.md - 대화 세션 컨텍스트: 현재 요청, 최근 수정 흐름, TODO
- 자동 메모리/요약: 긴 세션을 보조하는 환경별 요약 정보
따라서 좋은 프로젝트 컨텍스트는 한 파일짜리 백과사전이 아닙니다. 루트 규칙은 루트에, 서비스별 규칙은 하위 디렉터리에, 세부 내용은 개별 문서에 나눠 두는 계층형 설계가 가장 효율적입니다.
3. 프로젝트 컨텍스트 설계 전략
좋은 프로젝트 컨텍스트는 많은 정보를 담는 문서가 아니라, 자주 필요한 기준을 빠르게 찾게 해주는 문서입니다. 특히 CLAUDE.md는 시작점이므로 항상 필요한 정보만 남겨야 합니다.
실무에서는 다음 다섯 가지를 요약 형태로 넣는 것이 가장 효과적입니다.
- 비즈니스 목표와 제품의 핵심 가치
- 도메인 개념과 용어 정의
- 아키텍처 개요와 데이터 흐름
- 기술 스택과 패키지 매니저
- 팀 코딩 규칙과 금지사항
기준은 단순합니다. 어떤 작업을 하든 알아야 하는가? 그렇다면 CLAUDE.md에 두고, 아니라면 별도 문서로 분리합니다. 예를 들어 긴 API 스펙, 회의록, 대량 예시 코드는 외부 문서로 넘기고 경로만 남기는 편이 훨씬 좋습니다.
짧게 쓰되, 찾아갈 길은 정확히 남기는 것. 이것이 좋은 프로젝트 컨텍스트 설계의 핵심입니다.
관련 문서로 연결할 때는 파일 포인터를 명확히 적어두면 좋습니다. 예를 들어 docs/api-guidelines.md, schemas/user.yml, backend/src/models/User.ts 같은 식입니다.
4. 잘 만든 CLAUDE.md와 잘못 만든 CLAUDE.md 비교
잘 만든 CLAUDE.md는 Claude Code가 바로 행동할 수 있도록 씁니다. 반대로 잘못 만든 CLAUDE.md는 길고 장황하지만 실제 판단 기준이 없어 응답 품질을 떨어뜨립니다.
좋은 문서의 특징은 다음과 같습니다.
- 구조가 분명하다: Overview, Stack, Domain, Don’ts, References
- 규칙이 행동 가능하다: “SWR만 사용”, “모든 명령은 pnpm 사용”
- 상세 정보는 외부 문서로 분리한다
- 담당자와 리뷰 주기가 있어 유지보수가 가능하다
반대로 나쁜 문서는 이런 안티 패턴을 보입니다.
- API 스펙 전체를 복붙해 핵심 규칙이 묻힘
- “깔끔하게 짜주세요”처럼 기준이 모호함
- 서로 충돌하는 규칙이 동시에 존재함
- 프로젝트 특화 정보 없이 너무 일반적인 지시만 있음
길다고 좋은 문서가 아니고, 짧다고 약한 문서도 아닙니다. 실제로는 짧지만 기준이 선명한 문서가 더 강합니다.
5. CLAUDE.md vs AGENTS.md
CLAUDE.md vs AGENTS.md는 비슷해 보이지만 목적이 다를 수 있습니다. 핵심만 정리하면, Claude Code 중심 팀이라면 CLAUDE.md가 우선이며, 여러 AI 도구를 함께 쓰는 조직이라면 AGENTS.md를 공통 기준 문서로 둘 수 있습니다.
- CLAUDE.md: Claude Code 전용 프로젝트 컨텍스트
- AGENTS.md: 여러 에이전트가 공유하는 일반 컨텍스트
운영 기준은 단순합니다. 한 도구만 쓰면 단순하게, 여러 도구를 쓰면 공통 규칙과 프로필을 분리합니다. 이때 중요한 것은 중복을 피하는 것입니다. 규칙이 두 문서에 흩어지면 충돌이 생기고 관리 비용도 올라갑니다.
관련 개념을 더 넓게 보고 싶다면 Claude의 공식 문서나 팀 내부 가이드 링크를 함께 배치하는 것이 좋습니다. 예를 들어 Anthropic 관련 참고 링크를 별도 레퍼런스로 둘 수 있습니다.
6. CLAUDE.md 길이 관리 전략
CLAUDE.md 길이 관리는 단순한 문서 미관 문제가 아닙니다. 이 파일은 Claude Code가 매 세션마다 읽는 고정 컨텍스트이기 때문에, 길어질수록 비용과 혼선이 함께 커집니다.
너무 긴 문서는 중요한 규칙보다 덜 중요한 설명에 더 많은 공간을 내주게 됩니다. 결국 규칙의 우선순위가 흐려지고, 응답 품질도 흔들릴 수 있습니다.
- 항상 필요한 정보만 남긴다
- 상세 설명은 외부 문서로 분리한다
- README와 중복되는 내용을 반복하지 않는다
- 중요도 높은 규칙을 문서 상단에 둔다
실무에서는 설치 방법, 배포 절차, 긴 예시 코드를 모두 넣고 싶어지지만, 그런 정보는 대개 다른 문서에 더 잘 어울립니다. CLAUDE.md에는 한 줄 요약과 파일 경로만 남기는 편이 훨씬 효과적입니다.
7. CLAUDE.md 토큰 관리 실무 가이드
CLAUDE.md 토큰 관리는 길이 관리의 실무 버전입니다. 토큰은 모델이 텍스트를 처리하는 기본 단위이며, 이 파일은 매 세션마다 포함되므로 불필요한 문장은 일회성 낭비가 아니라 반복 비용이 됩니다.
따라서 토큰 관점에서는 핵심 규칙이 먼저 살아남도록 문서를 압축해야 합니다.
- 군더더기 없는 명령형 문장 사용
- 반복되는 규칙은 표나 목록으로 압축
- 예시 코드는 최소한만 유지
- 프로젝트 역사, 회의록, 장문 배경 설명은 분리
예를 들어 가능하면 pnpm을 사용하는 것을 권장합니다보다 모든 명령은 pnpm 사용이 더 짧고 명확합니다. 이런 작은 문장 교정이 쌓이면 토큰 효율 차이가 커집니다.
실무에서는 대략 3k~5k 토큰 안쪽을 상한으로 의식해 관리하는 팀이 많습니다. 절대값 자체보다도, 상한을 정하고 넘치면 분리하는 습관이 중요합니다.
8. 팀 프로세스에 녹여 넣는 방법
좋은 문서도 운영되지 않으면 빠르게 낡습니다. 그래서 CLAUDE.md란 무엇인가를 문서 정의로만 끝내지 말고, 팀 프로세스 안에 넣어야 합니다. 그래야 프로젝트 컨텍스트가 살아 있는 기준 문서가 됩니다.
- 신규 프로젝트 템플릿에
CLAUDE.md를 기본 포함 - 온보딩 문서에 읽는 순서와 수정 원칙 추가
- PR 템플릿에 “CLAUDE.md 업데이트 필요 여부” 체크박스 추가
- 분기별 또는 주요 릴리스 전 리뷰 일정 운영
- 문서 오너를 명시해 책임 소재를 분명히 함
실무 템플릿은 아래 정도로 시작하면 충분합니다.
- Project Overview
- Your Role
- Coding Guidelines
- Domain Knowledge
- Non-goals & Don’ts
- References
9. 핵심 정리와 실천 체크리스트
정리하면 CLAUDE.md란 Claude Code가 먼저 읽는 루트 프로젝트 컨텍스트 파일입니다. 이 문서는 프로젝트의 역할 정의, 개발 규칙, 도메인 지식, 금지사항을 짧고 선명하게 정리해 반복 설명을 줄이고 응답 품질을 높이는 데 목적이 있습니다.
특히 Claude Code 메모리 구조, CLAUDE.md vs AGENTS.md, CLAUDE.md 길이 관리, CLAUDE.md 토큰 관리를 함께 이해해야 실제 팀 운영에서 효과가 납니다.
지금 가장 중요한 일은 완벽한 문서를 만드는 것이 아니라, 최소 버전을 만들고 지속적으로 다듬는 것입니다.
- 현재 레포에
CLAUDE.md가 있는지 확인한다 - 없다면 최소 템플릿부터 만든다
- 회의록과 장문 요구사항 복붙이 있는지 점검한다
- README와 중복되는 내용을 제거한다
- 핵심 규칙과 도메인 정보를 문서 상단에 배치한다
자주 묻는 질문 (FAQ)
Q1. CLAUDE.md는 README와 무엇이 다른가요?
README는 사람을 위한 프로젝트 안내서에 가깝고, CLAUDE.md는 Claude Code가 먼저 읽는 운영 기준 문서에 가깝습니다. 즉, 설치법이나 소개보다 역할, 규칙, 도메인 지식, 금지사항이 더 중요합니다.
Q2. CLAUDE.md에는 얼마나 많은 내용을 넣어야 하나요?
원칙은 간단합니다. 어떤 작업을 하든 항상 필요한 정보만 넣어야 합니다. 긴 API 문서, 회의록, 요구사항 원문은 별도 문서로 분리하고 경로만 남기는 편이 좋습니다.
Q3. CLAUDE.md와 AGENTS.md를 함께 써도 되나요?
가능합니다. 다만 문서가 둘 이상일수록 중복과 충돌 위험이 커집니다. Claude Code만 쓴다면 CLAUDE.md 하나로 단순하게 운영하는 편이 낫고, 여러 에이전트를 쓰는 조직이라면 AGENTS.md를 공통 문서로 두는 전략이 유효합니다.
이 문서는 매 세션마다 읽히는 고정 컨텍스트이기 때문입니다. 길어질수록 토큰 비용이 커지고, 중요한 규칙보다 덜 중요한 설명이 더 많은 자리를 차지해 우선순위 판단이 흐려질 수 있습니다.
Q5. 처음 만드는 팀은 어떻게 시작하는 것이 좋을까요?
처음부터 완벽하게 만들려고 하지 말고, 프로젝트 개요, 역할, 핵심 코딩 규칙, 도메인 용어, 금지사항, 참고 링크만 담은 최소 템플릿으로 시작하는 것이 가장 좋습니다. 이후 PR과 릴리스 주기에 맞춰 조금씩 다듬으면 됩니다.