Dissecting Karpathy's 65-Line CLAUDE.md

첫 번째 섹션의 핵심 명령은 두 단어다: Don't assume. 그리고 바로 이어서: Don't hide confusion.

이 두 문장이 AI 에이전트의 가장 흔한 실패를 막는다. AI는 모호한 지시를 받았을 때 가장 그럴듯한 해석을 선택하고 구현을 시작한다. 사용자에게 물어보는 것보다 그게 더 '도움이 되는' 행동처럼 느껴지기 때문이다. 하지만 틀린 방향으로 구현된 200줄의 코드는 애초에 아무것도 안 한 것보다 훨씬 나쁘다.

## 1. Think Before Coding

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

'Push back when warranted'는 특히 중요하다. Claude에게 반박할 권한을 명시적으로 주는 것이다. 이 줄이 없으면 Claude는 비효율적인 접근법도 그냥 구현해버린다. 이 줄이 있으면 '더 간단한 방법이 있는데요'라고 먼저 말한다.

자가 테스트 질문: 구현 전에 명시적으로 가정을 드러냈는가? 불분명한 게 있으면 이름을 붙여서 물어봤는가?

두 번째 섹션은 AI의 가장 흔한 죄악과 싸운다 — 요청하지 않은 것을 추가하는 습관.

## 2. Simplicity First

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

마지막 두 줄이 특히 천재적이다. 'Senior Engineer Test'는 Claude에게 자가 검증 메커니즘을 준다. Claude는 코드를 작성한 후 스스로 시니어 엔지니어의 관점에서 평가해야 한다. 이것은 외부 검토를 내부화한 것이다.

'If you write 200 lines and it could be 50, rewrite it'은 더 나아간다 — 한 번에 최소한으로 쓰는 게 아니라, 너무 많이 썼다면 다시 쓰라는 명령이다. 이 명령이 없으면 Claude는 일단 쓴 코드를 유지하려는 경향이 있다.

세 번째 섹션은 매우 구체적인 메타포를 사용한다 — 'Surgical'. 외과 수술처럼 정확히 필요한 부분만 건드리라는 것이다.

## 3. Surgical Changes

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

마지막 줄 Traceability Test가 핵심이다: 변경된 모든 줄이 사용자의 요청으로 직접 추적될 수 있어야 한다. 이 테스트가 명시되면, Claude는 PR에 들어가는 모든 변경에 대해 '왜 이 줄이 필요한가'를 스스로 검증해야 한다.

'Match existing style, even if you'd do it differently'는 미묘하지만 중요하다. Claude에게는 자신의 선호가 있다. 이 줄이 없으면 Claude는 기존 코드를 자신의 스타일로 맞추려 한다. 이 줄이 있으면 그러지 않는다.

마지막 섹션은 가장 야심찬 변환을 요구한다 — 모든 태스크를 검증 가능한 목표로 바꾸는 것.

## 4. Goal-Driven Execution

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
1. [Step] → verify: [check]
2. [Step] → verify: [check]

이 변환이 강력한 이유는, 검증 단계를 구현 단계와 분리하기 때문이다. '검증'이 명시적으로 있으면 Claude는 '완료'를 선언하기 전에 실제로 검증한다. 없으면 구현이 끝나는 것이 곧 완료다.

멀티스텝 태스크를 위한 플랜 템플릿도 포함되어 있다. 각 스텝에 대응하는 검증 체크가 붙어있어, 루프를 독립적으로 돌릴 수 있다. 이것이 '약한 기준(make it work)'과 '강한 기준(test passes)' 사이의 차이다.

이 파일이 기록적인 속도로 퍼진 데는 기술적 이유와 심리적 이유가 함께 작용했다.

기술적 이유: 파일이 해결하는 네 가지 실패 패턴은 실재하고 측정 가능하다. 각 섹션 끝의 자가 테스트(Senior Engineer Test, Traceability Test)는 Claude가 실제로 따를 수 있는 구체적인 기준을 제공한다. 규칙이 아니라 기준이다.

심리적 이유: 이 파일은 프롬프트 엔지니어링처럼 느껴지지 않는다. 새 팀원에게 주는 온보딩 문서처럼 느껴진다. 개발자들은 이것을 읽고 '나도 이게 필요했어'라고 즉각 인식한다. 공유하기 쉽고, 커스터마이즈하기 쉽고, 팀원에게 설명하기 쉽다.

Tradeoff 고지: 파일 첫 줄에 있는 이 문장도 중요하다 — 'These guidelines bias toward caution over speed. For trivial tasks, use judgment.' 이 솔직함이 신뢰를 만든다. '항상 이렇게 하라'가 아니라 '이 트레이드오프를 알고 쓰라'고 말하는 것이다.