CLAUDE.md는 클로드 코드(Claude Code)에게 주는 프로젝트 지시서다. 대화를 시작할 때마다 자동으로 읽히며, 코드 스타일이나 폴더 구조 같은 규칙을 적어두면 매 대화마다 다시 설명하지 않아도 된다.
처음 md 파일을 만들때 200줄 까지 채웠었다. 코딩 스타일, 변수명 규칙, 주석 형식, 폴더 구조, 예외 처리 방법까지 한 파일에 넣었던 결과였다.하지만 md 파일에 지침이 많다고해서 지시사항을 제대로 따르는 것은 아니였다. 클로드가 규칙 절반을 그냥 무시했다. 너무 많은 지시는 없는 것과 같다는 걸 그때 알았다.
클로드 코드가 CLAUDE.md를 읽는 방식
세션을 시작할 때마다 자동으로 불러온다
클로드는 CLAUDE.md가 있으면 세션을 시작할 때 자동으로 읽는다. 별도 설정이나 명령어가 없어도 된다.
클로드 코드는 현재 작업에 가까운 md 파일 일수록 우선 적용한다. 홈 디렉토리(`~/.claude/CLAUDE.md`)에 두면 모든 프로젝트에 공통으로 적용된다. 프로젝트 루트에 두면 그 프로젝트에만 적용된다. 둘 다 있으면 두 파일을 모두 읽되, 프로젝트 루트 쪽이 우선한다.
파일이 길어질수록, 중요한 규칙은 잃어버린다
md에는 시스템 프롬프트(AI에게 주는 초기 지시)에 포함된다. 파일이 길어질수록, 중요한 규칙은 잃어버리게 된다.
실제로 200줄짜리 md를 써봤더니 클로드가 뒤쪽 규칙을 자주 잊어버렸다. 앞에 있는 규칙은 잘 반영했다. 짧게 유지하는 게 단순히 편의 때문이 아니라 성능의 문제였다.
폴더마다 md 파일을 따로 두는 이유
클로드 코드는 작업 중인 파일에 가까운 md파일을 우선 읽는다. `src/` 안에서 작업하면 `src/CLAUDE.md`가 루트보다 강하게 적용된다. 기능별로 폴더를 나눠 규칙을 두면 클로드가 맥락에 맞게 따른다.
루트 md 파일에서는 `@파일경로`로 각 하위 파일을 연결해줘야 한다.
프로젝트 루트/
├── CLAUDE.md ← src, docs md 파일 연결
├── src/
│ └── CLAUDE.md ← 소스 코드 규칙만
└── docs/
└── CLAUDE.md ← 문서 규칙만루트에 있는 md 파일이 길어지기 시작하면 기능별로 md 파일 분리를 고민할 타이밍이다.
클로드의 실수가 더 정교한 md 파일을 만든다
처음에 뭘 넣어야 하는지 몰랐다
클로드 코드에는 `/init` 명령어가 있다. 실행하면 프로젝트를 분석해서 기초 CLAUDE.md를 자동으로 만들어준다.
그걸로 시작했는데 그게 끝이 아니었다. 프로젝트 정보와 기본 코딩 컨벤션 등 필요한 것들을 추가하다 보니 200줄이 넘었다. 클로드가 규칙을 잘 안 따르는 것처럼 느껴졌다. 무엇이 문제인지 몰랐다.
그러다 md 파일은 기능별로 쪼개는 게 좋다는 팁을 보게 됐다. 그렇게 수정했다. `/init`으로 만든 파일도 결국 프로젝트에 맞게 계속 손봐야 했다. 클로드가 실수할 때마다 한 줄씩 추가하는 방식으로 지금까지 고쳐왔다.
추상적으로 길게 쓴 규칙보다 명확한 규칙을 더 잘 따른다
“서비스의 성능에 영향이 없는 좋은 코드를 써라”처럼 추상적인 지시는 내가 원하는 대로 작동하지 않았다. “함수 하나에 역할 하나”는 따랐다. “모든 함수에 한 줄 주석을 달아라”는 반영됐다. 뭘 해야 하는지 바로 알 수 있는 규칙일수록 잘 따랐다.
지금은 규칙을 적기 전에 한 번 확인한다. 이게 실제로 뭘 하라는 건지 바로 답이 나오는가. 답이 안 나오면 다시 쓴다.
마치며
CLAUDE.md는 처음부터 잘 쓸 수 없다. 뭘 적어야 할지 모르는 게 정상이다.
`/init` 명령어로 기초 파일을 만들고, 기능별로 쪼개고, 클로드가 실수할 때마다 계속 손보면 된다. 그렇게 다듬은 규칙이 실제로 프로젝트에 맞는 md 파일이 된다.
처음엔 `/init` 결과물에서 시작해도 충분하다. 규칙은 쓰면서 만들어진다.