CLAUDE.md 작성법

CLAUDE.md는 저장소 루트에 두는 프로젝트 지침 파일입니다. 세션이 시작될 때마다 자동으로 로드되며, 매번 같은 설명을 반복하지 않아도 되게 만들어 줍니다.

만드는 법

세션 안에서 다음을 실행하면 저장소를 훑어 초안을 만들어 줍니다.

/init

초안이 나오면 반드시 손으로 다듬으세요. 자동 생성본은 "이 프로젝트가 무엇인지"는 잘 적지만, "이 팀이 무엇을 싫어하는지"는 알 수 없습니다.

무엇을 적어야 하나

반드시 적을 것

• 실행 명령 — 빌드, 테스트, 린트, 개발 서버를 어떤 명령으로 돌리는지
• 금지 사항 — 건드리면 안 되는 파일, 쓰면 안 되는 라이브러리
• 비직관적인 규칙 — 코드만 봐서는 알 수 없는 관례

적지 말아야 할 것

• 코드를 읽으면 알 수 있는 디렉터리 구조
• 일반적인 코딩 상식 ("변수명은 의미 있게")
• 과거에 한 번 있었던 사건의 서술

동작을 바꾸는 문장 vs 그렇지 않은 문장

차이는 하나입니다. 검증 가능한가. 지킨 건지 아닌지 판별할 수 없는 문장은 지침이 아니라 장식입니다.

짧게 유지해야 하는 이유

이 파일은 매 세션 항상 로드됩니다. 길면 매번 비용을 냅니다. 100줄을 넘어가기 시작하면 다음을 검토하세요.

• 특정 폴더에만 해당하는 규칙 → 그 폴더에 별도 CLAUDE.md를 둡니다
• 자주 참조하지 않는 상세 문서 → 별도 파일로 빼고 링크만 남깁니다
• 이미 지켜지고 있는 규칙 → 삭제합니다

계층 구조

지침 파일은 여러 위치에 둘 수 있고, 좁은 범위가 우선합니다.

~/.claude/CLAUDE.md        ← 모든 프로젝트 공통 (개인 설정)
프로젝트/CLAUDE.md          ← 저장소 전체 (팀 공유, 커밋 대상)
프로젝트/apps/web/CLAUDE.md ← 해당 폴더에서 작업할 때만

팀 규칙은 저장소에 커밋하고, 개인 취향(응답 언어, 말투 등)은 홈 디렉터리에 두세요.

점검 주기

지침은 한 번 쓰고 끝나는 문서가 아닙니다. 같은 지적을 세 번 반복했다면, 그건 지침에 들어가야 할 내용입니다. 반대로 반년 동안 한 번도 위반되지 않은 규칙은 지워도 됩니다.

좋은 CLAUDE.md의 기준: 새로 합류한 팀원에게 그대로 건네도 유용한가?