Karpathy의 CLAUDE.md가 48K 스타를 받은 이유 — 그리고 나만의 CLAUDE.md 작성법

Karpathy의 CLAUDE.md가 48K 스타를 받은 이유 — 그리고 나만의 CLAUDE.md 작성법

마크다운 파일 하나가 AI 코딩 정확도를 65%에서 94%로 올렸습니다.

48,000개의 별이 말하는 것

2026년 1월, Andrej Karpathy가 트위터에 글을 올렸습니다.

"LLM 코딩 에이전트의 문제는 더 이상 구문 오류가 아닙니다. 판단력(judgment)의 문제입니다."

Karpathy는 자신의 워크플로우가 "80% 수동 코딩 / 20% 에이전트"에서 "80% 에이전트 / 20% 수정"으로 바뀌는 과정에서, LLM이 반복적으로 보이는 실패 패턴을 관찰했습니다. 그리고 그 관찰을 하나의 CLAUDE.md 파일로 정리한 레포가 andrej-karpathy-skills입니다.

결과: 48,900개 이상의 GitHub 스타. 하루 만에 7,900개가 찍혔습니다. 마크다운 파일 하나가 왜 이런 반응을 얻었을까요?

LLM이 코딩할 때 보이는 4가지 실패 패턴

Karpathy가 관찰한 패턴은 "Claude Code를 써본 사람이라면 누구나 겪었을" 것들입니다:

1. Silent Assumptions (침묵의 가정)

AI에게 "이 함수를 리팩토링해"라고 하면, 확인 없이 자기 나름의 해석으로 달려갑니다. 데이터베이스 스키마가 PostgreSQL인지 MySQL인지 물어보지 않고, 자기가 맞다고 생각하는 쪽으로 진행합니다.

❌ AI가 하는 것: "I'll refactor this using the repository pattern..."
✅ AI가 해야 하는 것: "I see two possible approaches. Which do you prefer?"

2. Overengineering (과잉 설계)

"로그인 폼 만들어줘"라고 하면 OAuth 2.0 + JWT + refresh token + 2FA + rate limiting까지 구현합니다. 100줄이면 될 것을 1,000줄로 만듭니다.

❌ 요청: "validation 추가해"
   결과: 500줄의 커스텀 validation 프레임워크

✅ 기대:
   필드 3개에 대한 if 문 10줄

3. Scope Creep (범위 침범)

버그 하나를 고쳐달라고 했는데, 주변 코드의 변수명도 바꾸고, 주석도 다시 쓰고, 포매팅도 수정합니다. diff를 보면 실제 수정은 3줄인데 변경된 파일이 15개입니다.

❌ git diff: 200줄 변경, 실제 의미 있는 변경 3줄
✅ git diff: 딱 3줄 변경

4. Lack of Judgment (판단력 부재)

문법적으로는 맞지만, "이게 진짜 좋은 코드인가?"에 대한 판단이 없습니다. 시니어 개발자라면 "이건 너무 복잡한데?"라고 할 코드를, AI는 자신 있게 제출합니다.

Karpathy의 4가지 규칙

이 실패 패턴에 대응하는 4가지 규칙이 CLAUDE.md의 전부입니다:

Rule 1: Think Before Coding

가정하지 마세요. 혼란을 숨기지 마세요. 트레이드오프를 드러내세요.

구현하기 전에:

• 가정을 명시적으로 밝힙니다
• 여러 해석이 가능하면 선택지를 제시합니다 — 조용히 하나를 고르지 않습니다
• 더 간단한 방법이 있으면 말합니다
• 뭔가 불명확하면 멈추고 물어봅니다

Rule 2: Simplicity First

문제를 해결하는 최소한의 코드. 추측으로 만든 것은 없어야 합니다.

• 요청받지 않은 기능 추가 금지
• 한 번만 쓰는 코드에 추상화 금지
• 요청하지 않은 "유연성"이나 "설정 가능성" 금지
• 불가능한 시나리오에 대한 에러 핸들링 금지
• 200줄이 50줄이 될 수 있으면 다시 작성

자문: "시니어 엔지니어가 이걸 보고 '이건 너무 복잡한데?'라고 할까?" 그렇다면 단순화.

Rule 3: Surgical Changes

필요한 것만 건드립니다. 자기가 만든 쓰레기만 치웁니다.

기존 코드를 편집할 때:

• 인접한 코드, 주석, 포매팅을 "개선"하지 않습니다
• 고장나지 않은 것을 리팩토링하지 않습니다
• 기존 스타일과 다르게 하고 싶어도 기존 스타일을 따릅니다
• 관련 없는 데드 코드를 발견하면 삭제하지 않고 언급만 합니다

자신의 변경으로 인해 미사용이 된 것만 정리합니다:

• 자신의 변경이 만든 미사용 import/변수/함수는 제거
• 기존에 있던 데드 코드는 요청받기 전에는 제거하지 않음

테스트: 모든 변경된 줄은 사용자의 요청에 직접 추적 가능해야 합니다.

Rule 4: Goal-Driven Execution

성공 기준을 정의합니다. 확인될 때까지 반복합니다.

작업을 검증 가능한 목표로 변환합니다:

• "validation 추가해" → "잘못된 입력에 대한 테스트를 작성하고, 통과시켜라"
• "버그 수정해" → "버그를 재현하는 테스트를 작성하고, 통과시켜라"
• "X를 리팩토링해" → "리팩토링 전후에 테스트가 통과하는지 확인해라"

다단계 작업에는 간단한 계획을 제시합니다:

1. [단계] → 검증: [확인 방법]
2. [단계] → 검증: [확인 방법]
3. [단계] → 검증: [확인 방법]

강한 성공 기준은 에이전트가 독립적으로 반복할 수 있게 합니다. 약한 성공 기준("잘 되게 해")은 끊임없는 확인을 요구합니다.

나만의 CLAUDE.md 작성법 — 실전 가이드

karpathy-skills를 그대로 쓸 수도 있지만, 프로젝트에 맞는 규칙을 직접 추가하면 효과가 더 커집니다. 실전에서 검증된 패턴들을 공유합니다.

기본 구조

# Project Rules

## 코딩 원칙
(karpathy-skills의 4가지 규칙)

## 프로젝트 규칙
(이 프로젝트에만 적용되는 규칙)

## 금지사항
(절대 하지 말아야 할 것들)

프로젝트 규칙 작성 팁

1. 반복되는 수정 지시를 규칙으로 만드세요

AI에게 3번 이상 같은 피드백을 줬다면, 그건 규칙이 되어야 합니다.

## 프로젝트 규칙
- 한국어 콘텐츠는 항상 합니다/입니다 존댓말체로 작성
- slug 규칙: 한국어 포스트는 접미사 없음, 영어는 -en 접미사
- 커밋은 사용자가 명시적으로 요청했을 때만 수행

2. "하지 마" 규칙이 "해라" 규칙보다 효과적입니다

LLM은 새로운 것을 추가하는 성향이 강합니다. 그래서 뭘 하지 말아야 하는지를 알려주는 것이 더 효과적입니다.

## 금지사항
- 기존 코드에 독스트링이나 타입 어노테이션을 추가하지 말 것
- 파일을 새로 만들기보다 기존 파일을 수정할 것
- git push는 사용자가 명시적으로 요청하지 않는 한 절대 하지 말 것
- 에러 핸들링을 추측으로 추가하지 말 것

3. 구체적 예시를 포함하세요

추상적 규칙은 무시되기 쉽습니다. 구체적 예시를 주세요.

## 스타일 가이드
- 컴포넌트 파일명: PascalCase (예: UserProfile.tsx)
- 유틸 함수: camelCase (예: formatDate.ts)
- API 라우트: kebab-case (예: /api/user-profile)

### 잘못된 예:

// ❌ 이렇게 하지 마세요

export default function userProfile() { ... }

### 올바른 예:

// ✅ 이렇게 하세요

export default function UserProfile() { ... }

4. 크기를 제한하세요

CLAUDE.md는 매 세션 시작 시 전체가 로드됩니다. 200줄을 넘기면 토큰 낭비가 됩니다. 핵심만 담으세요.

실전 CLAUDE.md 예시

# CLAUDE.md

## Coding Principles
- Think before coding. State assumptions explicitly. If uncertain, ask.
- Simplicity first. No features beyond what was asked.
- Surgical changes. Don't "improve" adjacent code.
- Goal-driven. Transform tasks into verifiable goals.

## Project Rules
- This is a Next.js 14 + Sanity CMS blog
- Korean posts: slug without suffix (e.g., `my-post`)
- English posts: slug with `-en` suffix (e.g., `my-post-en`)
- All Korean prose MUST use 합니다/입니다 formal style
- Upload scripts: always use `createOrReplace`, never `create`
- Thumbnails: matplotlib scripts in `scripts/`, output to `public/thumbnails/`

## Never Do
- Never commit without explicit user request
- Never push to remote without explicit user request
- Never add docstrings, type annotations, or comments to unchanged code
- Never create new files when editing existing ones would work
- Never use git --force or destructive operations without asking

## Tech Stack
- Frontend: Next.js 14 (App Router)
- CMS: Sanity v3 (project: 11k7hfqk)
- Auth: NextAuth.js
- Styling: Tailwind CSS
- Deploy: Vercel (auto-deploy from main)

CLAUDE.md 너머의 세계

CLAUDE.md는 강력하지만 한계가 있습니다:

• 수동입니다 — 사람이 직접 작성하고 관리해야 합니다
• 정적입니다 — 프로젝트가 진행되면서 쌓이는 맥락은 담을 수 없습니다
• 200줄이 실질적 한계입니다

이 한계를 넘어서려면:

1. claude-mem (59K stars) — 세션 간 컨텍스트를 자동으로 캡처하고 주입하는 플러그인
2. Claude Code 자체 메모리 — ~/.claude/projects/<project>/memory/에 자동으로 학습 패턴 저장
3. 커스텀 지식 베이스 — Obsidian + 슬래시 커맨드로 규칙/결정/패턴/보류 항목을 구조화

CLAUDE.md는 출발점입니다. 여기서 시작해서, AI와의 협업이 깊어질수록 기억 시스템도 진화해야 합니다.

마무리: 왜 마크다운 파일 하나가 중요한가

48,000개의 스타는 이 파일의 기술적 복잡도에 대한 반응이 아닙니다. 이 파일이 해결하는 문제에 대한 반응입니다.

AI 코딩 에이전트는 이미 충분히 뛰어납니다. 문법도 맞고, 구조도 알고, 심지어 테스트도 씁니다. 하지만 판단이 없습니다. "이건 너무 복잡한데?"라고 스스로에게 묻지 않습니다. "이걸 정말 건드려야 해?"라고 확인하지 않습니다.

Karpathy의 CLAUDE.md는 그 판단을 외부에서 주입합니다. 그리고 그것만으로도 65%에서 94%로의 도약이 가능합니다.

당신의 프로젝트에서 AI가 반복적으로 저지르는 실수가 있다면, 지금 바로 CLAUDE.md에 적으세요. 마크다운 파일 하나의 ROI는, 생각보다 훨씬 큽니다.

*관련 프로젝트:*

• andrej-karpathy-skills — 원본 CLAUDE.md (48.9K stars)
• claude-mem — 영구 기억 플러그인 (59.3K stars)
• cognee — AI 메모리 엔진 (16.4K stars)