CLAUDE.md란 — 클로드 코드가 세션마다 먼저 읽는 메모
공식 문서의 설명부터 옮기면, CLAUDE.md는 프로젝트 · 개인 작업 방식 · 조직 전체에 대한 지속적인 지시를 클로드에게 주는 마크다운 파일이고, 클로드는 세션을 시작할 때마다 이 파일을 읽는다. 형식은 평범한 텍스트라 특별한 문법을 배울 필요가 없다. 문서는 CLAUDE.md를 «안 적어 두면 매번 다시 설명하게 될 것을 적는 곳»으로 다루라고 권한다.
클로드 코드를 아직 설치하지 않았다면 클로드 코드 설치·요금제·첫 사용 (2026) — Windows에서 시작하기부터 보면 된다. 그 글에서는 CLAUDE.md를 한 문단으로만 소개했고, 이 글은 그 문단을 처음부터 끝까지 풀어 쓴 편이다.
언제 내용을 더하면 좋은지도 문서에 기준이 있다. 클로드가 같은 실수를 두 번째로 할 때, 코드 검토에서 클로드가 이 코드베이스에 대해 알았어야 할 것이 걸렸을 때, 지난 세션에 쳤던 정정이나 설명을 이번 세션에 또 칠 때, 새로 온 동료에게도 똑같은 맥락이 필요할 때다. 넷 다 «같은 설명을 두 번 하게 되는 순간»이라는 공통점이 있다.
자동 메모리와 무엇이 다르고, 어디에 두나
클로드 코드에는 세션을 넘어 기억을 잇는 장치가 둘 있다. 사람이 쓰는 CLAUDE.md와, 클로드가 정정과 선호를 보고 스스로 적는 자동 메모리다. CLAUDE.md는 지시와 규칙을 담고 프로젝트 · 사용자 · 조직 범위로 두며 세션마다 전부 읽힌다. 자동 메모리는 배운 것과 패턴을 담고 저장소마다 따로 쌓이며, 세션 시작 때는 색인 파일 MEMORY.md의 처음 200줄 또는 25KB까지만 읽힌다. 클로드에게 «npm 말고 pnpm을 써, 기억해 둬»라고 하면 자동 메모리에 들어가고, CLAUDE.md에 넣고 싶으면 «이걸 CLAUDE.md에 추가해 줘»라고 콕 집어 말하거나 /memory로 파일을 직접 고친다. 클로드 앱(claude.ai)의 메모리와는 다른 기능이며, 앱 쪽 메모리는 시리즈의 클로드 메모리와 지난 대화 찾기 — 남기고 지우고 끄는 법에서 다뤘다.
CLAUDE.md를 둘 수 있는 자리는 네 곳이고, 자리마다 적용되는 범위가 다르다.
- 관리 정책 — 조직의 IT 담당이 배포하는 회사 공통 지시다. Windows에서는
C:\Program Files\ClaudeCode\CLAUDE.md에 놓이고, 그 PC의 모든 사용자에게 적용된다. - 사용자 지시 —
~/.claude/CLAUDE.md. 내 모든 프로젝트에 쓰이는 개인 선호를 둔다. Windows에서~/.claude는%USERPROFILE%\.claude폴더를 뜻한다. - 프로젝트 지시 — 프로젝트 폴더의
./CLAUDE.md또는./.claude/CLAUDE.md. 버전 관리로 팀과 함께 쓰는 지시다. - 로컬 지시 — 프로젝트 폴더의
./CLAUDE.local.md. 이 프로젝트에서 나만 쓰는 선호를 두고, 저장소에 올라가지 않게.gitignore에 넣는다.
읽히는 순서도 정해져 있다. 클로드 코드는 시작한 폴더와 그 위의 모든 폴더에서 CLAUDE.md와 CLAUDE.local.md를 읽고, 이 파일들은 서로를 덮어쓰지 않고 이어 붙여진다. 파일 시스템의 맨 위에서 시작한 폴더 쪽으로 내려오는 순서라서, 시작한 곳에 가까운 지시일수록 나중에 읽힌다. 같은 폴더 안에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙는다. 시작한 폴더 아래의 하위 폴더에 있는 CLAUDE.md는 처음에 읽지 않고, 클로드가 그 하위 폴더의 다른 파일을 읽거나 쓰거나 고칠 때 불러온다. 대화에서 @로 파일을 짚어도 그 파일이 있는 폴더와 위 폴더의 CLAUDE.md가 함께 맥락에 들어간다.
정리하면 회사 규칙은 관리 정책, 내 습관은 사용자 지시, 팀이 함께 지킬 것은 프로젝트 지시, 남과 나눌 필요 없는 내 환경 메모는 로컬 지시다. 처음 시작하는 사람이라면 프로젝트 폴더의 ./CLAUDE.md 한 장으로 충분하고, 나머지 자리는 필요해질 때 늘리면 된다.
CLAUDE.md 쓰는 법 — /init 초안에서 줄을 지워 나간다
빈 파일에서 시작할 필요는 없다. 세션에서 /init을 입력하면 클로드가 코드베이스를 분석해 찾아낸 빌드 명령 · 테스트 방법 · 프로젝트 관례를 담은 CLAUDE.md를 만들어 준다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 고칠 점을 제안한다. 환경 변수 CLAUDE_CODE_NEW_INIT을 1로 두고 /init을 돌리면 CLAUDE.md · 스킬 · 훅 가운데 무엇을 만들지 먼저 묻고, 하위 에이전트로 코드베이스를 살핀 뒤 빈 곳을 질문으로 채워, 파일을 쓰기 전에 검토할 수 있는 제안을 보여 준다. 커서(Cursor)의 .cursor/rules/나 .cursorrules, 코파일럿(Copilot)의 .github/copilot-instructions.md가 있는 폴더라면 /init이 그 안에서 쓸 만한 부분을 가져와 CLAUDE.md에 녹인다.
초안이 생긴 뒤의 일은 대부분 «지우기»다. 모범 사례 문서는 /init이 만든 시작판에서 할 일은 주로 줄을 빼는 것이라고 적었다. 이유는 비용이다. 클로드 코드는 CLAUDE.md를 모든 세션에 불러오므로, 거기 적힌 줄 하나하나가 관련이 있든 없든 매 작업에서 클로드의 주의를 조금씩 가져간다.
그래서 남길 줄을 고르는 기준이 필요하다. 모범 사례 문서는 무언가를 적기 전에 두 가지를 물어보라고 한다. 클로드가 코드를 읽어서 이것을 찾을 수 있는가, 그리고 실제로 찾아보러 갈 것인가. 둘 다 «그렇다»면 빼도 된다. 같은 문서는 아키텍처와 폴더 구조를 CLAUDE.md에 설명하는 것을 «이제 그만해도 되는 옛 조언»으로 꼽았다. 클로드가 저장소를 스스로 읽기 때문이다.
넣을 것과 뺄 것, 그리고 예시 한 장
반대로 꼭 넣을 것은 클로드가 코드만 보고는 알 수 없는 것들이다. 모범 사례 문서는 네 가지를 든다.
- 이 저장소에서 일을 확인하는 방법 — 정확한 테스트 · 타입 검사 · 린트 명령, 그리고 테스트 파일 하나만 돌리는 법.
- 코드가 오해를 부르는 곳 — 곳곳에 남아 있지만 새 코드가 따라 하면 안 되는 옛 방식, 안 쓰는 것처럼 보이지만 실제로 쓰는 폴더.
- 저장소에 없는 결정 — 팀이 고른 오류 처리 방식, 배포 방법, 검토가 필요한 변경.
- 이미 두 번 정정한 것.
문서는 지시를 «확인할 수 있을 만큼 구체적으로» 쓰라고도 한다. «코드를 잘 정리해» 대신 «들여쓰기는 공백 2칸», «변경을 시험해 봐» 대신 «커밋 전에 npm test 실행», «파일을 정리해 둬» 대신 «API 처리 코드는 src/api/handlers/에 있다»처럼 쓰는 식이다. 관련된 지시는 마크다운 제목과 목록으로 묶는다. 빽빽한 문단보다 정리된 절이 따라 하기 쉽기 때문이다.
모범 사례 문서의 예시는 «명령 · 관례 · 함정» 세 덩어리로 된 짧은 파일이다. 같은 틀을 월별 보고서를 만드는 작은 파이썬 프로젝트에 옮기면 이런 모양이 된다(아래 명령과 폴더 이름은 설명을 위해 이 글에서 지은 예다).
# 명령
- 설치: pip install -r requirements.txt
- 테스트 파일 하나만: pytest tests/test_report.py
- 보고서 만들기: python make_report.py
# 관례
- 결과 파일은 output/ 폴더에만 쓴다. data/ 원본은 고치지 않는다
- 날짜는 YYYY-MM-DD로 적는다
# 함정
- old_scripts/ 는 아직 쓰는 폴더다. 지우거나 옮기지 않는다
- 통합 테스트는 환경 변수 DB_URL이 있어야 돈다. .env.example 참고폴더 구조나 쓰는 라이브러리 목록은 일부러 넣지 않았다. 클로드가 코드를 읽어 금방 아는 내용이라 위의 두 질문에서 걸러지기 때문이다. 파일을 만들었으면 세션에서 /context를 실행해 Memory files 목록에 그 파일이 있는지 확인한다.
나만 쓰는 메모는 CLAUDE.local.md로 뺀다. 내 테스트용 주소나 즐겨 쓰는 시험 데이터처럼 팀과 나눌 필요가 없는 것들이다. 긴 문서를 따로 두고 싶다면 CLAUDE.md 안에 @README나 @docs/git-instructions.md처럼 @경로를 적어 다른 파일을 불러올 수 있다. 상대 경로는 작업 폴더가 아니라 그 줄이 적힌 파일을 기준으로 풀린다. 경로를 글로만 적고 불러오지는 않으려면 백틱으로 감싼다.
인용 — Claude Code Docs «How Claude remembers your project»«Treat CLAUDE.md as the place you write down what you'd otherwise re-explain.» — CLAUDE.md는 안 적어 두면 다시 설명하게 될 것을 적어 두는 곳으로 다루라.
문서는 바로 이어서 빌드 명령 · 관례 · «늘 이렇게 하라»는 규칙처럼 매 세션 알고 있어야 할 사실만 두고, 여러 단계 절차나 코드베이스 한 부분에만 해당하는 내용은 스킬이나 경로 범위 규칙으로 옮기라고 적었다.
CLAUDE.md를 안 따를 때 — 클로드 코드에서 확인하는 순서
먼저 알아 둘 전제가 있다. CLAUDE.md의 내용은 시스템 프롬프트의 일부가 아니라 시스템 프롬프트 뒤에 사용자 메시지로 전달된다. 클로드는 이를 읽고 따르려 하지만 엄격한 준수가 보장되지는 않고, 막연하거나 서로 부딪히는 지시일수록 더 그렇다. 모범 사례 문서도 프롬프트 · CLAUDE.md · 스킬은 모델이 읽고 판단하는 지시라서, 대개 따르지만 반드시 따른다는 보장은 없다고 적었다.
그래서 «안 따른다» 싶을 때는 다음 순서로 본다.
- 실제로 읽혔는지 —
/context를 실행해 Memory files 아래에 그 CLAUDE.md와 CLAUDE.local.md가 있는지 본다. 목록에 없으면 클로드는 그 파일을 볼 수 없다. - 자리가 맞는지 — 그 세션에서 읽히는 위치에 파일이 있는지 확인한다. 하위 폴더의 CLAUDE.md는 시작할 때 읽지 않으므로 Memory files에 나오지 않고, 불러올 때 터미널에 경로와 함께
Loaded줄이 보인다. - 충분히 구체적인지 — «코드를 보기 좋게»보다 «들여쓰기는 공백 2칸»이 잘 먹힌다.
- 서로 부딪히지 않는지 — 두 파일이 같은 행동에 다른 지시를 하면 클로드가 아무 쪽이나 고를 수 있다. 사용자 지시와 프로젝트 지시, 하위 폴더의 CLAUDE.md,
.claude/rules/를 함께 살핀다.
예외 없이 지켜야 하는 규칙은 CLAUDE.md 밖으로
자주 하는 실수가 하나 있다. 클로드가 어떤 줄을 계속 놓치면 «중요» «IMPORTANT» 같은 강조를 덧붙이는 것이다. 모범 사례 문서는 그래서는 대개 고쳐지지 않는다고 적었다. 파일이 길어져 그 줄이 묻혔거나, 그 줄이 예외가 있으면 안 되는 규칙이라서다. 같은 문서의 «그만해도 되는 옛 조언» 표에도 강조를 쌓으면 오히려 클로드가 그 규칙을 지나치게 적용하게 된다는 설명이 있다.
예외가 없어야 하는 규칙은 클로드 코드(하네스)가 직접 적용하는 설정으로 옮긴다. 모범 사례 문서가 드는 예는 세 가지다. «.env를 읽지 마»는 어떤 권한 모드에서도 유지되는 거부(deny) 규칙으로, «편집 뒤 늘 포매터를 돌려»는 편집이나 쓰기 뒤에 도는 PostToolUse 훅으로, «migrations 폴더는 건드리지 마»는 그 경로에 대한 편집을 막는 PreToolUse 훅으로 바꾼다. 반대로 «이름 붙인 내보내기를 선호»처럼 예외가 많은 선호는 CLAUDE.md에 그대로 둔다. 커밋 직전이나 파일 편집 직후처럼 정해진 때에 꼭 돌아야 하는 일도 훅으로 쓰라는 것이 메모리 문서의 안내다.
시스템 프롬프트 수준의 지시가 꼭 필요하면 실행할 때 --append-system-prompt를 붙이는 방법이 있다. 시작할 때 넘기는 값이라 대화형보다는 스크립트에 맞는다고 문서는 적었다. 클로드 코드의 시스템 프롬프트 자체는 공개되지 않으므로, 상시 지시는 CLAUDE.md나 이 옵션으로 준다.
표의 위쪽 네 줄은 파일을 고치는 문제이고, 아래쪽 두 줄은 CLAUDE.md로 풀 문제가 아니라는 신호다. 대화가 길어져 압축(/compact)한 뒤 지시가 사라진 것 같을 때도 같은 원리로 본다. 프로젝트 맨 위의 CLAUDE.md는 압축 뒤에 디스크에서 다시 읽혀 세션에 다시 들어가므로, 사라진 지시는 대화로만 말했거나 아직 다시 불러오지 않은 하위 폴더 파일에 있던 것이다. 대화로만 준 지시를 남기고 싶으면 CLAUDE.md에 옮겨 적는다.
알아 둘 한도와 주의 — 200줄 · 가져오기 · AGENTS.md
길이의 기준은 파일 하나당 200줄 이하다. 한국어판 문서도 «CLAUDE.md 파일당 200줄 이하를 목표로» 하라고 같은 기준을 적었다. 파일이 길수록 맥락을 많이 차지하고 지시를 따르는 정도가 떨어진다. 권장 길이를 넘는 파일이 있으면 시작할 때와 /status를 실행할 때 경고가 보이고, 파일마다는 기준 안이어도 시작 시점에 합친 양이 한도를 넘으면 역시 경고가 뜬다. 4 MiB를 넘는 파일은 아예 건너뛰고 한 줄도 읽지 않는다. 하위 폴더의 CLAUDE.md처럼 필요할 때 불러오는 파일에는 따로 한도가 있어, 200K 맥락 창에서는 40,000자를 넘는 부분을 클로드가 처음에 받지 못한다. 맥락 창과 사용량이 어떻게 줄어드는지는 시리즈의 클로드 사용 한도 이해하기 — 왜 빨리 닳고 언제 풀리나에서 따로 봤다.
@ 가져오기에도 주의할 점이 있다. 가져온 파일은 그것을 부른 CLAUDE.md와 함께 불려 오므로, 긴 파일을 나눠 정리하는 데는 도움이 되지만 맥락 비용은 줄지 않는다. 가져온 파일이 또 다른 파일을 부를 수 있지만 최대 네 단계까지다. 경로에 공백이 있으면 공백마다 앞에 역슬래시를 붙여야 하고, 따옴표로 감싼 경로는 아예 불러오지 않는다. 프로젝트 파일이 작업 폴더 밖의 파일을 부르면 처음 한 번 승인 창이 뜨고, 거절하면 그 가져오기는 꺼진 채로 남고 창도 다시 뜨지 않는다. 남이 올린 저장소의 파일로부터 나를 지키려는 장치다.
길어지면 나누는 곳과 AGENTS.md
200줄을 넘기 시작하면 나눌 곳이 두 군데 있다. 하나는 .claude/rules/ 폴더다. testing.md, api-design.md처럼 주제 하나에 파일 하나를 두고, 파일 맨 위 머리말에 paths를 적으면 클로드가 그 경로에 맞는 파일을 다룰 때만 그 규칙을 불러온다. paths가 없는 규칙 파일은 .claude/CLAUDE.md와 같은 우선순위로 시작할 때 읽힌다. 모든 프로젝트에 쓰는 개인 규칙은 ~/.claude/rules/에 둔다. 다른 하나는 스킬이다. 배포 절차처럼 여러 단계로 된 일은 스킬로 옮기면, 클로드가 평소에는 이름과 설명만 보고 일이 필요할 때 전체를 읽는다. 스킬을 만드는 법은 바로 앞 글 클로드 스킬 — 반복하는 일을 규칙으로 저장하고 꺼내 쓰는 법에 정리했다.
정리하는 도구도 있다. /doctor는 저장소에 올린 CLAUDE.md에서 폴더 구조 · 의존성 목록 · 아키텍처 개요처럼 코드에서 알 수 있는 내용을 덜어 내자고 제안하고, 함정 · 이유 · 도구 기본값과 다른 관례는 남긴다. /doctor prompt-audit는 옛 모델용으로 쓴 지시, 없는 파일이나 명령을 가리키는 줄, 서로 부딪히는 파일을 찾아 고칠 안을 보고하며, 요청하기 전에는 파일을 바꾸지 않는다. 이 명령은 Claude Code v2.1.283 이상에서 쓸 수 있다. 사람에게만 남기고 싶은 메모는 블록 단위 HTML 주석(<!-- -->)으로 적으면 클로드에게 넘어가기 전에 지워져 맥락을 쓰지 않는다.
다른 코딩 도구와 함께 쓴다면 AGENTS.md도 알아 둔다. Claude Code v2.1.277 이상은 작업 폴더나 그 위에 CLAUDE.md · .claude/CLAUDE.md · CLAUDE.local.md가 하나도 없을 때 AGENTS.md를 프로젝트 지시로 읽는다. 둘 다 있으면 기본값으로는 CLAUDE.md만 읽고, /config의 Project instructions 값을 바꾸면 둘을 함께 읽게 할 수 있다. 한 파일을 여러 도구가 함께 쓰려면 CLAUDE.md 첫 줄에 @AGENTS.md를 적고 그 아래에 클로드 전용 지시를 더한다. Windows에서는 CLAUDE.md를 AGENTS.md로 잇는 심볼릭 링크 대신 이 가져오기를 쓰라고 문서가 따로 적었다. 링크를 만들려면 관리자 권한이나 개발자 모드가 필요하고, 깃이 링크를 한 줄짜리 텍스트 파일로 받아 올 수 있어서다. 클로드 코드와 다른 코딩 도구의 차이는 AI 코딩 도구 비교 2026 — Claude Code·Codex·Cursor에서 비교했다.
처음 만드는 CLAUDE.md는 /init 초안에서 시작해, 테스트 명령 한 줄과 클로드가 실제로 틀렸던 것 몇 줄만 남긴 짧은 파일이면 충분하다. 그 뒤로는 같은 정정을 두 번째로 하게 될 때마다 한 줄씩 더하고, 가끔 /doctor로 덜어 내는 흐름이 문서가 그리는 관리 방식이다.
자주 묻는 것
CLAUDE.md는 꼭 만들어야 하나요?
꼭 필요하지는 않습니다. 클로드 코드는 파일이 없어도 코드를 읽고 일합니다. 다만 같은 설명이나 정정을 세션마다 되풀이하고 있다면 공식 문서는 그 내용을 CLAUDE.md에 적으라고 권하며, /init으로 시작판을 바로 만들 수 있습니다.
CLAUDE.md는 몇 줄까지 써도 되나요?
공식 문서는 파일 하나당 200줄 이하를 목표로 하라고 권합니다. 길수록 맥락을 많이 쓰고 지시를 따르는 정도가 떨어지므로, 특정 부분에만 쓰이는 규칙은 경로 범위 규칙(.claude/rules/)으로, 여러 단계 절차는 스킬로 옮깁니다.
CLAUDE.md와 CLAUDE.local.md는 어떻게 나누나요?
CLAUDE.md는 버전 관리로 팀과 함께 쓰는 프로젝트 지시이고, CLAUDE.local.md는 이 프로젝트에서 나만 쓰는 선호를 두는 파일입니다. 같은 폴더에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 읽히며, 저장소에 올라가지 않도록 .gitignore에 넣습니다.
적어 둔 규칙을 클로드가 가끔 어기면 어떻게 하나요?
먼저 /context의 Memory files 목록에서 파일이 읽혔는지 보고, 지시를 더 구체적으로 고치고, 다른 파일과 부딪히는 지시가 없는지 확인합니다. 예외 없이 지켜야 하는 규칙이라면 CLAUDE.md에 강조를 더하기보다 훅이나 거부 규칙으로 옮기는 것이 공식 문서의 권장입니다.
자동 메모리를 켜 두면 CLAUDE.md가 필요 없나요?
둘은 맡는 일이 다릅니다. 자동 메모리는 클로드가 정정과 선호를 보고 스스로 적는 메모이고, CLAUDE.md는 사람이 쓰는 지시와 규칙입니다. 자동 메모리는 CLAUDE.md에 이미 적힌 내용은 따로 저장하지 않으므로 둘을 함께 씁니다.
정리 — 두 번 한 설명만 남기는 짧은 파일
CLAUDE.md는 클로드 코드가 세션을 시작할 때마다 읽는 지시 파일이고, 관리 정책 · 사용자 · 프로젝트 · 로컬 네 자리에 둘 수 있으며 덮어쓰지 않고 이어 붙여 읽힌다. 시작은 /init 초안이고, 그다음은 클로드가 코드를 읽어 알 수 있는 줄을 지우는 일이다. 남길 것은 확인 명령, 오해를 부르는 곳, 저장소에 없는 결정, 두 번 정정한 것이다. 파일 하나는 200줄 이하로, 지시는 확인할 수 있을 만큼 구체적으로 쓴다. 안 따를 때는 /context로 읽혔는지부터 보고, 예외가 없어야 하는 규칙은 훅이나 거부 규칙으로 옮긴다. 메뉴 이름과 기능은 자주 바뀌므로 이 글은 2026년 10월 29일 기준으로 읽고, 쓰기 전에 공식 문서를 한 번 더 확인한다. 클로드에게 같은 정정을 두 번째로 하게 된 순간이 있다면, 그 한 줄이 CLAUDE.md의 첫 줄이다.
참고 자료
- Claude Code Docs. How Claude remembers your project — CLAUDE.md와 자동 메모리 차이 · 네 자리와 Windows 관리 경로 · 읽히는 순서 · /init과 CLAUDE_CODE_NEW_INIT · 200줄 · @ 가져오기 4단계 · 외부 가져오기 승인 · .claude/rules · AGENTS.md v2.1.277 · /doctor prompt-audit v2.1.283 · 4 MiB · 하위 폴더 40,000자 · MEMORY.md 200줄 · 25KB · /compact 뒤 다시 읽음(2026-10-29 확인). code.claude.com
- Claude Code Docs. Best practices for Claude Code — 정해진 지시와 모델이 판단하는 지시 · 코드에서 못 찾는 것만 적기 · 두 가지 질문 · 짧게 유지할 네 가지 · CLAUDE.md 예시 · IMPORTANT를 더해도 안 고쳐짐 · 훅 · 거부 규칙 · 그만해도 되는 옛 조언 표(2026-10-29 확인). code.claude.com
- Claude Code 문서. Claude가 프로젝트를 기억하는 방법 — 한국어판 «지침 및 메모리 저장» · «경로 범위 규칙» · «가져오기» 용어와 200줄 · /init 설명(2026-10-29 확인). code.claude.com
- Claude Code Docs. Settings files and precedence — Windows에서 ~/.claude = %USERPROFILE%\.claude · 시스템 프롬프트는 공개 안 함 → CLAUDE.md나 --append-system-prompt(2026-10-29 확인). code.claude.com
- Claude Code Docs. Common workflows — @ 파일 참조가 그 파일 폴더와 위 폴더의 CLAUDE.md를 함께 불러옴(2026-10-29 확인). code.claude.com
