CLAUDE.md 작성법

CLAUDE.md는 프로젝트의 문맥과 규칙을 Claude Code에 전하는 프로젝트 지침 파일입니다. 저장소 루트에 두면 세션이 시작될 때마다 자동으로 로드되어, 매번 같은 설명을 반복하지 않아도 Claude Code가 프로젝트 배경을 이해한 상태로 작업을 시작합니다. 파일 하나로 "매번 같은 설명을 하는" 수고가 사라지는 셈입니다.

핵심 요약

• CLAUDE.md는 프로젝트 규칙과 문맥을 Claude Code에 전하는 Markdown 설정 파일입니다
• 프로젝트 루트에 두며, 파일명은 반드시 대문자 CLAUDE.md입니다
• /init으로 프로젝트를 분석해 초안을 자동 생성한 뒤 손으로 다듬습니다
• 실행 명령·금지 사항·비직관적 규칙처럼 검증 가능한 문장만 남깁니다
• 매 세션 로드되므로 짧게 유지하고, 상세 규칙은 .claude/rules/로 분리합니다

CLAUDE.md가 있으면 무엇이 달라지나

CLAUDE.md는 Claude Code가 프로젝트 정보를 '기억'하기 위한 파일입니다. 프로젝트 개요, 사용 기술, 코딩 규약을 적어 두면 세션을 넘어 정보가 유지됩니다. RPG의 '세계관' 설정과 비슷합니다. '중세 판타지', '마법이 존재한다' 같은 세계관이 플레이어가 어느 지역에 있든 변하지 않는 전제이듯, CLAUDE.md의 내용은 Claude Code가 어느 파일을 편집하고 있든 늘 참조되는 기본 설정으로 작동합니다.

• 컨텍스트 공유: 프로젝트 문맥을 이해한 상태로 작업을 시작합니다
• 설명 생략: 매번 같은 설명을 하는 수고가 없어집니다
• 규약 준수: 코딩 규약을 지키게 하기 쉬워집니다
• 팀 공유: 전원이 같은 규칙으로 Claude Code를 쓸 수 있습니다

다만 CLAUDE.md는 어디까지나 '지시'이며, Claude가 모든 것을 엄밀히 따르는 것은 아닙니다. 복잡한 규칙이나 모호한 표현은 의도대로 해석되지 않을 수 있으므로, 규칙은 구체적이고 간결하게 씁니다.

파일명은 대문자 CLAUDE.md로 씁니다. claude.md나 Claude.md는 대소문자 차이로 인식되지 않는 경우가 있습니다.

/init 으로 초안 만들기

Claude Code 세션 안에서 /init을 실행하면 프로젝트를 분석해 틀을 자동 생성해 줍니다.

/init

대체로 아래 순서로 진행됩니다.

1. 프로젝트 구조를 분석해 파일·디렉터리 구성과 사용 언어·프레임워크를 검출합니다
2. README.md, package.json, requirements.txt 등 중요한 파일을 읽어들입니다
3. 해석한 내용을 바탕으로 CLAUDE.md를 생성해 그대로 써넣습니다

/init은 Claude Code가 에이전트로서 해석하는 처리이므로 매번 완전히 같은 절차를 밟지는 않습니다. 생성되는 제목(헤딩)도 프로젝트에 따라 달라지며, What this is / Commands / Structure / Notes처럼 영어 헤딩으로 나오는 경우도 있습니다. '프로젝트 개요·기술 스택·디렉터리 구조·개발 가이드라인' 같은 항목이 반드시 포함되는 것은 아닙니다.

초안이 나오면 반드시 손으로 다듬으세요. 자동 생성본은 "이 프로젝트가 무엇인지"는 잘 적지만, "이 팀이 무엇을 싫어하는지"는 알 수 없습니다. 그래도 처음부터 쓰는 것보다 훨씬 효율적이니, 생성 후 조정해 나가는 방식을 권합니다. /init을 포함한 기본 커맨드는 기본 조작과 명령어에서 정리했습니다.

무엇을 적고 무엇을 빼야 하나

반드시 적을 것

• 실행 명령 — 빌드, 테스트, 린트, 개발 서버를 어떤 명령으로 돌리는지
• 금지 사항 — 건드리면 안 되는 파일, 쓰면 안 되는 라이브러리
• 비직관적인 규칙 — 코드만 봐서는 알 수 없는 관례

적지 말아야 할 것

• 코드를 읽으면 알 수 있는 디렉터리 구조
• 일반적인 코딩 상식 ("변수명은 의미 있게")
• 과거에 한 번 있었던 사건의 서술

기본 구조 예시

필요한 정보를 섹션별로 정리한 구성 예입니다. 실무에서 자주 쓰이는 형태로, 프로젝트 특성에 맞게 섹션을 더하거나 빼면 됩니다.

# 프로젝트명

## 개요
프로젝트의 목적과 주요 기능을 간결하게 씁니다.

## 기술 스택
- Frontend: React 18 + TypeScript 5
- Backend: Node.js 20 + Express
- Database: PostgreSQL

## 디렉터리 구조
src/
├── components/  # React 컴포넌트
├── hooks/       # 커스텀 훅
├── utils/       # 유틸리티 함수
└── types/       # TypeScript 타입 정의

## 코딩 규약
- TypeScript의 strict 모드를 쓰세요
- 컴포넌트는 functional component로 기술하세요
- 함수명은 camelCase, 컴포넌트명은 PascalCase로 쓰세요

## 금지 사항
- any 사용은 최소한으로 해주세요
- console.log를 프로덕션 코드에 남기지 마세요
- 기존 테스트를 삭제하지 마세요

## 자주 쓰는 커맨드
- npm run dev: 개발 서버 실행
- npm test: 테스트 실행
- npm run build: 프로덕션 빌드

디렉터리 구조 절은 코드를 읽으면 알 수 있는 경우가 많으니, 구조가 비직관적일 때만 남기는 편이 좋습니다. 프로젝트 유형별 완성본은 CLAUDE.md 템플릿에서 가져다 쓸 수 있습니다.

동작을 바꾸는 문장 vs 그렇지 않은 문장

차이는 하나입니다. 검증 가능한가. 지킨 건지 아닌지 판별할 수 없는 문장은 지침이 아니라 장식입니다. Claude가 규칙을 지키지 않는다고 느껴지면, 규칙 자체보다 문장이 검증 가능한지부터 점검하세요.

짧게 유지해야 하는 이유

이 파일은 매 세션 항상 로드됩니다. 길면 매번 컨텍스트 비용을 내고, 너무 길어지면 컨텍스트 윈도우를 압박해 정작 중요한 규칙이 묻힙니다. 100줄을 넘어가기 시작하면 다음을 검토하세요.

• 특정 폴더에만 해당하는 규칙 → 그 폴더에 별도 CLAUDE.md를 둡니다
• 상세한 규칙 → .claude/rules/ 디렉터리로 분리합니다
• 자주 참조하지 않는 상세 문서 → 별도 파일로 빼고 @ 참조나 링크만 남깁니다
• 이미 지켜지고 있는 규칙 → 삭제합니다

규칙을 파일 단위로 모듈화하는 방법은 .claude/rules/로 규칙 모듈화에서, 다른 파일을 끌어오는 @ 참조 문법은 CLAUDE.md @참조에서 다룹니다.

어디에 두나 — 계층 구조

지침 파일은 여러 위치에 둘 수 있고, 좁은 범위가 우선합니다.

~/.claude/CLAUDE.md        ← 모든 프로젝트 공통 (개인 설정)
프로젝트/CLAUDE.md          ← 저장소 전체 (팀 공유, 커밋 대상)
프로젝트/apps/web/CLAUDE.md ← 해당 폴더에서 작업할 때만

팀 규칙은 저장소에 커밋하고, 개인 취향(응답 언어, 말투 등)은 홈 디렉터리의 글로벌 파일에 두세요. 각 위치가 언제 로드되고 충돌하면 무엇이 이기는지는 CLAUDE.md 배치 장소와 우선순위에서 자세히 설명합니다.

점검 주기

지침은 한 번 쓰고 끝나는 문서가 아닙니다. 같은 지적을 세 번 반복했다면, 그건 지침에 들어가야 할 내용입니다. 반대로 반년 동안 한 번도 위반되지 않은 규칙은 지워도 됩니다.

좋은 CLAUDE.md의 기준: 새로 합류한 팀원에게 그대로 건네도 유용한가?

정리

• CLAUDE.md는 프로젝트 루트에 두는 대문자 이름의 지침 파일로, 매 세션 자동 로드됩니다
• /init으로 초안을 만들고, "이 팀이 무엇을 싫어하는지"를 손으로 보탭니다
• 실행 명령·금지 사항·비직관적 규칙을 검증 가능한 문장으로 적습니다
• 100줄을 넘기 시작하면 폴더별 파일, .claude/rules/, @ 참조로 분리합니다
• 팀 규칙은 저장소에, 개인 취향은 ~/.claude/CLAUDE.md에 둡니다