direcf / 하네스 엔지니어링 / Ch03
GitHub ↗
CHAPTER 03 OF 10
📄

CLAUDE.md Mastery

CLAUDE.md 마스터리 — 50줄의 예술

CLAUDE.md는 200줄 이내, 지시가 아닌 원칙으로, Progressive Disclosure 패턴으로 — 이 3가지만 지켜도 에이전트 일관성이 극적으로 개선된다.

CLAUDE.md Mastery cheatsheet
🍌 NANO BANANA CHEATSHEET · CH 03

Overview

개관

CLAUDE.md는 하네스 엔지니어링에서 가장 큰 레버리지를 가진 단일 아티팩트다. 동시에 가장 많이 잘못 쓰이는 것이기도 하다. 1,000줄짜리 CLAUDE.md를 자랑스럽게 보여주는 사람들이 있는데, 이건 역효과다.

ETH Zurich 연구(arXiv:2602.11988)의 충격적인 발견: LLM이 자동 생성한 컨텍스트 파일(/init 명령 등으로 생성)은 태스크 성공률을 3% 낮추고 비용을 20% 올렸다. 수동으로 작성한 파일조차 성공률을 겨우 4% 올렸다.

결론: CLAUDE.md는 지시(instruction)의 도구가 아니라 집중(focus)의 도구다. 에이전트에게 모든 것을 알려주는 게 아니라, 에이전트가 현재 태스크에 집중할 수 있도록 꼭 필요한 컨텍스트만 제공하는 것이다. 그 나머지는 Progressive Disclosure — 필요할 때 로드한다.

🎯 Learning Goals
  • CLAUDE.md의 4개 스코프와 로딩 순서를 설명할 수 있다
  • 50-200줄 황금률의 근거를 설명할 수 있다
  • Progressive Disclosure 패턴으로 CLAUDE.md를 구조화할 수 있다
  • @import 구문과 .claude/rules/ 폴더를 활용할 수 있다

Sections

본문

4-Level 계층 구조와 로딩 메커니즘

Claude Code는 CLAUDE.md를 4개 스코프에서 로드하고 모두 연결(concatenate)한다:

스코프 위치 공유 범위
Managed (org) /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) 조직 전체
User (global) ~/.claude/CLAUDE.md 나의 모든 프로젝트
Project ./CLAUDE.md 또는 ./.claude/CLAUDE.md 팀 (git 공유)
Local ./CLAUDE.local.md (gitignored) 나만, 이 프로젝트

로딩 메커니즘: cwd에서 위로 올라가며 모든 CLAUDE.md와 CLAUDE.local.md를 찾는다. 파일시스템 루트 → cwd 순서로 연결 (cwd에 가까울수록 내용이 나중에 읽힘 = 사실상 높은 우선순위).

중요: 하위 디렉토리의 CLAUDE.md는 lazy loading — Claude가 해당 디렉토리의 파일을 읽을 때 비로소 로드된다. 전체를 미리 로드하는 것이 아니다.

HTML 주석 <!-- ... -->은 Claude의 컨텍스트에서 제거된다. 유지보수 메모를 숨기기에 좋다.

50-200줄 황금률 — 그 이상은 역효과

경험적 한계: LLM은 150-200개 지시를 합리적인 일관성으로 따를 수 있다. 그 이상을 추가하면 전체 지시 준수율이 균등하게 저하된다. 개별 규칙이 무작위로 무시된다.

  • Claude Code 자체 시스템 프롬프트: 약 50개 지시
  • HumanLayer의 CLAUDE.md: 60줄 이내
  • WPBoilerplate의 AGENTS.md: 1,000줄 이상 — 모든 가이드가 인용하는 안티패턴

넣을 것 vs. 넣지 말 것:

넣어야 함 넣지 말아야 함
Claude가 추측할 수 없는 bash 명령어 Claude가 코드에서 파악할 수 있는 것
기본값과 다른 코드 스타일 규칙 표준 언어 관례
테스트 지시사항, 선호 런너 상세 API 문서 (링크로 대체)
리포지토리 예절 (브랜치 명명, PR 규칙) 자주 바뀌는 정보
아키텍처 결정 사항 (ADR 참조) 긴 설명이나 튜토리얼
개발자 환경 특이사항, 필요 환경변수 "깔끔한 코드를 써라" 같은 자명한 조언

Progressive Disclosure 패턴

핵심 CLAUDE.md를 50줄로 유지하면서도 에이전트에게 풍부한 컨텍스트를 제공하는 패턴.

구조:

project/
  CLAUDE.md               ← 핵심 50줄 + 포인터들
  agent_docs/
    building.md           ← 빌드 상세
    architecture.md       ← 아키텍처 상세
    db_schema.md         ← DB 스키마
    conventions.md        ← 코딩 규칙
  .claude/rules/
    api-rules.md          ← path-scoped: src/api/**에만 적용
    test-rules.md         ← path-scoped: tests/**에만 적용

CLAUDE.md에서 참조:

## More Detail On-Demand
- 빌드 방법: @agent_docs/building.md
- 아키텍처: @agent_docs/architecture.md
- DB 스키마: @agent_docs/db_schema.md

장점: 깨진 포인터(링크)는 큰 소리로 실패한다. 오래된 설명(stale description)은 소리 없이 실패한다. 포인터 방식이 훨씬 안전하다.

실전 CLAUDE.md 템플릿

HumanLayer, shanraisshan/claude-code-best-practice, 다수의 실무 팀의 검증된 구조:

# Project: [이름]

## Overview
- Stack: Next.js 15, TypeScript strict, PostgreSQL via Prisma
- Build: `npm run build`
- Test: `npm run test` (Vitest unit), `npm run test:e2e` (Playwright)
- Lint: `npm run lint` (Oxlint)

## Layout
- `src/app/` — Next.js App Router 페이지
- `src/lib/` — 공용 유틸리티
- `infrastructure/` — READ ONLY (태스크가 명시적으로 인프라 작업이 아닌 한)

## Key Decisions
- Auth: Clerk (NOT NextAuth — 2026-03 마이그레이션, ADR #003)
- DB: Prisma만 사용 (raw SQL 금지 — SQL injection 사례, ADR #007)

## Enforcement
위 규칙은 권고사항입니다. 하드 제한은:
- `.claude/settings.json`: 권한 규칙
- `~/.claude/settings.json`: 훅
- CI 파이프라인: 린터 + 타입 체크

핵심: 맨 마지막 "Enforcement" 섹션이 중요하다. "이 규칙들은 실제로 어디서 강제되는가"를 명시하면 Claude가 우선순위를 이해한다.

💡 Analogy · 비유
신입 직원 온보딩 문서

CLAUDE.md를 신입 직원에게 주는 온보딩 문서라고 생각해보자.

나쁜 온보딩 문서는 회사의 모든 규정, 모든 프로세스, 회사 역사까지 담은 200페이지짜리 매뉴얼이다. 신입 직원은 첫날 이것을 읽고 모두 기억할 수 없다. 기억하려 해도 뭐가 중요한지 모른다.

좋은 온보딩 문서는 딱 1페이지다. 오늘 당장 알아야 할 5가지, 항상 지켜야 할 3가지, 더 알고 싶을 때 읽을 링크들. 나머지는 필요할 때 찾아보는 wiki에 있다.

CLAUDE.md가 바로 이 1페이지 온보딩 문서여야 한다. 핵심 규칙 몇 가지, 중요한 결정들, 더 알고 싶을 때 읽을 파일 링크들. Claude는 현명하다 — 모든 것을 알려줄 필요 없이 어디서 찾아야 하는지만 알려줘도 된다.

새 프로젝트에서 CLAUDE.md를 빠르게 생성하는 스크립트. /init 명령 대신 수동으로 작성하되, 프로젝트 컨텍스트를 자동 감지해서 초안을 만들어준다.

bash
#!/usr/bin/env bash
# generate-claude-md.sh — 프로젝트 자동 감지로 CLAUDE.md 초안 생성
# 주의: 이것은 초안입니다. 반드시 수동으로 검토하고 수정하세요.

OUTPUT="CLAUDE.md"

# 프로젝트 이름
PROJECT_NAME=$(basename "$(pwd)")

# 스택 감지
STACK=""
[ -f package.json ] && STACK=$(python3 -c "
import json
d=json.load(open('package.json'))
deps = {**d.get('dependencies',{}), **d.get('devDependencies',{})}
stack=[]
if 'next' in deps: stack.append('Next.js')
if 'react' in deps: stack.append('React')
if 'typescript' in d.get('devDependencies',{}): stack.append('TypeScript')
if '@prisma/client' in deps: stack.append('Prisma')
print(', '.join(stack) if stack else 'Node.js')
" 2>/dev/null)
[ -f pyproject.toml ] || [ -f setup.py ] && STACK="Python"
[ -f Cargo.toml ] && STACK="Rust"
[ -f go.mod ] && STACK="Go"

# 테스트 명령 감지
TEST_CMD="npm test"
[ -f pyproject.toml ] && TEST_CMD="pytest"
[ -f Cargo.toml ] && TEST_CMD="cargo test"
[ -f go.mod ] && TEST_CMD="go test ./..."

# 린트 명령 감지
LINT_CMD="npm run lint"
[ -f pyproject.toml ] && LINT_CMD="ruff check ."
[ -f Cargo.toml ] && LINT_CMD="cargo clippy"

cat > "$OUTPUT" << EOF
# Project: $PROJECT_NAME

## Overview
- Stack: ${STACK:-알 수 없음}
- Test: \`$TEST_CMD\`
- Lint: \`$LINT_CMD\`

## Layout
<!-- 주요 디렉토리와 역할을 여기에 작성 -->

## Key Decisions
<!-- 중요한 아키텍처 결정, 왜 그 기술을 선택했는지 -->

## Critical Constraints
<!-- 절대 위반하면 안 되는 규칙 (최대 5개) -->
- NEVER commit directly to main

## Enforcement
- \`.claude/settings.json\`: 권한 규칙 (팀 공유)
- \`~/.claude/settings.json\`: 훅 (개인)
- CI 파이프라인: 린터 + 타입 체크
EOF

echo "✅ $OUTPUT 생성 완료"
echo "⚠️  반드시 수동으로 검토하고 수정하세요 (ETH Zurich: 자동 생성은 성공률 3% 하락)"
echo "📏 현재 줄 수: $(wc -l < $OUTPUT) — 목표: 50-200줄"

스크립트가 package.json, pyproject.toml 등을 분석해서 스택을 자동 감지하고 CLAUDE.md 초안을 생성한다. 가장 중요한 것은 마지막 경고 메시지 — ETH Zurich 연구에 따르면 자동 생성 컨텍스트 파일은 역효과가 날 수 있으니 반드시 수동으로 다듬어야 한다.

🏭 현업에서의 평가
누군가의 CLAUDE.md를 보면 그 사람이 AI 도구를 얼마나 이해하고 있는지 즉시 알 수 있다. 200줄 이하, Progressive Disclosure, Enforcement 섹션 — 이 3가지가 있으면 '이 사람은 안다'고 판단한다.

✅ 시니어가 보는 것

  • 전역 CLAUDE.md가 200줄 이내로 관리되고 있는가
  • LLM이 자동 생성한 내용이 아닌 수동으로 작성된 내용인가
  • Progressive Disclosure 패턴으로 세부사항을 별도 파일로 분리했는가
  • .claude/rules/에 path-scoped 규칙이 있는가
  • Enforcement 섹션에서 규칙이 실제로 어디서 강제되는지 명시했는가

⚠️ 레드 플래그

  • CLAUDE.md가 없음
  • 1,000줄 이상의 CLAUDE.md (WPBoilerplate 안티패턴)
  • /init으로 자동 생성한 CLAUDE.md를 그대로 사용
  • 모든 규칙을 CLAUDE.md에 넣고 훅이나 권한 설정 없음

🎤 예상 인터뷰 질문

  1. CLAUDE.md를 200줄 이하로 유지해야 하는 이유는? 그 이상이 되면 무슨 일이 생기는가?
  2. Progressive Disclosure 패턴에서 @import와 .claude/rules/의 차이는?
  3. ETH Zurich 연구에서 자동 생성 CLAUDE.md가 왜 역효과가 났는가?
숙달 vs 익숙함: 단순히 아는 사람은 CLAUDE.md에 규칙을 넣는다. 마스터한 사람은 CLAUDE.md에 무엇을 넣지 않을지를 더 고민한다. Enforcement 섹션을 추가하고, agent_docs/로 세부사항을 분리하고, HTML 주석으로 유지보수 메모를 숨기고, path-scoped 규칙으로 파일 타입별 지침을 분리한다.

Key Takeaways

핵심 정리

4개 스코프

Managed → User(~/.claude) → Project(./) → Local — 모두 concatenate되어 로드된다.

50-200줄 황금률

그 이상이면 모든 규칙 준수율이 균등하게 저하된다. 핵심만 남기고 나머지는 링크로.

자동 생성은 역효과

ETH Zurich: /init 자동 생성 파일은 성공률 -3%, 비용 +20%. 수동 작성이 필수.

지시가 아닌 원칙

Step 1, 2, 3 절차 대신 'why'와 원칙을 쓰면 에지 케이스에서도 올바른 결정을 내린다.

Progressive Disclosure

50줄 핵심 + agent_docs/에 세부사항 + .claude/rules/에 path-scoped 규칙.

Enforcement 섹션 필수

CLAUDE.md 규칙은 권고다. 하드 제한이 어디에 있는지 명시해야 Claude가 우선순위를 안다.

@import 구문

@path/to/file 문법으로 외부 파일을 세션 시작 시 로드. 최대 4단계 재귀.

HTML 주석 활용

주석은 Claude 컨텍스트에서 제거된다. 유지보수 메모를 숨기기에 완벽.

← Ch02 · Claude Code's Internal Architecture Ch04 · Permission System Design →