Why CLAUDE.md? The Anatomy of an AI Instruction File
왜 CLAUDE.md인가 — AI 지시 파일의 해부학
모든 AI 에이전트 실패의 근원은 컨텍스트 부재다 — CLAUDE.md는 그 컨텍스트를 구조화하는 가장 강력한 단일 도구다.
Overview
2026년 초, Andrej Karpathy는 X(트위터)에 짧은 포스트를 올렸다. 자신의 코딩 패턴이 바뀌었다는 것 — 80%가 직접 코딩하고 20%가 AI를 보조 도구로 쓰던 방식에서, 이제는 80%가 에이전트 주도 코딩이고 자신은 검토자 역할을 한다는 것이었다. 그는 동시에 이 전환 과정에서 겪은 네 가지 반복적인 AI 실패 패턴도 공유했다.
그 다음 날, 개발자 Forrest Chang이 그 네 가지 패턴을 65줄짜리 CLAUDE.md 파일로 정제해 GitHub에 올렸다. 결과는 폭발적이었다 — 개인 계정과 조직 미러 합산 22만 개가 넘는 star를 기록하며 GitHub 역사상 가장 빠르게 성장한 저장소 중 하나가 되었다.
이 현상은 단순한 유행이 아니다. CLAUDE.md라는 파일이 해결하는 문제는 실제로 존재하고, 그 문제는 매일 개발자들을 좌절시키고 있다. AI가 틀린 가정을 하고 코드를 만들어내거나, 요청하지 않은 기능을 추가하거나, 관련 없는 코드를 '개선'하거나, '완료'라고 말하면서 실제로 작동하는지 확인하지 않는 경험 — 이 모든 것이 하나의 파일로 극적으로 개선된다.
- AI 에이전트가 왜 실패하는지 근본 원인을 설명할 수 있다
- CLAUDE.md가 Claude Code의 컨텍스트 윈도우에 어떻게 주입되는지 이해한다
- 첫 번째 CLAUDE.md를 처음부터 작성할 수 있다
- 좋은 CLAUDE.md와 나쁜 CLAUDE.md의 차이를 구분한다
- 지시 파일이 팀 생산성에 미치는 정량적 영향을 안다
Sections
컨텍스트 주입이란 무엇인가
Claude Code가 실행될 때, Claude 모델은 빈 상태로 시작하지 않는다. 시스템 프롬프트, 사용자 지시, 현재 파일 내용, 그리고 CLAUDE.md 파일들 — 이 모든 것이 컨텍스트 윈도우라는 거대한 텍스트 버퍼에 순서대로 주입된다. Claude는 이 버퍼 전체를 한 번에 읽고 응답을 생성한다.
CLAUDE.md = 이 컨텍스트 버퍼에 자동으로 주입되는 개발자 작성 지시 파일.
핵심은 이렇다: Claude는 당신의 프로젝트에 대해 아무것도 모른다. 당신 팀의 코딩 규칙, 피해야 할 패턴, 선호하는 테스트 전략, 절대로 건드리면 안 되는 파일 — 이 모든 것을 Claude는 당신이 가르쳐주지 않으면 알 수 없다. CLAUDE.md는 그 교육의 도구다.
Anthropic 내부 데이터에 따르면, 잘 구성된 CLAUDE.md를 가진 팀은 그렇지 않은 팀보다 태스크를 40% 빠르게 완료한다. 이유는 단순하다 — 같은 실수를 반복하지 않기 때문이다.
4가지 AI 에이전트 실패 패턴
Karpathy가 명명한 네 가지 패턴은 전 세계 개발자들이 '맞아 바로 이거야'라고 반응한 공통 경험이다.
패턴 1: Silent Assumptions (침묵하는 가정) — AI가 모호한 요청에서 한 가지 해석을 선택하고, 선택했다는 사실조차 말하지 않는다. 개발자는 엉뚱한 방향으로 구현된 코드를 받고 나서야 오해가 있었음을 알게 된다.
패턴 2: Code Hypertrophy (코드 비대화) — 요청한 기능 외에 '있으면 좋을 것 같은' 추상화, 에러 핸들링, 설정 옵션들이 스스로 추가된다. 50줄로 해결할 수 있는 것을 200줄로 만들어낸다.
패턴 3: Collateral Damage (부수 피해) — 요청받지 않은 주변 코드를 '개선'하거나, 형식을 맞추거나, 리팩토링한다. 실제로 요청한 변경과 관련 없는 diff가 리뷰를 어렵게 만든다.
패턴 4: Unverifiable Success (검증 불가 성공) — '완료했습니다'라고 말하지만, 실제로 작동하는지 확인하는 기준을 정의하지 않았다. '잘 작동하게 해주세요'는 성공 기준이 아니다.
이 네 패턴은 모두 같은 근원을 가진다 — 컨텍스트의 부재. Claude는 당신이 원하는 것, 원하지 않는 것, 성공이 무엇을 의미하는지를 가르쳐주지 않으면 스스로 추론해서 채운다.
CLAUDE.md가 컨텍스트 윈도우에 주입되는 방식
Claude Code가 세션을 시작할 때 파일을 로드하는 순서는 정확하게 정의되어 있다.
시스템 프롬프트 — Anthropic이 Claude Code에 내장한 기본 지시들
2. 글로벌 CLAUDE.md (~/.claude/CLAUDE.md) — 모든 프로젝트에 적용되는 개인 규칙
3. 프로젝트 CLAUDE.md (.claude/CLAUDE.md 또는 루트 CLAUDE.md) — 이 저장소에만 적용되는 팀 규칙
4. 로컬 CLAUDE.md (.claude/CLAUDE.md.local) — gitignore된 개인 오버라이드
5.
서브디렉토리 CLAUDE.md — Claude가 해당 경로의 파일에 접근할 때 지연 로드됨
중요한 것은 우선순위다. 더 구체적인 파일이 더 일반적인 파일을 오버라이드한다. 프로젝트 CLAUDE.md의 규칙이 글로벌 CLAUDE.md와 충돌하면, 프로젝트 규칙이 이긴다.
또 하나의 핵심 특성: 서브디렉토리 CLAUDE.md는 세션 시작 시 로드되지 않는다. Claude의 도구가 실제로 그 경로의 파일에 접근할 때 비로소 로드된다. 따라서 중요한 규칙은 서브디렉토리가 아닌 루트 레벨에 두어야 한다.
첫 CLAUDE.md 작성 — 무엇을 담아야 하는가
좋은 CLAUDE.md는 세 가지 질문에 답한다: 이 프로젝트가 무엇인가? 무엇을 해야 하는가? 무엇을 절대로 하지 말아야 하는가?
가장 임팩트 높은 단일 패턴은 Negative Constraints (부정적 제약) 목록이다:
## 하지 말아야 할 것들
- default export 사용 금지
- schema.prisma를 직접 수정하지 말 것
- `any` 타입 추가 금지
- console.log를 프로덕션 코드에 남기지 말 것
- 마이그레이션 파일을 내가 확인하기 전에 생성하지 말 것
이 목록이 강력한 이유는, 금지 규칙 하나가 특정 오류 범주 전체를 예방하기 때문이다. 또한 Claude는 '해야 할 것' 목록보다 '하지 말아야 할 것' 목록에 더 신뢰성 높게 순응한다.
두 번째로 중요한 패턴은 검증 스텝 명시다:
## 변경 후 반드시 실행할 것
- npm test
- npm run typecheck
- 둘 중 하나라도 실패하면 완료를 선언하기 전에 수정할 것
/init 커맨드를 사용하면 현재 프로젝트 구조를 분석해 초안을 자동 생성해준다. 이것을 시작점으로 삼아 정제하는 것이 가장 빠른 접근법이다.
당신이 새로운 팀원을 채용했다고 상상해보자. 그는 훌륭한 개발자다 — 언어를 알고, 패턴을 이해하고, 빠르게 코드를 작성한다. 하지만 첫날 아무 지시 없이 바로 프로덕션 태스크를 맡기면 어떻게 될까?
그는 자신의 경험에서 좋다고 배운 패턴을 적용할 것이다. 기존 팀의 규칙이 아니라 자신이 훈련받은 방식대로. 아마도 좋은 코드를 작성할 것이다 — 하지만 당신이 원하는 방식의 코드가 아닐 수 있다.
Claude는 정확히 이 새 팀원과 같다. 온보딩 문서 없이 바로 투입된 탁월한 개발자. CLAUDE.md는 그 온보딩 문서다. '우리 팀은 이렇게 합니다', '이 파일들은 절대 건드리지 마세요', '완료의 정의는 테스트 통과입니다' — 이것들을 한 번 써두면 Claude는 매번 물어보지 않는다.
가장 좋은 온보딩 문서가 팀의 암묵지를 명문화하듯, 가장 좋은 CLAUDE.md는 '당연히 알겠지'라고 생각해서 말 안 한 것들을 명시적으로 적는다.
실제로 사용되는 프로덕션 CLAUDE.md의 구조를 보여주는 예제다. 각 섹션이 어떤 역할을 하는지, 왜 이 순서로 작성하는지 주목하라.
# CLAUDE.md — MyApp 프로젝트 규칙
## 프로젝트 개요
MyApp은 Next.js 14 + TypeScript + PostgreSQL 기반 SaaS다.
API: /api/* (Next.js API Routes), DB: Prisma ORM.
## 절대 하지 말아야 할 것 (Do NOT)
- `any` 타입 사용 금지 — 타입 에러는 항상 제대로 해결할 것
- default export 금지 — 모든 export는 named export 사용
- `schema.prisma` 직접 수정 금지 — 반드시 나에게 먼저 물어볼 것
- `console.log` 프로덕션 코드에 남기기 금지
- 요청하지 않은 리팩토링 금지 — 관련 없는 코드는 건드리지 말 것
## 코드 스타일
- 컨벤션 참조: src/utils/validators.ts:1-30 (canonical pattern)
- 에러 처리: src/lib/errors.ts의 AppError 클래스 사용
- API 응답: src/lib/api-response.ts 패턴 따를 것
## 변경 후 반드시 실행
1. npm run typecheck → 타입 에러 0개 확인
2. npm test → 테스트 통과 확인
3. 둘 중 하나라도 실패하면 완료 선언 전 수정할 것
## 모호할 때
- 여러 해석이 가능하면 구현 전에 먼저 물어볼 것
- 더 간단한 방법이 있으면 말해줄 것 (구현 전에)맨 위에 프로젝트 개요를 두는 이유는 Claude가 파일을 위에서 아래로 읽으며 초반 내용에 더 집중하기 때문이다. 'Do NOT' 섹션을 두 번째에 배치한 것도 같은 이유다 — 가장 중요한 제약을 빨리 확인시킨다. 코드 스타일 섹션에서 실제 파일 경로와 라인 번호를 참조하는 것은 코드 스니펫을 직접 넣는 것보다 낫다 — 스니펫은 코드가 변경되면 stale해지지만, 파일 참조는 항상 최신이다.
✅ 시니어가 보는 것
- Do NOT 리스트의 구체성 — 'bad code 쓰지 말 것' 같은 모호한 규칙은 의미 없음
- 팀 전체가 기여하고 있는지 (git blame으로 단일 작성자인지 확인)
- 최근에 업데이트되었는지 — 오래된 CLAUDE.md는 없는 것만 못함
- 검증 스텝이 구체적으로 명시되어 있는지
⚠️ 레드 플래그
- CLAUDE.md가 없는 프로젝트 — AI를 진지하게 활용하지 않는 신호
- 모든 항목이 긍정적 지시만 있고 부정적 제약이 없는 경우
- 코드 스니펫을 직접 포함하는 경우 — stale해질 가능성이 높음
- 너무 길어서 실제로 관리되지 않는 경우
🎤 예상 인터뷰 질문
- 팀의 CLAUDE.md에 있는 규칙 중 실제 사고에서 배운 것이 있나요?
- Do NOT 항목을 추가하게 된 구체적인 사건이 있었나요?
- 서브디렉토리 CLAUDE.md와 루트 CLAUDE.md를 어떻게 분리해서 사용하시나요?
Key Takeaways
컨텍스트가 모든 것이다
AI 에이전트 실패의 95%는 모델 한계가 아니라 컨텍스트 부재다. CLAUDE.md는 그 컨텍스트를 구조화하는 도구다.
부정적 제약이 가장 강력하다
Do NOT 목록 하나가 특정 오류 범주 전체를 예방한다. 긍정적 지시보다 부정적 제약이 Claude에게 더 신뢰성 높게 작동한다.
검증 기준을 명시하라
'완료'의 정의를 항상 포함하라. 테스트 통과, 타입체크 성공 — 구체적인 기준 없이는 Claude가 스스로 판단한다.
파일 참조 > 코드 스니펫
CLAUDE.md에 코드를 직접 붙여넣지 마라. src/utils/helpers.ts:1-30 같은 파일 참조가 항상 최신 상태를 유지한다.
/init으로 시작하라
/init 커맨드가 현재 프로젝트 구조를 분석해 초안을 만들어준다. 이것을 기점으로 팀의 암묵지를 추가하라.
실수가 생기면 즉시 추가하라
Claude가 잘못된 행동을 할 때마다 CLAUDE.md에 규칙을 추가하라. 이 피드백 루프가 시간이 지날수록 강력한 팀 도구를 만든다.
팀 문서로 관리하라
CLAUDE.md를 git에 커밋하고 팀 전체가 기여하게 하라. 한 사람의 파일이 아닌 팀의 집단 지식이 되어야 한다.