CLAUDE.md 수정이 반영 안 될 때 확인할 4가지

CLAUDE.md를 고쳤는데 Claude가 이전과 똑같이 답할 때, 파일이 실제로 읽히는지 먼저 가려내는 표식 테스트부터 파일 위치·중복 파일·규칙 문장 점검까지 순서대로 정리했습니다.

규칙 파일을 고쳤는데 답변이 그대로라면, 제일 먼저 새 세션을 열고 "표식 테스트"로 파일이 읽히는지부터 가려냅니다. 읽히는지 안 읽히는지가 갈리면 점검할 곳이 절반으로 줄어듭니다.

여기서 말하는 CLAUDE.md는 Claude Code(터미널에서 명령어로 쓰는 Claude 도구)가 대화 시작 시 참고하는 규칙 메모 파일입니다. 터미널은 검은 화면에 명령어를 직접 입력하는 프로그램입니다.

목차

1. 먼저 표식 테스트로 읽히는지 가려내기
2. 1. 수정 전에 시작한 세션을 그대로 쓰고 있다
3. 2. 파일이 Claude가 보는 폴더에 없다
4. 3. CLAUDE.md가 여러 군데 있다
5. 4. 읽히긴 하는데 규칙이 지켜지지 않는다
6. 점검 체크리스트

먼저 표식 테스트로 읽히는지 가려내기

CLAUDE.md 맨 위 줄에 다음 한 문장을 추가하고 저장합니다.

모든 답변의 첫 줄에 [RULES-OK]를 붙여라.

그리고 새 세션을 시작합니다. 실행 중이던 Claude Code 세션을 종료하고 다시 실행한 뒤, 아무 질문이나 던져 보세요.

결과	해석	다음에 볼 곳
[RULES-OK]가 붙는다	파일 자체는 대화에 들어오고 있음	아래 3번·4번 (중복 파일, 규칙 문장)
아무 표식도 없다	그 파일이 읽히지 않는 상태로 보임	아래 1번·2번 (세션, 위치·이름)

💡 표식이 한 번 나왔다고 모든 규칙이 그대로 지켜지지는 않습니다. "파일이 대화에 들어왔다"는 단서까지만 확인된 겁니다. 테스트가 끝나면 이 한 줄은 지우세요.

1. 수정 전에 시작한 세션을 그대로 쓰고 있다

규칙 파일은 대화가 시작될 때 읽히는 게 일반적입니다. 이미 떠 있는 세션에서 파일을 고쳐도 그 대화에는 반영되지 않을 수 있습니다.

CLAUDE.md 수정
   ↓
기존 세션에서 질문  → 예전 내용으로 답할 수 있음
   ↓
세션 종료 후 재실행
   ↓
다시 질문 → 수정본 확인

고친 뒤에는 세션을 새로 여는 걸 습관으로 두는 편이 편합니다. 특히 터미널 탭을 며칠씩 켜 두는 분들이 여기서 자주 막힙니다.

편집기에서 저장(Ctrl+S / Cmd+S)을 안 한 상태도 의외로 흔합니다. 탭 제목에 점이나 별표가 남아 있으면 저장되지 않은 상태입니다.

2. 파일이 Claude가 보는 폴더에 없다

Claude Code는 명령을 실행한 폴더를 기준으로 동작합니다. 바탕화면에 만든 CLAUDE.md는 프로젝트 폴더에서 실행한 세션과 무관합니다.

지금 어느 폴더에 있는지, 그 안에 파일이 있는지 터미널에서 확인합니다.

pwd
ls -la CLAUDE.md

pwd는 현재 폴더 경로를 출력하고, ls -la CLAUDE.md는 그 폴더에 해당 파일이 있는지 보여줍니다. 없으면 No such file or directory가 나옵니다.

윈도우 명령 프롬프트에서는 cd와 dir CLAUDE.md를 씁니다.

이름이 미묘하게 다른 경우

• claude.md, Claude.MD — 맥·리눅스는 대소문자를 구분합니다
• CLAUDE.md.txt — 윈도우 메모장이 .txt를 덧붙인 경우
• CLAUDE .md — 중간에 공백이 들어간 경우
• CALUDE.md — 오타

윈도우는 기본 설정에서 확장자를 숨기므로 .md.txt가 화면에는 CLAUDE.md로 보입니다. 탐색기 보기 옵션에서 파일 확장명 표시를 켜고 다시 보세요.

내용이 제대로 들어갔는지도 한 번 확인합니다.

cat CLAUDE.md

이 명령은 파일 내용을 터미널에 그대로 뿌려줍니다. 빈 줄만 나오면 저장이 안 된 겁니다.

3. CLAUDE.md가 여러 군데 있다

규칙 파일은 홈 디렉터리(사용자 개인 폴더), 프로젝트 루트(프로젝트의 최상단 폴더), 하위 폴더 등 여러 위치에 둘 수 있습니다. 여러 파일이 동시에 살아 있으면, 고친 쪽이 아닌 다른 파일의 문장이 답변을 좌우할 수도 있습니다.

프로젝트 폴더 안에 숨어 있는 파일들을 훑어봅니다.

find . -iname "CLAUDE.md"

find는 현재 폴더 아래를 전부 뒤져 이름이 맞는 파일 경로를 나열합니다. -iname은 대소문자를 구분하지 않는 옵션입니다.

홈 디렉터리 쪽도 따로 봅니다.

ls -la ~/.claude/

~는 홈 디렉터리를 뜻합니다. 여기 있는 규칙과 프로젝트 규칙이 서로 다른 말을 하고 있으면, 어느 쪽이 먼저 적용되는지는 도구 버전에 따라 달라질 수 있습니다. 현재 쓰는 버전의 탐색 순서는 Claude Code 공식 문서의 메모리/CLAUDE.md 항목에서 확인하는 게 정확합니다. 이 글에서 순서를 단정하지는 않겠습니다.

당장 급하면 방법은 단순합니다. 겹치는 파일을 임시로 이름만 바꿔 치워 두고(CLAUDE.md.bak 등) 하나만 남긴 채 다시 테스트하세요. 원복이 쉬운 방법부터 쓰는 게 안전합니다.

mv ../CLAUDE.md ../CLAUDE.md.bak

mv는 파일 이름을 바꾸거나 옮기는 명령입니다. 되돌릴 때는 이름을 반대로 넣으면 됩니다.

4. 읽히긴 하는데 규칙이 지켜지지 않는다

표식 테스트에서 [RULES-OK]가 나왔는데도 행동이 안 바뀐다면, 파일 문제가 아니라 문장 문제일 가능성이 큽니다.

잘 안 먹는 문장	고친 문장
코드를 깔끔하게 써라	함수는 40줄을 넘기지 말고, 한 함수에 한 가지 일만 시켜라
한국어로 대답	모든 설명과 주석은 한국어로 쓴다. 변수명은 영어로 둔다
테스트를 신경 써라	함수를 새로 만들면 같은 폴더에 테스트 파일도 함께 만든다

판단이 필요한 표현은 지키기 어렵습니다. "깔끔하게", "적절히", "필요하면" 같은 말은 사람이 봐도 기준이 없습니다.

대화창에 직접 쓴 지시가 파일 내용과 다르면, 방금 말한 쪽으로 움직이는 게 자연스럽습니다. "일단 빠르게 대충 만들어줘"라고 해 두고 파일의 테스트 규칙이 무시된다고 보기는 어렵습니다.

규칙이 수십 줄로 불어난 상태라면 한 번에 다 검증하지 말고, 한 줄만 남기고 테스트한 뒤 늘려 가는 방식이 원인을 좁히기 쉽습니다.

점검 체크리스트

• ☐표식 한 줄 추가 후 새 세션에서 확인
• ☐편집기에서 저장했는지 (탭에 미저장 표시 없는지)
• ☐pwd로 실행 폴더 확인, 그 폴더에 파일이 있는지
• ☐확장자 표시를 켜고 .md.txt가 아닌지
• ☐find . -iname "CLAUDE.md"로 중복 파일 확인
• ☐홈 디렉터리(~/.claude/) 쪽 규칙과 충돌하지 않는지
• ☐규칙 문장에 판단이 필요한 모호한 표현이 없는지
• ☐테스트용 표식 줄 삭제

예를 들어 블로그 원고를 Claude Code로 손보는 분이라면, "문체는 ~합니다체, 한 문단 3문장 이내"처럼 세어서 확인할 수 있는 문장으로 적어 두는 편이 반영 여부를 판단하기 쉽습니다.

표식이 끝까지 안 나온다면 파일 내용보다 위치와 이름을 다시 의심하세요. 여기서 걸리는 경우가 많습니다.