CLAUDE.md 작성법 (적을 것과 뺄 것) 익히기

Claude Code로 같은 업무를 맡길 때마다 "날짜는 2026-11-12 형식으로, 장소는 장소: 값 형식으로 써 줘"처럼 같은 설명을 요청에 다시 적게 됩니다. Claude Code 공식 Memory 문서는 이런 설명을 적어 두는 파일로 CLAUDE.md를 소개합니다.

CLAUDE.md는 Claude Code가 세션을 시작할 때마다 읽는 지침 파일로, 세션마다 다시 설명하게 되는 사실과 규칙을 적어 두는 곳입니다. 세션은 Claude Code를 실행해 대화를 주고받는 한 번의 작업 단위입니다. 이 글은 2026년 10월 25일 기준 Claude Code 공식 문서(Memory, Best practices)와 이날 Claude Code v2.1.310에서 본 화면을 근거로 씁니다.

CLAUDE.md란: 규칙을 요청에 적을 때와 파일에 적을 때

CLAUDE.md는 작업 폴더에 두는 일반 텍스트 파일입니다. 파일 이름은 대문자 CLAUDE와 확장자 .md로 되어 있고, 내용은 마크다운으로 씁니다. 마크다운은 # 제목, - 항목처럼 간단한 기호로 구조를 표시하는 글 형식입니다. Claude Code는 세션을 시작할 때 이 파일을 읽어 대화의 맥락으로 씁니다.

위 표의 요청과 회의 메모 파일은 이 글에서 만든 가상 예시입니다.

CLAUDE.md를 쓰는 이유

Claude Code 세션은 매번 빈 컨텍스트 창으로 시작합니다. 컨텍스트 창은 AI 모델이 한 번에 참고하는 대화와 자료의 범위입니다. 월요일 세션에서 "날짜는 2026-11-12 형식으로 써 줘"라고 말했어도, 화요일에 새로 연 세션은 그 말을 모르는 상태로 시작합니다.

공식 Memory 문서는 CLAUDE.md를 "다시 설명하게 될 것을 적어 두는 곳"으로 설명하고, 한 줄을 더할 때를 네 가지로 꼽습니다.

• Claude가 같은 실수를 두 번째 했을 때
• 코드 리뷰나 결과 검토에서 Claude가 알았어야 할 내용이 나왔을 때
• 지난 세션에 했던 교정이나 설명을 또 입력하고 있을 때
• 새 팀원에게도 같은 설명이 필요할 때

같은 문서는 CLAUDE.md를 강제 설정이 아니라 맥락으로 다룬다고 적습니다. Claude는 CLAUDE.md를 읽고 따르려 하지만, 모든 지시를 반드시 지킨다는 보장은 없습니다. 흐리거나 서로 어긋나는 지시일수록 Claude가 지키지 않을 수 있습니다. 그래서 지시를 구체적이고 짧게 쓸수록 Claude가 더 꾸준히 따릅니다.

좋은 CLAUDE.md 작성법: 적을 것과 뺄 것

Claude Code 모범 사례 문서는 CLAUDE.md에 넣을 것과 뺄 것을 표로 정리해 두었고, 원문 표는 코드 작업을 예로 듭니다. 아래 표의 왼쪽 칸은 원문 항목 가운데 일부를 옮긴 것이고, 오른쪽 칸의 업무 파일 예는 이 글에서 붙인 것입니다.

한 줄을 넣을지 판단할 때 쓰는 질문도 같은 문서에 있습니다. "이 줄을 지우면 Claude가 실수할까?" 실수하지 않을 줄이면 지웁니다. 문서는 CLAUDE.md가 길어지면 Claude가 실제 지시를 무시하게 된다고 경고합니다. 회사나 팀이 정한 필수 규칙인지는 지우기 전에 먼저 확인합니다.

뺄 줄이 정말 쓸모없는 정보라는 뜻은 아닙니다. 이번 주 담당자처럼 자주 바뀌는 정보는 그 주의 요청에 적고, 특정 업무에만 필요한 여러 단계 절차는 클로드 스킬로 옮깁니다.

CLAUDE.md 예시: 회의 메모 폴더

비개발 업무 폴더에 쓰는 CLAUDE.md 예시입니다. 모범 사례 문서는 정해진 형식은 없지만 짧고 사람이 읽기 쉽게 쓰라고 안내합니다.

세 줄 모두 Claude가 혼자서는 알 수 없는 규칙이고, 답을 보면 지켰는지 바로 확인할 수 있는 문장입니다. 맨 위의 # 회의 메모 규칙은 마크다운 제목입니다. 규칙이 늘어나면 # 날짜와 장소, # 결과 파일처럼 제목 아래에 관련된 줄을 모읍니다.

CLAUDE.md 길이와 쓰는 법

공식 Memory 문서가 권하는 목표는 CLAUDE.md 파일당 200줄 미만입니다. 파일이 길수록 컨텍스트를 더 차지하고, Claude가 지시를 지키는 정도도 떨어진다고 적혀 있습니다. 권장 길이를 넘는 지침 파일이 있으면 Claude Code는 시작할 때와 /status(버전, 모델, 계정 상태를 보여 주는 명령) 명령에서 경고를 보여 줍니다.

200줄은 잘리는 한계가 아니라 권고입니다. 세션을 시작할 때 읽는 CLAUDE.md는 4MiB(약 400만 바이트) 이하이면 파일 전체를 읽고, 그보다 크면 그 파일을 통째로 건너뜁니다.

• 구체적으로: "코드를 제대로 정리한다" 대신 "들여쓰기는 공백 2칸"처럼 지켰는지 확인할 수 있게 씁니다.
• 구조: 관련된 지시를 마크다운 제목과 - 목록으로 묶습니다.
• 일관성: 두 지시가 서로 어긋나면 Claude가 둘 중 하나를 임의로 고를 수 있습니다. 하위 폴더의 CLAUDE.md와 .claude/rules/ 폴더의 규칙 파일(아래 "import와 규칙 폴더" 절)까지 가끔 읽어 낡거나 어긋나는 줄을 지웁니다.
• 강조는 한 줄에만: Claude가 계속 건너뛰는 지시 한 줄에만 IMPORTANT 같은 강조를 붙입니다. 여러 줄에 붙이면 어느 줄도 눈에 띄지 않는다고 모범 사례 문서가 경고합니다.

<!-- 메모 -->처럼 블록으로 쓴 HTML 주석은 Claude Code가 CLAUDE.md를 컨텍스트에 넣기 전에 지웁니다. 사람에게만 남길 메모에 씁니다. 다만 Claude가 파일 자체를 열어 읽으면 주석도 보입니다.

CLAUDE.md 파일 위치와 읽는 순서

CLAUDE.md는 네 범위에 둘 수 있습니다. ~는 홈 폴더, ./는 Claude Code를 실행한 작업 폴더를 뜻합니다.

여러 파일이 있으면 덮어쓰지 않고 모두 이어 붙여 읽습니다. 표의 위쪽 범위부터 읽고, 폴더 기준으로는 파일 시스템 맨 위에서 작업 폴더 쪽으로 내려오며 붙이므로 Claude Code를 실행한 폴더에 가까운 파일이 나중에 들어갑니다. 같은 폴더에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙습니다. 나중에 읽은 규칙이 앞 규칙을 이긴다는 보장은 없으므로, 같은 일을 정하는 규칙은 한 파일에만 적습니다.

작업 폴더와 그 위쪽 폴더의 CLAUDE.md는 세션을 시작할 때 읽고, 작업 폴더 아래 하위 폴더의 CLAUDE.md는 Claude가 그 하위 폴더의 파일을 읽거나 고칠 때 불러옵니다. 회사가 배포한 관리 정책 CLAUDE.md는 특정 CLAUDE.md를 읽지 않게 하는 설정 claudeMdExcludes로도 뺄 수 없습니다.

클로드 코드 메모리: CLAUDE.md와 자동 메모리(MEMORY.md)의 차이

클로드 코드의 메모리(memory)는 새 세션에서도 참고할 지침과 메모를 파일로 남기는 기능입니다. 지난 대화 전체를 그대로 이어 주는 기능이 아니고, 모델을 다시 학습시키는 기능도 아닙니다. 지난 대화 자체를 다시 열 때는 지난 세션 목록을 여는 /resume 명령으로 그 세션을 고릅니다.

공식 Memory 문서는 메모리를 두 가지로 나눕니다. CLAUDE.md는 사람이 쓰는 지침이고, 자동 메모리(auto memory)는 Claude가 작업하면서 스스로 남기는 메모입니다. 두 가지 모두 세션을 시작할 때 불러오지만 쓰는 사람과 불러오는 양이 다릅니다.

워크트리는 같은 Git 저장소를 여러 폴더에 나눠 연 작업 폴더입니다.

자동 메모리가 저장되는 위치와 MEMORY.md

자동 메모리는 프로젝트마다 ~/.claude/projects/<프로젝트>/memory/ 폴더에 저장됩니다. <프로젝트> 이름은 Git 저장소를 기준으로 정해지므로, 같은 저장소 안의 하위 폴더와 워크트리는 메모리 폴더 하나를 함께 씁니다. Git 저장소가 아닌 폴더에서는 프로젝트 맨 위 폴더가 기준입니다. 메모리 폴더는 지금 쓰는 컴퓨터에만 있고 다른 컴퓨터나 클라우드 환경과 공유되지 않습니다.

메모리 폴더 안의 MEMORY.md는 메모 목록을 한 줄에 하나씩 적은 색인 파일이고, 자세한 내용은 주제별 파일에 나뉘어 있습니다. 새 세션을 시작할 때 Claude Code는 MEMORY.md의 첫 200줄과 첫 25KB 가운데 먼저 닿는 범위까지만 불러옵니다. 주제별 파일은 Claude가 필요할 때 엽니다. 이 제한은 MEMORY.md의 제한이며, 세션을 시작할 때 읽는 CLAUDE.md는 4MiB 이하이면 파일 전체를 읽습니다.

Claude가 남기는 메모는 네 종류입니다.

• 사용자 정보: 사용자의 역할, 전문 분야, 작업 선호
• 교정: 사용자가 바로잡아 준 내용과 사용자가 맞다고 확인한 작업 방법
• 프로젝트 맥락: 파일이나 Git 기록에서 알 수 없는 진행 중인 일, 마감, 결정
• 참고 위치: 이슈 관리 도구나 대시보드처럼 프로젝트 밖 자료를 찾는 곳

파일을 읽으면 알 수 있는 구조나 경로, CLAUDE.md에 이미 적힌 내용은 메모로 남기지 않습니다. Claude가 세션마다 메모를 남기는 것도 아니며, 다음 대화에 쓸모 있을지를 보고 정합니다. Claude Code 화면에 "Saved 2 memories"나 "Recalled 2 memories" 같은 문구가 보이면 Claude가 메모리 폴더에 메모를 쓰거나 메모를 읽었다는 표시입니다.

기억해 달라고 할 때와 CLAUDE.md에 추가해 달라고 할 때

Claude에게 "앞으로 금액은 원 단위로 써 줘. 기억해 줘"처럼 기억해 달라고 말하면, Claude는 금액 규칙을 CLAUDE.md가 아닌 자동 메모리에 저장합니다. 같은 규칙을 팀원도 읽는 CLAUDE.md에 넣으려면 "이 규칙을 CLAUDE.md에 추가해 줘"라고 요청하거나 /memory로 CLAUDE.md를 직접 엽니다.

자동 메모리 켜고 끄기와 고치기

자동 메모리는 내 컴퓨터에서 실행하는 세션에서 기본으로 켜져 있습니다. /memory 화면의 Auto-memory 줄에서 끄면 사용자 설정 파일 ~/.claude/settings.json에 autoMemoryEnabled 값이 저장됩니다. 프로젝트 하나에서만 끄려면 그 프로젝트의 설정 파일에 "autoMemoryEnabled": false를 적습니다. 환경 변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1로도 끌 수 있습니다.

자동 메모리는 Claude의 판단으로 쌓이므로 틀린 내용이나 지난 가정이 남을 수 있습니다. 메모 파일은 일반 마크다운이라 언제든 열어 고치거나 지울 수 있습니다. Claude Code가 오래된 대화 기록을 정기적으로 지울 때도 메모리 폴더는 지우지 않으므로, 메모는 사용자나 Claude가 고치거나 지울 때까지 남습니다. 답이 예상과 다르게 나오면 /memory에서 Open auto-memory folder를 골라 잘못 기억한 메모가 있는지부터 봅니다.

CLAUDE.md를 관리하는 명령: /init, /memory, /context, /doctor prompt-audit

/init은 다른 도구의 지침 파일도 읽어 초안에 반영합니다. Cursor의 .cursor/rules/나 .cursorrules, GitHub Copilot의 .github/copilot-instructions.md가 그 대상입니다. 슬래시 명령을 입력하는 방법은 슬래시 명령어 수업에서 다뤘습니다.

import와 규칙 폴더로 CLAUDE.md 나누기

CLAUDE.md가 길어졌을 때 나누는 방법은 두 가지입니다.

import(@경로)는 다른 파일을 끌어와 붙이는 문법입니다. CLAUDE.md에 @docs/보고서-규칙.md처럼 적으면 Claude Code가 그 파일 내용도 함께 읽습니다. 상대 경로는 import를 적은 파일이 있는 폴더를 기준으로 하고, import한 파일이 다시 다른 파일을 import하는 연쇄는 4단계까지입니다. 공식 문서는 import가 정리에 도움이 될 뿐 컨텍스트를 줄여 주지는 않는다고 적습니다. import한 파일도 그 CLAUDE.md와 함께 불러오기 때문입니다. 백틱 기호로 감싸거나 코드 블록 안에 적은 경로는 import되지 않습니다. 프로젝트의 CLAUDE.md에서 작업 폴더 밖의 파일을 import하면 그 프로젝트에서 처음 한 번 승인 창이 나오고, 거절하면 그 import는 꺼진 채로 남습니다. 홈 폴더의 ~/.claude/CLAUDE.md처럼 사용자가 직접 쓴 사용자 범위 파일의 import에는 이 승인 창이 나오지 않습니다.

규칙 폴더(.claude/rules/)는 주제별 규칙 파일을 두는 폴더입니다. 파일 하나에 주제 하나를 두고, 파일 맨 위의 설정 영역(frontmatter)에 paths를 적으면 그 경로에 맞는 파일을 Claude가 읽거나 고칠 때만 그 규칙을 불러옵니다. paths가 없는 규칙 파일은 CLAUDE.md처럼 세션을 시작할 때 읽습니다.

위 파일은 형식을 보여 주는 가상 예시입니다. 영수증 폴더에만 해당하는 규칙을 이렇게 빼 두면 CLAUDE.md 본문이 짧아지고, 다른 폴더를 다룰 때는 이 규칙을 불러오지 않아 컨텍스트도 줄어듭니다.

CLAUDE.md, 규칙, 스킬, 권한 규칙과 훅을 나누는 기준

공식 Memory 문서는 두 가지를 구분합니다. 설정 파일의 권한 규칙은 Claude의 판단과 상관없이 Claude Code가 강제로 지킵니다. CLAUDE.md 지시는 Claude의 행동에 영향을 줄 뿐 강제 장치가 아닙니다. 예를 들어 CLAUDE.md에 "원본 폴더의 파일은 고치지 않는다"고 적으면 Claude가 그 지시를 참고합니다. 원본 폴더를 반드시 막아야 한다면 권한 규칙으로 그 경로의 편집을 막고, 실제로 막히는지 시험합니다. 권한 규칙을 쓰는 방법은 다음 수업 클로드 코드 권한 모드와 허용 규칙 설정하기에서 다룹니다.

AGENTS.md와 함께 쓰기

AGENTS.md는 Codex 같은 여러 코딩 에이전트가 함께 읽는 지침 파일입니다. Claude Code는 v2.1.277부터 AGENTS.md를 직접 읽습니다. 기본 설정에서는 작업 폴더와 그 위쪽 폴더에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 하나도 없을 때만 AGENTS.md를 읽습니다. 홈 폴더의 ~/.claude/CLAUDE.md와 관리 정책 파일은 이 판정에 들어가지 않습니다. AGENTS.md 자체는 AGENTS.md 수업에서, Claude Code의 지원 조건은 클로드 코드 AGENTS.md 지원에서 다뤘습니다.

두 파일을 함께 쓰려면 CLAUDE.md 첫 줄에 @AGENTS.md를 적어 공용 규칙을 import하고, 그 아래에 Claude에게만 필요한 지시를 적습니다. 또는 /config 설정 화면에서 Project instructions를 claude-md-and-agents-md로 바꿔 두 파일을 함께 읽게 합니다.

직접 해 보기: 연습 폴더에서 규칙 세 줄 확인하기

Claude Code 설치와 로그인이 끝났다면 진행합니다. 아직이라면 설치 기초를 먼저 따라 합니다. 요청을 보내면 계정의 사용량이 듭니다.

1. Finder나 파일 탐색기에서 빈 폴더 회의메모를 만듭니다. 이미 CLAUDE.md가 있는 업무 폴더는 쓰지 않습니다.
2. 메모장이나 텍스트 편집기로 회의메모 폴더 안에 예산회의.txt를 만들고 "2026년 11월 12일 2번 회의실 예산 회의"를 한 줄 적어 저장합니다.
3. 같은 폴더에 CLAUDE.md를 만들고 위 CLAUDE.md 예시의 제목 한 줄과 규칙 세 줄, 모두 네 줄을 붙여 넣어 저장합니다. Windows 메모장에서는 파일 형식을 "모든 파일"로 바꿔 이름이 CLAUDE.md.txt가 되지 않게 합니다.
4. 터미널이나 PowerShell에서 cd 뒤에 회의메모 폴더를 끌어다 놓고 Enter를 누른 뒤 claude를 입력합니다. 이 폴더를 처음 열면 폴더를 믿는지 묻는 화면이 나오고, Yes, I trust this folder를 고르면 세션이 시작됩니다.
5. 입력창에 "지금 불러온 프로젝트 지침의 규칙을 그대로 보여 줘"를 보내, CLAUDE.md에 적은 세 줄이 답에 나오는지 봅니다.
6. 입력창에 "예산회의.txt 정리해 줘"를 보냅니다. 답에 날짜: 2026-11-12, 장소: 2번 회의실, 시간: 미정이 있는지 CLAUDE.md의 세 줄과 하나씩 대조합니다.
7. /exit로 세션을 끝내고 다시 claude로 새 세션을 연 뒤 같은 요청을 보냅니다. 규칙을 다시 적지 않아도 같은 형식으로 나오는지 봅니다.

다른 자료로 한 번 더 해 봅니다. 예산회의.txt의 장소를 3번 회의실로 바꾸고 오후 3시를 적어 저장한 뒤 새 세션에서 같은 요청을 보내면, 답의 장소와 시간이 바뀐 자료대로 나와야 합니다.

막혔을 때

자주 묻는 질문

CLAUDE.md와 CLAUDE.local.md는 무엇이 다른가요?

CLAUDE.md는 Git 저장소에 올려 팀이 함께 읽는 프로젝트 지침이고, CLAUDE.local.md는 그 프로젝트에서 나만 쓰는 지침이라 .gitignore에 넣습니다. 같은 폴더에 둘 다 있으면 CLAUDE.md를 읽은 다음 CLAUDE.local.md를 이어 붙여 읽습니다. CLAUDE.local.md는 그 파일을 만든 워크트리에만 있으므로, 여러 워크트리에서 같은 개인 지시를 쓰려면 홈 폴더의 파일을 import하라고 공식 문서가 안내합니다.

CLAUDE.md가 200줄을 넘으면 뒷부분이 잘리나요?

잘리지 않습니다. 세션을 시작할 때 읽는 CLAUDE.md는 4MiB 이하이면 파일 전체를 읽습니다. 200줄은 규칙을 잘 지키게 하려는 권고이고, 첫 200줄과 첫 25KB 가운데 먼저 닿는 범위까지만 불러오는 제한은 자동 메모리의 MEMORY.md에 적용됩니다. 다만 하위 폴더의 CLAUDE.md와 paths 규칙 파일처럼 필요할 때 불러오는 파일은 파일마다 글자 수 한도가 있어, 200K 컨텍스트 창에서는 40,000자를 넘는 부분이 처음에 전달되지 않고, Claude가 파일을 직접 열어야 읽습니다.

CLAUDE.md와 자동 메모리는 어떻게 다른가요?

CLAUDE.md는 사용자가 직접 쓰는 지침 파일이고, 자동 메모리는 Claude가 사용자의 교정과 선호를 보고 스스로 쓰는 메모입니다. CLAUDE.md는 작업 폴더나 홈 폴더의 .claude 폴더에 있고, 자동 메모리는 ~/.claude/projects/<프로젝트>/memory/ 폴더에 있습니다. 둘 다 /memory에서 열어 고칠 수 있습니다.

참고 자료

• Claude Code 공식 문서: How Claude remembers your project(CLAUDE.md, 자동 메모리, /memory)
• Claude Code 공식 문서: Best practices(Write an effective CLAUDE.md)
• Claude Code 공식 문서: Commands(/init, /memory, /context, /doctor)
• Claude Code 공식 문서: Configure permissions(권한 규칙)
• Claude Code 공식 문서: Prompt caching(CLAUDE.md를 고친 뒤 반영되는 때)