[Claude Code CLAUDE.md 작성법] 완벽 가이드 — 개념부터 실무까지

 

안녕하세요!

재아군의 관찰인생입니다.

 

최근 AI 코딩 어시스턴트의 발전 속도가 놀라울 정도인데요, 그중에서도 Claude Code는 터미널 기반의 에이전틱 코딩 도구로 개발자들 사이에서 빠르게 자리잡고 있습니다.

하지만 Claude Code를 제대로 활용하려면 단순히 설치하고 명령어를 입력하는 것만으로는 부족합니다.

프로젝트의 맥락을 정확하게 전달하는 CLAUDE.md 파일이 핵심 열쇠입니다.

오늘은 Claude Code CLAUDE.md 작성법을 개념부터 실무 적용까지 완벽하게 다뤄보겠습니다.

 

 

---

 

1. Claude Code CLAUDE.md 작성법이란 무엇인가?

 

CLAUDE.md는 Claude Code가 프로젝트에 진입할 때 가장 먼저 읽는 컨텍스트 파일입니다.

쉽게 말해, 새로운 팀원에게 건네는 "프로젝트 온보딩 문서"와 같은 역할을 합니다.

Claude Code는 대화가 시작될 때 이 파일을 자동으로 로드하여, 프로젝트의 구조, 빌드 방법, 코딩 컨벤션, 그리고 주의사항을 파악합니다.

 

등장 배경

 

AI 코딩 어시스턴트가 보편화되면서, 단순한 코드 자동완성을 넘어 프로젝트 전체를 이해하고 자율적으로 작업하는 에이전틱 코딩 패러다임이 등장했습니다.

이 패러다임에서 AI가 효과적으로 작동하려면 프로젝트별 맥락 정보가 필수적인데, CLAUDE.md가 바로 그 표준화된 인터페이스입니다.

 

기존 문제 4가지

 

1. 매번 반복되는 컨텍스트 설명: 새 대화를 시작할 때마다 "우리 프로젝트는 이런 구조이고, 빌드는 이렇게 하고..."를 반복해야 했습니다. 시간 낭비가 상당했습니다.
2. 일관성 없는 코드 생성: 프로젝트의 코딩 스타일, 네이밍 컨벤션, 아키텍처 패턴을 모르는 상태에서 생성된 코드는 기존 코드베이스와 충돌하는 경우가 빈번했습니다.
3. 빌드/테스트 실패의 반복: AI가 프로젝트의 빌드 시스템이나 테스트 환경을 모르면, 생성한 코드가 로컬에서 돌아가지 않는 상황이 계속 발생했습니다.
4. 팀 내 지식 파편화: 각 개발자가 AI에게 서로 다른 방식으로 컨텍스트를 전달하면서, 생성되는 코드의 품질과 스타일이 개인마다 달라지는 문제가 있었습니다.

 

 

---

 

2. 핵심 특징 & 기능 분석

 

2-1. 계층적 로딩 시스템

 

CLAUDE.md는 단일 파일이 아니라 3단계 계층 구조로 동작합니다.

사용자 홈 디렉토리의 ~/.claude/CLAUDE.md(전역 설정), 프로젝트 루트의 CLAUDE.md(프로젝트 설정), 그리고 각 하위 디렉토리의 CLAUDE.md(모듈별 설정)가 순서대로 로드됩니다.

이를 통해 글로벌 코딩 스타일은 전역에서, 프로젝트 특화 규칙은 루트에서, 모듈 특화 지침은 해당 디렉토리에서 관리할 수 있습니다.

 

2-2. 자동 컨텍스트 주입

 

Claude Code는 대화 시작 시 CLAUDE.md를 시스템 프롬프트의 일부로 자동 주입합니다.

개발자가 별도로 "이 파일을 읽어줘"라고 요청할 필요가 없습니다.

이는 모든 대화에서 일관된 기반 지식을 보장합니다.

 

2-3. 명령형 지시 체계

 

CLAUDE.md의 내용은 단순한 참고 문서가 아니라 Claude Code의 행동을 직접 제어하는 명령입니다.

"절대 ~하지 마세요", "반드시 ~하세요"와 같은 지시어가 실제로 모델의 행동을 바꿉니다.

특히 IMPORTANT: 접두사를 사용하면 우선순위가 높아집니다.

 

2-4. 동적 컨텍스트 관리

 

Claude Code는 대화가 길어지면 이전 메시지를 자동 압축하지만, CLAUDE.md의 내용은 항상 전체 컨텍스트에 유지됩니다.

긴 작업 세션에서도 프로젝트 규칙이 잊히지 않는 것이 핵심 장점입니다.

 

2-5. 팀 동기화 인터페이스

 

CLAUDE.md를 Git에 커밋하면 팀 전체가 동일한 AI 컨텍스트를 공유하게 됩니다.

코드 리뷰 때 "AI에게 이렇게 시켰더니 이런 코드가 나왔다"는 식의 논쟁이 사라지고, 일관된 AI 활용 기준이 만들어집니다.

 

 

---

 

3. 기술 아키텍처 & 동작 원리

 

구성 요소

 

구성 요소	역할	위치
전역 CLAUDE.md	사용자 공통 설정 (코딩 스타일, 선호 언어)	~/.claude/CLAUDE.md
프로젝트 CLAUDE.md	빌드/테스트 명령, 아키텍처, 주의사항	프로젝트 루트 /CLAUDE.md
디렉토리 CLAUDE.md	모듈별 특화 규칙	각 서브디렉토리 /src/api/CLAUDE.md
.claude/settings.json	권한, 허용 명령어 설정	.claude/settings.json
.claude/settings.local.json	개인별 로컬 오버라이드	.claude/settings.local.json

 

로딩 흐름

 

# Claude Code 컨텍스트 로딩 순서 (의사 코드)

def load_context(project_path, current_file):
    context = []
    
    # 1단계: 전역 설정 로드
    global_md = read_file("~/.claude/CLAUDE.md")
    if global_md:
        context.append(global_md)
    
    # 2단계: 프로젝트 루트 CLAUDE.md 로드
    project_md = read_file(f"{project_path}/CLAUDE.md")
    if project_md:
        context.append(project_md)
    
    # 3단계: 현재 작업 파일의 상위 디렉토리 체인에서 CLAUDE.md 탐색
    for directory in walk_parents(current_file, up_to=project_path):
        dir_md = read_file(f"{directory}/CLAUDE.md")
        if dir_md:
            context.append(dir_md)
    
    # 4단계: .claude/settings.json 에서 권한 설정 병합
    settings = read_json(f"{project_path}/.claude/settings.json")
    context.append(format_permissions(settings))
    
    return merge_context(context)  # 하위 설정이 상위 설정을 오버라이드

 

설계 원칙 4가지

 

1. Convention over Configuration: 파일 이름과 위치만 맞추면 별도 설정 없이 자동으로 동작합니다.
2. Locality Principle: 가장 가까운 디렉토리의 CLAUDE.md가 가장 높은 우선순위를 가집니다.
3. Additive Merging: 하위 레벨의 지침이 상위 레벨을 완전히 대체하지 않고 누적됩니다.
4. Persistence Guarantee: 컨텍스트 윈도우 압축 시에도 CLAUDE.md 내용은 보존됩니다.

 

---

 

4. 실무 활용 가이드

 

시작하기: 기본 CLAUDE.md 작성

 

다음은 실제 프로젝트에 바로 적용할 수 있는 CLAUDE.md 템플릿입니다.

 

# CLAUDE.md

## Build & Run

```bash
# 의존성 설치
npm install

# 개발 서버 실행
npm run dev

# 테스트 실행
npm test

# 타입 체크
npx tsc --noEmit

# 린트
npm run lint
```

## Architecture

이 프로젝트는 Next.js 14 App Router 기반의 SaaS 대시보드입니다.

- `/src/app/` — App Router 페이지 및 레이아웃
- `/src/components/` — 재사용 가능한 React 컴포넌트
- `/src/lib/` — 유틸리티 함수 및 API 클라이언트
- `/src/db/` — Drizzle ORM 스키마 및 마이그레이션

## Coding Conventions

- TypeScript strict 모드 사용
- 컴포넌트는 named export만 사용 (default export 금지)
- CSS는 Tailwind CSS 유틸리티 클래스 사용
- API 응답은 반드시 Zod 스키마로 검증

## Important Rules

IMPORTANT: `.env` 파일을 절대 읽거나 수정하지 마세요.
IMPORTANT: `drizzle-kit push` 명령어를 직접 실행하지 마세요.
마이그레이션은 반드시 `npm run db:migrate`를 사용하세요.

 

기존 환경에 도입하는 4단계

 

단계	작업	핵심 포인트
1단계: 기본 정보 정리	빌드, 테스트, 실행 명령어 문서화	신규 개발자가 README를 안 보더라도 개발을 시작할 수 있는 수준으로
2단계: 아키텍처 기술	디렉토리 구조, 데이터 흐름, 핵심 모듈 설명	과도한 상세 설명보다 "이 디렉토리는 이런 역할" 수준이 적절
3단계: 규칙 및 제약 추가	코딩 컨벤션, 금지 사항, 보안 규칙 명시	IMPORTANT: 접두사로 강조, "~하지 마세요" 형태의 명확한 금지 표현 사용
4단계: 팀 리뷰 및 커밋	PR을 통해 팀 합의 후 Git 커밋	개인 설정은 .claude/settings.local.json으로 분리

 

팀 활용 팁

 

• 모노레포 환경: 각 패키지 디렉토리에 CLAUDE.md를 두어 패키지별 빌드 규칙을 분리하세요.
• 코드 리뷰 연계: PR 템플릿에 "CLAUDE.md 변경 필요 여부"를 체크리스트로 추가하면 규칙이 자연스럽게 최신 상태를 유지합니다.
• 온보딩 자동화: 새 팀원이 합류하면 CLAUDE.md만 읽으면 프로젝트의 핵심 구조를 바로 파악할 수 있습니다.

 

---

 

5. 경쟁 기술 비교 분석

 

비교 항목	Claude Code CLAUDE.md	Cursor .cursorrules	GitHub Copilot Instructions	Windsurf .windsurfrules
형식	Markdown (자유 형식)	Markdown (자유 형식)	Markdown (자유 형식)	Markdown (자유 형식)
계층 구조	전역 → 프로젝트 → 디렉토리 3단계	프로젝트 단일 파일	전역 + 리포지토리 2단계	프로젝트 단일 파일
자동 로딩	대화 시작 시 자동 주입	에디터 시작 시 로드	채팅/인라인 요청 시 로드	에디터 시작 시 로드
터미널 통합	네이티브 (터미널 환경)	IDE 내장 터미널	IDE 내장 터미널	IDE 내장 터미널
에이전틱 실행	파일 CRUD, bash 실행, 웹 검색	파일 편집 중심	제한적 에이전트 모드	파일 편집 + 터미널
Git 연동	git status/log 자동 인식	수동	PR 코멘트 연동	수동

 

선택 가이드

 

• 터미널 중심 워크플로우 + 자율적 에이전트 작업이 필요하다면 → Claude Code + CLAUDE.md
• IDE 내에서 코드 편집 중심 작업이라면 → Cursor + .cursorrules 또는 Windsurf + .windsurfrules
• GitHub 생태계에 강하게 결합된 팀이라면 → GitHub Copilot Instructions
• 여러 도구를 병행 사용한다면, 각 도구의 설정 파일을 모두 유지하되 핵심 규칙은 하나의 소스(예: CLAUDE.md)에서 관리하고 나머지에 복사하는 전략이 효과적입니다.

 

---

 

6. 도입 시 베스트 프랙티스

 

5가지 원칙

 

1. 간결하게 유지하세요: CLAUDE.md가 너무 길면 오히려 핵심 정보가 묻힙니다. 500줄 이내를 권장하며, 상세한 API 문서는 별도 파일로 분리하고 "자세한 내용은 docs/api.md를 참고하세요"로 연결하세요.
2. 명령형으로 작성하세요: "~하면 좋겠습니다"보다 "반드시 ~하세요" 또는 "절대 ~하지 마세요"가 훨씬 효과적입니다. AI 모델은 명확한 지시를 더 잘 따릅니다.
3. 실행 가능한 명령어를 포함하세요: "빌드하려면 적절한 명령어를 사용하세요"가 아니라 npm run build처럼 복사-붙여넣기 가능한 구체적 명령어를 제공하세요.
4. 변경 시 함께 업데이트하세요: 아키텍처가 바뀌거나 새 컨벤션이 도입되면 CLAUDE.md도 즉시 업데이트하세요. 오래된 CLAUDE.md는 없는 것보다 나쁩니다.
5. 보안 경계를 명확히 하세요: 환경 변수 파일(.env), 시크릿, 프로덕션 데이터베이스 접근 등 AI가 절대 건드려서는 안 되는 영역을 IMPORTANT: 태그로 명시하세요.

 

흔한 실수와 해결 방법

 

실수	문제점	해결 방법
모든 것을 CLAUDE.md에 넣기	컨텍스트 윈도우 낭비, 핵심 규칙 희석	핵심 규칙만 루트에, 상세 내용은 하위 디렉토리 또는 별도 문서로 분리
모호한 표현 사용	"적절한 에러 처리"는 해석이 다양함	"모든 API 호출은 try-catch로 감싸고 에러를 logger.error()로 기록하세요"처럼 구체적으로
.gitignore에 CLAUDE.md 추가	팀원 간 AI 컨텍스트 불일치	CLAUDE.md는 반드시 Git 커밋, 개인 설정은 settings.local.json으로 분리
업데이트 누락	아키텍처 변경 후 CLAUDE.md가 과거 상태를 기술	아키텍처 변경 PR에 CLAUDE.md 수정을 필수 체크리스트로 포함
코드 전체를 복사해서 넣기	불필요한 토큰 소비, 오히려 혼란 유발	핵심 패턴과 예시만 간결하게, 나머지는 파일 경로 참조

 

---

 

7. 향후 전망 & 발전 방향

 

발전 방향 4가지

 

1. 동적 컨텍스트 생성: 현재는 정적 마크다운 파일이지만, 향후에는 프로젝트 상태(빌드 결과, 테스트 커버리지, 최근 변경 이력)를 실시간으로 반영하는 동적 CLAUDE.md가 등장할 가능성이 높습니다. 이미 Claude Code의 hooks 시스템이 그 기반을 마련하고 있습니다.
2. 크로스 툴 표준화: CLAUDE.md, .cursorrules, .github/copilot-instructions.md 등 도구별로 파편화된 AI 컨텍스트 파일이 하나의 표준(예: .ai-context.md)으로 통합되는 움직임이 예상됩니다.
3. MCP 서버와의 깊은 통합: Model Context Protocol(MCP)을 통해 CLAUDE.md가 외부 시스템(Jira, Slack, 데이터베이스 스키마)의 정보를 실시간으로 참조하는 구조로 발전할 것입니다. 이미 Claude Code는 MCP 서버 연결을 지원하고 있습니다.
4. 자동 생성 및 자가 진화: AI가 프로젝트를 분석하여 초기 CLAUDE.md를 자동 생성하고, 개발 과정에서 발견된 패턴을 스스로 반영하여 업데이트하는 시나리오가 현실화될 것입니다. Claude Code의 /init 명령이 이미 이 방향의 첫 걸음입니다.

 

개발자 시사점

 

• AI 컨텍스트 엔지니어링이 새로운 개발자 역량으로 부상하고 있습니다. 프롬프트를 잘 작성하는 것을 넘어, 프로젝트 전체의 AI 친화적 문서 체계를 설계하는 능력이 중요해집니다.
• CLAUDE.md 작성 능력은 곧 팀의 AI 활용 생산성을 결정하는 핵심 요소가 됩니다. 단순히 코드를 잘 짜는 것을 넘어, AI와 효과적으로 협업하는 환경을 구축하는 것이 경쟁력입니다.
• 오픈소스 프로젝트에 CLAUDE.md를 포함하는 것이 새로운 컨트리뷰션 문화로 자리잡을 것입니다. 잘 작성된 CLAUDE.md는 기여 장벽을 크게 낮춥니다.

 

---

 

마무리

 

지금까지 Claude Code CLAUDE.md 작성법에 대해 개념부터 실무 적용까지 살펴보았습니다.

핵심을 정리하면 다음과 같습니다.

 

• CLAUDE.md는 AI에게 건네는 프로젝트 온보딩 문서입니다. 빌드 명령, 아키텍처, 코딩 컨벤션, 보안 경계를 명확히 기술하세요.
• 계층 구조(전역 → 프로젝트 → 디렉토리)를 활용하여 관심사를 분리하고 모듈별 맥락을 효과적으로 전달하세요.
• 간결하고 명령형으로 작성하되, 실행 가능한 코드 예시를 포함하세요. 모호한 표현보다 구체적인 지시가 효과적입니다.
• Git에 커밋하고 팀과 공유하여, 모든 팀원이 동일한 AI 컨텍스트에서 작업할 수 있도록 하세요.

 

Claude Code CLAUDE.md 작성법을 제대로 익히면, AI 코딩 어시스턴트의 생산성이 체감할 수 있을 정도로 달라집니다.

직접 프로젝트에 CLAUDE.md를 작성해보고, 그 차이를 경험해 보시길 강력히 추천합니다.

 

궁금한 점이나 여러분만의 CLAUDE.md 작성 팁이 있다면 댓글로 공유해 주세요!

이 글이 도움이 되셨다면 공유도 부탁드립니다.

감사합니다! 🙏