Andrej Karpathy는 LLM이 코딩할 때 반복적으로 저지르는 실수를 관찰해 X에 게시했다. forrestchang/andrej-karpathy-skills는 이 관찰을 CLAUDE.md 파일 하나로 압축한 것으로, Claude Code(및 Cursor)의 행동을 교정하는 단순하고 효과적인 방법이다.
Karpathy가 지적한 문제들
“모델은 당신 대신 잘못된 가정을 하고 그냥 진행한다. 혼란을 관리하지 않고, 명확화를 요청하지 않고, 불일치를 발견하지 않고, 트레이드오프를 제시하지 않고, 그래야 할 때 밀어붙이지 않는다.”
“코드와 API를 지나치게 복잡하게 만들고, 추상화를 부풀리고, 죽은 코드를 정리하지 않는다.”
“때때로 태스크와 무관한 주석이나 코드를 이해가 부족한 채로 변경하거나 제거한다.”
4가지 원칙
1. 코딩 전에 생각하기 (Think Before Coding)
가정하지 말고, 혼란을 숨기지 말고, 트레이드오프를 제시한다.
- 불확실하면 추측이 아닌 질문
- 모호성이 있으면 침묵 대신 여러 해석 제시
- 더 단순한 방법이 있으면 직접 말하기
- 헷갈리면 무엇이 불분명한지 명시하고 명확화 요청
2. 단순성 우선 (Simplicity First)
문제를 해결하는 최소한의 코드. 투기적인 것은 없다.
- 요청 받은 것 이상의 기능 추가 금지
- 단일 사용 코드에 추상화 금지
- 요청되지 않은 “유연성”이나 “구성 가능성” 금지
- 불가능한 시나리오에 대한 오류 처리 금지
- “시니어 엔지니어가 과도하게 복잡하다고 할까?” → 그렇다면 단순화
3. 외과적 변경 (Surgical Changes)
반드시 건드려야 할 것만 건드린다.
기존 코드 편집 시:
- 인접한 코드, 주석, 포맷 “개선” 금지
- 망가지지 않은 것을 리팩토링 금지
- 기존 스타일에 맞추기 (다르게 했을 것이라도)
내 변경으로 생긴 고아(orphan)가 있을 때만:
- 내 변경으로 쓸모없어진 import/변수/함수 제거
- 기존 죽은 코드는 요청받지 않는 한 건드리지 않음
테스트: 변경된 모든 줄이 사용자 요청으로 직접 추적 가능해야 한다.
4. 목표 중심 실행 (Goal-Driven Execution)
성공 기준을 정의하고, 검증될 때까지 루프한다.
| 명령형 지시 대신 | 이렇게 변환 |
|---|---|
| “검증 추가” | “잘못된 입력 테스트 작성, 통과시키기” |
| “버그 수정” | “버그를 재현하는 테스트 작성, 통과시키기” |
| “X 리팩토링” | “테스트가 전후 모두 통과하는지 확인” |
Karpathy의 핵심 인사이트: “LLM은 구체적인 목표를 향해 루프하는 데 탁월하다. 뭘 해야 할지 말하지 말고, 성공 기준을 주고 실행하게 하라.”
설치 방법
방법 A: Claude Code 플러그인 (권장)
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills방법 B: 프로젝트별 CLAUDE.md
# 새 프로젝트
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# 기존 프로젝트에 추가
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.mdCursor에서도 .cursor/rules/karpathy-guidelines.mdc로 동일하게 적용 가능.
적용 후 확인 지표
- diff에 불필요한 변경 감소: 요청된 변경만 나타남
- 첫 번째 구현이 단순: 재작성 횟수 감소
- 구현 전에 명확화 질문: 실수 후가 아닌 전에
- 깔끔한 최소 PR: 드라이브바이 리팩토링 없음
관련 문서
- claude-code — Claude Code 터미널 AI 코딩 에이전트 전반
- claude-code-tips-best-practice — GitHub Trending #1 Claude Code 베스트 프랙티스 종합
- agent-skills — AI 에이전트 스킬 시스템 개요
- caveman — 출력 토큰을 75% 줄이는 Claude Code 스킬
참고 자료
- forrestchang/andrej-karpathy-skills — GitHub 공식 저장소