CLAUDE.md 작성법: 매번 설명하던 것을 파일 하나로

채팅형 AI에는 대화마다 다시 설명하지 않도록 미리 저장해두는 맞춤 지침이 있습니다. Claude Code(클로드 코드)에도 이와 비슷한 자리가 있는데, 매 세션을 시작할 때마다 자동으로 읽어 들이는 CLAUDE.md 파일입니다.

"저희 고객사는 항상 이런 형식으로 리포트를 써주세요." Claude Code 새 세션을 열 때마다 이 말을 다시 타이핑하고 있다면 신호입니다.

지난 레슨에서 다섯 확장 장치가 각각 무엇을 대신하는지 확인했다면, 오늘은 그중 가장 먼저 손이 가는 CLAUDE.md 파일 하나를 직접 만들 차례입니다. CLAUDE.md 작성법이 급해서 오셨다면 이 레슨만 보셔도 됩니다. 파일 형식 자체는 잘 안 바뀌는 편이지만 관련 명령이나 설정 화면은 릴리스마다 조금씩 달라질 수 있으니, 오래된 시점에 읽으신다면 공식 문서를 함께 확인해 주세요.

CLAUDE.md

CLAUDE.md는 프로젝트나 개인 작업 방식, 조직 전체에 적용되는 지침을 담은 마크다운 파일로, Claude Code가 매 세션을 시작할 때마다 전체 내용을 읽어 들인다. 새 세션마다 손으로 다시 설명하던 규칙을 여기 적어두면 다시 말할 필요가 없다.

CLAUDE.md 두는 곳: 세 자리

CLAUDE.md는 한 자리에만 있는 파일이 아닙니다. 자동완성에도 "claude.md 위치"가 상위 쿼리로 잡힐 만큼 헷갈리는 지점입니다. 공식 문서가 정리한 위치 중 개인이나 소규모 팀이 실제로 쓰는 세 자리만 추리면 이렇습니다.

셋 다 겹치는 부분이 있다는 점이 중요합니다. 공식 문서는 이 파일들이 서로를 덮어쓰지 않고 전부 컨텍스트에 이어 붙는다고 설명합니다. 세션을 시작하면 홈의 CLAUDE.md가 먼저 읽히고 그 뒤에 프로젝트의 CLAUDE.md가 이어집니다. 둘의 내용이 부딪히면 Claude(클로드)는 판단을 내려야 하는데, 대개는 더 구체적인 쪽, 그러니까 나중에 읽은 프로젝트 쪽을 따르는 편입니다. 강제 규칙이 아니라 판단이라는 점은 기억해 둘 만합니다.

이 글의 관통 시나리오인 고객사 월간 콘텐츠 리포트로 예를 들어 보겠습니다. "나는 존댓말보다 평서문을 선호한다" 같은 내 작업 습관은 홈에 둡니다. 어느 프로젝트를 열든 따라옵니다. "이 리포트는 표 첫 칸이 게시일이다" 같은 이 고객사만의 규칙은 프로젝트 루트에 둡니다. 팀원과 함께 쓰는 저장소라면 버전 관리에 커밋해서 같이 봅니다. 여기에 하나 더, 이 고객사의 접속 정보처럼 저장소에 커밋하면 안 되는 개인 메모가 있다면 ./CLAUDE.local.md에 적고 .gitignore에 올려둡니다. 프로젝트 CLAUDE.md와 함께 로드되지만 나만 봅니다. (조직 전체에 배포하는 관리자용 CLAUDE.md도 있지만 IT 부서가 있는 큰 조직 이야기라 여기서는 다루지 않습니다.)

CLAUDE.md에 적을 것: 검증 가능하게

직접 만들어보는 게 가장 빠릅니다. 고객사 월간 콘텐츠 리포트의 형식과 표기 규칙을 프로젝트 루트의 CLAUDE.md에 적어보겠습니다.

# 고객사 월간 콘텐츠 리포트 규칙
 
## 형식
- 리포트 제목은 "{고객사명} {YYYY년 M월} 콘텐츠 리포트" 형태로 쓴다
- 표의 첫 칸은 항상 게시일(YYYY-MM-DD), 둘째 칸은 채널명이다
- 채널명은 줄이지 않는다: "인스타" 대신 "인스타그램"이라고 쓴다
 
## 표기 규칙
- 숫자는 천 단위마다 콤마를 찍는다 (12,345)
- 증감률은 소수점 첫째 자리까지, 부호를 함께 쓴다 (+3.2%, -1.5%)
- 지난달과 비교하는 문장에는 반드시 근거 수치를 괄호로 병기한다

공식 문서가 안내하는 요령은 검증 가능할 만큼 구체적으로 쓰는 것입니다. "표를 깔끔하게 정리해줘"보다 "표의 첫 칸은 게시일이다"가 낫고, "숫자를 보기 좋게"보다 "천 단위 콤마"가 낫습니다. Claude가 규칙을 지켰는지 안 지켰는지 눈으로 바로 판단할 수 있어야 합니다. 마크다운 헤더와 목록으로 묶어두면 Claude도 사람처럼 구조를 따라 읽습니다.

빈 파일부터 채우기가 막막하다면 /init을 먼저 쳐보는 것도 방법입니다. Claude Code가 프로젝트 코드를 훑어서 빌드 명령이나 테스트 방법, 폴더 구조 같은 것을 스스로 찾아내고 CLAUDE.md 초안을 만들어줍니다. 이미 CLAUDE.md가 있는 프로젝트라면 덮어쓰지 않고 개선할 점을 제안하는 쪽으로 동작합니다. 다만 코드가 없는 프로젝트, 그러니까 리포트 형식이나 표기 규칙처럼 코드만 봐서는 알 수 없는 내용은 /init이 대신 채워주지 않습니다. 그 부분은 위 예시처럼 직접 적어야 합니다.

CLAUDE.md에서 뺄 것: 길이는 비용이다

CLAUDE.md는 길이가 곧 비용입니다. 공식 문서는 CLAUDE.md 전체 내용이 세션을 시작할 때마다 컨텍스트 창에 그대로 올라가고, 그 이후 모든 요청마다 함께 딸려 간다고 설명합니다. 대화가 길어질수록, 파일 자체가 길어질수록 매번 그만큼의 토큰을 반복해서 소비한다는 뜻입니다. 그래서 공식 문서는 CLAUDE.md 하나를 200줄 이하로 유지하라고 권합니다. 이보다 길어지면 컨텍스트를 더 먹는 것을 넘어 Claude가 정작 중요한 규칙을 놓칠 확률도 올라갑니다.

저도 이 비용을 모른 채 그대로 냈습니다. 처음 생성된 CLAUDE.md를 제대로 살펴보지 않고 쓰기 시작한 게 출발이었습니다. Claude가 규칙을 지키다가도 가끔 어긋나길래, 그때마다 강조 표시를 붙이고 우선순위를 끌어올리며 여러 번 고쳤습니다. 몇 줄로 시작한 파일이 순식간에 100줄을 넘겼고, 저는 그 상태로 한참을 더 썼습니다. 그렇게 쓰는 게 아니라는 건 나중에 공부하면서 알았습니다. 어긋날 때 필요한 건 강조를 덧대는 게 아니라 정리였습니다.

그럼 무엇을 빼야 할까요. 기준은 "이 줄을 지우면 Claude가 실수를 할까"입니다. 아니라면 지웁니다. 공식 문서가 제외 대상으로 꼽는 것들이 실무에서 자주 걸립니다. 코드나 파일 구조를 보면 Claude가 스스로 알아낼 수 있는 내용, 자주 바뀌는 정보(이번 달 요금이나 이번 주 마감일 같은 것), 긴 설명이나 튜토리얼, API 문서 전문(링크로 대체) 같은 것들입니다. 우리 시나리오로 치면 "리포트 만드는 법을 처음부터 끝까지 설명"은 CLAUDE.md가 아니라 다음 레슨 이후에 배울 스킬의 몫입니다.

우리 시나리오로 하나만 더 짚으면, "이번 달 마감은 25일이다" 같은 문장은 CLAUDE.md에 넣지 않는 편이 낫습니다. 다음 달이면 틀린 말이 되는데 파일을 매번 고치러 돌아올 사람은 없기 때문입니다. 마감일이 매번 바뀌는 규칙이라면 그건 CLAUDE.md가 아니라 그때그때의 프롬프트에서 알려주면 됩니다.

무엇을 어떻게 적을지의 표현 방식은 이미 다룬 적이 있습니다. 금지 목록을 길게 늘어놓기보다 원하는 동작을 구체적으로 적는 편이 낫다는 원칙은 프로젝트 지침 레슨에서 다룬 것과 같은 원칙이고, CLAUDE.md에도 그대로 적용됩니다. "이렇게 쓰지 마세요"를 나열하는 대신 "이렇게 쓰세요"를 하나 더 적는 편이 실제로 더 잘 통합니다.

실무에서 한 가지 더 걸리는 지점이 있습니다. 세션 도중에 CLAUDE.md를 고쳐도 그 세션에는 바로 반영되지 않습니다. Claude Code는 세션을 시작할 때 파일을 한 번 읽어서 기억해두기 때문입니다. 고친 내용은 /clear나 /compact를 하거나 세션을 새로 열어야 반영됩니다. "방금 고쳤는데 왜 안 먹히지"라는 의심이 든다면 대개 이 문제입니다.

AGENTS.md와 뭐가 다른가

자동완성에 "claude.md agents.md"가 함께 잡히는 이유가 있습니다. Claude Code 말고 다른 코딩 에이전트를 함께 쓰는 저장소가 늘면서 생긴 혼동입니다. 답은 명확합니다. 공식 문서는 Claude Code가 CLAUDE.md만 읽고 AGENTS.md는 읽지 않는다고 못박습니다.

이미 AGENTS.md로 다른 에이전트에게 지침을 주고 있는 저장소라면, 공식 문서가 권하는 방법은 CLAUDE.md를 새로 만들되 그 안에서 AGENTS.md를 불러오는 것입니다. 파일 맨 위에 @AGENTS.md라고 한 줄만 적으면 Claude Code가 세션 시작 시 그 내용을 그대로 가져와 읽습니다. 그 아래에 Claude Code에서만 필요한 내용을 더 적으면 됩니다.

@AGENTS.md
 
## 클로드코드 전용
- src/billing/ 아래를 고칠 때는 Plan Mode를 쓴다

Claude Code 전용으로 더할 내용이 없다면 ln -s AGENTS.md CLAUDE.md로 심볼릭 링크만 걸어도 됩니다(윈도우에서는 관리자 권한이 필요해 @AGENTS.md 방식을 씁니다). 두 방법을 고르는 기준은 단순합니다. Claude Code에게만 따로 시킬 말이 하나라도 있다면 @AGENTS.md 임포트를 쓰고, 정말 아무것도 더할 게 없다면 심볼릭 링크로 끝냅니다.

이 블로그가 쓰는 저장소의 CLAUDE.md도 정확히 이 구조입니다. 맨 위 몇 줄에서 AGENTS.md가 원천이라고 밝힌 뒤 @AGENTS.md로 불러오고, 그 아래에 Claude Code에서만 쓰는 등록 스킬 목록이 이어집니다. 핵심 규칙(금지 사항, 빌드 명령, 콘텐츠 구조)은 AGENTS.md 한 곳에만 적어두고 Claude Code는 그걸 가져다 쓸 뿐입니다. CLI 트랙에서 함께 다룬 Codex(코덱스) CLI처럼 다른 도구도 이 저장소를 다룰 일이 있다면, 규칙을 두 벌로 관리하지 않아도 되는 구조입니다.

자동 메모리란: 클로드가 스스로 쌓는 기록

CLAUDE.md 말고 하나가 더 있습니다. Claude Code는 기본적으로 자동 메모리라는 걸 켜둔 채로 시작합니다. 이름 그대로 내가 쓰는 게 아니라 Claude가 알아서 씁니다. 세션에서 일하다가 내가 정정해준 것, 코드만 봐서는 알 수 없는 진행 상황이나 결정, 나중에 참고할 자료의 위치 같은 것을 Claude가 스스로 판단해서 기록해둡니다. ~/.claude/projects/ 아래 프로젝트별 폴더 안의 memory/ 디렉토리에 MEMORY.md라는 인덱스 파일과 주제별 파일들로 저장되고, 세션을 시작할 때 인덱스 파일의 앞부분(200줄 또는 25KB 중 먼저 걸리는 쪽까지)이 자동으로 로드됩니다. /memory를 열면 켜고 끌 수 있고 쌓인 내용도 확인할 수 있습니다. 기본값은 켜짐입니다.

이 구도, 어디서 본 것 같지 않으신가요? 트랙 ①의 메모리와 맞춤 지침 레슨에서 다룬 구도가 그대로 터미널로 넘어온 것입니다. 웹에서 AI가 알아서 저장해두던 "메모리"가 터미널에서는 자동 메모리로, 내가 직접 써서 고정해두던 "맞춤 지침"이 CLAUDE.md로 자리만 바뀌었을 뿐 역할은 같습니다.