Karpathy CLAUDE.md 는 AI 코딩 에이전트가 자주 저지르는 실수를 줄이려고 만든 2,357바이트짜리 지침 파일입니다. 코딩 전에 생각하기, 단순함 먼저, 외과적 수정, 목표 주도 실행이라는 네 규칙이 각각 잘못된 가정, 과잉 복잡화, 요청과 무관한 수정, 약한 성공 기준을 겨냥합니다. 이 글은 그 네 규칙이 어떤 실수를 어떤 장치로 막으려 하는지 정리한 기록입니다.

먼저 밝혀 둘 것이 있습니다. 저는 이 파일을 제 레포에 그대로 설치해 효과를 재 보지 않았습니다. 아래의 내용은 저장소의 CLAUDE.md, README, EXAMPLES 문서를 읽은 범위이고, 별 수 같은 수치는 2026년 11월 6일에 확인한 것입니다. 효과가 있다고 말하는 글이 아니라, 규칙 문장 하나하나가 무엇을 겨누고 있는지 곱씹어 본 글로 읽어 주시면 좋겠습니다.

Karpathy CLAUDE.md 의 작성자는 Karpathy 가 아닙니다

이 파일은 흔히 «Karpathy 네 규칙»이라고 불리지만, 작성자는 Andrej Karpathy 가 아닙니다. Karpathy 가 X 에 LLM 의 코딩 실수를 관찰한 게시물을 올렸고, Jiayuan Chang 이라는 개발자가 그 관찰을 규칙 파일로 옮겼습니다. README 도 이 파일을 Karpathy 의 관찰에서 «끌어낸(derived from)» 것이라고 소개합니다. 아래에서 인용하는 Karpathy 의 문장들도 README 가 인용한 것이고, X 원문은 제가 직접 열어 보지 않았습니다.

저장소는 지금 multica-ai/andrej-karpathy-skills 에 있습니다. 원래는 forrestchang 계정의 저장소였고, README 의 설치 명령은 아직 그 옛 경로를 씁니다. GitHub 이 옛 주소를 새 주소로 넘겨 주기 때문입니다. 2026년 11월 6일 GitHub API 기준으로 별은 229,797개이고, 저장소는 2026년 1월 27일에 만들어져 4월 20일에 마지막으로 push 되었습니다.

본체인 CLAUDE.md 말고도 Cursor 규칙(.cursor/rules/karpathy-guidelines.mdc), Claude Code 플러그인(skills/karpathy-guidelines), 규칙별로 나쁜 예와 좋은 예를 모은 EXAMPLES.md 가 들어 있습니다. 가져다 쓰실 분께 한 가지 적어 둡니다. README 끝에는 라이선스가 MIT 라고 적혀 있지만, 저장소 루트에 LICENSE 파일이 없고 GitHub 도 라이선스를 인식하지 못합니다(API 의 license 값이 비어 있습니다). 조직의 저장소에 붙여 넣을 생각이라면 이 점은 한 번 확인해 두는 편이 좋겠다는 생각이 들었습니다.

Karpathy 가 지적한 LLM 코딩 실수 세 가지

README 는 Karpathy 의 게시물에서 세 문장을 가져와 문제를 정의합니다.

"The models make wrong assumptions on your behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

첫째는 잘못된 가정입니다. 모델이 사용자 대신 가정을 세우고, 확인하지 않은 채 그 가정 위에서 그대로 달린다는 지적입니다. 헷갈려도 헷갈린다고 말하지 않고, 되묻지 않고, 반박해야 할 때 반박하지 않는다는 말이 뒤따릅니다.

"They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code... implement a bloated construction over 1000 lines when 100 would do."

둘째는 과잉 복잡화입니다. 100줄이면 될 일에 1000줄이 넘는 구조물을 세운다는 표현이 꽤 구체적이었습니다.

"They still sometimes change/remove comments and code they don't sufficiently understand as side effects, even if orthogonal to the task."

셋째는 요청과 직교하는(orthogonal) 수정입니다. 충분히 이해하지 못한 주석과 코드를, 작업과 상관없는데도 부수 효과처럼 바꾸거나 지운다는 지적입니다.

README 는 네 규칙을 이 실수들에 하나씩 대응시킨 표를 둡니다. 옮기면 이렇습니다.

규칙겨냥하는 것 (README 대응표)
Think Before Coding잘못된 가정, 숨겨진 혼란, 드러나지 않은 트레이드오프
Simplicity First과잉 복잡화, 부풀려진 추상화
Surgical Changes요청과 무관한 수정, 건드리지 말아야 할 코드
Goal-Driven Execution테스트 우선과 검증 가능한 성공 기준을 통한 지렛대

표를 보다가 넷째 행만 결이 다르다는 것을 알아차렸습니다. 앞의 셋은 특정한 실수를 막는 규칙인데, 넷째는 실수가 아니라 «지렛대(leverage)»라고 적혀 있습니다. 막는 규칙이라기보다, 모델이 잘하는 것에 힘을 싣는 규칙에 가깝다는 생각이 들었습니다.

1. Think Before Coding — 해석을 조용히 고르지 않습니다

첫 규칙의 머리말은 "Don't assume. Don't hide confusion. Surface tradeoffs." 입니다. 구현하기 전에 할 일로 네 가지를 적어 둡니다.

  • 가정을 명시적으로 밝힌다. 확실하지 않으면 묻는다.
  • 해석이 여럿이면 제시한다. 조용히 하나를 고르지 않는다.
  • 더 단순한 방법이 있으면 말한다. 필요하면 반박한다.
  • 무언가 불분명하면 멈춘다. 무엇이 헷갈리는지 이름을 붙이고, 묻는다.

EXAMPLES 에는 «검색을 빠르게 해 줘»라는 요청이 나옵니다. 나쁜 예의 모델은 캐시와 데이터베이스 인덱스와 비동기 처리를 한꺼번에 붙이고, 200줄짜리 최적화 코드를 씁니다. 어떤 «빠름»이 중요한지는 묻지 않습니다. 좋은 예는 코드를 쓰기 전에 이렇게 답합니다.

plaintext
"검색을 빠르게"는 세 가지로 읽을 수 있습니다.

1. 응답 시간 (500ms → 100ms 미만)
   - DB 인덱스 추가, 자주 쓰는 쿼리 캐시
2. 동시 검색 처리량 (throughput)
   - async/await, 커넥션 풀링
3. 체감 속도 (UX)
   - 부분 결과를 먼저 보여 주기, 점진적 로딩

지금 일반적인 쿼리는 약 500ms 가 걸립니다.
어느 쪽이 가장 중요한가요?

«사용자 데이터를 내보내는 기능을 추가해 줘»라는 예도 같은 구조입니다. 나쁜 예는 전체 사용자를 파일 하나로 쓰고, 파일 위치와 CSV 필드명을 마음대로 정합니다. 좋은 예가 가장 먼저 묻는 것은 범위입니다. 전체인지, 걸러 낸 일부인지. 그 옆에 «개인정보 영향(privacy implications)»이라는 말이 붙어 있었습니다. 숨어 있던 가정이 기술적인 것만이 아니었다는 점이 눈에 들어왔습니다.

두 예를 읽으며 든 생각은, 문제는 요청이 모호하다는 사실이 아니라는 것이었습니다. 사람의 요청은 원래 모호합니다. 문제는 모델이 그 모호함을 혼자 해소해 버리는 데 있습니다. 사람이 한 문장으로 답하면 끝날 질문을 모델이 대신 결정하면, 틀린 해석의 비용은 그 위에 쌓인 diff 의 크기만큼 늘어납니다. 규칙이 «고르라(pick)»가 아니라 «제시하라(present)»라는 동사를 쓴 이유가 거기에 있다고 읽었습니다.

2. Simplicity First — 내일의 문제를 오늘 풀지 않습니다

둘째 규칙의 머리말은 "Minimum code that solves the problem. Nothing speculative." 입니다. 금지 목록이 구체적입니다.

  • 요청받은 것 이상의 기능
  • 한 번만 쓰는 코드를 위한 추상화
  • 요청받지 않은 «유연성»이나 «설정 가능성»
  • 일어날 수 없는 경우를 위한 에러 처리
  • 200줄로 썼는데 50줄이 될 수 있다면, 다시 쓴다

EXAMPLES 의 예는 «할인을 계산하는 함수를 추가해 줘»입니다. 나쁜 예의 모델은 추상 클래스 DiscountStrategy 를 만들고, 그 밑에 정률 할인과 정액 할인 클래스를 두고, 최소 구매액과 최대 할인액을 담은 설정 dataclass 와 계산기 클래스까지 세웁니다. 문서는 «간단한 계산 하나를 쓰려고 30줄이 넘는 준비가 필요하다»고 적습니다. 좋은 예는 이것이 전부입니다.

python
def calculate_discount(amount: float, percent: float) -> float:
    """Calculate discount amount. percent should be 0-100."""
    return amount * (percent / 100)

discount = calculate_discount(100.0, 10.0)  # $10 off

«사용자 설정을 DB 에 저장해 줘»라는 예도 같습니다. 나쁜 예는 캐시, 검증기, 병합 옵션, 변경 알림까지 갖춘 PreferenceManager 를 만들고, 좋은 예는 UPDATE 한 번을 실행하는 함수 하나를 씁니다. 대신 «나중에 필요하면 추가할 것»을 적어 둡니다. 캐시는 성능이 문제가 될 때, 검증은 나쁜 데이터가 나타날 때, 병합은 그런 요구가 생길 때입니다.

이 규칙에서 가장 오래 붙잡고 있었던 것은 EXAMPLES 끝의 한 단락이었습니다.

The "overcomplicated" examples aren't obviously wrong—they follow design patterns and best practices. The problem is timing: they add complexity before it's needed.

과잉 설계된 예시들은 대놓고 틀린 코드가 아니고, 디자인 패턴과 모범 사례를 따른 코드라는 말입니다. 문제는 타이밍이라고 합니다. 익숙한 이름으로 부르면 YAGNI(You Aren't Gonna Need It, 필요해지기 전에는 만들지 않는다)입니다. 돌이켜 생각해 보면 Strategy 패턴으로 짠 할인 계산을 코드 리뷰에서 «틀렸다»고 지적하기는 어렵습니다. 틀린 곳이 없기 때문입니다. 그래서 이 규칙은 «틀렸다» 대신 «아직 필요 없다»는 기준을 줍니다. 문서의 마지막 문장도 같은 이야기입니다. "Good code is code that solves today's problem simply, not tomorrow's problem prematurely."

다만 한계도 보였습니다. 규칙은 «시니어 엔지니어가 보기에 과하게 복잡한가?»라고 스스로 물어보라고 합니다. 이 판정은 결국 코드를 쓴 모델 자신이 내립니다. 그 질문이 실제로 얼마나 힘을 쓰는지는 문서를 읽는 것만으로는 알 수 없었습니다.

200줄과 50줄이라는 숫자가 붙은 문장 쪽이 오히려 더 확인하기 쉬운 기준처럼 보였습니다.

3. Surgical Changes — 바뀐 줄마다 요청으로 거슬러 올라갈 수 있어야 합니다

셋째 규칙의 머리말은 "Touch only what you must. Clean up only your own mess." 입니다. 기존 코드를 고칠 때의 규칙과, 내 변경이 고아를 만들었을 때의 규칙으로 나뉩니다.

  • 옆에 있는 코드, 주석, 포맷을 «개선»하지 않는다.
  • 고장 나지 않은 것을 리팩터링하지 않는다.
  • 내 취향과 달라도 기존 스타일을 따른다.
  • 무관한 죽은 코드를 발견하면 알린다. 지우지는 않는다.
  • 내 변경 때문에 쓰이지 않게 된 import, 변수, 함수는 지운다.
  • 원래 있던 죽은 코드는 요청이 없으면 지우지 않는다.

EXAMPLES 의 예는 «이메일이 비어 있으면 검증기가 죽는 버그를 고쳐 줘»입니다. 나쁜 예의 모델은 버그를 고치면서 이메일 형식 검증을 «강화»하고, 아무도 요청하지 않은 사용자명 길이와 영숫자 검사를 넣고, 주석 문구를 바꾸고, docstring 을 추가합니다. 좋은 예의 diff 는 이렇습니다.

plaintext
  def validate_user(user_data):
      # Check email format
-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")

      # Basic email validation
-     if '@' not in user_data['email']:
+     if '@' not in email:
          raise ValueError("Invalid email")

      # Check username
      if not user_data.get('username'):
          raise ValueError("Username required")

      return True

주석 세 줄이 원래 문구 그대로 남아 있고, 사용자명 검사는 한 글자도 바뀌지 않았습니다. 규칙은 이 차이를 한 문장의 시험으로 정리합니다. "Every changed line should trace directly to the user's request." 바뀐 줄 하나하나가 사용자의 요청으로 곧장 거슬러 올라갈 수 있어야 한다는 뜻입니다.

Karpathy 의 셋째 문장을 다시 읽으면 핵심 낱말은 «충분히 이해하지 못한(don't sufficiently understand)»입니다. 왜 있는지 모르는 울타리는 그 이유를 알기 전까지 치우지 말라는 체스터턴의 울타리(Chesterton's fence)가 떠올랐습니다. 무관한 죽은 코드를 «지우지 말고 알리라»는 규칙은 그 울타리를 치울지 말지를 사람에게 넘기는 장치로 읽혔습니다. 반대로 내 변경이 만든 고아는 내가 치웁니다. 치울 범위를 «내가 만든 것»으로 긋는 선입니다.

흥미로운 것은 이 규칙이 흔히 듣는 보이스카우트 규칙(캠프장을 처음보다 깨끗하게 해 두고 떠나라)과 반대 방향이라는 점이었습니다. 곰곰이 생각해 보니 그 차이는 diff 를 읽는 사람의 비용에서 오는 것 같습니다. 버그 수정 세 줄 사이에 무관한 개선 스무 줄이 섞이면, 리뷰하는 사람은 진짜 수정을 찾는 데부터 힘을 씁니다.

저도 개인 블로그 모노레포의 주석을 정리할 때(「코드 주석은 다섯 종류만 남깁니다」) 범위를 PR 단위로 나눴습니다. 바뀐 줄이 모두 «주석 정리»라는 한 의도로 거슬러 올라가야, «주석 말고는 같다»는 검증이 의미를 가졌기 때문입니다.

4. Goal-Driven Execution — 명령 대신 성공 기준을 줍니다

넷째 규칙의 머리말은 "Define success criteria. Loop until verified." 입니다. 명령형 작업을 검증 가능한 목표로 바꾸라고 하고, 바꾸는 예를 표로 둡니다.

이렇게 말하는 대신이렇게 바꾼다
"검증을 추가해 줘""잘못된 입력에 대한 테스트를 쓰고, 통과시켜라"
"버그를 고쳐 줘""버그를 재현하는 테스트를 쓰고, 통과시켜라"
"X 를 리팩터링해 줘""리팩터링 전후로 테스트가 통과하는지 확인하라"

여러 단계로 된 작업이면, 단계마다 확인 방법을 단 짧은 계획을 먼저 세우라고 합니다.

plaintext
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

README 는 이 규칙의 근거로 Karpathy 의 또 다른 문장을 인용합니다.

"LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go."

LLM 은 구체적인 목표를 만족할 때까지 반복하는 데 유난히 강하니, 무엇을 하라고 시키지 말고 성공 기준을 주라는 말입니다. 앞에서 넷째 규칙만 «지렛대»라고 적혀 있던 이유가 여기서 이해되었습니다. 앞의 세 규칙이 모델의 약점을 막는다면, 이 규칙은 모델의 강점이 일할 자리를 만들어 줍니다.

EXAMPLES 의 예는 «인증 시스템을 고쳐 줘»입니다. 나쁜 예는 «코드를 검토하고, 문제를 찾고, 개선하고, 테스트하겠다»는 계획을 세우고 성공 기준 없이 고치기 시작합니다. 좋은 예는 먼저 무엇을 고치는지 정합니다. 문제가 «비밀번호를 바꿔도 기존 로그인이 유지된다»는 것이라면, 비밀번호 변경 뒤 옛 세션이 무효화되는지 확인하는 테스트를 먼저 쓰고 그 테스트가 실패하는 것(버그가 재현되는 것)을 확인합니다. 그다음 구현해서 테스트를 통과시키고, 여러 세션이 열려 있는 경우 같은 경계 조건을 확인하고, 기존 인증 테스트가 그대로 통과하는지 봅니다. 익숙한 이름으로는 TDD 의 레드-그린 순서입니다.

이 예에서 눈에 띈 것은 마지막 줄이었습니다. 좋은 예는 계획을 다 세운 뒤에도 «지금 겪고 있는 인증 문제가 구체적으로 무엇인가요?»라는 질문으로 끝납니다. 성공 기준을 정할 수 없으면 묻는다는 점에서, 넷째 규칙은 첫째 규칙과 다시 만납니다.

다만 이 규칙은 테스트가 있는 레포에서만 제 힘을 쓸 것 같다는 생각이 들었습니다. 테스트 환경이 없으면 «테스트를 쓰고 통과시켜라»라는 목표를 만들 수단부터 없기 때문입니다. 규칙이 약한 기준의 예로 든 «되게 해 줘(make it work)»로 돌아갈 수밖에 없습니다. 이것은 원문에 적힌 내용이 아니라 제 해석입니다.

2,357바이트짜리 CLAUDE.md 가 짧은 이유

이 파일을 처음 열었을 때 가장 먼저 눈에 들어온 것은 길이였습니다. 규칙 네 개와 끝맺음 한 줄이 2,357바이트 안에 들어갑니다.

예전에 Claude Code 에서 SuperClaude 프레임워크를 걷어낸 적이 있습니다(「Claude Code에서 SuperClaude 프레임워크를 걷어낸 이유 — 71KB를 5KB로」). 그때 세운 기준 가운데 하나가 «모델이 이미 아는 원칙은 지워도 된다»였습니다. 그 기준으로만 보면 이 파일도 지워야 할 문장투성이처럼 보입니다. 요청받지 않은 기능을 넣지 말라는 원칙을 모델이 모를 리 없기 때문입니다.

그런데 곰곰이 생각해 보니 겨누는 대상이 달랐습니다. SuperClaude 에서 걷어낸 것은 모델이 이미 알고 또 지키는 원칙이었습니다. 네 규칙이 겨누는 것은 알면서도 어기는 습관입니다. Karpathy 의 세 문장도 «모델이 모른다»가 아니라 «모델이 그렇게 한다»는 관찰이었습니다. 지식을 가르치는 문서는 길어지지만, 습관을 짚는 문서는 짧아도 된다는 생각이 들었습니다. 이것 역시 제 해석이고, 짧은 지침이 실제로 습관을 바꾸는지는 이 글이 답할 수 있는 범위 밖입니다.

하나 더 눈에 띈 것은 규칙마다 자기 점검 문장이 붙어 있다는 점이었습니다. 둘째 규칙은 «시니어 엔지니어가 과하다고 할까?», 셋째 규칙은 «바뀐 줄마다 요청으로 거슬러 올라가는가?», 넷째 규칙은 «성공 기준이 강한가 약한가»를 묻습니다. 무엇을 하지 말라는 목록만 두지 않고, 끝낸 뒤 스스로 확인할 질문을 하나씩 남겨 둔 셈입니다.

트레이드오프와 효과를 확인하는 신호

파일의 첫머리는 스스로 한계를 밝힙니다. 이 지침은 속도보다 신중함 쪽으로 기울어 있고, 오타 수정이나 뻔한 한 줄짜리 변경 같은 사소한 작업은 판단에 맡기라고 적혀 있습니다. README 는 «목표는 사소한 작업을 느리게 하는 것이 아니라, 사소하지 않은 작업에서 값비싼 실수를 줄이는 것»이라고 덧붙입니다. 질문이 늘고 계획이 길어지는 만큼, 작은 일에는 그 비용이 더 크게 느껴질 수 있다는 뜻으로 읽었습니다.

README 는 지침이 효과를 내고 있는지 알 수 있는 신호도 네 가지 적어 둡니다.

  • diff 에 불필요한 변경이 줄어든다. 요청한 변경만 나타난다.
  • 과잉 복잡화 때문에 다시 쓰는 일이 줄어든다.
  • 확인 질문이 실수 뒤가 아니라 구현 전에 나온다.
  • 드라이브바이 리팩터링이나 «개선»이 없는 작고 깔끔한 PR 이 된다.

앞에서 밝혔듯이 저는 이 신호들을 재 보지 않았기 때문에, 효과가 있다고도 없다고도 말할 수 없습니다. 다만 네 신호가 모두 자기 diff 와 PR 에서 직접 셀 수 있는 것이라는 점은 좋다고 생각했습니다. «AI 가 더 똑똑해진 느낌»처럼 재기 어려운 기준을 내세우지 않았습니다.

설치는 두 가지 방법이 안내되어 있습니다. Claude Code 플러그인으로 설치하면 모든 프로젝트에서 쓸 수 있습니다.

plaintext
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

프로젝트 하나에만 넣으려면 CLAUDE.md 로 받거나, 기존 CLAUDE.md 뒤에 붙입니다.

bash
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

README 는 이 지침을 프로젝트별 규칙과 합쳐 쓰라고 권합니다. CLAUDE.md 와 스킬이 에이전트의 행동 규칙으로 어떻게 읽히는지는 예전에 「Claude Code Skills - AI 코딩 도구에 행동 규칙을 심는 법」에 적어 둔 적이 있습니다.

Karpathy CLAUDE.md 네 규칙 한 줄 요약

네 규칙을 한 줄씩 줄이면 이렇습니다. «해석이 여럿이면 고르지 말고 보여 준다», «필요해지기 전에는 만들지 않는다», «바뀐 줄마다 요청으로 거슬러 올라갈 수 있게 한다», «무엇을 하라고 시키는 대신 무엇이 성공인지 정한다». 어느 것도 새로운 지식은 아닙니다. YAGNI 도, 체스터턴의 울타리도, TDD 도 오래된 이름입니다.

결국 이 파일이 하는 일은 새 원칙을 가르치는 것이 아니라, 모델이 알면서도 어기는 지점에 이름표를 붙여 두는 것이라는 생각이 들었습니다. 그 이름표가 실제로 diff 를 줄이는지는 읽기만으로는 알 수 없습니다. 다만 써 본다면 무엇을 세어야 하는지는, README 가 이미 네 줄로 적어 두었습니다.