# CLAUDE.md

> 출처: https://retn.kr/glossary/claude-md/ · 수정 2026-10-26 · 리텐션 주식회사

**정의:** Claude Code가 세션을 시작할 때마다 읽는 마크다운 지침 파일로, 프로젝트 규칙과 맥락을 담는다.

**다른 이름:** 클로드 엠디

## 실무에서 뜻하는 것

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

## 리텐션에서 쓴 예

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

## 헷갈리기 쉬운 것

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