CLAUDE.md 작성법과 위치: 뭘 적고 뭘 빼야 하나

AI와 나눈 대화는 이어갈 수 있습니다. 한 번 시작해서 이어 가는 대화 한 묶음을 세션이라고 합니다. Claude Code(클로드 코드)에는 직전 대화를 그대로 잇는 claude --continue와 지난 세션을 골라 여는 claude --resume이 있습니다. 창을 닫으면 전부 사라진다고 알고 계셨다면 그건 아닙니다.

하지만 이어가기로 해결되지 않는 자리도 있습니다. 새 세션은 처음부터 시작하고, 긴 대화의 앞부분은 요약으로 눌립니다. 같은 프로젝트를 받은 다른 사람의 세션에는 내 대화가 붙지 않습니다. 일을 계속 맡기다 보면 "이 프로젝트에서는 이렇게 해 주세요"라는 설명을 매번 다시 하게 됩니다.

CLAUDE.md는 그 반복 설명을 적어 두는 파일입니다. Claude(클로드)가 세션을 시작할 때마다 읽으므로 한 번 써 두면 계속 참고합니다. 이름 끝의 .md는 마크다운 파일이라는 뜻입니다. 마크다운은 제목 앞에 #, 목록 앞에 - 같은 표시를 붙여 구조를 나타내는 글쓰기 형식입니다. 이 글에서는 파일의 생김새부터 위치, 적당한 분량, 다른 지침 파일과 함께 쓰는 법까지 차례로 살펴봅니다.

파일 안에는 다음처럼 평범한 문장이 들어갑니다.

# 이 프로젝트에서 지킬 일
- 답변은 한국어로 씁니다
- 보고서는 결론부터 씁니다
- 날짜는 YYYY-MM-DD 형식으로 씁니다
- 초안 파일은 삭제하지 않습니다

제목과 목록만으로도 시작할 수 있고 정해진 양식은 없습니다. 만들어 두고도 "왜 안 지키지?" 싶다면 위치, 분량, 표현부터 확인하면 됩니다. 이 글은 2026년 8월 기준이며 근거는 공식 문서입니다.

파일 위치: 적용 범위 결정

같은 내용이라도 파일을 어디에 두느냐에 따라 적용 범위가 달라집니다. 표를 보기 전에 낯선 경로 표시부터 풀어보겠습니다. 경로는 컴퓨터 안에서 파일이 있는 주소입니다.

터미널은 마우스 대신 글자로 명령을 입력하는 창입니다. ~는 내 사용자 폴더를 뜻하고, ./는 지금 터미널에서 열어 둔 프로젝트 폴더를 뜻합니다. .claude처럼 점으로 시작하는 이름은 평소 파일 목록에서 숨겨질 수 있습니다. 따라서 ~/.claude/CLAUDE.md는 "내 사용자 폴더 안의 숨김 .claude 폴더에 있는 CLAUDE.md"라고 읽으면 됩니다.

아래 표는 Claude Code가 파일을 읽는 순서대로 정리했습니다.

서로 덮어쓰지 않고 이어 붙습니다. 위에서부터 차례로 읽히고, 나중에 읽힌 쪽이 더 가까운 지시로 취급됩니다.

가장 많이 쓰시게 될 자리는 프로젝트 CLAUDE.md입니다. 프로젝트 파일과 함께 저장하면 그 프로젝트를 받은 사람 모두에게 같은 지침이 적용됩니다.

CLAUDE.local.md에는 테스트용 주소나 개인 취향처럼 나만 쓸 설정을 둡니다. 이 파일은 .gitignore에 넣어야 합니다. .gitignore는 깃에 올리지 않을 파일 이름, 즉 다른 사람과 공유하지 않을 파일을 적는 목록입니다.

탐색 방식: 상위와 하위 폴더

Claude Code는 현재 폴더에서 시작해 한 단계씩 바깥의 상위 폴더로 올라가며 CLAUDE.md를 찾습니다. 안쪽 폴더에서 시작해도 바깥 폴더의 지침을 챙기는 이유입니다.

반대로 하위 폴더의 CLAUDE.md는 세션을 시작할 때 바로 읽히지 않습니다. Claude가 그 폴더의 파일을 읽을 때 함께 들어옵니다.

자동 메모리: Claude가 쓰는 기록

여기서 헷갈리기 쉬운 게 하나 있습니다. Claude Code가 참고하는 기억은 두 종류입니다. CLAUDE.md는 내가 직접 쓰고, 자동 메모리(auto memory)는 Claude가 작업 중에 스스로 씁니다.

자동 메모리는 기본으로 켜져 있습니다. 내가 CLAUDE.md를 만들지 않아도 Claude는 작업 중에 배운 내용을 기억할 수 있습니다. "메모리 2개 저장됨" 같은 표시를 보신 적이 있다면 자동 메모리에 기록됐다는 뜻입니다.

Claude가 저장하는 내용은 네 갈래입니다. 내 역할과 선호(user), 내가 바로잡아 준 내용(feedback), 프로젝트 파일만 봐서는 알 수 없는 진행 상황(project), 외부 자료의 위치(reference)입니다. 프로젝트 파일을 읽어서 바로 알 수 있는 폴더 구조나 파일 경로는 저장하지 않습니다.

/memory처럼 /로 시작하는 표현은 Claude Code 입력창에서 실행하는 명령입니다. 무엇이 쌓였는지 궁금하면 /memory를 실행한 뒤 자동 메모리 폴더를 여시면 됩니다. 여기도 마크다운 파일이라 내용을 읽고 고치고 지울 수 있습니다.

자동 메모리를 끄고 싶다면 같은 /memory 화면에서 설정을 바꾸거나 프로젝트 설정에 다음 내용을 넣으면 됩니다.

{
  "autoMemoryEnabled": false
}

그럼 무엇을 어디에 적어야 할까요? 매번 지켜야 하는 규칙은 CLAUDE.md에 내가 적습니다. 작업하며 배운 내용을 Claude가 기억하면 되는 경우에는 자동 메모리에 맡깁니다. 대화 중에 "이건 기억해 줘"라고 말하면 자동 메모리에 들어갑니다. "CLAUDE.md에 추가해 줘"라고 말하면 내가 관리하는 지침 파일에 들어갑니다.

분량 기준: 200줄

CLAUDE.md는 자세할수록 좋을 것 같지만 너무 길면 오히려 지시가 묻힙니다. 공식 문서는 파일당 200줄 이하를 권합니다.

컨텍스트는 Claude가 한 번에 참고하는 대화와 자료의 범위입니다. CLAUDE.md가 길수록 이 범위를 많이 차지하고 지시는 덜 지켜집니다.

CLAUDE.md는 무조건 적용되는 잠금 설정이 아닙니다. 대화에서 내가 보내는 메시지와 같은 방식으로 전달되는 참고 자료입니다. Claude는 읽고 따르려 하지만 내용이 길고 모호하면 일부를 놓칠 수 있습니다.

설명서가 두꺼워질수록 아무도 안 읽는 것과 같습니다.

삭제 대상: 파일에서 보이는 정보

파일이 길어졌는데 뭘 지워야 할지 모르겠다면 Claude Code에게 물어볼 수 있습니다. 대화 입력창에 /doctor라고 치면 됩니다. 설치와 설정이 제대로 돼 있는지 훑어 주는 점검 명령인데, CLAUDE.md에서 덜어낼 만한 내용도 함께 짚어 줍니다.

직접 판단하실 때 기준은 하나입니다. Claude가 스스로 알아낼 수 있는가입니다.

프로젝트 파일을 열어 보면 알 수 있는 것은 뺍니다. 폴더가 어떻게 나뉘어 있는지, 어떤 프로그램을 쓰는지, 전체 구조가 어떤지 같은 내용입니다. Claude는 일을 시작할 때 파일을 직접 훑어보기 때문에, 이런 것까지 적어 두면 같은 정보를 두 번 읽는 셈이 됩니다.

반대로 파일만 봐서는 알 수 없는 것은 남깁니다. 남들과 다르게 하는 부분, 왜 그렇게 정했는지, 지켜야 할 규칙입니다.

"우리 프로젝트는 다른 곳과 달리 이렇게 한다"는 내용이 CLAUDE.md에 들어갈 자리입니다.

추가 시점: 같은 설명의 반복

언제 규칙을 추가해야 할지 망설여지신다면 다음 네 순간을 보시면 됩니다.

• Claude가 같은 실수를 두 번째로 할 때
• 코드를 검토하다 Claude가 알아야 할 걸 발견했을 때
• 지난번에 했던 같은 설명을 또 입력하고 있을 때
• 새 팀원이 들어오면 똑같이 알려줘야 할 내용일 때

같은 말을 두 번 했다면 적을 때입니다. 이 기준 하나만 지켜도 파일이 쓸데없이 불어나지 않습니다.

작성 방식: 확인 가능한 규칙

규칙은 지켰는지 바로 확인할 수 있게 씁니다. 공식 문서의 개발 작업 예시를 보면 차이가 선명합니다.

들여쓰기는 줄의 시작을 안쪽으로 밀어 쓰는 간격입니다. npm test는 프로젝트 검사를 실행하는 명령이고, API 핸들러는 들어온 요청을 처리하는 파일입니다. 정확한 개발 용어보다 왼쪽과 오른쪽의 차이를 보시면 됩니다. 오른쪽은 간격, 실행할 명령, 저장할 폴더가 정해져 있습니다. 지켰는지 판별할 수 있어야 실제 지시로 작동합니다.

사람용 메모: HTML 주석

HTML 주석은 <!--와 --> 사이에 넣는 메모입니다. CLAUDE.md 안에서는 Claude에게 전달되기 전에 빠지고, 파일을 직접 여는 사람에게만 배경을 남길 수 있습니다.

<!-- 이 규칙은 2026년 1월 배포 사고 때문에 생겼음. 담당자 확인 후 수정할 것 -->
 
- 배포 전에 반드시 스테이징에서 확인합니다

위 주석은 Claude가 읽는 분량을 전혀 차지하지 않습니다. 규칙이 생긴 이유나 수정 전 확인할 일을 사람에게만 남길 때 유용합니다. 단, 예시 코드를 따로 표시한 코드 블록 안의 주석은 그대로 남습니다.

파일 분리: @로 가져오기

파일이 길어지면 내용을 다른 파일로 나눌 수 있습니다. @ 뒤에 가져올 파일의 경로를 적으면 됩니다.

프로젝트 개요는 @README를 참고합니다.
 
# 추가 지침
- git 워크플로우 @docs/git-instructions.md

가져온 파일도 세션을 시작할 때 함께 읽힙니다. 가져온 파일이 다시 다른 파일을 가져오는 구조는 최대 네 단계까지 이어집니다.

여기서 오해하기 쉬운 게 있습니다. 파일을 나눈다고 컨텍스트가 줄지는 않습니다. 가져오기는 내용을 정리하는 데 도움이 될 뿐입니다. 시작할 때 모든 파일을 읽으므로 전체 분량은 그대로입니다.

Claude가 처음부터 읽을 분량을 줄이려면 경로별 규칙이나 스킬을 써야 합니다.

경로별 규칙은 특정 파일을 다룰 때만 필요한 지침입니다. .claude/rules/ 폴더에 규칙 파일을 두고 맨 위의 paths에 적용할 파일 경로를 적습니다. 그러면 Claude가 그 파일을 만질 때만 지침이 읽힙니다.

---
paths:
  - "src/api/**/*.ts"
---
 
# API 작성 규칙
- 모든 엔드포인트에 입력 검증을 넣습니다

위 예시는 src/api 폴더 아래의 모든 TypeScript 파일을 다룰 때 입력값 검사 규칙을 읽으라는 뜻입니다.

스킬은 특정 작업의 순서를 따로 적어 두는 파일입니다. 단계별 절차라면 CLAUDE.md보다 스킬에 두는 편이 맞습니다. 스킬은 그 작업에 실제로 쓸 때만 읽힙니다.

늘 알고 있어야 하는 사실은 CLAUDE.md에 둡니다. 특정 파일에만 필요한 규칙은 경로별 규칙에, 특정 작업의 절차는 스킬에 둡니다.

AGENTS.md: @로 함께 쓰기

코딩을 돕는 AI 도구를 여러 개 쓰다 보면 공통 규칙을 적은 AGENTS.md가 이미 있을 수 있습니다.

Claude Code는 CLAUDE.md를 읽지만 AGENTS.md는 읽지 않습니다. 같은 규칙을 두 파일에 복사하면 한쪽만 고쳤을 때 내용이 어긋납니다.

공식 문서가 권하는 방법은 앞에서 본 @ 가져오기입니다. CLAUDE.md를 만들고 첫 줄에 다음처럼 씁니다.

@AGENTS.md
 
## Claude Code 전용
 
`src/billing/` 아래를 고칠 때는 계획 모드를 씁니다.

위 예시는 src/billing/ 폴더를 고칠 때 바로 수정하지 않고 계획부터 세우라는 Claude Code 전용 규칙입니다.

공통 규칙은 AGENTS.md 한 곳에만 둡니다. Claude Code에만 해당하는 내용은 가져오기 아래에 덧붙입니다. 저도 이 방식을 씁니다. 공통 규칙을 고칠 때 한 파일만 손보면 되니 두 파일이 어긋나지 않습니다.

Claude Code 전용으로 덧붙일 내용이 없다면 심볼릭 링크로 이어도 됩니다. 심볼릭 링크는 한 파일을 다른 이름으로 가리키는 연결입니다.

ln -s AGENTS.md CLAUDE.md

윈도우에서는 심볼릭 링크에 관리자 권한이나 개발자 모드가 필요합니다. 이 경우에는 @AGENTS.md 가져오기를 쓰시면 됩니다.

최초 생성: /init 초안

처음부터 직접 쓰기 부담스러우신가요? Claude Code 입력창에 /init을 입력하면 초안을 받을 수 있습니다.

/init

Claude가 프로젝트 파일을 훑고 실행에 필요한 빌드 명령, 오류를 확인하는 테스트 방법, 프로젝트 규칙을 찾아 초안을 만듭니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선안을 제안합니다.

프로젝트에 AGENTS.md나 .cursorrules 같은 다른 도구 설정이 있다면 그것도 읽어서 반영합니다.

초안은 출발점입니다. Claude가 프로젝트 파일만 보고 알 수 없는 내용, 특히 "왜 이렇게 하는지"를 내가 채워야 쓸모가 생깁니다.

저도 처음에는 /init이 만든 파일을 열어보지 않고 그대로 썼습니다. Claude가 규칙을 가끔 어기면 그때마다 강조를 덧붙였습니다. 글자를 굵게 하고, 규칙을 맨 위로 올리고, 우선순위도 적었습니다. 그러다 몇 줄이던 파일이 100줄을 넘겼지만 규칙이 어긋나는 빈도는 그대로였습니다.

답은 강조가 아니라 정리였습니다. 겹치는 지시를 지우자 무엇을 따라야 하는지가 선명해졌습니다. 200줄 기준이 중요한 이유도 여기에 있습니다. 길어질수록 잘 지켜지는 게 아니라 필요한 지시가 다른 문장 사이에 묻힙니다.

문제 해결: 파일 확인 순서

지시를 적었는데도 Claude가 따르지 않는다면 다음 순서로 확인하세요.

1. 파일이 실제로 읽혔는지 봅니다. /context를 실행하면 이번 세션에 읽혀 들어온 CLAUDE.md가 나옵니다. 목록에 없다면 파일 위치가 잘못됐을 가능성이 큽니다. /memory는 파일을 열어 고치는 명령이라 아직 만들지 않은 파일도 목록에 보여 줍니다. 읽혔는지 확인할 때는 /context를 쓰셔야 합니다.
2. 지시가 구체적인지 봅니다. 앞의 표처럼 행동이나 명령, 위치가 정해져 있어야 합니다.
3. 서로 충돌하는 지시가 없는지 봅니다. 조직, 개인, 프로젝트, 로컬 파일이 함께 읽힐 때 서로 다른 지시가 들어 있을 수 있습니다. 두 지시가 부딪히면 Claude가 임의로 하나를 고릅니다.
4. 반드시 실행해야 하는 일인지 봅니다. 커밋 전이나 파일을 고칠 때마다 정해진 명령을 실행해야 한다면 CLAUDE.md보다 훅(hook)이 맞습니다. 훅은 정해 둔 순간에 명령을 자동으로 실행하므로 Claude의 판단에 좌우되지 않습니다.

대화가 길어져 앞부분이 요약된 뒤에도 지시가 남는지 궁금하실 수 있습니다. 프로젝트의 가장 바깥 폴더인 루트에 둔 CLAUDE.md는 요약 뒤에 다시 읽힙니다. 하위 폴더의 CLAUDE.md는 자동으로 다시 들어오지 않습니다. 그 폴더의 파일을 다시 읽을 때 함께 들어옵니다.