클로드 코드 CLAUDE.md 작성법 2026 — 반복 설명 없애는 메모리 파일

CLAUDE.md는 클로드 코드에게 프로젝트 작업 방식을 미리 적어두는 일반 마크다운 파일입니다. 세션을 새로 열 때마다 자동으로 읽히기 때문에, 지난번에 했던 지시를 다시 입력할 필요가 없습니다. 폴더 안에 텍스트 파일 하나를 두는 것이 전부라 코드를 몰라도 만들 수 있습니다.

공식 문서는 이 파일을 "지속 지침(persistent instructions)"이라고 설명합니다. 클로드가 스스로 기록하는 자동 메모리(auto memory)와는 역할이 다릅니다. CLAUDE.md는 사람이 쓴 규칙이고, 자동 메모리는 클로드가 대화 중 교정받은 내용을 스스로 저장하는 별도 파일입니다. 두 가지 모두 세션 시작 시 불러오지만, 규칙을 강제로 지키게 하려면 파일이 아니라 후크(hook) 기능을 써야 한다고 공식 문서는 밝히고 있습니다.

CLAUDE.md는 범위에 따라 여러 자리에 둘 수 있습니다. 공식 문서 기준으로 범위가 넓은 순서는 다음과 같습니다.

1. 조직 전체: 관리자가 배포하는 관리 정책 파일(macOS·Linux·Windows 경로 별도).
2. 사용자 전체: 홈 폴더의 ~/.claude/CLAUDE.md. 모든 프로젝트에 공통으로 적용됩니다.
3. 프로젝트: 작업 폴더의 ./CLAUDE.md 또는 ./.claude/CLAUDE.md. 버전 관리로 팀과 공유됩니다.
4. 개인·로컬: ./CLAUDE.local.md. 이 프로젝트에서만, 나만 쓰는 값이라 .gitignore에 넣도록 안내되어 있습니다.

작업 폴더보다 위에 있는 CLAUDE.md들은 실행 시점에 한꺼번에 불러오고, 하위 폴더의 CLAUDE.md는 클로드가 그 폴더의 파일을 열 때 추가로 불러옵니다. 여러 층을 한 번에 시작할 필요는 없습니다. 사용자 층과 프로젝트 층, 두 층으로 시작해서 규칙이 늘어날 때 나누는 방식이 더 관리하기 쉽습니다.

공식 문서는 CLAUDE.md에 넣을 내용으로 빌드·테스트 명령, 코딩 규칙, 프로젝트 구조, "항상 이렇게 하라"는 규칙을 꼽습니다. 그리고 이렇게 판단하라고 안내합니다.

• 클로드가 같은 실수를 두 번째 반복할 때
• 코드 리뷰에서 이 프로젝트만의 사정을 놓친 게 드러났을 때
• 지난 세션에서 했던 교정을 이번 세션에도 또 입력하고 있을 때
• 새 팀원에게도 똑같이 알려줘야 할 맥락일 때

반대로 절차가 여러 단계이거나 코드베이스 일부에만 해당하는 내용은 CLAUDE.md 대신 스킬(skill)이나 경로 지정 규칙(.claude/rules/)으로 옮기라고 안내합니다. CLAUDE.md는 매 세션 통째로 읽히는 파일이라, 자주 쓰지 않는 절차까지 넣으면 그만큼 맥락(컨텍스트)을 잡아먹기 때문입니다.

공식 문서가 제시하는 기준은 파일당 200줄 이내입니다. 파일이 길수록 맥락을 더 많이 차지하고, 지시를 따르는 정확도도 떨어진다고 설명합니다. 200줄을 넘길 것 같으면 경로 지정 규칙으로 쪼개거나, @경로 방식으로 다른 파일을 불러오는 임포트 구문을 쓰는 방법이 있습니다. 다만 임포트한 파일도 실행 시점에 함께 불러오므로 맥락 절약 효과는 없고, 정리 목적으로만 유효합니다.

문장도 구조가 있어야 잘 지켜집니다. 공식 문서는 "코드를 깔끔하게 정리하라" 같은 모호한 문장보다 "2칸 들여쓰기를 쓴다", "커밋 전에 npm test를 실행한다"처럼 검증 가능한 문장을 예로 듭니다. 규칙끼리 서로 어긋나면 클로드가 둘 중 하나를 임의로 고르게 되므로, 주기적으로 파일을 점검해 낡은 규칙을 정리하라고도 안내합니다.

CLAUDE.md는 "많이 적을수록 좋다"는 착각을 하기 쉬운 파일입니다. 공식 문서가 200줄이라는 상한을 못박아 둔 이유도 여기 있습니다. 매 세션 통째로 읽히는 구조라서, 규칙 한 줄을 추가할 때마다 실제로는 다른 모든 규칙이 읽힐 확률을 같이 깎아 먹습니다. 그래서 이 파일은 "생각날 때 추가하는 메모장"이 아니라 "같은 지적을 반복해서 받은 것만 남기는 최종 목록"으로 다뤄야 합니다. 또 하나 놓치기 쉬운 지점은, CLAUDE.md가 시스템 프롬프트가 아니라 사용자 메시지로 전달된다는 점입니다. 강제 규칙이 아니라 참고 지침이라는 뜻이므로, 절대 어기면 안 되는 사항(삭제 금지, 외부 발송 금지 같은 것)은 CLAUDE.md 문장만으로 안심하지 말고 후크나 권한 설정 같은 강제 장치를 따로 걸어야 합니다.

CLAUDE.md는 정말 매번 읽히나요?

그렇습니다. 세션을 시작할 때 자동으로 불러오며, 세션 도중 컨텍스트가 정리(compact)되어도 프로젝트 루트의 CLAUDE.md는 디스크에서 다시 읽어와 대화에 재주입한다고 공식 문서는 설명합니다.

사용자 CLAUDE.md와 프로젝트 CLAUDE.md가 충돌하면 어느 쪽이 이기나요?

두 파일 모두 컨텍스트에 함께 들어가며, 공식 문서는 작업 폴더에 가까운 파일일수록 나중에 읽힌다고 설명합니다. 순서가 뒤에 있는 지시가 더 최근 맥락으로 작용하므로, 프로젝트 규칙을 사용자 규칙보다 아래에 적는 편이 안전합니다.

코드가 아닌 작업에도 쓸 수 있나요?

쓸 수 있습니다. CLAUDE.md는 일반 마크다운 텍스트이므로 문서 정리, 콘텐츠 제작, 자료 조사 같은 비개발 작업에도 그대로 적용됩니다.

CLAUDE.md는 클로드 코드에게 프로젝트 규칙을 미리 적어 두는 파일이며, 사용자·프로젝트·로컬 등 범위별로 나눠 둘 수 있습니다. 200줄 이내로 짧게 유지하고, 같은 지적을 반복해서 받은 규칙만 남기는 방식이 공식 문서가 권하는 방향입니다. 정확한 문법과 최신 옵션은 아래 공식 문서에서 확인하는 것이 가장 안전합니다.

• Anthropic — How Claude remembers your project (https://code.claude.com/docs/en/memory, 확인일 2026-09-18)