CLAUDE.md 제대로 읽히게 쓰기

CLAUDE.md 에 규칙을 적어 두었는데 어떤 날은 지키고 어떤 날은 안 지킵니다.

Claude 에게 '규칙 읽었어?' 라고 물으면 늘 '네' 라고 합니다.

이 책은 Claude Code 의 지침 파일이 언제 · 왜 읽히는지를 Claude 의 말이 아니라 기록으로 확인합니다.

이런 일을 하고 계신다면

· CLAUDE.md 를 써 두었는데 지켜지는지 반신반의한다

· 폴더마다 · 파일 종류마다 다른 규칙을 두고 싶다

· @가져오기로 CLAUDE.md 를 나눴는데 효과가 없다

· 메모장으로 고친 뒤 한글 지시를 안 지킨다

· 다른 코딩 도구의 AGENTS.md 와 함께 쓰고 싶다

이 책에 들어 있는 것

레시피 열네 개 · 열다섯 단계 · 93쪽

01 CLAUDE.md 는 '읽혔는지' 부터 — Claude 에게 묻지 말고 기록을 봅니다

02 첫 CLAUDE.md — 있으면 [기억], 없으면 그냥. 기록에는 session_start 한 줄

03 다섯 자리 — 넷은 처음에 읽혔고, 하위 폴더 것만 안 읽혔습니다

04 하위 폴더의 CLAUDE.md — Glob 으로 보면 안 읽히고, Read 로 열 때 읽힙니다

05 @가져오기 — @ 바로 뒤가 한글이면 조용히 빠졌습니다. ./ 를 붙이면 읽힙니다

06 .claude/rules 와 paths — 맞는 파일을 열 때만 읽혔고, 머리말이 깨진 규칙은 아예 안 보였습니다

07 지시가 부딪히면 — CLAUDE.local.md 가, 아래 폴더가 이겼습니다 (여섯 번 모두)

08 400 줄 CLAUDE.md — 지켜지기는 했지만 입력 토큰이 4만 개 넘게 늘었습니다

09 HTML 주석 · cp949 · UTF-16 — '읽힘' 으로 기록됐는데 지켜지지 않았습니다

10 AGENTS.md — 혼자면 읽히고, CLAUDE.md 나 CLAUDE.local.md 가 있으면 가려집니다

11 --setting-sources 와 CLAUDE.md — project 를 빼면 CLAUDE.md 도, local 을 빼면 CLAUDE.local.md 도 빠졌습니다

12 --add-dir 로 더한 폴더의 CLAUDE.md — 그냥은 안 읽히고, 환경 변수 하나로 읽혔습니다

13 위 폴더의 남의 CLAUDE.md 빼기 — claudeMdExcludes 는 **/ 꼴도, Windows 경로 그대로도 먹었습니다

14 안 읽히는 지침을 Claude 없이 찾는 검사기 — 놀이터의 지침 파일 81개

15 지침 한 벌로 실제 일 맡기기 — 무엇이 언제 읽혔는지와 결과 파일로 6/6

조용히 빠진 것을 다 실었습니다

이 책을 만들면서 오류 하나 없이 빠진 것들입니다.

· @규칙/말투.md 처럼 @ 바로 뒤가 한글인 가져오기 — 하나도 안 읽힘 (앞에 ./ 를 붙이면 읽힘)

· 메모장 ANSI(cp949) · 유니코드(UTF-16) 로 저장한 CLAUDE.md — '읽힘' 으로 기록되고도 안 지켜짐

· CLAUDE.local.md 하나 때문에 팀의 AGENTS.md 가 통째로 가려짐

· 머리말이 깨진 paths 규칙 — 아예 안 보임

· 400 줄 CLAUDE.md — 질문마다 입력 토큰이 4만 개 넘게 늘어남

읽혔는지는 기록이 압니다

Claude Code 의 InstructionsLoaded 훅으로 어떤 지침 파일이 언제 · 왜(처음 · 가져오기 · 하위 폴더 · paths 규칙) 읽혔는지 기록했습니다.

읽혔는지는 기록으로, 지켰는지는 답과 결과 파일로 따로 봅니다.

전부 실제로 돌려 확인했습니다

2026년 10월 3일, Windows 10 · Claude Code 2.1.281 에서 레시피 열네 개를 세 판 만들어 돌렸습니다.

기록이 남은 호출 122번. 본문의 검은 상자는 그때 나온 화면 그대로이고, 부록의 코드도 실제로 돌아간 파일 그대로입니다.

지침 파일은 연습용 놀이터에만 썼고, 내 사용자 설정과 자동 기억은 건드리지 않았습니다.

이런 분께

· Claude Code 로 일을 맡기는데 규칙이 들쭉날쭉한 분

· 한글 폴더 · 메모장을 쓰는 Windows 사용자

· 팀에서 CLAUDE.md · AGENTS.md 를 관리하는 분

포함 파일

PDF (A4 · 93쪽) · EPUB (모바일 · 리더용)

두 가지가 ZIP 하나에 들어 있습니다.

「Claude Code 실전」 시리즈입니다. 이 책은 Anthropic 과 관계가 없는 개인의 사용기입니다.