세션을 새로 시작할 때마다 "주석은 한국어로", "커밋 전에 테스트 돌려", "이 폴더는 건드리지 마"를 다시 설명하고 있다면, CLAUDE.md가 없거나 잘못 쓰여 있는 것입니다. 이 파일은 작업을 시작할 때 자동으로 읽히는 프로젝트 규칙서라, 한 번 잘 써두면 같은 말을 반복할 일이 사라집니다. 어디에 두는지, 무엇을 적고 무엇을 빼야 하는지 정리했습니다.
1. CLAUDE.md는 무엇을 하는 파일인가
대화로 전달한 지시는 세션이 끝나면 사라집니다. 반면 CLAUDE.md에 적어둔 내용은 작업을 시작할 때마다 자동으로 함께 읽히므로, 매번 설명할 필요가 없습니다.
즉 "기억해줘"라고 부탁하는 대신 파일로 남기는 방식입니다. 팀으로 일한다면 이 파일을 저장소에 커밋해 두는 것만으로 규칙이 공유됩니다.
2. 어디에 두느냐에 따라 적용 범위가 다릅니다
| 홈 폴더의 ~/.claude/CLAUDE.md | 내 모든 프로젝트에 공통 적용되는 개인 취향 |
| 프로젝트 루트의 ./CLAUDE.md | 해당 저장소 전체. 커밋하면 팀이 함께 사용 |
| 하위 폴더의 CLAUDE.md | 그 폴더 안에서 작업할 때만 적용 |
| CLAUDE.local.md | 커밋하지 않는 나만의 로컬 설정 |
여러 위치에 파일이 있으면 더 구체적인(더 가까운) 파일의 내용이 우선합니다. 개인 취향은 홈 폴더에, 팀 규칙은 저장소에 두는 식으로 나누면 충돌이 줄어듭니다.
3. 시작은 /init, 핵심은 '절반으로 줄이기'
빈 파일부터 쓰려면 막막합니다. 프로젝트 폴더에서 /init 명령을 실행하면 코드베이스를 훑어 초안을 만들어 줍니다.
중요한 것은 그다음입니다.
생성된 초안을 절반으로 줄이는 작업이 실제로 가장 큰 효과를 냅니다.
특히 빌드·테스트·실행 명령어를 정확한 형태로 맨 위에 올려두는 것이 투자 대비 효과가 가장 큽니다. 명령어 한 줄이 잘못 추측되는 것만 막아도 시간이 크게 절약됩니다.
4. 무엇을 적어야 할까
- 정확한 명령어 – 빌드, 테스트, 개발 서버 실행 커맨드를 그대로
- 절대 하면 안 되는 것 – "main 브랜치에 직접 커밋 금지" 같은 금지 규칙
- 프로젝트 고유의 약속 – 폴더의 의미, 파일 네이밍 규칙
- 함정 – "이 파일은 자동 생성되니 직접 수정하지 말 것"처럼 모르면 반드시 실수하는 지점
💡 판단 기준 "매 세션에 항상 참인 내용인가?"를 물어보세요. 지금 이번 작업에만 해당하는 내용이라면 CLAUDE.md가 아니라 그냥 대화로 말하면 됩니다.
5. 오히려 빼야 할 것들
첫째, 린터와 포매터가 이미 잡아주는 규칙.
들여쓰기 칸 수나 따옴표 종류처럼 도구가 자동으로 강제하는 항목은 적을 필요가 없습니다. 도구가 확실하게 처리할 일을 문장으로 옮기면 파일만 길어집니다.
둘째, 코드를 보면 바로 알 수 있는 설명.
폴더 구조를 그대로 나열하는 식의 내용은 금방 낡습니다. 구조가 바뀌면 오히려 틀린 정보를 매 세션 주입하는 꼴이 됩니다.
셋째, 분량 자체.
200줄을 넘어가기 시작하면 규칙의 밀도가 떨어집니다. 세부 내용은 별도 문서로 빼고 "자세한 규칙은 OO.md 참고"처럼 가리키는 방식이 훨씬 잘 작동합니다.
6. 짧게 쓴 예시
개인 프로젝트라면 이 정도 분량으로 시작해도 충분합니다. 문장마다 판단이 가능한지를 기준으로 보세요.
📄 CLAUDE.md
실행 — 개발 서버는 npm run dev, 테스트는 npm test로 실행
커밋 전 — 반드시 테스트를 돌리고, 실패하면 커밋하지 말 것
금지 — main 브랜치에 직접 커밋 금지. 작업은 항상 새 브랜치에서
주의 — src/generated/ 아래 파일은 자동 생성되므로 직접 수정 금지
스타일 — 주석과 커밋 메시지는 한국어로
상세 규칙 — API 설계 규칙은 docs/api.md 참고
여섯 줄뿐이지만 매번 반복하던 지시가 전부 들어 있습니다. 여기에 프로젝트가 커지면서 알게 된 함정을 한 줄씩 덧붙여 나가면 됩니다.
7. 어떻게 관리할까
가장 좋은 신호는 "같은 지적을 두 번 했을 때"입니다. 두 번 반복해서 고쳐줬다면, 그건 대화가 아니라 파일에 들어가야 할 내용입니다.
반대로 적어뒀는데도 지켜지지 않는 규칙이 있다면 문장이 모호할 가능성이 큽니다. "깔끔하게 작성" 같은 표현보다 "함수는 50줄을 넘기지 말 것"처럼 판단 가능한 문장으로 바꿔보세요.
규칙이 많아지면 주제별로 나누는 방법도 있습니다. .claude/rules/ 폴더에 넣은 문서들도 프로젝트 규칙으로 함께 읽히므로, 항상 필요한 것만 CLAUDE.md에 남기고 나머지는 분리하면 됩니다.
자주 묻는 질문 (FAQ)
Q. CLAUDE.md를 깃에 커밋해야 하나요?
A. 팀이 함께 지킬 규칙이라면 커밋하는 것이 맞습니다. 개인 취향이나 로컬 경로처럼 남과 공유할 필요 없는 내용은 CLAUDE.local.md에 두고 깃에서 제외하세요.
Q. 내용이 많은데 통째로 다 넣으면 안 되나요?
A. 이 파일은 매 세션 통째로 읽히기 때문에 길수록 정작 중요한 규칙이 묻힙니다. 항상 참인 규칙만 남기고 나머지는 별도 문서로 옮긴 뒤 필요할 때 참조하도록 하는 편이 결과가 좋습니다.