CLAUDE.md
CLAUDE.md는 Claude Code가 세션을 시작할 때마다 자동으로 읽는 프로젝트 안내서로, 빌드·테스트 명령이나 "이 폴더는 건드리지 마"처럼 코드만 봐서는 알 수 없는 규칙을 매번 다시 설명하지 않으려고 쓴다. 파일을 두는 위치에 따라 적용 범위가 달라진다.
| 위치 | 적용 범위 | 넣을 내용 |
|---|---|---|
~/.claude/CLAUDE.md | 내 모든 프로젝트 | 개인 선호(답변 언어, 커밋 스타일) |
./CLAUDE.md | 이 프로젝트, 팀 공유 | 빌드·테스트 명령, 컨벤션, 금지 사항 |
| 하위 폴더의 CLAUDE.md | 그 폴더 작업 시 | 특정 모듈에만 있는 규칙 |
/init으로 시작해서 실수할 때마다 키운다
처음에는 Claude Code에서 /init을 실행하면 프로젝트를 훑어보고 초안을 만들어 준다. 이후 내용을 고칠 때는 /memory로 파일을 열거나 편집기로 직접 수정한다.
가장 효과적인 방법은 작업하면서 조금씩 키우는 것이다. Claude가 같은 실수를 두 번 하면 그 교정 내용을 한 줄로 적어 둔다. 프로젝트 파일은 git에 커밋해 두면 팀원 모두가 같은 규칙으로 작업한다.
짧고 구체적으로 써야 지켜진다
CLAUDE.md는 세션마다 통째로 컨텍스트에 들어간다. 길어질수록 토큰을 더 쓰고, 중요한 규칙이 다른 내용 사이에 묻힌다. "코드를 깔끔하게"보다는 "npm run lint 통과 후 커밋"처럼 확인할 수 있게 쓴다.
| 넣는다 | 빼는다 |
|---|---|
| 자주 쓰는 명령어 | 코드를 읽으면 알 수 있는 구조 설명 |
| 프로젝트 고유의 규칙·예외 | 일반적인 코딩 상식 |
| 건드리면 안 되는 파일·폴더 | 긴 문서 원문(@경로로 불러오기) |
긴 문서는 CLAUDE.md 안에 @docs/guide.md처럼 경로를 적어 불러올 수 있다.
지시일 뿐, 강제는 아니다
CLAUDE.md의 내용은 모델이 따르려고 하는 지시이지 시스템이 막아 주는 규칙이 아니다. 반드시 지켜야 하는 것은 다른 장치를 쓴다.
| 수단 | 성격 | 이럴 때 쓴다 |
|---|---|---|
| CLAUDE.md | 지시(맥락 제공) | 컨벤션, 작업 순서, 배경 지식 |
| settings.json 권한 | 강제 허용·차단 | 특정 명령·파일 접근 금지 |
| 훅(hooks) | 강제 자동 실행 | 수정 후 포매터 실행처럼 매번 해야 하는 일 |
다른 코딩 에이전트에서 쓰는 AGENTS.md도 목적은 같다. Claude Code에서 자동으로 읽히는 이름은 CLAUDE.md이므로, 두 도구를 함께 쓴다면 한쪽 파일에서 다른 쪽을 불러오게 해 내용을 한곳에서 관리하면 된다.
팀 저장소의 공용 안내서로 가장 많이 쓴다
가장 흔한 방식은 저장소 루트에 CLAUDE.md를 두고 git에 커밋해 팀 공용 안내서로 쓰는 것이다. 그 위에 개인 선호는 홈 폴더 파일에, 모듈별 규칙은 하위 폴더 파일에 나눠 적는다.
| 어디서 | 어떻게 쓰나 |
|---|---|
| 팀 저장소 | 빌드·테스트 명령과 금지 사항을 적어 커밋하고, Claude가 같은 실수를 반복하면 한 줄씩 추가 |
| 개인 작업 환경 | 홈 폴더 파일에 답변 언어·커밋 스타일을 적어 모든 프로젝트에 똑같이 적용 |
| 여러 모듈이 있는 큰 저장소 | 모듈 폴더마다 CLAUDE.md를 두어 그 폴더를 작업할 때만 필요한 규칙을 전달 |
| 여러 코딩 에이전트를 함께 쓰는 저장소 | AGENTS.md와 한쪽에서 다른 쪽을 불러오게 해 규칙을 한곳에서 관리 |
