CLAUDE.md Mastery — Context Engineering

CLAUDE.md 마스터하기 — 컨텍스트 엔지니어링의 핵심

2026년의 실력은 프롬프트 문구가 아니라 Claude가 받는 컨텍스트의 구조 설계에서 결정된다. CLAUDE.md는 그 구조의 중심이다.

🍌 NANO BANANA CHEATSHEET · CH 06

Overview

개관

2026년 최고의 Claude Code 실력자들이 공통으로 강조하는 것: 프롬프트 엔지니어링보다 컨텍스트 엔지니어링이 중요하다.

Claude에게 전달되는 모든 것 — CLAUDE.md, 메모리, 스킬, MCP 도구 목록, 파일 내용 — 의 구조를 어떻게 설계하느냐가 진짜 실력이다. 개별 요청의 문구는 2차적이다.

CLAUDE.md는 이 구조의 핵심이다. 매 세션마다 자동으로 로드되는 '팀의 집단 기억'이다. 너무 짧으면 효과가 없고, 너무 길면 Claude가 일부를 무시한다. 파워 유저의 CLAUDE.md 평균: 60줄.

🎯 Learning Goals

60줄 이내의 효과적인 CLAUDE.md를 작성할 수 있다
자주 적용되는 규칙과 조건부 규칙을 Rules로 분리하는 방법을 안다
디렉토리별 CLAUDE.md로 영역별 규칙을 충돌 없이 관리한다
컨텍스트 컴팩션이 일어날 때 핵심 정보가 살아남도록 설계한다

Sections

본문

60줄의 과학 — 뭘 넣고 뭘 빼나

CLAUDE.md에 넣을 것:

프로젝트 개요 (2-3줄)
가장 중요한 금지사항 (5-10개, 앞부분에)
코드 스타일 핵심 규칙 (3-5개)
특이한 아키텍처 결정 (잊기 쉬운 것만)
자주 쓰는 명령어 레퍼런스

빼야 할 것:

코드에서 읽을 수 있는 것 (eslint 설정, tsconfig)
Git 히스토리로 알 수 있는 것 (누가 뭘 작업했는지)
일시적 작업 컨텍스트 (현재 진행 중인 PR)

Rules — 조건부 로딩 시스템

CLAUDE.md가 60줄을 넘기 시작하면 Rules 시스템을 활용한다. .claude/rules/ 디렉토리에 개별 파일로 저장하면, 관련 컨텍스트가 감지될 때만 로드된다.

예: react-patterns.md는 React 파일을 편집할 때만, sql-queries.md는 데이터베이스 관련 작업 시에만 로드된다. 항상 모든 규칙을 로드하는 것보다 컨텍스트를 아낄 수 있다.

디렉토리별 CLAUDE.md — 충돌 없는 다층 규칙

루트 CLAUDE.md → src/CLAUDE.md → src/components/CLAUDE.md → src/api/CLAUDE.md

각 디렉토리의 CLAUDE.md는 해당 경로에서 작업할 때 추가로 로드된다. 컴포넌트 디렉토리에는 Tailwind 클래스 컨벤션, API 디렉토리에는 에러 처리 패턴 — 영역별로 전문화된 규칙을 적용할 수 있다.

💡 Analogy · 비유

신입사원 온보딩 문서의 최적 길이

너무 짧은 온보딩 문서는 신입이 매번 물어봐야 한다. 너무 긴 온보딩 문서는 아무도 읽지 않는다. 60페이지 매뉴얼보다 2페이지 '가장 중요한 것들' 문서가 실제로 읽힌다. CLAUDE.md도 같다 — Claude가 실제로 전부 읽고 적용하는 최적 길이가 있다.

파워 유저 스타일의 CLAUDE.md 예시 (60줄 이내)

markdown

# SynapseGo Platform — Claude Code Guidelines

## 프로젝트
Next.js 15 App Router + FastAPI + PostgreSQL + Redis. 실시간 AI 에이전트 협업 플랫폼.

## 절대 금지 (Hook으로도 강제됨)
- `rm -rf`, `git push --force` → 확인 없이 실행 금지
- 하드코딩된 API 키, 비밀번호 → 즉시 .env로 이동
- `any` 타입 → 구체적 타입 또는 unknown으로

## 코드 스타일
- 컴포넌트: Server Component 기본, 클라이언트 상태만 'use client'
- API 응답: { data, error, meta } 구조 통일
- 에러: Result 패턴 (throw 금지, 명시적 에러 반환)
- 테스트: RTL + Vitest, getByRole 우선 로케이터

## 아키텍처 주의
- WebSocket은 /api/ws 전용 핸들러로만
- AI 에이전트 작업은 반드시 jobQueue를 통해 비동기 처리
- DB 쿼리는 항상 Prisma ORM, 직접 SQL 지양

## 자주 쓰는 명령어
- 개발 서버: `npm run dev`
- 테스트: `npm test -- --watch`
- DB 마이그레이션: `npx prisma migrate dev`
- 타입 검사: `npx tsc --noEmit`

## 컴팩션 전 저장
- 중요한 아키텍처 결정은 .claude/memory/에 기록

절대 금지 섹션을 앞에 배치해 Claude가 가장 먼저 읽도록 한다. Hook으로도 강제된다는 표시로 이 규칙의 신뢰도를 높인다. 자주 쓰는 명령어는 레퍼런스로 포함해 Claude가 직접 실행할 수 있게 한다.

🏭 현업에서의 평가

코드 기여자 권한을 줄 때 첫 번째로 확인하는 것: .claude/CLAUDE.md가 있는가. 없다면 이 팀은 Claude Code를 장난감으로 쓰고 있다. 있다면 도구로 쓰고 있다. 내용을 보면 도구를 얼마나 잘 이해하는지 알 수 있다.

✅ 시니어가 보는 것

60줄 이내로 핵심만 담겨 있는가
가장 중요한 금지사항이 앞부분에 배치되어 있는가
코드에서 파생 가능한 내용은 제외되어 있는가
git에 커밋되어 팀이 공유하고 있는가

Key Takeaways

핵심 정리

60줄이 황금 비율

Claude가 전부 읽고 적용하는 최대 길이. 초과분은 Rules로 분리.

중요한 것을 앞에 배치

Claude는 컨텍스트 앞부분을 더 신뢰한다. 금지사항 최우선.

CLAUDE.md는 팀 자산 — git에 커밋

개인 설정은 팀에 아무런 혜택이 없다.

← Ch05 · Integration Skills — Claude Talks to Everything Ch07 · Hooks System — From Advisory to Guaranteed →