CLAUDE.md 제대로 작성하기: Claude Code 성능을 극대화하는 실전 가이드

원문: Writing a good CLAUDE.md by Kyle Mistele (HumanLayer)

Claude Code를 사용하면서 "왜 Claude가 내 지시를 무시하지?"라고 생각해 본 적 있으신가요? CLAUDE.md 파일을 제대로 작성하면 이 문제를 해결할 수 있습니다. 이 글에서는 Claude Code의 성능을 극대화하는 CLAUDE.md 작성법을 실전 예제와 함께 상세히 알아봅니다.

---

핵심 원칙: LLM은 (거의) 상태가 없다

LLM은 상태 비저장(stateless) 함수입니다. 추론(inference) 시점에 모델의 가중치는 이미 고정되어 있으므로, 시간이 지나도 학습하지 않습니다. 모델이 여러분의 코드베이스에 대해 아는 것은 오직 컨텍스트 윈도우에 입력된 토큰뿐입니다.

Claude Code 같은 코딩 에이전트 하네스도 마찬가지입니다. 에이전트의 메모리는 명시적으로 관리해야 하며, CLAUDE.md는 기본적으로 모든 세션에 포함되는 유일한 파일입니다.

이것이 의미하는 바

사실 시사점

매 세션 시작 시 Claude는 코드베이스를 전혀 모른다	중요한 정보를 매번 알려줘야 한다
컨텍스트 윈도우가 모든 것이다	불필요한 정보는 성능을 저하시킨다
CLAUDE.md는 모든 세션에 들어간다	여기에 넣는 내용이 가장 높은 레버리지를 가진다

---

CLAUDE.md의 역할: Claude를 코드베이스에 온보딩하기

CLAUDE.md는 Claude를 여러분의 코드베이스에 온보딩시키는 문서입니다. 신입 개발자에게 프로젝트를 소개하는 것처럼 생각하면 됩니다.

포함해야 할 3가지 핵심 요소: WHAT, WHY, HOW

1. WHAT (무엇) - 기술 스택과 프로젝트 구조

## 기술 스택
- Frontend: Next.js 14 (App Router), TypeScript, Tailwind CSS
- Backend: FastAPI, PostgreSQL, Redis
- 인프라: Docker, AWS ECS, Terraform

## 프로젝트 구조
├── apps/
│   ├── web/          # Next.js 프론트엔드
│   └── api/          # FastAPI 백엔드
├── packages/
│   ├── ui/           # 공유 UI 컴포넌트
│   ├── db/           # Prisma 스키마 및 클라이언트
│   └── utils/        # 공통 유틸리티
└── infra/            # Terraform 설정

특히 모노레포에서는 각 앱과 패키지가 무엇인지, 어디서 무엇을 찾을 수 있는지 명확히 알려주는 것이 중요합니다.

2. WHY (왜) - 프로젝트의 목적과 각 부분의 역할

## 프로젝트 개요
스테픈은 M2E 모바일 앱으로, 사용자가 걸으면서
토큰 보상을 받는 서비스입니다.

## 주요 도메인
- **Walking**: GPS 추적, 걸음 수 계산, 보상 로직
- **Shoes**: 신발 상태 관리, 진화 시스템, NFT 민팅
- **Wallet**: 다중 지갑 지원, 토큰 전송, 스테이킹

3. HOW (어떻게) - 실제 작업 방법

## 개발 환경
- 패키지 매니저: pnpm (npm 사용 금지!)
- Node.js 버전: 20.x (nvm 사용 권장)
- Python: 3.11+ (pyenv 사용)

## 주요 명령어
pnpm install          # 의존성 설치
pnpm dev              # 개발 서버 실행
pnpm test             # 테스트 실행
pnpm typecheck        # 타입 검사

## 변경사항 검증
1. pnpm typecheck     # 타입 에러 확인
2. pnpm test          # 테스트 통과 확인
3. pnpm lint          # 린트 검사

---

충격적인 사실: Claude는 종종 CLAUDE.md를 무시한다

Claude Code는 내부적으로 다음과 같은 시스템 메시지를 CLAUDE.md 내용과 함께 전송합니다:

<system-reminder>
IMPORTANT: this context may or may not be relevant to your tasks. 
You should not respond to this context unless it is highly relevant to your task.
</system-reminder>

즉, Claude가 현재 작업과 관련 없다고 판단하면 CLAUDE.md 내용을 무시합니다!

왜 이런 설계가 되었을까?

많은 사용자들이 CLAUDE.md를 "핫픽스" 저장소처럼 사용합니다. 마음에 안 드는 동작이 있을 때마다 지시사항을 추가하다 보니, 파일이 비대해지고 대부분의 내용이 현재 작업과 무관해집니다.

Anthropic 팀은 "나쁜 지시사항을 무시하라"고 했을 때 오히려 더 좋은 결과가 나온다는 것을 발견한 것으로 보입니다.

---

좋은 CLAUDE.md 작성법: 실전 가이드

1. 적을수록 좋다 (Less is More)

연구 결과가 말해주는 것

최근 연구에 따르면:

모델 유형 안정적으로 따를 수 있는 지시사항 수

프론티어 사고 모델 (Claude Sonnet 등)	~150-200개
소형 모델	훨씬 적음 (지수적 성능 감소)
비사고(non-thinking) 모델	사고 모델보다 적음

Claude Code의 시스템 프롬프트 자체에 이미 ~50개의 지시사항이 포함되어 있습니다. 이는 사용 가능한 지시사항 용량의 약 1/3을 이미 차지한다는 의미입니다!

나쁜 예시 ❌

# CLAUDE.md

## 코딩 스타일
- 변수명은 camelCase 사용
- 함수는 20줄 이하로 유지
- 주석은 한글로 작성
- import 순서: 외부 → 내부 → 상대경로
- 빈 줄은 2개 이하
- 세미콜론 항상 사용
- 들여쓰기 2칸
...
(50줄 이상의 코딩 스타일 가이드)

## Git 커밋 메시지
- feat: 새로운 기능
- fix: 버그 수정
- docs: 문서 수정
...
(20줄의 커밋 메시지 가이드)

## 데이터베이스 스키마 작성법
- 테이블명은 복수형
- PK는 id로
...
(30줄의 DB 스키마 가이드)

좋은 예시 ✅

# CLAUDE.md

## 기술 스택
Next.js 14, TypeScript, Prisma, PostgreSQL

## 프로젝트 구조
- apps/web: 프론트엔드
- apps/api: 백엔드 API
- packages/db: DB 스키마

## 필수 명령어
pnpm dev          # 개발 서버
pnpm test         # 테스트
pnpm typecheck    # 타입 검사

## 참고 문서
상세 가이드는 docs/ 디렉토리 참조

HumanLayer의 실제 CLAUDE.md는 60줄 미만입니다!

2. 보편적으로 적용 가능한 내용만

CLAUDE.md는 모든 세션에 들어갑니다. 따라서 내용은 최대한 보편적으로 적용 가능해야 합니다.

포함하면 안 되는 것들

내용 이유

DB 스키마 작성법	매번 DB 작업을 하는 것이 아님
특정 기능의 구현 방법	그 기능 작업할 때만 필요
과거의 버그 수정 이력	현재 작업과 무관
특정 라이브러리 사용법	해당 라이브러리 사용 시에만 필요

포함해야 하는 것들

내용 이유

기술 스택 개요	항상 필요
프로젝트 구조	파일 탐색에 필수
테스트/빌드 명령어	거의 모든 작업에서 사용
패키지 매니저 (npm vs pnpm 등)	일관성 유지에 필수

3. 점진적 공개 (Progressive Disclosure) 패턴

모든 정보를 CLAUDE.md에 넣는 대신, 필요할 때만 참조하도록 구성합니다.

디렉토리 구조 예시

agent_docs/
├── building_the_project.md      # 빌드 방법
├── running_tests.md             # 테스트 실행법
├── code_conventions.md          # 코드 컨벤션
├── service_architecture.md      # 서비스 아키텍처
├── database_schema.md           # DB 스키마 설명
└── api_design.md                # API 설계 원칙

CLAUDE.md에서 참조하는 방법

# CLAUDE.md

## 참고 문서
작업에 필요한 문서를 먼저 읽고 시작하세요:

| 파일 | 설명 | 언제 필요한가 |
|------|------|--------------|
| agent_docs/building_the_project.md | 빌드 및 배포 | 빌드 관련 작업 시 |
| agent_docs/running_tests.md | 테스트 전략 | 테스트 작성/실행 시 |
| agent_docs/code_conventions.md | 코드 스타일 | 새 코드 작성 시 |
| agent_docs/database_schema.md | DB 구조 | DB 마이그레이션 시 |
| agent_docs/service_architecture.md | 시스템 구조 | 새 기능 설계 시 |

**중요**: 코드 스니펫은 복사하지 말고, 실제 파일 위치(예: `src/utils/auth.ts:45`)를 
참조하세요. 복사본은 빠르게 구식이 됩니다.

이 패턴은 Claude Skills의 작동 방식과 개념적으로 유사합니다.

4. Claude는 린터가 아니다!

코드 스타일 가이드라인을 CLAUDE.md에 넣는 것은 매우 흔한 실수입니다.

왜 나쁜가?

문제 영향

LLM은 린터에 비해 비싸고 느림	비용과 시간 낭비
지시사항 수 증가	전체 지시사항 따르기 성능 저하
관련 없는 코드 스니펫이 컨텍스트 차지	유용한 정보 공간 감소

대신 이렇게 하세요

1. 린터와 포매터 설정

// biome.json
{
  "formatter": {
    "indentStyle": "space",
    "indentWidth": 2
  },
  "linter": {
    "rules": {
      "recommended": true
    }
  }
}

2. Claude Code Hook 활용

# .claude/hooks/stop.sh
#!/bin/bash
# Stop Hook: 작업 완료 전 자동으로 린트/포맷 실행
pnpm lint --fix
pnpm format

3. Slash Command로 분리

/.claude/commands/format.md:

코드 스타일 가이드를 확인하고 현재 변경사항을 검토해주세요:

1. `git diff --name-only` 로 변경된 파일 확인
2. 각 파일에 대해 코드 스타일 검토
3. 필요시 수정 제안

이렇게 하면 구현과 포매팅을 분리할 수 있고, 둘 다 더 좋은 결과를 얻습니다.

5. /init 또는 자동 생성 기능 사용 금지

Claude Code와 다른 도구들은 CLAUDE.md를 자동 생성하는 기능을 제공합니다. 사용하지 마세요!

왜?

CLAUDE.md는 Claude Code 하네스의 가장 높은 레버리지 포인트입니다:

나쁜 코드 한 줄 → 나쁜 코드 한 줄

나쁜 계획 한 줄 → 나쁜 코드 여러 줄

나쁜 리서치 한 줄 → 나쁜 계획 여러 줄 → 나쁜 코드 훨씬 더 많이

나쁜 CLAUDE.md 한 줄 → 모든 단계에서 문제 발생!

모든 세션, 모든 작업 단계, 모든 결과물에 영향을 미치기 때문에 한 줄 한 줄 신중하게 작성해야 합니다.

---

실전 CLAUDE.md 템플릿

최소한의 템플릿 (권장)

# 프로젝트명

## 스택
TypeScript, Next.js 14, Prisma, PostgreSQL

## 구조
- src/app: 페이지 및 라우트
- src/components: UI 컴포넌트
- src/lib: 유틸리티 및 헬퍼
- prisma: DB 스키마

## 명령어
pnpm dev        # 개발 서버 (localhost:3000)
pnpm test       # 테스트 실행
pnpm build      # 프로덕션 빌드

## 검증
변경 후 항상: pnpm typecheck && pnpm test

## 문서
상세 가이드: docs/ 디렉토리 참조

모노레포 템플릿

# 스테픈

## 스택
Flutter 3.x, Dart, Riverpod, Firebase, Web3

## 모노레포 구조
├── apps/
│   └── mobile/           # Flutter 앱 (진입점)
├── packages/
│   ├── core/             # 비즈니스 로직
│   ├── data/             # 레포지토리 구현
│   ├── domain/           # 엔티티, 유즈케이스
│   └── presentation/     # UI 컴포넌트
└── docs/                 # 상세 문서

## 명령어
melos bootstrap    # 의존성 설치
melos run test     # 전체 테스트
melos run analyze  # 정적 분석

## 아키텍처
Clean Architecture 적용. 각 레이어 문서:
- docs/architecture.md

## 주의사항
- 상태관리: Riverpod 사용 (Provider 아님)
- 라우팅: go_router
- 네트워크: dio + retrofit

---

체크리스트: 좋은 CLAUDE.md인지 확인하기

작성 후 다음 질문들로 검토해보세요:

• [ ] 300줄 이하인가? (60줄 이하면 더 좋음)
• [ ] 모든 내용이 대부분의 작업에 적용되는가?
• [ ] 코드 스타일 가이드가 포함되어 있지 않은가?
• [ ] 코드 스니펫이 아닌 파일 참조를 사용하는가?
• [ ] 점진적 공개 패턴을 활용하는가?
• [ ] 자동 생성이 아닌 직접 작성했는가?
• [ ] 린터/포매터 설정이 별도로 되어 있는가?

---

요약

원칙 실천 방법

온보딩	WHAT, WHY, HOW를 명확히
Less is More	300줄 이하, 가능하면 60줄 이하
보편적 적용	모든 작업에 해당되는 내용만
점진적 공개	상세 문서는 별도 파일로 분리
린터 활용	스타일 가이드는 린터에게 맡기기
직접 작성	/init 사용 금지, 한 줄씩 신중하게

CLAUDE.md는 Claude Code의 가장 높은 레버리지 포인트입니다. 시간을 들여 신중하게 작성하면, 모든 작업에서 더 나은 결과를 얻을 수 있습니다.

---

참고 자료

• 원문: Writing a good CLAUDE.md
• Context Engineering Best Practices
• Claude Code 공식 문서
• Claude Skills 가이드
• Claude Code Hooks
• Slash Commands