CLAUDE.md

실무에서 뜻하는 것

CLAUDE.md는 AI 팀원에게 주는 온보딩 문서입니다. 빌드 명령, 코딩 규칙, 폴더 구조, “항상 X를 한다” 같은 규칙을 적습니다. 홈 폴더의 ~/.claude/CLAUDE.md는 모든 프로젝트에 적용됩니다. 저장소 루트의 CLAUDE.md는 그 프로젝트에만 적용되고, Git으로 팀과 공유합니다. 공식 문서는 파일당 200줄 이하를 권합니다. 길수록 컨텍스트 윈도우를 더 차지하고 지침을 덜 따르기 때문입니다. /init을 실행하면 Claude가 코드베이스를 분석해 첫 초안을 만듭니다.

리텐션에서 쓴 예

AI 코딩 에이전트를 10명으로 늘리는 법에서는 CLAUDE.md에 네 가지만 적었습니다. 나는 누구인지, 어떻게 일하는지, 자주 쓰는 도구와 맥락, 절대 하지 말아야 할 것입니다. 작성에는 30분이 걸렸습니다. 그 뒤 대화마다 5-10분 들던 맥락 설명이 0분이 됐습니다. 결과물 수정 횟수도 3-5회에서 0-1회로 줄었습니다.

헷갈리기 쉬운 것

CLAUDE.md는 강제 설정이 아니라 맥락입니다. Claude가 반드시 지키게 하려면 훅나 권한 규칙을 씁니다. 2026-10 기준 저장소에 CLAUDE.md 없이 AGENTS.md만 있으면 Claude Code는 AGENTS.md를 대신 읽습니다.