당신은 CLAUDE.md를 작성했습니다. 프로젝트 루트(root)에 그것을 두었습니다. 하지만 Claude Code는 여전히 any를 사용하고, 당신이 Next.js를 원했음에도 Express를 선택하며, 여전히 당신의 명명 규칙(naming conventions)을 무시합니다.

익숙한 상황인가요? 당신만 그런 것이 아닙니다.

우리의 이전 기사에서 우리는 시스템 프롬프트(system prompts)를 설계하기 위한 5가지 규칙을 다루었습니다. 오늘은 특정 파일인 CLAUDE.md와 그것을 비효율적으로 만드는 실수들에 집중해 보겠습니다.

우리의 AI Autonomous Revenue Project를 통해 여러 프로젝트에 걸쳐 CLAUDE.md 설정을 구축한 후, 우리는 왜 당신의 CLAUDE.md가 "작동하지 않는지"를 설명하는 5가지 일반적인 실패 패턴과 각 패턴을 어떻게 수정할 수 있는지를 식별했습니다.

실수 1: 지침(Instructions) 대신 포부(Aspirations)를 작성하는 것

문제점

# 철학 (Philosophy)
- 클린 코드 (Clean code)는 중요합니다
- 우리는 영리함보다 가독성을 가치 있게 여깁니다
...

이것은 지침 세트가 아니라 팀 선언문처럼 읽힙니다. "클린 코드는 중요합니다"라는 문장은 Claude Code에게 실행 가능한 정보를 전혀 제공하지 않습니다. 무엇이 클린 코드인가요? 그것을 어떻게 측정하나요?

인간 팀원들은 문화적 맥락에서 의미를 추론할 수 있습니다. AI는 할 수 없습니다. AI는 텍스트를 문자 그대로 해석합니다.

해결 방법

# 코딩 규칙 (Coding Rules)
- 함수는 30줄 미만이어야 합니다. 더 길어지면 더 작은 함수로 추출하세요.
- 변수 이름: camelCase, 최소 3자 (루프 카운터만 단일 문자 허용)
...

원칙: 통과/실패(pass/fail)로 평가할 수 있는 규칙을 작성하세요. 규칙이 준수되었는지 확인할 수 없다면, Claude Code도 그것을 따를 수 없습니다.

실수 2: 너무 많은 콘텐츠 (중요한 규칙이 묻힘)

문제점

당신의 CLAUDE.md는 스택 세부 정보, 모든 명령어, 모든 디렉토리 설명, 80개의 코딩 규칙, Git 워크플로우, 배포 지침 등 모든 것을 다루느라 200줄이 넘습니다.

모든 것이 중요하다면, 아무것도 중요하지 않습니다. 긴 설정 파일은 핵심적인 규칙의 무게를 희석시킵니다.

해결 방법

# CRITICAL (항상 준수할 것)
- TypeScript strict mode (엄격 모드). `any` 타입 사용 절대 금지
- 기본적으로 Server Components 사용. "use client"는 명시적인 지시어가 있을 때만 사용
...

원칙 (Principle): 3계층 구조를 사용하세요:

1. CRITICAL (최상단에 3~5개 규칙 — 타협 불가능한 규칙)
2. Reference info (스택, 명령어 — Claude가 알아야 할 정보)
3. Details elsewhere (포괄적인 컨벤션을 위한 문서 링크/)

실수 3: 실제로 사용하지 않는 기술을 나열하는 것

문제점

# Stack
- Next.js 14 (App Router 사용)
- NextAuth.js v5 (인증용)    ← 아직 설치되지 않음
...

Claude Code는 CLAUDE.md를 절대적인 사실(ground truth)로 취급합니다. 프로젝트에 존재하지 않는 라이브러리를 나열하면 다음과 같은 문제가 발생합니다:

• 설치되지 않은 모듈을 임포트(import)함
• 사용할 수 없는 API를 기준으로 코드를 작성함
• 실제 설정과 모순되는 구조를 생성함

이는 보통 템플릿을 복사한 후 커스텀하는 것을 잊었을 때 발생합니다.

해결 방법

# Stack (실제 설치됨 — package.json과 대조하여 확인)
- Next.js 14 (App Router 사용)
- Drizzle ORM + SQLite (src/lib/db/schema.ts)
...

원칙 (Principle): 실제로 설치된 것만 나열하세요. 사용 불가능한 것은 명시적으로 언급하세요. 이렇게 하면 Claude가 이를 제안하는 것을 방지할 수 있습니다.

실수 4: 대안 없는 제약 사항

문제점

# Rules
- `any` 타입을 사용하지 말 것
- 새로운 의존성(dependencies)을 추가하지 말 것
...

"하지 말 것(don'ts)" 목록은 Claude에게 무엇을 피해야 하는지는 알려주지만, 대신 무엇을 사용해야 하는지는 알려주지 않습니다. 만약 any가 금지되었다면, 타입 가드(type guards)와 함께 unknown을 사용해야 할까요? 제네릭(Generics)을 사용해야 할까요? 아니면 명시적인 타입 정의를 사용해야 할까요?

해결 방법

# Type Safety
- `any`를 절대 사용하지 말 것. 대신:
  - 외부 API 응답 → Zod 스키마로 정의하고, `z.infer<typeof schema>` 사용
...

원칙 (Principle): 모든 "하지 말 것(don't)"에 대해 "대신 할 것(do instead)"을 짝지어 주세요. 이렇게 하면 모호함을 제거하고 Claude에게 명확한 진행 경로를 제공할 수 있습니다.

실수 5: 한 번 작성하고 절대 업데이트하지 않는 것

문제점

당신의 CLAUDE.md는 프로젝트가 시작된 3개월 전에 작성되었습니다. 그 이후로:

• 패키지 매니저가 npm에서 pnpm으로 변경됨
• 테스트 프레임워크가 Jest에서 Vitest로 전환됨
• 디렉터리 구조가 재구성됨

Claude Code는 이제 npm test를 실행하고(실패), Jest 구문을 작성하며(잘못됨), 더 이상 존재하지 않는 디렉터리에 파일을 생성합니다.

해결 방법 (The Fix)

업데이트 트리거 섹션을 추가하세요:

# Meta
Last updated: 2026-08-01
Update this file when:
...

원칙: CLAUDE.md는 살아있는 문서입니다. 매월 또는 프로젝트 설정이 변경될 때마다 검토하세요. 오래된 지침은 지침 자체가 없는 것보다 더 나쁩니다.

빠른 점검 목록: 당신의 CLAUDE.md가 실제로 작동하나요?

• 규칙이 구체적이며 통과/실패 테스트가 가능함 (추상적이지 않음)
• 파일 상단에 ≤5개의 규칙을 가진 CRITICAL 섹션이 존재함
• Stack 섹션의 모든 기술 스택이 실제로 설치되어 있음 (package.json 확인)
• 모든 '하지 말 것(don't)'에는 상응하는 '대신 할 것(do instead)'이 있음
• 파일이 지난 30일 이내에 검토되었음
• 전체 길이가 100줄 미만임 (자세한 내용은 별도 문서 참조)

자료 (Resources)

CLAUDE.md를 처음부터 작성하는 시행착오를 건너뛰고 싶다면:

🎁 Claude Code Config Starter Pack (무료) — 위의 모든 원칙을 따르는 3가지 템플릿(Next.js, TypeScript Library, Python FastAPI).

🛠️ Claude Code Config Pack — 20 Templates ($5) — Go, Rust, Flutter, Terraform 등 20개 프로젝트 유형에 대한 Docker 검증 구성.

📘 The AI Coding Prompt Toolkit ($5) — 프로젝트 설정, 기능 구현, 테스트 및 리팩토링을 위한 52가지 구조화된 프롬프트.

CLAUDE.md에서 어떤 실수를 발견했나요? 아래에 댓글을 남겨주세요. 제가 놓친 패턴에 대해 듣고 싶습니다.