Claude Code의 CLAUDE.md 활용법

이 글에서 다루는 내용

Claude Code에서 세션마다 자동으로 컨텍스트에 주입되는 CLAUDE.md 파일의 개념과 계층 구조, 네이티브/프론트/백엔드를 모두 다루는 풀스택 개발자가 모노레포 환경에서 CLAUDE.md를 어떻게 배치하고 작성해야 Claude가 일관된 규칙을 따르는지를 실전 예시와 함께 정리합니다. 마지막에 관련 기술 용어도 짧게 풀어둡니다.

CLAUDE.md란

CLAUDE.md는 Claude Code가 새 세션을 시작할 때마다 자동으로 읽어서 컨텍스트에 주입하는 마크다운 파일입니다. 프로젝트의 빌드 명령, 디렉터리 구조, 코드 컨벤션, 팀 규칙 같은 것을 여기에 적어두면 매 세션마다 같은 설명을 반복하지 않아도 Claude가 알아서 따라줍니다. 내부 동작은 단순합니다. 별도의 DB나 장기 학습이 아니라, 파일 내용을 그대로 시스템 프롬프트 뒤에 붙이는 구조입니다. 그래서 "Claude가 기억한다"는 표현보다는 "매번 읽어온다"가 정확한 멘탈 모델입니다.

계층 구조와 로드 순서

Claude Code는 여러 위치의 CLAUDE.md를 모두 모아서 읽되, 뒤로 갈수록 우선순위가 높아집니다.

위치	용도
/etc/claude-code/CLAUDE.md	조직/머신 전체 정책 (관리자용)
~/.claude/CLAUDE.md	개인 전역 설정 (모든 프로젝트 공통)
<repo>/CLAUDE.md	프로젝트 공통 (팀 공유, git 커밋)
<repo>/CLAUDE.local.md	로컬 전용 (gitignore, 개인 메모)
<subdir>/CLAUDE.md	하위 디렉터리 전용 (모노레포에 유용)

하위 디렉터리의 CLAUDE.md는 시작 시점에 통째로 로드되지 않고, Claude가 그 디렉터리 안의 파일을 읽을 때 함께 주입됩니다. 덕분에 모노레포에서 apps/mobile/CLAUDE.md, apps/web/CLAUDE.md, services/api/CLAUDE.md를 따로 두는 패턴이 잘 맞습니다. 각 스택의 규칙이 해당 폴더를 건드릴 때만 활성화되므로 컨텍스트가 깔끔해집니다.

풀스택 모노레포 실전 예시

전역 ~/.claude/CLAUDE.md — 본인의 선호

## 언어
- 답변은 한국어, 코드 주석은 영어

## 공통 선호
- TypeScript strict 모드, `any` 금지 (`unknown` + type guard 사용)
- 에러는 절대 삼키지 않기 — 명시적으로 처리하거나 rethrow
- 커밋 전 typecheck + lint + test 자동 실행

## 커뮤니케이션
- 변경 전 계획을 먼저 제시, 확인받고 실행
- 큰 리팩터는 plan mode로

모노레포 루트 CLAUDE.md

# MyApp Monorepo

## 구조
- `apps/mobile` — React Native (iOS/Android)
- `apps/web` — Next.js 15 (App Router)
- `services/api` — NestJS + PostgreSQL
- `packages/shared` — 공통 타입/유틸

## 공통 규칙
- 패키지 매니저: pnpm (npm/yarn 사용 금지)
- 공유 타입은 반드시 `packages/shared/types`에 정의
- API 응답 스키마는 zod로 검증

@./docs/architecture.md
@./docs/api-conventions.md

apps/mobile/CLAUDE.md — 네이티브

## React Native 규칙
- Expo SDK 사용, bare workflow 금지
- 네비게이션: expo-router (React Navigation 직접 사용 X)
- 상태관리: Zustand, 서버 상태는 TanStack Query

## 명령어
- 개발: `pnpm dev`
- iOS 빌드: `pnpm ios`
- Android 빌드: `pnpm android`

## 플랫폼 분기
- iOS/Android 차이는 `.ios.tsx` / `.android.tsx`로 분리
- Platform.OS 체크는 최소화

apps/web/CLAUDE.md — 프론트엔드

## Next.js 규칙
- App Router만 사용 (pages router 금지)
- Server Component 기본, `'use client'`는 필요할 때만
- 스타일: Tailwind + shadcn/ui

## 데이터 페칭
- 서버: fetch + Next 캐시
- 클라이언트: TanStack Query
- 절대 useEffect에서 fetch하지 않기

services/api/CLAUDE.md — 백엔드

## NestJS 규칙
- 모듈 구조: feature 기반 (`users/`, `orders/`)
- DTO는 class-validator + class-transformer
- DB: Prisma, raw SQL은 금지 (성능 이슈 시 예외)

## 명령어
- 개발: `pnpm start:dev`
- 마이그레이션: `pnpm prisma migrate dev`
- 테스트: `pnpm test`, e2e는 `pnpm test:e2e`

## 주의
- 환경변수 추가 시 `src/config/env.schema.ts`에 zod 스키마 업데이트
- 트랜잭션은 `PrismaService.$transaction` 사용

작성 팁

짧게, 밀도 높게 쓰기. 20~80줄이 sweet spot입니다. 100줄을 넘어가면 Claude가 모든 규칙을 일관되게 따르지 못하는 경향이 있습니다. README에 있는 내용을 중복해서 쓰지 말고 @./README.md로 참조하세요.

"코드만 봐서는 알 수 없는 것"만 적기. 파일 구조나 import 경로는 Claude가 직접 읽어서 파악합니다. 대신 "왜 이렇게 하는지", "팀 내부 암묵적 컨벤션", "하면 안 되는 것" 같은 맥락 지식을 담으세요.

HTML 주석 활용. <!-- 팀 내부 메모 --> 형태로 감싼 블록 주석은 컨텍스트 주입 시점에 제거되어 토큰을 아낄 수 있습니다. 단 코드 블록 안의 주석은 그대로 유지됩니다.

@경로 참조로 분리. 상세한 API 컨벤션이나 아키텍처 문서는 별도 파일로 빼고 @./docs/xxx.md로 참조하면 본체 CLAUDE.md를 가볍게 유지할 수 있습니다.

유용한 명령어

세션 안에서 /memory를 입력하면 현재 로드된 CLAUDE.md 목록을 보여주고 바로 편집할 수 있는 에디터가 열립니다. 대화 중에 # 이 규칙 기억해줘처럼 #로 시작하는 메시지를 보내면 Claude가 어느 CLAUDE.md 파일에 이 규칙을 추가할지 되물어봅니다. 파일을 외부에서 수정한 경우 세션을 재시작하거나 /memory로 리로드해야 반영됩니다.