Claude Code의 버그와 환각을 줄이는 비결: CLAUDE.md 실전 작성 가이드 & 템플릿

Claude Code를 쓰다 보면 다음과 같은 난감한 상황을 종종 겪게 됩니다.

• 분명 TypeScript 프로젝트인데 any 타입을 남발하거나 JS 문법으로 작성함
• 프로젝트에서 쓰는 스타일(Tailwind, CSS Modules 등)을 무시하고 인라인 스타일을 적용함
• 테스트 코드를 돌려보지도 않고 "작업이 완료되었습니다"라며 커밋을 요구함
• 레거시 API나 쓰지 않기로 한 서드파티 라이브러리를 멋대로 npm install 해버림

이 문제의 90%는 에이전트의 지능 부족이 아니라, 프로젝트의 맥락(Context)을 전달하지 않아서 발생합니다.

Claude Code는 세션을 시작할 때 프로젝트 루트의 CLAUDE.md를 최우선으로 읽고 지침을 학습합니다. 이번 글에서는 Claude Code의 버그 발생률을 극적으로 낮추는 CLAUDE.md 작성법과 실전 템플릿을 정리합니다.

---

1. CLAUDE.md란 무엇이며 어떻게 동작하는가?

CLAUDE.md는 AI 에이전트를 위한 프로젝트 전용 시스템 프롬프트 겸 온보딩 문서입니다.

• 자동 주입: 터미널에서 claude를 실행하면 프로젝트 루트의 CLAUDE.md가 컨텍스트 윈도우 상단에 자동으로 로드됩니다.
• 디렉토리별 계층 구조 지원: 모노레포(Monorepo)의 경우 루트뿐만 아니라 하위 패키지 디렉토리에 각각 CLAUDE.md를 두면 해당 디렉토리 작업 시 하위 규칙이 추가 적용됩니다.
• 비용 절감 효과: 매 프롬프트마다 "테스트 돌려줘", "스타일 규칙 지켜줘"라고 길게 지시할 필요가 없어 불필요한 토큰 낭비를 줄입니다.

---

2. 좋은 CLAUDE.md를 작성하는 4가지 핵심 원칙

(1) 추상적인 칭찬 대신 "구체적인 명령어"를 적어라

• ❌ "코드를 깔끔하게 작성하고 테스트를 잘 수행해줘."
• ⭕ "수정 후 반드시 npm run test:unit과 npm run lint를 실행해 실패가 없어야 함."

(2) 금지 조항(Anti-patterns)을 명확히 명시하라

에이전트가 흔히 저지르는 실수를 방지하는 가장 좋은 방법은 하지 말아야 할 행동을 못 박는 것입니다.

• 예: "절대로 any 타입을 사용하지 말고 제네릭 또는 unknown으로 선언할 것"
• 예: "새로운 라이브러리를 설치하기 전에는 반드시 사용자에게 사전 승인을 요청할 것"

(3) 디렉토리 구조와 파일 명명 규칙을 가이드하라

에이전트가 엉뚱한 위치에 새 파일을 만드는 것을 방지합니다.

• 예: "공용 컴포넌트는 components/ui/, 페이지별 컴포넌트는 components/features/{feature}/에 작성"
• 예: "파일 이름은 kebab-case, 컴포넌트 이름은 PascalCase 사용"

(4) Git 커밋 규칙을 고정하라

• 예: "커밋 메시지는 한글 대신 영문 Conventional Commits 형식(feat:, fix:)을 사용할 것"

---

3. 바로 복사해서 쓰는 실전 템플릿

실제 프로젝트 루트에 CLAUDE.md라는 이름으로 저장해 사용할 수 있는 범용 템플릿입니다.

# Project Overview & Guidelines

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.x (Strict mode)
- Styling: Tailwind CSS, Radix UI
- State Management: TanStack Query (v5), Zustand
- Testing: Jest, React Testing Library

## Build & Test Commands
- Local Dev Server: `npm run dev` (Runs on port 3000)
- Type Check: `npm run type-check` (Must pass without errors)
- Unit Tests: `npm test`
- Single Test: `npm test -- <path-to-test-file>`
- Linter: `npm run lint`

## Architecture & Code Style
1. **TypeScript Strictness**:
   - `any` is strictly prohibited. Use proper type definitions or `unknown` with type guards.
   - Do not use `@ts-ignore`. If unavoidable, use `@ts-expect-error` with a descriptive reason.

2. **Component Conventions**:
   - Client components must start with `'use client';` at the very top.
   - Separate business logic into custom hooks under `hooks/`.
   - Prefer named exports over default exports for components.

3. **Error Handling**:
   - Wrap async server actions with standardized error response objects (`{ success: false, error: ... }`).

## Rules of Engagement for Claude
- **Verification First**: After modifying any functional code, always run `npm test` and `npm run type-check` to verify changes.
- **Minimal Diffs**: Do not reformat untouched parts of files. Keep edits tightly scoped to the requested task.
- **Dependencies**: Never add new packages without explicit user confirmation.
- **Git Commit**: Use Conventional Commits (`feat:`, `fix:`, `refactor:`, `test:`).

---

4. 실무 활용 팁: CLAUDE.local.md 활용

개인별 API 키, 로컬 테스트 포트, 혹은 특정 개발자만의 환경 변수처럼 git에 공유되면 안 되는 개인 설정은 .gitignore에 다음을 추가해 관리할 수 있습니다.

CLAUDE.local.md

Claude Code는 CLAUDE.md를 읽은 뒤 CLAUDE.local.md가 있으면 이를 병합하여 읽으므로, 팀 공통 규칙과 개인 로컬 규칙을 깔끔하게 분리할 수 있습니다.

---

마치며

AI 에이전트를 잘 다루는 개발자는 프롬프트를 화려하게 쓰는 사람이 아니라, 에이전트가 실수할 수 없는 환경(가드레일)을 만들어두는 개발자입니다.

오늘 작업하는 프로젝트에 5분만 투자해 CLAUDE.md를 만들어보세요. 에이전트의 답변 품질과 코드 완성도가 단번에 달라지는 것을 경험하실 수 있습니다.