꾸비데브

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

AI 코딩 도구에게 같은 규칙을 매번 다시 설명하고 있다면, 클로드 코드의 CLAUDE.md 파일을 어디에 두고 무엇을 적어야 하는지 정리했습니다.

한 줄 요약

CLAUDE.md는 클로드 코드에게 프로젝트 규칙을 미리 적어 두는 마크다운 파일이라, 세션마다 같은 지시를 반복하지 않아도 됩니다. 사용자와 프로젝트 두 층으로 시작해 200줄 이내로 짧게 유지하는 것이 공식 문서가 권하는 방향입니다.

AI에게 이렇게 시키기
지금 프로젝트에 맞는 CLAUDE.md 초안을 만들어 줘.
- 이 대화에서 내가 두 번 이상 교정한 내용만 규칙으로 넣어 줘
- 규칙은 "2칸 들여쓰기를 쓴다"처럼 검증할 수 있는 문장으로 써 줘
- 전체를 200줄 이내로 맞춰 줘
- 절차가 여러 단계인 내용은 CLAUDE.md에 넣지 말고 스킬로 옮길 후보로 따로 알려 줘

AI 코딩 도구에게 같은 규칙을 매번 다시 설명하고 있다면 이 글을 읽어야 합니다. 클로드 코드(Claude Code)는 CLAUDE.md라는 파일 하나로 이 반복을 없앱니다. 파일 하나를 어디에 두고 무엇을 적어야 하는지를 정리했습니다.

CLAUDE.md란 무엇인가

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

공식 문서는 이 파일을 "지속 지침(persistent instructions)"이라고 설명합니다. 클로드가 스스로 기록하는 자동 메모리(auto memory)와는 역할이 다릅니다. CLAUDE.md는 사람이 쓴 규칙이고, 자동 메모리는 클로드가 대화 중 교정받은 내용을 스스로 저장하는 별도 파일입니다.

두 가지 모두 세션 시작 시 불러오지만, 규칙을 강제로 지키게 하려면 파일이 아니라 후크(hook) 기능을 써야 한다고 공식 문서는 밝히고 있습니다.

CLAUDE.md와 자동 메모리강제하려면 후크를 씁니다CLAUDE.md자동 메모리쓰는 이사람클로드내용직접 쓴 규칙교정받은 내용불러오기세션 시작 시세션 시작 시
STEP 1

파일을 둘 자리 정하기

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

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

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

STEP 2

적을 내용 고르기

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

규칙으로 적을 때인지 확인하나라도 해당하면 적습니다클로드가 같은 실수를 두 번째 반복함코드 리뷰에서 프로젝트 사정을 놓침지난 교정을 이번에도 또 입력 중새 팀원에게도 알려줄 맥락
  • 클로드가 같은 실수를 두 번째 반복할 때
  • 코드 리뷰에서 이 프로젝트만의 사정을 놓친 게 드러났을 때
  • 지난 세션에서 했던 교정을 이번 세션에도 또 입력하고 있을 때
  • 새 팀원에게도 똑같이 알려줘야 할 맥락일 때

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

STEP 3

200줄 안쪽으로 유지하기

공식 문서가 제시하는 기준은 파일당 200줄 이내입니다. 파일이 길수록 맥락을 더 많이 차지하고, 지시를 따르는 정확도도 떨어진다고 설명합니다. 이 상한선이 왜 중요한지는 컨텍스트가 채워지는 방식을 알면 더 잘 이해됩니다.

200줄을 넘길 것 같으면 경로 지정 규칙으로 쪼개거나, @경로 방식으로 다른 파일을 불러오는 임포트 구문을 쓰는 방법이 있습니다. 다만 임포트한 파일도 실행 시점에 함께 불러오므로 맥락 절약 효과는 없고, 정리 목적으로만 유효합니다.

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

운영자 한마디

CLAUDE.md는 "많이 적을수록 좋다"는 착각을 하기 쉬운 파일입니다. 공식 문서가 200줄이라는 상한을 못박아 둔 이유도 여기 있습니다. 매 세션 통째로 읽히는 구조라서, 규칙 한 줄을 추가할 때마다 실제로는 다른 모든 규칙이 읽힐 확률을 같이 깎아 먹습니다.

그래서 이 파일은 "생각날 때 추가하는 메모장"이 아니라 "같은 지적을 반복해서 받은 것만 남기는 최종 목록"으로 다뤄야 합니다. 또 하나 놓치기 쉬운 지점은, CLAUDE.md가 시스템 프롬프트가 아니라 사용자 메시지로 전달된다는 점입니다. 강제 규칙이 아니라 참고 지침이라는 뜻이므로, 절대 어기면 안 되는 사항(삭제 금지, 외부 발송 금지 같은 것)은 CLAUDE.md 문장만으로 안심하지 말고 후크나 권한 설정 같은 강제 장치를 따로 걸어야 합니다.

자주 하는 실수

생각날 때마다 규칙을 계속 추가함

매 세션 통째로 읽히는 파일이라 규칙이 늘수록 다른 규칙이 읽힐 확률이 줄어듭니다. 같은 지적을 반복해서 받은 것만 남기고 200줄 이내로 유지합니다.

모호하거나 서로 어긋나는 규칙을 적음

"코드를 깔끔하게 정리하라" 같은 문장은 지켜졌는지 확인할 수 없습니다. 규칙끼리 어긋나면 클로드가 둘 중 하나를 임의로 고르므로, 검증 가능한 문장으로 쓰고 낡은 규칙은 주기적으로 정리합니다.

CLAUDE.md에 적으면 반드시 지켜진다고 믿음

CLAUDE.md는 참고 지침이라 강제력이 없습니다. 삭제 금지나 외부 발송 금지처럼 절대 어기면 안 되는 사항은 후크나 권한 설정을 따로 겁니다.

자주 묻는 질문

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

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

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

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

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

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

정리

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

공식 자료

← BLOG 전체 보기무료자료 보기 →