CLAUDE.md 작성법 — AI 에이전트를 내 프로젝트에 맞추는 방법

Claude Code는 세션을 시작할 때마다 컨텍스트 창을 완전히 비웁니다. 지난 대화에서 어떤 규칙을 알려줬더라도, 새 세션이 열리면 그 내용은 사라집니다. CLAUDE.md는 이 문제를 해결하기 위해 존재합니다. 세션이 시작될 때마다 자동으로 읽히는 마크다운 파일로, 코딩 스타일·아키텍처·금지 규칙·자주 쓰는 명령어를 한 번만 써두면 매번 반복하지 않아도 됩니다.

이 가이드에서는 CLAUDE.md가 무엇인지, 어디에 두어야 하는지, 어떻게 작성해야 Claude가 실제로 따르는지, 팀과 어떻게 공유하는지, 그리고 AGENTS.md·GEMINI.md 같은 다른 AI 도구의 설정 파일과 어떻게 다른지를 정리합니다.

CLAUDE.md란 무엇인가

CLAUDE.md는 Claude Code가 대화 시작 시 자동으로 읽는 마크다운 파일입니다. 형식은 자유롭지만 역할은 명확합니다. Claude가 코드를 읽는 것만으로는 파악하기 어려운 정보, 즉 빌드 명령어·코드 스타일 결정·워크플로우 규칙·아키텍처 판단을 담아두는 곳입니다.

이 파일은 단순한 텍스트 문서입니다. Claude는 이를 사용자 메시지로 받아 세션에 주입합니다. 따라서 지시는 강제가 아니라 컨텍스트입니다. 구체적이고 간결하게 작성할수록 Claude가 지시를 일관되게 따릅니다.

/init 명령으로 기본 파일 생성하기

프로젝트 디렉토리에서 /init 을 실행하면 Claude Code가 코드베이스를 분석해 빌드 시스템·테스트 프레임워크·코드 패턴을 감지하고 기본 CLAUDE.md를 생성합니다. 이미 파일이 존재하면 덮어쓰지 않고 개선 사항을 제안합니다. 이 파일을 시작점으로 삼고, Claude가 없어도 알 수 있는 내용은 지워나가는 방식으로 다듬는 것이 좋습니다.

$ claude
> /init
✓ Analyzing codebase...
✓ Detected: Node.js, TypeScript, Jest, ESLint
✓ Created CLAUDE.md with project conventions
  → Review and refine before committing

파일 위치와 계층 구조

CLAUDE.md는 여러 위치에 둘 수 있으며, 위치에 따라 적용 범위가 달라집니다. Claude Code는 현재 작업 디렉토리에서 위쪽으로 디렉토리 트리를 올라가며 CLAUDE.md와 CLAUDE.local.md 파일을 모두 찾아 컨텍스트에 합칩니다. 덮어쓰지 않고 모두 연결해서 읽습니다.

Windows + WSL 환경에서의 경로

Windows에서 WSL을 통해 Claude Code를 사용한다면 관리형 정책 파일의 경로는 /etc/claude-code/CLAUDE.md 입니다. 전역 설정은 WSL 내부의 홈 디렉토리인 ~/.claude/CLAUDE.md 에 둡니다. Windows 네이티브 경로(C:\Users\...)는 Claude Code가 읽지 않으므로 반드시 WSL 경로를 사용해야 합니다.

/etc/claude-code/
  CLAUDE.md              ← 조직 전체 정책 (IT 배포)
~/.claude/
  CLAUDE.md              ← 내 모든 프로젝트 공통 설정
  rules/
    preferences.md       ← 개인 선호 규칙
    workflows.md         ← 개인 워크플로우
my-project/
  CLAUDE.md              ← 팀 공유 프로젝트 설정
  CLAUDE.local.md        ← 내 개인 오버라이드 (.gitignore)
  .claude/
    CLAUDE.md            ← 팀 공유 (프로젝트 루트 대신)
    rules/
      testing.md         ← 테스트 컨벤션
      api-design.md      ← API 설계 규칙
  src/
    api/
      CLAUDE.md          ← API 디렉토리 전용 규칙

로딩 순서와 우선순위

파일은 범위가 넓은 것(전역)부터 좁은 것(하위 디렉토리) 순서로 로드됩니다. 나중에 읽히는 파일이 더 높은 우선순위를 가집니다. 같은 디렉토리에서는 CLAUDE.md가 먼저, CLAUDE.local.md가 나중에 읽히므로 개인 오버라이드가 팀 공유 설정을 덮을 수 있습니다. 상위 디렉토리의 파일들은 세션 시작 시 전부 로드되고, 하위 디렉토리의 파일은 해당 디렉토리의 파일을 Claude가 작업할 때 필요에 따라 로드됩니다.

.claude/rules/ 디렉토리와의 차이

프로젝트가 커지면 단일 CLAUDE.md 파일에 모든 지시를 담기 어려워집니다. Claude Code는 .claude/rules/ 디렉토리를 지원합니다. 이 디렉토리 안에 주제별 마크다운 파일을 두면 됩니다. 파일명은 자유롭게 정할 수 있고 하위 디렉토리로 추가 구조화도 가능합니다.

경로 지정 규칙 (path-specific rules)

rules 파일에 YAML frontmatter로 paths 를 지정하면, Claude가 해당 패턴과 일치하는 파일을 작업할 때만 이 규칙이 컨텍스트에 추가됩니다. 불필요한 규칙이 컨텍스트 창을 채우는 것을 막아 성능을 개선할 수 있습니다.

---
paths:
  - "src/api/**/*.ts"
  - "src/routes/**/*.ts"
---

# API 설계 규칙

- 모든 API 엔드포인트는 입력 유효성 검사를 포함해야 합니다
- 응답은 항상 { data, error } 형태로 반환합니다
- OpenAPI 문서 주석을 포함합니다
- 에러 코드는 docs/error-codes.md를 참조합니다

반면 paths 가 없는 rules 파일은 매 세션에 전체 로드됩니다. 항상 적용해야 할 규칙은 paths 없이, 특정 파일 타입에만 필요한 규칙은 paths를 설정해서 구분하면 됩니다.

효과적인 CLAUDE.md 작성법

CLAUDE.md는 매 세션 컨텍스트 창에 로드됩니다. 파일이 길면 Claude가 중요한 지시를 놓칩니다. 공식 문서 권장 기준은 파일당 200줄 이하입니다. 연구에 따르면 최신 프론티어 LLM이 일관되게 따를 수 있는 지시의 수는 150~200개이며, Claude Code의 시스템 프롬프트 자체가 이미 약 50개의 지시를 사용합니다. 따라서 CLAUDE.md에는 정말 필요한 것만 담아야 합니다.

무엇을 넣고 무엇을 빼야 하는가

지시 작성 형식: 구체적으로, 검증 가능하게

지시는 검증 가능할 만큼 구체적으로 작성합니다. 마크다운 헤더와 불릿을 사용해 관련 지시를 묶으면 Claude가 구조를 스캔하기 쉬워집니다. 두 규칙이 서로 모순되면 Claude가 임의로 하나를 택하므로, 주기적으로 규칙 간 충돌을 점검해야 합니다.

코드를 잘 포맷하세요.
테스트를 작성하세요.
파일을 정리된 상태로 유지하세요.

들여쓰기는 2칸 공백을 사용합니다.
커밋 전 npm test를 실행합니다.
API 핸들러는 src/api/handlers/에 위치합니다.

@import로 외부 파일 가져오기

CLAUDE.md 파일은 @경로/파일명 문법으로 다른 파일을 포함할 수 있습니다. 포함된 파일도 세션 시작 시 CLAUDE.md와 함께 컨텍스트에 로드됩니다. 상대·절대 경로 모두 허용하며 최대 5단계 재귀 포함이 가능합니다. 긴 내용을 분리하거나 여러 git 워크트리에서 공통 설정을 공유할 때 유용합니다.

# 프로젝트 개요
See @README.md and @package.json for project overview and commands.

# 추가 지침
- git 워크플로우: @docs/git-instructions.md
- 개인 오버라이드: @~/.claude/my-project-instructions.md

실전 작성 예시

아래는 실제 프로젝트에 적용할 수 있는 CLAUDE.md 예시입니다. 각 섹션의 목적과 함께 설명합니다.

기본 구조: 스택·명령어·컨벤션

# 프로젝트 스택
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.7 (strict mode)
- Styling: Tailwind CSS 4.0
- DB: PostgreSQL 16 + Drizzle ORM
- 환경: Windows WSL2 (Ubuntu 22.04)

# 명령어
- 빌드: `npm run build`
- 테스트: `npm test -- --testPathPattern=파일명`  (개별 파일 우선)
- 타입 체크: `npx tsc --noEmit`
- 린트: `npm run lint`

# 코드 스타일
- named export 사용, default export 금지
- 들여쓰기: 2칸 공백
- API 응답은 항상 { data, error } 형태

# 디렉토리 구조
- `app/` — Next.js App Router 페이지
- `components/` — 공통 컴포넌트
- `lib/` — 유틸리티 함수
- `src/api/handlers/` — API 핸들러

# 주의사항
- 커밋 전 반드시 `npm test && npx tsc --noEmit` 실행
- 마이그레이션 파일은 `drizzle/migrations/`에만 생성
- 환경 변수는 `src/env.ts`에서 유효성 검사 후 사용

아키텍처 결정 사항 기록하기

왜 그런 결정을 내렸는지, 어떤 접근을 이미 시도해서 포기했는지를 기록하면 Claude가 같은 실수를 반복하지 않습니다. 특히 비직관적인 결정이나 기술 부채는 반드시 남겨두는 것이 좋습니다.

# 아키텍처 결정

## 상태 관리
- Zustand 사용 (Redux 아님) — 보일러플레이트를 줄이기 위해 의도적으로 선택
- 전역 상태는 최소화하고 서버 상태는 TanStack Query로 관리

## 인증
- NextAuth.js가 아닌 자체 JWT 구현 — 멀티 테넌트 요구사항 때문에 불가피한 선택
- 토큰 갱신은 src/lib/auth/refresh.ts에서만 처리

## 금지 패턴
- any 타입 사용 금지 (린터로도 강제됨)
- console.log 프로덕션 코드 삽입 금지
- pages/ 디렉토리 신규 파일 생성 금지 (app/ 라우터로 전환 중)

개인 전역 설정 (~/.claude/CLAUDE.md)

모든 프로젝트에 공통으로 적용하고 싶은 개인 선호 사항은 전역 파일에 둡니다. 개인 코딩 스타일, 언어 선호, 커밋 메시지 형식 같은 것이 여기에 해당합니다. 프로젝트별 내용은 절대 전역 파일에 두지 않습니다.

# 언어
- 모든 응답은 한국어로
- 코드 주석도 한국어 우선

# 커밋 메시지
- 형식: feat|fix|docs|refactor|test: 간결한 설명
- 본문에 변경 이유 포함

# 선호 도구
- 패키지 매니저: pnpm 우선
- 포매터: Prettier + ESLint (자동 수정 후 보고)

# 작업 방식
- 변경 전 현재 상태 파악 후 작업
- 대형 변경은 단계별로 나눠서 진행

팀 공유 패턴과 git 관리

CLAUDE.md를 git에 커밋하면 팀 전체가 동일한 컨텍스트로 Claude를 사용할 수 있습니다. 이 파일은 시간이 지나면서 팀의 집단 지식이 담기는 문서가 됩니다. 온보딩 시간이 줄고 팀원 간 일관성이 높아집니다.

커밋할 것과 .gitignore에 추가할 것

# 팀 전체에 공유하는 파일들
git add CLAUDE.md
git add .claude/CLAUDE.md
git add .claude/rules/testing.md
git add .claude/rules/api-design.md

git commit -m "docs: CLAUDE.md 프로젝트 컨텍스트 추가"

# .gitignore에 추가 — 개인 설정은 공유하지 않음
CLAUDE.local.md
.claude/settings.local.json

모노레포에서의 관리

모노레포에서는 상위 디렉토리의 CLAUDE.md가 모두 로드됩니다. 다른 팀의 CLAUDE.md가 내 작업과 무관한 규칙을 컨텍스트에 추가하는 경우, claudeMdExcludes 설정으로 특정 파일을 제외할 수 있습니다. 이 설정은 .claude/settings.local.json에 추가해 개인 머신에만 적용합니다.

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

AGENTS.md·GEMINI.md와의 비교

AI 코딩 도구마다 프로젝트 지침 파일의 이름이 다릅니다. Claude Code는 CLAUDE.md, OpenAI Codex CLI는 AGENTS.md, Google Gemini CLI는 GEMINI.md를 읽습니다. 여러 도구를 동시에 사용하는 팀이라면 중복 작성을 피하기 위한 전략이 필요합니다.

여러 도구를 함께 쓸 때의 권장 전략

팀에서 Claude Code와 다른 AI 도구를 함께 사용한다면 AGENTS.md를 단일 소스로 유지하는 방법이 효율적입니다. Claude Code는 해당 디렉토리에 CLAUDE.md가 없을 때 AGENTS.md를 폴백으로 읽습니다. 또는 CLAUDE.md에서 AGENTS.md를 @import해서 두 파일을 동기화할 수도 있습니다.

# 공통 프로젝트 지침
@AGENTS.md

## Claude Code 전용 설정

- src/billing/ 변경 시 Plan Mode를 사용합니다
- 대형 리팩토링 전에 반드시 /compact를 실행합니다
- 커밋 메시지는 한국어로 작성합니다

Auto Memory: Claude가 직접 쓰는 기억

Claude Code v2.1.59 이상에서는 Auto Memory 기능이 기본으로 활성화됩니다. 세션 중 Claude가 유용하다고 판단한 정보, 빌드 명령어·디버깅 패턴·코드 스타일 선호를 ~/.claude/projects/<project>/memory/ 디렉토리에 스스로 저장합니다.

~/.claude/projects/<project>/memory/
  MEMORY.md              ← 인덱스 파일 (매 세션 첫 200줄 로드)
  debugging.md           ← 디버깅 패턴 상세 기록
  api-conventions.md     ← API 설계 결정 사항
  build-commands.md      ← 빌드 명령어 및 환경

자주 하는 실수와 해결법

CLAUDE.md를 처음 작성하거나 관리할 때 반복적으로 발생하는 문제들이 있습니다. 아래는 가장 흔한 실수와 그 해결법입니다.

CLAUDE.md에 모든 정보를 넣으려고 500줄이 넘는 파일을 작성한다.
→ 결과: Claude가 중요한 규칙을 무시하기 시작함

파일당 200줄 이하 유지.
상세 내용은 agent_docs/ 디렉토리에 별도 파일로 두고,
CLAUDE.md에는 해당 파일의 존재와 용도만 언급.
또는 .claude/rules/에 주제별로 분리.

들여쓰기 2칸, 세미콜론 없음, 따옴표는 작은따옴표...
→ 결과: 컨텍스트 낭비, 린터가 더 빠르고 확실함

코드 스타일은 ESLint + Prettier가 처리.
CLAUDE.md에는 린터가 잡지 못하는 아키텍처 결정만 남김.

/init이 생성한 CLAUDE.md를 검토 없이 바로 커밋한다.
→ 결과: 불필요한 내용이 가득한 비효율적 파일

/init은 시작점으로만 활용.
각 줄을 보며 "이게 없으면 Claude가 실수하는가?"를 묻고,
그렇지 않으면 삭제. 직접 작성한 50줄이 자동 생성 500줄보다 낫다.

그 외 자주 발생하는 문제들:

FAQ

CLAUDE.md는 한 번 쓰고 끝나는 문서가 아닙니다. 프로젝트가 발전하고 팀의 작업 방식이 변할수록 함께 다듬어야 합니다. Claude가 예상치 못한 실수를 반복하면 CLAUDE.md를 검토하고, 더 이상 필요 없는 규칙은 지우고, 새로운 결정은 추가하세요. 잘 관리된 CLAUDE.md는 팀의 집단 지식이 담긴 살아있는 문서가 됩니다.

CLAUDE.md 파일, Auto Memory, .claude/rules/ 등 Claude Code의 메모리 시스템 전체는 공식 메모리 문서에서 확인할 수 있습니다. CLAUDE.md 작성법을 포함한 Claude Code 전반의 모범 사례는 공식 Best Practices 가이드에 정리되어 있습니다.