CLAUDE.md 파일 위치 4곳, 로드 순서가 결과를 가릅니다

규칙은 덮어쓰이지 않고 전부 이어 붙습니다. 그래서 순서가 남습니다.

 

규칙은 덮어쓰이지 않고 전부 이어 붙습니다. 그래서 순서가 남습니다.

클로드코드에 규칙을 적어 주는 파일이 CLAUDE.md입니다. 세션을 열 때마다 통째로 읽히니까 여기 적힌 문장은 한 번이 아니라 매번 작동해요.

그런데 이 파일은 한 곳에만 있는 게 아닙니다. 네 자리에 놓일 수 있고, 전부 동시에 읽힙니다. 공식 문서를 열어 보고 나서야 제가 순서를 잘못 알고 있었다는 걸 알았어요.

 

놓이는 자리가 네 곳입니다

좁아지는 순서로 적으면 이렇습니다.

첫째, 관리 정책 자리입니다. 윈도우는 C:\Program Files\ClaudeCode\CLAUDE.md, 맥은 라이브러리 아래 ClaudeCode 폴더, 리눅스는 /etc/claude-code/CLAUDE.md예요. 회사가 배포하는 자리고, 개인 설정으로 뺄 수 없습니다.

둘째, 사용자 자리인 ~/.claude/CLAUDE.md입니다. 내 모든 프로젝트에 따라다녀요.

셋째, 프로젝트 자리입니다. ./CLAUDE.md 또는 ./.claude/CLAUDE.md 둘 다 됩니다. 팀과 공유하는 자리라 버전 관리에 들어가요.

넷째, 로컬 자리인 ./CLAUDE.local.md입니다. 내 샌드박스 주소나 테스트 데이터처럼 나만 쓰는 것을 두고, .gitignore에 넣습니다.

 

덮어쓰기가 아니라 이어 붙이기입니다

여기가 제가 잘못 알고 있던 부분입니다. 좁은 쪽이 넓은 쪽을 덮어쓸 거라고 생각했는데, 문서에는 발견한 파일이 전부 컨텍스트에 이어 붙는다고 적혀 있어요.

순서는 파일시스템 루트에서 작업 디렉터리 쪽으로 내려옵니다. foo/bar에서 실행하면 foo/CLAUDE.md가 먼저 들어가고 foo/bar/CLAUDE.md가 나중에 들어가요. 같은 폴더 안에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙습니다. 시작한 자리에 가까운 지시일수록 나중에 읽히는 셈입니다.

하위 폴더의 파일은 시작할 때 안 들어옵니다. 클로드가 그 폴더의 파일을 실제로 읽을 때 따라 들어와요.

이어 붙는다는 성질 때문에 모순이 생깁니다. 그리고 문서가 그 결과를 이렇게 적어 뒀어요. 두 규칙이 서로 모순되면 클로드가 그중 하나를 임의로 고를 수 있다고요. 경고를 띄우거나 물어보는 게 아닙니다. 고릅니다.

모노레포에서 남의 팀 규칙까지 딸려 오면 claudeMdExcludes 설정으로 특정 경로를 뺄 수 있습니다. 지금 세션에 무엇이 실제로 실렸는지는 /context를 쳐서 메모리 파일 목록으로 확인해요.

 

200줄이 목표선입니다

공식 권고는 파일당 200줄 이하고, 이유가 붙어 있습니다. 파일이 길수록 컨텍스트를 더 먹고 지시 준수율이 떨어진다고요.

그런데 줄 수라는 단위가 사람마다 다르게 걸립니다. 한 줄에 한 문장씩 짧게 쓰는 파일과, 한 줄에 긴 문단을 통째로 넣는 파일은 같은 200줄이어도 분량이 몇 배 차이가 나요. 제 파일이 후자였습니다. 줄 수로는 여유가 있는데 글자로는 아니었어요. 재실 때 줄 수와 글자 수를 같이 보시는 편이 낫습니다.

 

길어지면 나눕니다, 다만 임포트로는 안 줄어듭니다

먼저 함정부터요. CLAUDE.md는 @경로 문법으로 다른 파일을 끌어올 수 있는데, 문서가 분명히 적어 뒀습니다. 임포트한 파일도 시작할 때 같이 펼쳐져 컨텍스트에 들어갑니다. 정리는 되지만 용량은 그대로예요.

실제로 줄이는 방법은 .claude/rules/ 폴더입니다. 주제별로 파일을 나눠 두고, 각 파일 맨 위에 paths를 적어 어떤 파일을 만질 때만 불러올지 정할 수 있어요.

예를 들어 API 규칙 파일 위에 paths로 src/api/**/*.ts를 적어 두면, 클로드가 그 경로의 파일을 읽을 때만 그 규칙이 들어옵니다. 프런트 작업을 하는 동안에는 자리를 차지하지 않아요. paths가 없는 규칙 파일은 항상 실립니다.

더 드물게 쓰는 절차라면 규칙이 아니라 스킬로 빼는 편이 낫습니다. 규칙은 매번 실리고, 스킬은 필요할 때만 불려요. 매 세션 필요한가를 기준으로 가르면 됩니다.

 

주석은 컨텍스트를 안 먹습니다

작지만 유용한 성질이 하나 있어요. CLAUDE.md 안의 블록 단위 HTML 주석은 컨텍스트에 들어가기 전에 제거됩니다. 사람이 볼 메모, 이 줄을 왜 넣었는지 같은 사연을 주석으로 남기면 파일에는 남고 토큰은 안 씁니다. 코드 블록 안의 주석은 그대로 남고요.

 

반드시 지켜야 하는 건 규칙으로 적지 않습니다

이게 제일 중요한 문장 같습니다. 문서가 CLAUDE.md를 컨텍스트일 뿐 강제 설정이 아니라고 못 박아요. 잘 따르지만 보장은 아니라는 뜻입니다.

그래서 커밋 전에 반드시 돌아야 하는 것, 절대 건드리면 안 되는 경로 같은 건 규칙 문장이 아니라 훅으로 거는 게 맞습니다. 훅은 정해진 시점에 셸 명령으로 실행되니까 판단이 끼어들 자리가 없어요.

규칙에 적을 것과 훅으로 넘길 것을 갈라 보면 파일도 같이 짧아집니다. 반드시라는 말이 들어간 줄이 후보예요.

 

시작할 때와 정리할 때

빈 파일부터 쓰지 않아도 됩니다. /init를 치면 코드베이스를 훑어서 빌드 명령과 규약을 찾아 초안을 만들어 줘요. 이미 파일이 있으면 덮어쓰지 않고 보완할 곳을 제안합니다.

커서나 코파일럿 규칙 파일이 이미 있으면 /init가 그걸 읽어서 반영합니다. AGENTS.md를 쓰고 계시면 주의하실 게 있어요. 클로드코드는 AGENTS.md를 읽지 않습니다. CLAUDE.md를 만들어 첫 줄에 @AGENTS.md로 끌어오면 두 도구가 같은 문서를 봅니다.

이미 커진 파일은 /doctor에 다듬을 곳을 물어볼 수 있습니다. 코드에서 유추 가능한 디렉터리 구조나 의존성 목록을 덜어내고, 함정과 이유와 기본값과 다른 규약은 남기는 방향으로 제안해요. 클로드코드 2.1.206 이상에서 됩니다.

 

덧붙임

위 내용은 2026년 8월 5일에 클로드코드 공식 문서를 직접 열어 확인한 것입니다. 옮긴 문장은 제가 우리말로 바꾼 것이라 정확한 문구가 필요하시면 원문을 보셔야 해요.

이 파일의 품질을 여섯 가지 기준으로 채점해 주는 공식 플러그인이 따로 나와 있습니다. 그 채점표를 받아 제 파일에 직접 대 본 이야기는 원문에 적어 뒀어요. 간결성이 제일 무거운 기준이 아니었다는 것과, 경로 30개는 멀쩡했는데 손으로 관리하던 숫자 하나가 틀려 있었다는 이야기입니다.