CLAUDE.md 작성법, 뭘 넣고 뭘 빼야 클로드가 말을 듣나

3줄 요약

• CLAUDE.md에는 “매번 다시 설명하게 되는 것”만 넣는다. 코드를 읽으면 알 수 있는 것은 뺀다.
• 한 파일 200줄 아래를 지킨다. 내 프로젝트 5개 중 1개가 205줄이었고 그 파일에서만 규칙이 자주 씹혔다.
• 도구가 둘 이상이면 AGENTS.md가 원본, CLAUDE.md는 임포트 한 줄. 클로드가 배운 것은 자동 메모리에 맡긴다.

CLAUDE.md에 규칙을 적어뒀는데 클로드가 안 지킨다는 말을 자주 듣는다. 내가 겪은 범위에서 원인은 대부분 “안 적어서”가 아니라 “너무 많이 적어서”였다.

이 글은 CLAUDE.md 작성법을 줄 단위 기준으로 정리한다. 뭘 넣고 뭘 빼는지, AGENTS.md와 자동 메모리는 어디까지 맡기는지도 판정한다.

내 맥에는 CLAUDE.md가 5개 있다. 그중 하나가 공식 권장선을 넘어 있었다. 옵시디언 위키는 지난주 CLAUDE.md를 3줄로 줄이고 AGENTS.md를 원본으로 옮겼다. 그 과정을 기준 삼아 정리했다.

“CLAUDE.md는 규칙집이 아니라, 같은 말을 두 번째 할 때 적는 메모다.”

CLAUDE.md는 세션마다 새로 읽힌다

“파일을 어디에 두면 읽히나?”

클로드 코드(터미널에서 쓰는 Anthropic의 코딩 에이전트)는 세션을 열 때마다 빈 컨텍스트로 시작한다. 그래서 규칙을 매번 다시 말하지 않으려고 두는 파일이 CLAUDE.md다.

공식 문서(2026-09-05 확인)는 이 파일을 세션 시작 때 자동으로 읽는다고 설명한다. 둘 수 있는 위치는 4곳이다.

범위	위치	누구에게 적용되나
관리 정책	/Library/Application Support/ClaudeCode/CLAUDE.md(맥)	조직 전체, 개인이 끌 수 없음
사용자	~/.claude/CLAUDE.md	내 모든 프로젝트
프로젝트	./CLAUDE.md 또는 ./.claude/CLAUDE.md	저장소를 공유하는 팀 전체
로컬	./CLAUDE.local.md	나만, .gitignore에 넣는다

하나만 기억하면 된다. 이 파일은 강제 설정이 아니라 맥락이다. 클로드는 읽고 따르려 하지만 반드시 지킨다는 보장은 없다.

예외 없이 실행돼야 하는 일은 훅으로 건다. 훅이 낯설어도 괜찮다. 지금은 “정해진 시점에 자동으로 도는 스크립트” 정도로만 알면 된다.

파일이 읽혔는지 보려면 세션에서 /context를 친다. Memory files 목록에 경로가 보이면 된 것이다.

CLAUDE.md는 맥락이다. 예외 없이 실행돼야 하면 훅으로 건다.

CLAUDE.md 작성법의 기준은 하나다, 코드로 알 수 있으면 뺀다

“이 줄을 지우면 클로드가 실수하나?”

넣을 것과 뺄 것의 기준은 하나다. 클로드가 코드를 읽어서 알아낼 수 있는가. 알아낼 수 있으면 빼고 없으면 넣는다.

넣는다	뺀다
짐작할 수 없는 빌드·테스트 명령	코드를 읽으면 보이는 것
기본값과 다른 코드 스타일	언어의 표준 관례
이 프로젝트만의 설계 결정	자주 바뀌는 정보, 긴 튜토리얼
한 번 겪은 함정	“깔끔하게 짜라” 같은 당연한 말

언제 한 줄을 추가하나? 공식 문서는 4개 시점을 꼽는다. 클로드가 같은 실수를 두 번째로 했을 때, 코드 리뷰에서 걸렸을 때, 지난 세션의 교정을 또 타이핑할 때, 새 팀원에게도 같은 설명이 필요할 때다.

그래서 결론 문장이 나온다. “CLAUDE.md는 규칙집이 아니라, 두 번째로 같은 말을 하게 될 때 적는 메모다.”

이렇게 쓰면 안 먹힌다

• ✕코드를 깔끔하고 예쁘게 써라 지켰는지 확인할 방법이 없다.
• ✓들여쓰기 2칸, 커밋 전 npm test 검증 가능하다. 어겼는지 바로 보인다.

쓰는 방식도 검증 가능해야 한다. “코드를 예쁘게 써라”는 지켰는지 확인할 방법이 없다.

“들여쓰기 2칸”, “커밋 전 npm test“는 어겼는지 바로 보인다. 클로드도 뭘 바꿔야 하는지 안다.

자주 무시되는 한 줄이 있으면 그 줄에만 IMPORTANT를 붙인다. 여러 줄에 붙이면 아무것도 눈에 띄지 않는다.

검증할 수 있는 말만 적는다. 강조는 한 줄에만 붙인다.

내 파일에 실제로 남긴 줄

이 블로그의 발행 자동화 프로젝트 CLAUDE.md에서 추린 줄이다. 코드로 알 수 없는 것만 남았다.

# 발행
- 발행 스크립트 원본은 위키 저장소의 scripts/seoin_wp_publish.py. 홈 폴더의 옛 사본은 쓰지 않는다
- `--env` 경로를 항상 지정한다. 기본값이 seoin.dev라 빠뜨리면 donbrief 글이 엉뚱한 사이트로 나간다

# 문장
- 줄표(—)는 제목·본문 어디에도 쓰지 않는다. 발행 스크립트가 오류로 막는다
- 모든 문장은 "~다"로 끝낸다

# 함정
- frontmatter 리스트는 2칸 들여쓰기. 0칸이면 파서가 값을 빈 문자열로 읽는다

셋 다 한 번씩 실제로 사고가 났던 자리다.

200줄 규칙, 내 파일 5개로 재봤다

“길면 왜 안 지키나?”

공식 문서는 파일당 200줄 아래를 권한다. 길수록 컨텍스트를 먹고 준수율이 떨어진다.

줄 수를 세는 명령이 낯설면 파일을 열어 스크롤 길이만 봐도 된다. 나는 wc -l로 세어봤다.

프로젝트	줄 수	크기	판정
한글 윤문 하네스	205	17KB	초과
디스코드 브릿지	124	10KB	여유 있음
쇼츠 제작 자동화	77	5KB	여유 있음
옵시디언 위키 CLAUDE.md	3	0.2KB	포인터만
옵시디언 위키 AGENTS.md	57	6.5KB	원본, 여유 있음

205줄짜리 파일이 문제였다. “철칙” 아래 금지 항목이 줄줄이 있는데, 그 금지를 클로드가 넘기는 일이 다른 프로젝트보다 잦았다.

길이 하나 때문이라고 100% 단정하지는 못한다. 다만 공식 문서의 설명과 정확히 겹쳤다. 규칙이 있는데도 계속 어기면 파일이 너무 길어 그 규칙이 묻힌 것이다.

넘친 줄은 3갈래로 옮긴다. 여러 단계 절차는 스킬로 빼면 부를 때만 읽힌다. 특정 폴더 규칙은 .claude/rules/에 두고 paths로 범위를 정한다. 반드시 지킬 것은 훅으로 옮긴다.

처음이라면 손으로 지우기보다 /doctor부터 돌리는 편이 낫다. 저장소에 이미 있는 파일이면 잘라낼 후보를 골라준다. 코드로 알 수 있는 부분은 잘라내고 함정과 이유는 남긴다.

200줄 아래. 절차는 스킬, 폴더 규칙은 rules, 강제는 훅으로.

AGENTS.md와 CLAUDE.md, 둘 다 있어야 하나

“도구가 둘이면 규칙 파일도 둘인가?”

AGENTS.md는 특정 회사 파일이 아니다. Codex·Cursor·Jules·Copilot 코딩 에이전트 등 20개 넘는 도구가 읽는 공개 포맷이다.

지금은 리눅스 재단 산하 Agentic AI Foundation이 관리한다. 공식 사이트 기준으로 6만 개 넘는 공개 저장소가 쓰고 있다(2026-09-05 확인).

그런데 클로드 코드는 AGENTS.md를 직접 읽지 않는다. 대신 CLAUDE.md 첫 줄에 @AGENTS.md라고 쓰면 그 파일을 통째로 불러온다.

내 위키가 이 방식이다. 다른 AI가 위키를 읽을 때 규칙을 못 찾는 문제가 생겨서 규칙 57줄을 AGENTS.md로 옮기고 CLAUDE.md는 “원본은 AGENTS.md다”라는 3줄만 남겼다.

상황	파일 구성
클로드 코드만 쓴다	CLAUDE.md 하나
도구 2개 이상, 규칙은 같다	AGENTS.md 원본 + CLAUDE.md는 @AGENTS.md 한 줄
도구 2개 이상, 클로드 전용 지시가 있다	위 구성 + CLAUDE.md 아래쪽에 클로드 전용 절

판정 도구가 둘 이상이면 AGENTS.md가 원본, CLAUDE.md는 @AGENTS.md 한 줄이다.

자동 메모리는 CLAUDE.md와 뭐가 다른가

“내가 안 썼는데 클로드가 기억하는 건 뭔가?”

클로드 코드에는 내가 쓰지 않아도 채워지는 두 번째 기억이 있다. 자동 메모리, 클로드가 교정과 선호를 스스로 적어두는 파일이다.

항목	CLAUDE.md	자동 메모리
누가 쓰나	내가	클로드가
내용	지시와 규칙	배운 것과 패턴
용도	코딩 표준·작업 흐름	내 선호, 내가 준 교정

저장 위치는 ~/.claude/projects/<프로젝트>/memory/이고 MEMORY.md가 색인이다. 색인은 매 세션 첫 200줄 또는 25KB까지 읽힌다.

내 것을 열어보니 메모리 파일 16개, 색인 37줄이었다. “이 도구는 에이전트 모드 대신 repl로” 같은 교정이 feedback 파일로 남아 있었다.

내가 정한 규칙은 하나다. 원본은 위키, 메모리는 포인터. 결정의 전문은 위키에 쓰고 메모리에는 문서 위치와 한 줄 요약만 남긴다. 같은 사실이 두 곳에 다르게 남으면 클로드가 오래된 쪽을 믿는다.

판정 규칙은 CLAUDE.md에 내가 쓰고, 교정과 선호는 메모리에 맡기고, 가끔 /memory로 감사한다.

흔한 오해 세 가지

“CLAUDE.md에 적어두면 무조건 지키는 거 아닌가?” 그렇게 믿기 쉽다. 공식 문서도 시스템 프롬프트가 아니라 그 뒤에 붙는 사용자 메시지로 전달된다고 설명한다. 예외 없이 실행돼야 하면 훅이다.

“@ 임포트로 파일을 나누면 컨텍스트가 줄지 않나?” 안 줄어든다. 임포트한 파일도 시작 때 전부 읽힌다. 줄이려면 .claude/rules/의 paths처럼 조건부로 읽히게 만들어야 한다.

“/init 한 번 돌리면 끝 아닌가?” 시작점이다. 빌드 명령과 구조는 채워주지만 함정과 이유는 내가 겪은 뒤에야 적을 수 있다.

정리

• CLAUDE.md는 코드로 알 수 없는 것만 넣는다. 명령·설계 결정·함정이 그것이다.
• 한 파일 200줄 아래. 넘치면 절차는 스킬, 폴더별 규칙은 rules, 강제는 훅으로 뺀다.
• 도구가 둘 이상이면 AGENTS.md가 원본, CLAUDE.md는 @AGENTS.md 한 줄이다.
• 교정과 선호는 자동 메모리에 맡기고 /memory로 가끔 감사한다.

5분 안에 해볼 것은 하나다. 프로젝트 폴더에서 wc -l CLAUDE.md로 줄 수를 세고 200을 넘으면 줄마다 “이 줄을 지우면 클로드가 실수하나?”를 묻는다. 아니라고 답한 줄부터 지운다.

CLAUDE.md를 다르게 나눠 쓰는 방법이 있으면 댓글로 알려주면 좋겠다. 내 위키의 AGENTS.md 구성도 아직 실험 중이다.

검증 기준

• 마지막 업데이트일: 2026-09-05
• 확인 환경: Claude Code v2.1.261, macOS. 내 프로젝트 CLAUDE.md 5개(줄 수·바이트를 wc로 확인), bono 위키 AGENTS.md, 자동 메모리 디렉토리(~/.claude/projects/<프로젝트>/memory/) 직접 확인
• 주요 근거: Claude Code 공식 문서, How Claude remembers your project · Claude Code 공식 문서, Best practices · AGENTS.md 공식 사이트