Definition
CLAUDE.md
CLAUDE.md는 프로젝트 루트에 배치하는 마크다운 설정 파일로, Claude Code에 영구적인 프로젝트별 지침을 제공합니다. 에이전트에게 코딩 규칙, 아키텍처, 일반 명령, 규칙에 대해 알려주며, 해당 프로젝트의 모든 세션에 적용되는 장기 메모리 형태로 작동합니다.
CLAUDE.md의 작동 방식
Claude Code가 세션을 시작하면 프로젝트 루트(및 상위 디렉토리나 하위 디렉토리의 모든 CLAUDE.md 파일)의 CLAUDE.md 파일을 자동으로 읽습니다. 내용이 에이전트의 시스템 컨텍스트의 일부가 되어 매 세션마다 상기시킬 필요 없이 지침을 따릅니다. 이를 통해 에이전트가 팀의 규칙에 일관되게 동작합니다.
CLAUDE.md에 포함할 내용
- +프로젝트 아키텍처 개요 및 주요 파일 위치
- +코딩 규칙 (명명, 형식, 사용하거나 피할 패턴)
- +테스트, 빌드, 배포를 위한 일반 명령
- +"새 함수에는 항상 테스트 작성" 또는 "auth 모듈을 직접 수정하지 않음"과 같은 규칙
- +에이전트가 알아야 할 기술 스택 세부 정보
markdown
# CLAUDE.md
## Project
Next.js 14 app with App Router, TypeScript, Tailwind CSS.
## Commands
- `npm run dev` — start dev server
- `npm test` — run Jest tests
- `npm run lint` — ESLint check
## Conventions
- Use server components by default
- Client components go in `components/client/`
- All API routes must validate input with Zod
- Write tests for every new utility function
## Do NOT
- Modify files in `lib/core/` without explicit approval
- Use `any` type in TypeScript
- Add new dependencies without justificationCLAUDE.md를 간결하게 유지하세요. 에이전트는 매 세션마다 이 파일을 읽으므로 여러 작업에 걸쳐 관련된 정보만 포함하세요. 작업별 세부 사항은 프롬프트에 넣으세요.
CLAUDE.md 파일은 어디에 배치해야 하나요?+
프로젝트 디렉토리 루트에 배치하세요. Claude Code는 또한 모듈별 지침을 위한 하위 디렉토리의 CLAUDE.md 파일과 조직 전체 규칙을 위한 상위 디렉토리도 지원합니다. 적용 가능한 모든 파일이 병합됩니다.
CLAUDE.md는 다른 AI 도구와 함께 작동하나요?+
CLAUDE.md는 Claude Code에 특화되어 있습니다. 하지만 다른 도구들도 유사한 개념을 채택했습니다. Cursor는 .cursorrules를 사용하고, 다른 에이전트도 커스텀 설정 파일을 읽을 수 있습니다. 프로젝트 수준의 AI 지침 개념은 일반적인 패턴이 되고 있습니다.
CLAUDE.md는 얼마나 길어야 하나요?+
500줄 이하로 유지하세요. 가장 중요한 규칙과 규칙에 집중하세요. 에이전트는 세부 정보를 위해 개별 파일을 항상 읽을 수 있으므로, CLAUDE.md는 작업 전반에 걸쳐 적용되는 고수준 컨텍스트를 제공해야 합니다.
Related terms
Master Claude Code in days, not months
37 hands-on lessons from beginner to CI/CD automation. Module 1 is free.
START FREE →