클로드 코드 CLAUDE.md 위치와 작성법 완벽 가이드

CLAUDE.md는 정확히 어디에 둬야 하는가

클로드 코드를 쓰다 보면 가장 먼저 헷갈리는 게 "이 파일을 대체 어디에 만들어야 하나"다. 결론부터 말하면 CLAUDE.md는 스코프에 따라 놓는 위치가 다르고, 클로드 코드는 이 파일들을 전부 읽어서 하나의 컨텍스트로 합친다. 위치별로 정리하면 이렇다.

전역(사용자) 설정: ~/.claude/CLAUDE.md. 어떤 프로젝트에서 클로드 코드를 실행하든 항상 로드되는 파일이다. 코딩 스타일 취향, 개인적으로 선호하는 툴 사용법처럼 프로젝트와 무관하게 항상 적용하고 싶은 규칙을 여기 넣는다. 예를 들어 "커밋 메시지는 항상 한국어로 작성한다", "패키지 매니저는 npm 대신 pnpm을 쓴다" 같은 개인 습관이 여기 해당한다.

프로젝트 설정: 프로젝트 루트의 ./CLAUDE.md 또는 ./.claude/CLAUDE.md. 팀원 전체가 공유하는 규칙이라 git으로 커밋해서 버전 관리한다. 빌드 명령어, 아키텍처 설명, 코딩 컨벤션처럼 이 프로젝트에서 작업하는 사람이라면 누구나 알아야 할 내용을 넣는다.

로컬(개인) 설정: ./CLAUDE.local.md. 프로젝트 루트에 두지만 .gitignore에 추가해서 나만 보는 파일이다. 로컬 개발 서버 주소, 개인 테스트 데이터 경로처럼 팀과 공유할 필요 없는 정보를 넣는다.

하위 디렉토리 CLAUDE.md: 모노레포처럼 큰 프로젝트에서는 src/api/CLAUDE.md, packages/web/CLAUDE.md처럼 서브디렉토리마다 CLAUDE.md를 따로 둘 수 있다. 이건 세션 시작 시 무조건 로드되는 게 아니라, 클로드가 그 디렉토리 안의 파일을 실제로 읽을 때 온디맨드로 로드된다. 즉 src/api/ 밑에서 작업할 때만 src/api/CLAUDE.md가 컨텍스트에 들어온다.

조직 관리 정책: macOS는 /Library/Application Support/ClaudeCode/CLAUDE.md, 리눅스는 /etc/claude-code/CLAUDE.md, 윈도우는 C:\Program Files\ClaudeCode\CLAUDE.md. IT/DevOps 팀이 MDM 같은 도구로 배포하는 조직 전체 정책이라 개인이 끌 수 없다.

로드 순서와 병합 방식

여기서 중요한 오해가 하나 있다. 여러 CLAUDE.md 파일이 있으면 "가장 가까운 것 하나만" 적용되는 게 아니라, 발견된 파일들이 전부 컨텍스트에 이어 붙는다(concatenate). 로드 순서는 스코프가 넓은 것부터 좁은 것 순이다.

1. 조직 관리 정책 (managed policy)
2. 사용자 전역 ~/.claude/CLAUDE.md
3. 프로젝트 ./CLAUDE.md 혹은 ./.claude/CLAUDE.md
4. 로컬 ./CLAUDE.local.md

클로드 코드는 현재 작업 디렉토리에서 위로 올라가며 각 디렉토리의 CLAUDE.md와 CLAUDE.local.md를 전부 찾는다. foo/bar/에서 실행했다면 foo/CLAUDE.md가 먼저, foo/bar/CLAUDE.md가 그 다음에 배치된다. 즉 실행 위치에 가까운 지시사항일수록 나중에 읽혀서 우선순위가 높게 작동하는 구조다. 같은 디렉토리 안에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙는다.

실제로 어떤 파일이 로드됐는지 확인하려면 세션에서 /context를 실행해서 Memory files 목록을 보면 된다. 파일을 만들었는데 여기 안 뜬다면 경로가 틀렸거나 로드 대상이 아닌 위치에 있는 것이다.

서브디렉토리 CLAUDE.md, 이렇게 활용하면 좋다

모노레포에서 프론트엔드와 백엔드 컨벤션이 완전히 다르다면 루트 CLAUDE.md 하나에 다 우겨넣기보다 이렇게 나누는 게 낫다.

project-root/
├── CLAUDE.md              # 전체 아키텍처, 공통 규칙
├── frontend/
│   └── CLAUDE.md          # React 컨벤션, 컴포넌트 구조
└── backend/
    └── CLAUDE.md          # API 설계 규칙, DB 마이그레이션 방법

frontend/ 안의 파일을 건드릴 때만 frontend/CLAUDE.md가 로드되기 때문에 백엔드 작업 중에 불필요한 컨텍스트가 섞이지 않는다. 더 세밀하게 나누고 싶다면 .claude/rules/ 디렉토리에 paths 프론트매터로 스코프를 지정한 규칙 파일을 두는 방법도 있다.

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

# API 개발 규칙

- 모든 엔드포인트는 입력 검증을 거쳐야 한다
- 에러 응답은 표준 포맷을 따른다

이 방식은 src/api/ 밑의 TypeScript 파일을 다룰 때만 규칙이 컨텍스트에 들어오므로, CLAUDE.md 하나에 온갖 규칙을 다 넣어서 매 세션 컨텍스트를 낭비하는 걸 막아준다.

CLAUDE.md에 뭘 써야 하는가

핵심 기준은 하나다. "내가 매번 다시 설명해야 하는 것"을 적는다. 클로드가 같은 실수를 두 번째 반복했을 때, 코드 리뷰에서 클로드가 몰랐던 이 프로젝트만의 관례가 드러났을 때, 새 팀원에게도 똑같이 알려줘야 할 내용일 때 CLAUDE.md에 추가한다.

넣어야 할 것:

• 빌드/테스트/린트 명령어 (npm run build, pytest -x, make lint 등 실제로 실행하는 명령)
• 프로젝트 아키텍처 개요 — 디렉토리 구조가 뭘 의미하는지
• 코딩 컨벤션 — 들여쓰기, 네이밍, import 순서처럼 도구 기본값과 다른 것
• 클로드가 자주 틀리는 부분에 대한 명시적 지시
• 절대 하면 안 되는 것 (예: 특정 파일 직접 수정 금지, 특정 라이브러리 사용 금지)

넣지 말아야 할 것:

• 코드베이스를 읽으면 자동으로 알 수 있는 디렉토리 구조 나열
• package.json만 봐도 나오는 의존성 목록
• 너무 장황한 배경 설명

문서 자체도 "코드를 잘 짜라" 같은 두루뭉술한 문장보다 "2칸 들여쓰기를 쓴다", "커밋 전에 npm test를 실행한다", "API 핸들러는 src/api/handlers/에 있다"처럼 검증 가능한 구체적 문장이 훨씬 잘 지켜진다. CLAUDE.md는 시스템 프롬프트가 아니라 세션 시작 시 사용자 메시지 형태로 주입되는 컨텍스트이기 때문에, 강제 규칙이 아니라 참고 지침으로 취급된다는 점도 기억해두면 좋다. 반드시 지켜야 하는 동작(커밋 직전 실행 등)은 CLAUDE.md 대신 훅(hook)으로 강제하는 게 맞다.

파일 크기도 신경 써야 한다. 200줄을 넘어가면 컨텍스트 소비도 늘고 지시사항 준수율도 떨어진다는 게 공식 가이드다. 내용이 길어지면 .claude/rules/로 쪼개거나, @경로 임포트 문법으로 다른 파일을 참조하는 방식을 쓴다. 단, 임포트한 파일도 세션 시작 시 똑같이 로드되므로 컨텍스트 절약 목적이 아니라 순수하게 파일 구성을 정리하는 용도로만 유효하다. 임포트는 최대 4단계까지 재귀적으로 따라간다.

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

홈 디렉토리 밖을 가리키는 임포트(예: @~/.claude/my-project-instructions.md)는 프로젝트 CLAUDE.md에 있을 경우 "external import"로 분류돼서 처음 발견될 때 승인 다이얼로그가 뜬다. 다른 사람이 커밋한 프로젝트 파일이 내 홈 디렉토리의 파일을 몰래 끌어오는 걸 막기 위한 안전장치다.

AGENTS.md와 같이 쓰는 법

이미 다른 AI 코딩 도구용으로 AGENTS.md를 쓰고 있다면 클로드 코드는 AGENTS.md를 직접 읽지 않는다는 점을 알아야 한다. 대신 CLAUDE.md를 만들어서 임포트하면 중복 없이 두 도구가 같은 지시사항을 공유할 수 있다.

@AGENTS.md

## Claude Code

`src/billing/` 하위 변경은 항상 plan mode를 사용한다.

또는 심볼릭 링크로 처리해도 된다.

ln -s AGENTS.md CLAUDE.md

윈도우에서는 심볼릭 링크 생성에 관리자 권한이 필요하니 @AGENTS.md 임포트 방식을 쓰는 게 편하다.

/init으로 자동 생성하기

빈 프로젝트에 CLAUDE.md를 처음부터 손으로 쓸 필요는 없다. 클로드 코드 세션에서 /init을 실행하면 코드베이스를 분석해서 빌드 명령어, 테스트 방법, 프로젝트 컨벤션을 자동으로 뽑아 CLAUDE.md를 생성해준다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선 제안을 준다. 이후에는 클로드가 스스로 알아내지 못하는 내용(팀 내부 규칙, 배포 절차 등)을 손으로 다듬으면 된다.

실전 CLAUDE.md 예시

Next.js + tRPC + Prisma로 구성된 실제 프로젝트라면 이런 식으로 작성한다.

# 프로젝트 개요

Next.js 15 App Router 기반 SaaS 대시보드. tRPC로 API를 구성하고
Prisma + PostgreSQL을 쓴다. 인증은 next-auth v5.

## 빌드 & 테스트

- 개발 서버: `pnpm dev`
- 타입 체크: `pnpm typecheck`
- 테스트: `pnpm test` (vitest, watch 모드는 `pnpm test:watch`)
- 커밋 전 반드시 `pnpm lint && pnpm typecheck` 통과 확인

## 아키텍처

- `src/server/routers/`: tRPC 라우터, 도메인별로 파일 분리
- `src/server/db/schema.prisma`: DB 스키마, 마이그레이션은
  `pnpm prisma migrate dev --name <설명>`으로 생성
- `src/app/`: App Router 페이지. 서버 컴포넌트가 기본값이며
  클라이언트 컴포넌트는 파일 최상단에 `"use client"` 명시

## 컨벤션

- 컴포넌트는 named export만 사용, default export 금지
- API 에러는 `TRPCError`로 던지고 절대 `throw new Error()` 직접 사용 금지
- import 순서: 외부 패키지 → `@/` 절대경로 → 상대경로

## 주의사항

- `src/legacy/` 디렉토리는 마이그레이션 대상이라 신규 코드 추가 금지
- 결제 관련 로직(`src/server/routers/billing.ts`)은 수정 전 반드시
  테스트 케이스부터 작성

이 정도 분량이면 200줄 제한에도 여유가 있고, 클로드가 매번 다시 물어봐야 했던 것들(빌드 명령, 마이그레이션 방법, 에러 처리 컨벤션)을 한 번에 해결해준다.

한국어로 응답하게 만들기

클로드 코드가 영어로 답하는 게 불편하다면 CLAUDE.md에 명시적으로 한국어 사용을 지시하면 된다.

## 언어 설정

- 모든 응답, 커밋 메시지, 코드 주석은 한국어로 작성한다.
- 단, 변수명/함수명 등 코드 식별자는 영어 컨벤션을 따른다.
- 에러 메시지나 로그 문자열도 한국어로 작성한다.

전역으로 항상 적용하고 싶다면 ~/.claude/CLAUDE.md에, 이 프로젝트에서만 적용하고 싶다면 프로젝트 루트의 CLAUDE.md에 넣으면 된다. 다만 CLAUDE.md는 강제 규칙이 아니라 컨텍스트라서 100% 준수를 보장하지는 않는다. 지시가 애매하거나 다른 CLAUDE.md의 내용과 충돌하면 클로드가 임의로 하나를 고를 수 있으니, "항상 한국어로"처럼 구체적이고 명확한 문장으로 써야 준수율이 올라간다.

문제가 생겼을 때 디버깅하는 법

CLAUDE.md를 만들었는데 클로드가 지시를 안 따른다면 다음 순서로 확인한다.

1. /context를 실행해서 Memory files 목록에 해당 파일이 실제로 로드됐는지 확인한다.
2. 파일 위치가 올바른 스코프에 있는지 다시 확인한다. 서브디렉토리 CLAUDE.md는 그 디렉토리의 파일을 클로드가 실제로 읽어야 로드된다는 점을 놓치기 쉽다.
3. 지시사항을 더 구체적으로 바꾼다. "코드를 깔끔하게 짜라"보다 "2칸 들여쓰기, 세미콜론 사용"이 훨씬 잘 지켜진다.
4. 여러 CLAUDE.md 파일 사이에 충돌하는 규칙이 없는지 점검한다.
5. /compact로 컨텍스트를 압축한 뒤 지시사항이 사라진 것 같다면, 프로젝트 루트 CLAUDE.md는 압축 후 디스크에서 다시 읽어와 자동으로 재주입되지만, 서브디렉토리 CLAUDE.md나 paths 프론트매터가 붙은 규칙은 자동으로 재주입되지 않는다. 해당 디렉토리의 파일을 다시 읽을 때만 재로드된다.

특정 시점에 반드시 실행돼야 하는 동작(예: 매 커밋 전에 특정 스크립트 실행)은 CLAUDE.md로 지시하지 말고 훅으로 강제하는 게 맞다. CLAUDE.md는 어디까지나 클로드의 판단을 돕는 컨텍스트지, 클라이언트 레벨에서 강제되는 설정이 아니기 때문이다.

이렇게 위치별 역할을 정확히 나누고, 파일을 짧고 구체적으로 유지하고, 필요할 때만 로드되는 서브디렉토리/rules 구조를 활용하면 CLAUDE.md는 매 세션 반복 설명을 없애주는 가장 효율적인 장치가 된다.

CLAUDE.md와 auto memory는 다른 물건이다

CLAUDE.md만 쓰다 보면 놓치기 쉬운 부분이 auto memory다. 둘 다 매 세션 컨텍스트에 로드된다는 점은 같지만 역할이 완전히 다르다. CLAUDE.md는 사람이 직접 작성하는 규칙이고, auto memory는 클로드가 작업 중 스스로 알아낸 사실을 저장해두는 자동 메모다. 예를 들어 세션 중에 "빌드 명령이 사실 pnpm build:prod였다"는 걸 클로드가 직접 알아냈다면, 그 정보는 auto memory에 자동으로 저장될 수 있다.

auto memory는 저장소별로 ~/.claude/projects/<project>/memory/ 아래에 쌓인다. 이 디렉토리 안의 MEMORY.md가 색인 역할을 하고, 세션 시작 시 이 파일의 앞부분(최대 200줄 또는 25KB)만 로드된다. 상세한 내용은 debugging.md, api-conventions.md처럼 주제별 파일로 분리되고, 이 파일들은 필요할 때만 온디맨드로 읽힌다. /memory 명령으로 이 폴더를 열어서 클로드가 뭘 기억하고 있는지 직접 확인하고 편집할 수도 있다.

CLAUDE.md에 넣을지 auto memory에 맡길지 헷갈린다면 기준은 이렇다. 팀 전체가 항상 알아야 하고 코드 리뷰에서 문서화해야 할 규칙이라면 CLAUDE.md에 손으로 적는다. 반대로 세션 도중 클로드가 시행착오 끝에 알아낸 사소한 팁이라면 auto memory에 맡겨도 무방하다. "항상 pnpm을 쓴다"처럼 팀 컨벤션은 CLAUDE.md에, "이 저장소의 테스트는 로컬 Redis가 떠 있어야 통과한다"처럼 환경 특이사항은 auto memory에 자연스럽게 쌓이도록 두는 식이다.

흔한 실수 몇 가지

CLAUDE.md를 쓰다 보면 반복적으로 나오는 실수 패턴이 있다.

모든 걸 한 파일에 우겨넣기. 프로젝트가 커질수록 CLAUDE.md 하나에 프론트엔드, 백엔드, 인프라 규칙을 전부 쓰고 싶어지는데, 이러면 200줄 권장 상한을 금방 넘긴다. 서브디렉토리 CLAUDE.md나 .claude/rules/로 분리하는 게 장기적으로 유지보수가 쉽다.

추상적인 지시만 쓰기. "좋은 코드를 작성하라", "일관성을 유지하라" 같은 문장은 클로드 입장에서 검증할 기준이 없어서 사실상 무시되기 쉽다. "함수는 30줄을 넘기지 않는다", "에러는 항상 커스텀 AppError 클래스로 던진다"처럼 판단 기준이 명확한 문장으로 바꿔야 실제로 지켜진다.

업데이트를 안 하기. 프로젝트 구조가 바뀌었는데 CLAUDE.md는 예전 그대로 남아있으면, 클로드가 존재하지 않는 디렉토리를 참조하거나 이미 폐기된 컨벤션을 따르게 된다. 코드 리뷰 때 CLAUDE.md도 같이 갱신 대상에 포함시키는 습관이 필요하다. /doctor 체크업을 실행하면 코드베이스에서 유추 가능한 불필요한 서술(디렉토리 구조 나열 등)을 정리하라는 제안도 받을 수 있다.

민감한 정보를 프로젝트 CLAUDE.md에 적기. 내부 서버 주소나 개인 API 키처럼 팀 전체에 공유하면 안 되는 정보는 git으로 커밋되는 프로젝트 CLAUDE.md가 아니라 .gitignore에 등록된 CLAUDE.local.md에 적어야 한다.

이 네 가지만 피해도 CLAUDE.md는 훨씬 오래, 훨씬 안정적으로 제 역할을 한다.