CLAUDE.md가 무엇인가
먼저 파일부터 설명합니다. Claude Code로 작업할 때, 매번 처음부터 설명하지 않아도 되도록 「이건 알아 두었으면 하는 것」을 적어 두는 마크다운 파일이 CLAUDE.md입니다. 새 대화를 열 때마다 자동으로 함께 읽힙니다.
여기에 보통 적는 것은 이런 것들입니다. 이 프로젝트가 무엇을 하는 것인지, 어떤 명령으로 실행하고 테스트하는지, 쓰지 말아야 할 라이브러리가 무엇인지, 답변은 한국어로 할 것인지.
여기서 오해가 하나 생깁니다. 이 파일이 설정 파일처럼 강제된다고 생각하는 것입니다. 그렇지 않습니다. CLAUDE.md는 매번 함께 읽히는 지침 모음이고, 읽히는 것과 지켜지는 것은 다릅니다. 그래서 파일이 길어질수록 규칙끼리 자리를 다투고, 정작 중요한 지시가 사소한 지시에 묻힙니다.
이 사이트에서 한 번 다룬 「Claude가 실제로 따르는 CLAUDE.md는 어떻게 쓰는가」가 그 이야기였습니다. 그쪽이 한 파일을 어떻게 쓰느냐였다면, 이 글은 파일을 어디에 두느냐입니다.
세 자리 — 어디에 두면 어디까지 적용되나
권장 배치는 세 계층입니다. 같은 이름의 파일인데 어디에 두느냐로 적용 범위가 달라집니다.
| 자리 | 적용 범위 | 적기 좋은 것 |
|---|---|---|
| 홈 디렉터리 (~/.claude/CLAUDE.md) | 내 컴퓨터의 모든 프로젝트 | 답변 언어, 커밋 메시지 습관, 항상 지켰으면 하는 태도 |
| 프로젝트 루트 (./CLAUDE.md) | 그 저장소 전체 | 이 프로젝트가 무엇인지, 실행·테스트 명령, 저장소 전역 금지사항 |
| 개별 폴더 (./src/api/CLAUDE.md) | 그 폴더에서 작업할 때만 | 그 영역에만 있는 규칙 — API 응답 형식, 특정 폴더의 코드 관례 |
셋 다 읽힌다 — 그리고 충돌하면 구체적인 쪽이 이긴다
세 파일은 골라서 하나만 읽히는 게 아닙니다. 해당하는 것이 전부 로드돼 병합됩니다.
그래서 규칙이 서로 어긋나는 경우가 생기는데, 이때는 가장 구체적인 파일이 이깁니다. 폴더의 CLAUDE.md가 프로젝트 루트를 이기고, 프로젝트 루트가 홈 디렉터리를 이깁니다.
이 순서가 왜 자연스러운지는 회사 규정에 비유하면 쉽습니다. 전사 규정이 있고 부서 규정이 있고 팀 규칙이 있을 때, 셋이 어긋나면 가장 가까운 팀 규칙을 따르는 것과 같습니다.
중요한 건 이 우선순위가 있다는 사실이 아니라, 그것을 쓸 수 있게 자리를 나눠야 작동한다는 점입니다. 전부 한 파일에 있으면 우선순위를 매길 축 자체가 없습니다.
한 파일에 몰면 무엇이 깨지나 — 조용한 충돌
여기가 이 안티패턴의 핵심입니다. 규칙이 많아서 문제인 게 아니라, 규칙이 자기 자리를 벗어나서 문제입니다.
예를 들어 프런트엔드 폴더에서만 필요한 「스타일은 인라인으로 쓰지 말고 유틸리티 클래스로」라는 지침이 프로젝트 루트에 있다고 합시다. 데이터 정리 스크립트를 짜는 작업에도 이 문장이 따라옵니다. 데이터 스크립트에는 스타일이 없으니 아무 일도 안 일어날 것 같지만, 그렇지 않습니다. 무관한 지침도 읽히는 만큼 다른 지침의 상대적 무게를 깎습니다.
더 나쁜 경우는 실제로 어긋나는 때입니다. 루트에 「모든 함수에 타입을 명시할 것」이 있는데, 어떤 폴더는 자동 추론에 맡기는 관례를 쓰고 있다면 두 규칙이 매번 부딪힙니다.
그런데 이 충돌은 실패로 드러나지 않습니다. 빌드가 깨지지도, 경고가 뜨지도 않습니다. 결과가 미묘하게 어긋나는 형태로 나타나고, 어느 줄이 어느 줄과 싸웠는지는 어디에도 안 찍힙니다. 그래서 오래갑니다.
어떤 줄을 어디로 옮기나 — 판정 질문 하나
실제로 정리할 때는 규칙마다 질문 하나만 던지면 됩니다. 「이 규칙이 이 저장소의 모든 폴더에 맞나?」
맞으면 그대로 둡니다. 아니면 그 규칙이 실제로 적용되는 폴더의 CLAUDE.md로 옮깁니다. 없으면 그 폴더에 새로 만듭니다. 파일 이름은 어디서나 CLAUDE.md로 같습니다.
한 단계 더 올려 볼 수도 있습니다. 「이 규칙이 이 프로젝트가 아니라 내 모든 작업에 맞나?」 맞으면 홈 디렉터리로 올립니다. 답변 언어나 커밋 메시지 습관 같은 것이 여기 해당합니다.
핵심은 지우는 게 아니라 옮기는 것입니다. 규칙을 없애자는 이야기가 아니라, 필요 없는 자리에서 읽히지 않게 하자는 이야기입니다.
~/.claude/CLAUDE.md # 모든 프로젝트에 적용
my-project/
├── CLAUDE.md # 이 저장소 전체에 적용
├── src/
│ ├── api/
│ │ └── CLAUDE.md # api 폴더에서 작업할 때만
│ └── web/
│ └── CLAUDE.md # web 폴더에서 작업할 때만
└── scripts/
오늘 해 볼 것 하나
CLAUDE.md를 열어 위에서부터 한 줄씩 읽으며 「이 규칙이 이 저장소 전체에 맞나」를 물어보십시오. 스무 줄이 넘는 파일이라면 서너 줄은 반드시 아니라고 나옵니다.
그 줄들을 잘라내서 해당 폴더의 CLAUDE.md에 붙입니다. 파일이 없으면 만듭니다. 그게 오늘 할 일 전부입니다.
효과는 다음 대화부터 나타납니다. 무관한 작업을 시켰을 때 엉뚱한 지침이 끌려오지 않고, 정작 지켰으면 하는 규칙이 상대적으로 더 크게 읽힙니다.
다음 편은 세 번째 안티패턴입니다. 에이전트 하나에 툴을 몇 개까지 붙여도 되는가에 대한 이야기입니다.