CLAUDE.md는 Claude Code 같은 AI 코딩 도구가 세션을 시작할 때 자동으로 읽는 프로젝트 안내서입니다. 프로젝트 최상위 폴더에 두면 AI가 매번 묻지 않고 그 규칙대로 일합니다. 프로젝트 개요·명령어·코드 스타일·금지사항·커밋 규약의 다섯 섹션이면 충분하며, 짧게 유지하고 AI가 실제로 어기는 것만 적는 것이 요령입니다.
CLAUDE.md란 무엇이고 왜 필요한가?
CLAUDE.md는 Claude Code 같은 AI 코딩 도구가 세션을 시작할 때 자동으로 읽는 프로젝트 안내서입니다. 프로젝트 최상위 폴더에 이 파일이 있으면, AI는 매번 물어보지 않고 그 규칙대로 일합니다.
없으면 어떻게 될까요? AI는 세션마다 프로젝트를 처음 봅니다. 빌드 명령을 추측하고, 팀이 쓰지 않는 스타일로 코드를 쓰고, 하지 말라고 한 적 없으니 새 라이브러리를 마음대로 추가합니다. 같은 지적을 세션마다 반복하고 있다면, 그 지적이 바로 CLAUDE.md에 들어갈 내용입니다.
비슷한 파일이 도구마다 있습니다.
| 파일 | 읽는 도구 | 비고 |
|---|---|---|
CLAUDE.md | Claude Code | 하위 폴더에도 둘 수 있고, 가까운 것이 우선 적용됩니다 |
AGENTS.md | Codex 등 여러 도구 | 도구 중립적인 공통 규격으로 쓰입니다 |
.cursorrules | Cursor | 마크다운 구조 없이 규칙 나열 형식입니다 |
내용은 거의 같아서 하나를 잘 쓰면 나머지는 변환입니다.
CLAUDE.md에 무엇을 적어야 하나?
1. 프로젝트 개요 (2~3줄)
무슨 프로젝트고 어떤 스택인지. AI가 "이게 Next.js구나, 정적 사이트구나"를 아는 것만으로 잘못된 제안의 절반이 사라집니다.
## 프로젝트 개요
반려동물 용품 쇼핑몰. Next.js 14 (App Router) + TypeScript + Supabase.
정적 생성 우선 — 서버 컴포넌트가 기본이고 클라이언트 컴포넌트는 최소화한다.
2. 명령어
의외로 가장 효과가 큰 섹션입니다. 테스트·빌드 명령을 적어두면 AI가 작업을 마친 뒤 스스로 검증하고 제출합니다.
## 명령어
- 개발 서버: `npm run dev`
- 테스트: `npm test` (변경 후 반드시 실행)
- 빌드 검증: `npm run build`
3. 코드 스타일
장황한 스타일 가이드를 옮겨 적지 마세요. AI가 실제로 어기는 것만 적습니다.
## 코드 스타일
- 새 코드는 주변 코드의 네이밍·구조를 따른다. 새 패턴 도입 전에 기존 코드를 먼저 본다.
- 주석은 코드로 표현 못 하는 의도만. 코드를 반복 설명하는 주석 금지.
- any 금지. 타입 오류를 ts-ignore로 덮지 않는다.
4. 금지사항
경험상 "해라"보다 "하지 마라"가 잘 지켜집니다. 금전·보안·복구 불가능성이 걸린 것은 반드시 여기에 둡니다.
## 금지사항
- 시크릿(.env, API 키)을 절대 커밋하지 않는다.
- 새 의존성을 추가하기 전에 먼저 확인을 받는다.
- 요청받지 않은 대규모 리팩터링을 하지 않는다. 개선점은 제안만 한다.
5. 커밋 규약
## 커밋 규약
- Conventional Commits (feat:, fix:, chore:)를 따른다.
CLAUDE.md를 잘 쓰는 요령은?
- 짧게 유지하세요. 규칙이 50개면 AI는 그중 일부를 놓칩니다. 정말 지켜야 할 10개가 낫습니다. 컨텍스트는 유한한 자원입니다.
- 어긴 사례가 나올 때마다 한 줄씩 추가하세요. 처음부터 완벽한 파일을 쓰려 하지 말고, AI가 실수할 때마다 그 실수를 막는 규칙을 덧붙이는 게 현실적인 운영법입니다.
- 낡은 규칙은 삭제하세요. 프로젝트가 바뀌었는데 파일이 그대로면, AI는 낡은 규칙을 성실히 지킵니다. 없는 것보다 나쁩니다.
- 팀이라면 커밋하세요. CLAUDE.md는 개인 설정이 아니라 저장소의 일부입니다. 코드 리뷰 대상으로 다루면 팀 전체의 AI 사용 품질이 함께 올라갑니다.
자주 묻는 질문
- Q. CLAUDE.md와 AGENTS.md는 무엇이 다른가요?
- A. CLAUDE.md는 Claude Code가, AGENTS.md는 Codex 등 여러 도구가 읽는 안내서입니다. 내용은 거의 같아서 하나를 잘 쓰면 나머지는 변환입니다.
- Q. 규칙을 최대한 많이 적는 게 좋은가요?
- A. 아닙니다. 규칙이 50개면 AI는 그중 일부를 놓칩니다. 정말 지켜야 할 10개가 낫고, 어긴 사례가 나올 때마다 한 줄씩 추가하는 것이 현실적입니다.
- Q. 낡은 규칙은 그냥 둬도 되나요?
- A. 삭제하는 편이 낫습니다. 프로젝트가 바뀌었는데 규칙이 그대로면 AI가 낡은 규칙을 성실히 지켜, 없는 것보다 나쁠 수 있습니다.
CLAUDE.md를 직접 만들어보려면?
다섯 섹션을 클릭 몇 번으로 조립하고 싶다면 CLAUDE.md 생성기를 쓰세요. 프로젝트 유형·스택·규칙을 고르면 CLAUDE.md·AGENTS.md·.cursorrules 세 형식으로 만들어 내려받을 수 있습니다.
AI 에이전트가 도구·데이터와 연결되는 방식이 궁금하다면 MCP란 무엇인가를, 에이전트 개념 자체가 낯설다면 AI 에이전트 용어 정리를 함께 보세요.
규칙 파일을 여러 에이전트가 공유하는 단계로 넘어간다면 멀티에이전트 운영법에서 역할 분리와 충돌 방지 규칙을 확인할 수 있습니다.