안드레이 카파시의 CLAUDE.md로 AI 코딩 에이전트 환각 끝장내기

AI 코딩 에이전트를 쓸 때 이런 경험 한번쯤 있으셨을 겁니다.

 

• 뜬금없이 작동 잘 되던 다른 파일 코드까지 모조리 재작성해버림
• 단순한 버그 수정 요청인데 엉뚱하게 복잡한 프레임워크를 새로 도입함
• 코드 다 짜서 문제없다는데 막상 돌려보면 빌드 에러 터짐

테슬라 전 AI 이사이자 OpenAI 창립 멤버인 안드레이 카파시(Andrej Karpathy)가 언급한 AI 코딩의 고질적 문제점들을 해결하기 위해 개발자 커뮤니티에서 만들어진 핵심 솔루션, 바로 CLAUDE.md 프로젝트 지침 파일을 소개합니다.

 

💡 CLAUDE.md가 도대체 뭔가요?

CLAUDE.md는 Anthropic의 CLI 기반 코딩 에이전트인 Claude Code나 Cursor, Windsurf 같은 AI 개발 도구가 프로젝트에 진입할 때 가장 먼저 읽는 최우선 지침서입니다.

 

프로젝트 루트(Root) 디렉토리에 이 파일 하나만 던져두면, AI가 내 코드를 건드리기 전에 "어떤 원칙으로 코드를 짜야 하는지"를 자동으로 파악하고 작동합니다.

 

🎯 4가지 핵심 원칙 (The 4 Core Principles)

카파시 스타일 CLAUDE.md 핵심 원칙은 매우 직관적입니다.

 

원칙	내용 요약	AI 오작동 방지 효과
1. Think Before Coding	혼자 추측해서 짜지 말고, 불분명하면 개발자에게 되물어라.	엉뚱한 방향으로 코드 짜는 낭비 방지
2. Simplicity First	오버엔지니어링 금지. 200줄짜리 복잡한 구조보다 50줄짜리 단순한 코드를 짜라.	불필요한 프레임워크/추상화 오남용 방지
3. Surgical Changes	요청한 코드만 외과수술처럼 정밀하게 수정하고 주변 파일은 건드리지 마라.	멀쩡한 파일 포맷팅 파괴 및 사이드 이펙트 방지
4. Goal-Driven Execution	코드를 다 짰으면 끝났다고 하지 말고 직접 테스트/빌드해서 동작을 검증해라.	코드 환각(Hallucination) 및 빌드 에러 방지

🛠️ 실제 사용법 (30초 완성)

1. 사용 중인 프로젝트의 최상위 루트 디렉토리에 CLAUDE.md 파일을 생성합니다.
2. 아래의 템플릿 내용을 그대로 복사해 붙여넣습니다.
3. 맨 아래 Project Context & Commands 부분에 본인 프로젝트의 기술 스택과 테스트/빌드 명령어를 맞춰 수정합니다.

📄 CLAUDE.md 템플릿 전문 (복사해서 사용하세요)

Markdown

# Claude Code Project Guidelines

## Core Principles

1. **Think Before Coding**
   - Don't guess or assume requirements. If something is ambiguous, trade-offs exist, or context is missing, ask for clarification.
   - Plan out complex changes before writing code. Outline your approach step-by-step.

2. **Simplicity First**
   - Avoid over-engineering, unnecessary abstractions, or future-proofing for hypothetical needs.
   - Write the simplest code that completely solves the current problem.
   - Prefer concise, readable solutions (e.g., 50 clear lines over 200 lines of complex framework abstractions).

3. **Surgical Changes**
   - Only modify what was explicitly requested or strictly necessary for the fix.
   - Do not touch unrelated files, refactor working code unnecessarily, or change code formatting style across the repository.
   - Preserve existing code conventions and patterns.

4. **Goal-Driven Execution**
   - Set clear, verifiable success criteria before executing tasks.
   - Verify changes after implementation through tests, dry-runs, or manual verification steps.
   - Ensure the solution genuinely works as expected before declaring completion.

---

## Project Context & Commands

- **Tech Stack:** TypeScript, React, Node.js (필요 시 본인 스택으로 변경)
- **Build Command:** `npm run build`
- **Test Command:** `npm test`
- **Lint Command:** `npm run lint`

🚀 적용 후 기대 효과

매번 프롬프트 창에 "관련 없는 파일 건드리지 마", "테스트 꼭 돌려보고 말해줘" 라고 잔소리할 필요가 사라집니다. AI 에이전트의 개발 생산성을 200% 끌어올리고 싶다면, 지금 바로 프로젝트에 CLAUDE.md를 적용해 보세요!