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

이 글은 앤트로픽이 운영하는 code.claude.com/docs의 Memory 문서와 Best practices 문서를 한국어 사용자가 실무에 바로 옮길 수 있도록 정리한 글입니다. 기능 이름과 버전은 2026년 9월 28일 공식 문서 기준이고, 원문 링크는 글 끝 참고 자료에 모았습니다.

🤔 CLAUDE.md에 적은 규칙을 클로드가 자꾸 어길 때

CLAUDE.md를 만들어 두고 몇 주 쓰다 보면 파일이 길어집니다. 실수가 나올 때마다 한 줄씩 보태다 보니 200줄, 300줄이 넘고, 그런데도 적어 둔 규칙을 클로드가 가끔 건너뜁니다. 규칙을 더 세게 적어야 하는지, 오히려 줄여야 하는지 판단이 서지 않는 대목입니다.

공식 문서의 답은 줄이는 쪽입니다. 지금부터 무엇을 적고 무엇을 뺄지, 파일을 어디에 두고 어떻게 나누는지, 적어도 지켜지지 않는 규칙은 어디로 옮기는지 정리합니다. CLAUDE.md가 무엇인지 처음 보는 분은 입문 코스의 메모리 편을 먼저 읽으면 이어지는 설명이 쉬워집니다.

🔑 CLAUDE.md의 정의

CLAUDE.md는 클로드 코드가 세션을 시작할 때마다 읽는 프로젝트 지침 파일로, 매번 필요한 사실과 규칙만 짧게 적는 곳입니다.

여기서 먼저 알아 둘 점은 CLAUDE.md가 강제 설정이 아니라 맥락이라는 것입니다. 공식 문서에 따르면 CLAUDE.md 내용은 시스템 프롬프트의 일부가 아니라 그 뒤에 붙는 사용자 메시지로 전달됩니다. 클로드는 이 내용을 참고해 행동하지만, 반드시 따른다는 보장은 없습니다. 그래서 공식 문서는 반드시 막아야 하는 일이면 PreToolUse 훅을, 특정 도구나 경로를 막으려면 permissions.deny 설정을 쓰라고 안내합니다.

✅ 적을 것과 뺄 것

Best practices 문서는 CLAUDE.md에 넣을 것과 뺄 것을 표로 정리해 두었습니다.

한 줄을 넣을지 판단할 때 쓰는 질문도 문서에 있습니다. "이 줄을 지우면 클로드가 실수할까?" 아니라고 답이 나오면 그 줄은 지웁니다. 새 줄을 보탤 시점도 적혀 있는데, 같은 실수가 두 번째 나왔을 때, 지난 세션에 했던 교정을 또 입력하고 있을 때, 새 팀원에게도 필요한 맥락일 때입니다.

✂️ 길이는 파일당 200줄 미만

공식 문서가 권하는 목표는 파일당 200줄 미만입니다. 파일이 길수록 컨텍스트를 더 차지하고, 규칙을 지키는 비율도 떨어진다고 적혀 있습니다. 문서는 너무 긴 CLAUDE.md를 실패 패턴으로 꼽으며 "절반을 무시하게 된다"고 표현합니다.

200줄은 잘리는 한계가 아니라 권고입니다. 클로드 코드는 파일을 4MiB까지 통째로 읽고, 길이가 권고를 넘으면 시작할 때와 /status에서 경고가 뜹니다. 잘 지켜지게 만드는 원칙은 네 가지입니다.

• 크기: 파일당 200줄 미만
• 구조: 마크다운 제목과 불릿으로 나눕니다
• 구체성: "들여쓰기는 공백 2칸"처럼 확인할 수 있게 적습니다
• 일관성: 서로 어긋나는 규칙이 있으면 클로드가 둘 중 하나를 임의로 고를 수 있습니다

특정 규칙을 계속 건너뛴다면 그 한 줄에만 IMPORTANT 같은 강조를 붙입니다. 여러 줄에 붙이면 어느 것도 눈에 띄지 않는다고 문서가 경고합니다. 사람만 볼 메모는 <!-- --> 블록 주석으로 남기면 클로드에게 넘어가기 전에 지워지므로 토큰을 쓰지 않습니다.

📂 파일 위치와 읽는 순서

CLAUDE.md는 네 곳에 둘 수 있고, 위치마다 적용 범위가 다릅니다.

여러 파일이 있으면 덮어쓰지 않고 이어 붙입니다. 파일시스템 위쪽에서 작업 폴더 쪽으로 내려오며 붙이기 때문에, 실행한 폴더에 가까운 파일이 나중에 들어갑니다. 같은 폴더에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙습니다. 규칙끼리 부딪혀도 한쪽이 이긴다는 보장은 없다고 문서가 적고 있어서, 충돌하는 규칙은 한 곳에서만 정의하는 편이 안전합니다.

작업 폴더와 그 위쪽의 파일은 시작할 때 읽고, 하위 폴더의 CLAUDE.md는 클로드가 그 폴더의 파일을 열 때 불러옵니다. 모노레포에서 다른 팀 폴더의 CLAUDE.md를 빼고 싶다면 claudeMdExcludes 설정을 씁니다. 지금 클로드 코드가 어떤 파일을 불러왔는지는 /context의 Memory files 목록에서 확인합니다.

📎 import와 규칙 폴더로 나누기

CLAUDE.md가 길어졌을 때 쓸 수 있는 방법이 두 가지 있습니다.

import(@경로)는 다른 파일을 끌어와 붙이는 문법입니다. @docs/git-rules.md처럼 적으면 클로드 코드가 그 파일 내용도 함께 읽습니다. 상대 경로는 import를 적은 파일 기준이고, 연쇄 import는 4단계까지입니다. 다만 공식 문서는 import가 정리용일 뿐 컨텍스트를 줄여 주지는 않는다고 적습니다. 가져온 파일도 시작할 때 전부 불러오기 때문입니다.

규칙 폴더(.claude/rules/)는 주제별 파일을 두는 곳입니다. 파일 하나에 주제 하나를 두고, frontmatter에 paths를 적으면 그 패턴에 맞는 파일을 클로드가 읽을 때만 불러옵니다.

paths가 없는 규칙 파일은 CLAUDE.md처럼 시작할 때 읽어 들입니다. 일부 폴더에만 해당하는 규칙을 이렇게 빼 두면 CLAUDE.md 본문이 짧아지고, 실제로 컨텍스트도 줄어듭니다.

🔀 CLAUDE.md, 규칙, 스킬, 훅을 나누는 기준

한 가지 파일에 모든 것을 담으려다 길어지는 경우가 많습니다. 공식 문서의 기준을 옮기면 이렇게 나뉩니다.

CLAUDE.md의 한 절이 사실이 아니라 순서가 있는 절차가 되었다면 스킬로 옮길 때가 된 것입니다. 스킬 본문은 쓸 때만 불러오므로 평소 컨텍스트를 거의 차지하지 않습니다.

🧰 CLAUDE.md를 관리하는 명령

• /init: 코드베이스를 분석해 빌드 명령, 테스트 방법, 관례를 담은 초안을 만듭니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선안을 제안합니다
• /memory: 메모리 파일 목록을 열어 편집하고, 자동 메모리를 켜고 끕니다
• /doctor: 저장소에 올린 CLAUDE.md를 보고 코드에서 알 수 있는 폴더 구조나 의존성 목록은 덜어 내는 정리안을 제안합니다(v2.1.206 이상)
• /doctor prompt-audit: CLAUDE.md, 규칙, 스킬, 서브에이전트 지시를 함께 읽고 없는 파일 참조나 서로 모순되는 지시를 찾아 보고합니다(v2.1.283 이상)

🤝 AGENTS.md와 함께 쓰기

AGENTS.md는 코덱스 같은 여러 코딩 에이전트가 함께 읽는 지침 파일입니다. 클로드 코드는 v2.1.277부터 AGENTS.md를 직접 읽는데, 기본 설정에서는 작업 폴더와 그 위쪽에 CLAUDE.md가 하나도 없을 때만 읽습니다. 자세한 조건은 클로드 코드 AGENTS.md 지원에 정리했습니다.

두 파일을 함께 쓰려면 공식 문서가 권하는 방법이 간단합니다. CLAUDE.md 첫 줄에 @AGENTS.md를 적어 공용 규칙을 끌어오고, 그 아래에 클로드에게만 필요한 지시를 적습니다. 여러 도구가 같은 규칙을 따르면서 클로드 전용 지시도 유지됩니다.

⚠️ 자주 하는 실수

• 실수가 나올 때마다 한 줄씩 보태기만 합니다: 줄을 지우는 일도 같은 빈도로 해야 200줄 안에 머뭅니다
• 비밀 값을 적습니다: 프로젝트 CLAUDE.md는 저장소에 올라갑니다. 비밀 값은 환경 변수에 둡니다
• import로 줄였다고 생각합니다: import한 파일도 시작할 때 전부 불러옵니다. 컨텍스트를 줄이려면 paths 규칙이나 스킬로 옮깁니다
• 커밋 규칙을 적고 기본 지시와 부딪힙니다: 클로드 코드는 커밋과 PR에 관한 기본 지시를 갖고 있어서, 공식 문서는 직접 정한 규칙이 있으면 includeGitInstructions로 기본 지시를 끄라고 안내합니다

❓ 자주 묻는 질문

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

CLAUDE.md는 저장소에 올려 팀이 함께 쓰고, CLAUDE.local.md는 나만 쓰는 파일이라 .gitignore에 넣습니다. 둘 다 같은 폴더에 있으면 CLAUDE.local.md를 뒤에 붙여 읽습니다. 다만 로컬 파일은 git 워크트리끼리 공유되지 않으므로, 여러 워크트리에서 쓰려면 홈 폴더의 파일을 import하는 방법이 안내되어 있습니다.

200줄을 넘으면 뒷부분이 잘리나요?

잘리지 않습니다. 클로드 코드는 파일을 4MiB까지 통째로 읽습니다. 200줄은 규칙을 잘 지키게 하려는 권고이고, 실제로 첫 200줄만 읽는 제한은 클로드가 스스로 쓰는 자동 메모리 파일(MEMORY.md)에만 걸려 있습니다.

규칙을 적었는데 반영되지 않으면 무엇부터 보나요?

먼저 /context의 Memory files 목록에 그 파일이 있는지 봅니다. 목록에 있는데도 지키지 않는다면 파일이 너무 길어 규칙이 묻혔거나, 다른 파일의 규칙과 어긋나는 경우가 많습니다. 반드시 지켜야 하는 규칙이라면 훅으로 옮기는 것이 확실합니다.

📋 3줄 요약

1. CLAUDE.md는 클로드 코드가 세션마다 읽는 지침 파일이고, 공식 문서는 클로드가 추측할 수 없는 명령과 규칙만 적고 파일당 200줄 미만을 유지하라고 권합니다.

2. 사용자와 프로젝트, 로컬, 관리 정책 위치의 CLAUDE.md는 클로드 코드가 덮어쓰지 않고 이어 붙여 읽으며 하위 폴더 파일은 그 폴더의 파일을 열 때 불러옵니다.

3. CLAUDE.md는 강제 설정이 아니라 맥락이라서 반드시 막아야 할 일은 훅이나 permissions.deny로, 여러 단계 절차는 스킬로 옮깁니다.

📚 참고 자료

• 클로드 코드 메모리 문서: https://code.claude.com/docs/en/memory
• 클로드 코드 모범 사례 문서: https://code.claude.com/docs/en/best-practices
• 클로드 코드 스킬 문서: https://code.claude.com/docs/en/skills
• 클로드 코드 변경 기록: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md