CLAUDE.md 완전 정복

AI 에이전트를 내 뜻대로 제어하는 Claude Code 실전 설정하기

by AI개발자

Mar 20. 2026

CLAUDE.md란 무엇인가

Claude Code를 쓰기 시작하면, 얼마 지나지 않아 이런 패턴을 발견하게 됩니다.

"매번 같은 지시를 반복하고 있다" 는 것을....

"TypeScript로 작성해줘"

"테스트는 Vitest로"

"커밋 메시지는 한국어로 작성해줘"

프로젝트마다 이미 정해진 규칙을 AI에게 매번 말로 전달하는 건 낭비입니다.

실수로 빠뜨리기라도 하면, 혼자 규칙을 벗어나 코드를 생성해 버립니다.

CLAUDE.md는 바로 이 문제를 해결하는 파일입니다.

CLAUDE.md의 역할

CLAUDE.md는 Claude Code가 프로젝트 작업을 시작할 때 자동으로 읽어들이는 설정 파일입니다. 프로젝트 루트(또는 서브디렉토리)에 배치해 두면, Claude Code는 그 내용을 "이 프로젝트에서 당연히 지켜야 할 전제 지식"으로 받아들입니다.

쉽게 말하면, 새 팀원에게 온보딩 첫날 건네주는 개발 가이드북과 같습니다. 다만 AI는 한번 건네받은 규칙을 절대 잊지 않고, 모든 작업에 일관되게 적용합니다.

구체적으로 다음 정보를 기술할 수 있습니다.

코딩 규약 — 사용 언어, 프레임워크, 스타일 가이드, 네이밍 컨벤션

프로젝트 구성 — 디렉토리 구조 설명, 중요한 파일의 위치

워크플로우 — 테스트 방법, 빌드 커맨드, 배포 절차

금지 사항 — 해선 안 될 조작, 변경하면 안 되는 파일

품질 기준 — 코드 리뷰 기준, 성능 요건

3가지 스코프

CLAUDE.md는 배치 위치에 따라 적용 범위(스코프)가 달라집니다. 크게 3가지로 나뉩니다.

1. 프로젝트 CLAUDE.md

프로젝트의 루트 디렉토리에 배치합니다. 팀 전원이 공유해야 하는 규칙을 작성합니다.

my-project/
├── CLAUDE.md ← 프로젝트 전체 공통 규칙
├── src/
├── tests/
└── package.json

이 파일은 Git으로 버전을 관리하며, 팀 멤버 누구나 같은 규칙으로 Claude Code를 사용할 수 있게 합니다. 코드 리뷰 기준, 브랜치 전략, 금지 사항 등 팀 공통의 합의 사항을 여기에 담습니다.

2. 사용자 CLAUDE.md

~/.claude/CLAUDE.md에 배치합니다. 개인 취향이나 모든 프로젝트에 공통으로 적용하고 싶은 설정을 작성합니다.

~/.claude/
└── CLAUDE.md ← 모든 프로젝트에 적용되는 개인 설정

예를 들어 "응답은 항상 한국어로" "코드 설명은 간결하게" "console.log 대신 logger를 사용" 같은 개인 개발 습관은 여기에 작성합니다. 이 파일은 Git에 올리지 않고 본인 머신에서만 관리합니다.

3. 서브디렉토리 CLAUDE.md

특정 디렉토리 안에서만 적용할 규칙을 별도로 작성할 수 있습니다.

my-project/
├── CLAUDE.md ← 전체 공통 규칙
├── frontend/
│ └── CLAUDE.md ← 프론트엔드 전용 규칙
└── backend/
└── CLAUDE.md ← 백엔드 전용 규칙

모노레포 구성에서 프론트엔드(Next.js)와 백엔드(Spring Boot, Node.js 등)에 각각 다른 규칙을 적용할 때 특히 유용합니다. 상위 CLAUDE.md를 덮어쓰는 것이 아니라 컨텍스트로 추가되므로, 공통 규칙 위에 도메인별 규칙을 쌓는 구조가 됩니다.

최소 구성부터 시작하기

처음부터 완벽한 CLAUDE.md를 만들려고 할 필요는 없습니다. 아래 3줄짜리 파일부터 시작해 보세요. 이것만으로도 의미 있는 차이를 바로 느낄 수 있습니다.

# 프로젝트 규칙

- TypeScript로 작성한다. 타입은 반드시 명시한다
- 테스트는 Vitest로 작성한다. `pnpm test` 로 실행
- 커밋 메시지는 한국어로, 변경한 이유를 함께 적는다

이 3줄만 있어도, Claude Code는 매번 이 규칙에 맞게 동작합니다. 이후 프로젝트가 성장하면서 규칙을 조금씩 추가하면 됩니다.

팁 - 한국어 환경에서의 활용:
국내 팀에서는 커밋 메시지, 변수명 주석, PR 설명을 한국어로 통일하는 경우가 많습니다. CLAUDE.md에 이를 명시해 두면, AI가 일관되게 한국어로 작성하고 불필요한 영문 혼용을 방지할 수 있습니다.

CLAUDE.md가 효과적인 이유

CLAUDE.md가 단순한 README와 결정적으로 다른 점은, Claude Code가 대화 시작 시 반드시 자동으로 읽어들인다는 점입니다. 이 내용은 시스템 프롬프트의 일부로 받아들여지기 때문에, "이 규칙에 따라서"라고 매번 직접 말할 필요가 없습니다.

README는 사람이 읽는 문서입니다.

CLAUDE.md는 AI가 읽는 문서입니다.

두 파일이 같은 내용을 담더라도 그 역할은 전혀 다릅니다. CLAUDE.md에는 AI가 작업 판단에 실제로 활용할 수 있는 구체적이고 실행 가능한 지시를 담아야 합니다. "좋은 코드를 작성하라"가 아니라 "함수는 50행 이내로 작성하고, 단일 책임 원칙을 준수한다"처럼 작성해야 합니다.