Karpathy의 LLM 코딩 원칙을 CLAUDE.md로: 97.8k 스타 리포지토리 정리
Claude Code에 입력 유효성 검사를 추가해달라고 했더니, 추상 클래스 3개와 팩토리 메서드가 담긴 200줄짜리 코드가 돌아왔다. 필요한 건 5줄이었다.
버그 수정을 요청했더니, 버그는 고쳤지만 인접한 함수에 타입 힌트를 추가하고, 따옴표를 바꾸고, 변수명을 변경했다. diff의 절반이 요청과 무관한 변경이었다.
이건 내 문제가 아니다. LLM 코딩 어시스턴트의 근본적인 경향이다.
Andrej Karpathy(OpenAI 공동창업자, 전 Tesla AI 디렉터)도 같은 문제를 겪었다. 2026년 1월, 그는 X에 LLM 코딩 도구에서 반복적으로 마주치는 4가지 실패 패턴을 정리해 올렸다.
누군가 그 관찰을 단일 CLAUDE.md 파일로 만들었다. 프로젝트 루트에 넣으면 Claude Code가 이 규칙을 따른다.
리포지토리: [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills). 현재 GitHub에서 97.8k 스타.
4가지 규칙
규칙 1: 코딩 전에 생각하기
가장 흔한 실패 패턴: "내보내기 기능을 작성해"라고 하면 모델이 CSV 형식, 전체 필드, 기존 파일 덮어쓰기를 조용히 결정한다. 지정하지 않았는데도.
이 규칙은 다음을 요구한다:
불확실한 경우 명시적으로 확인
여러 해석이 가능한 경우 나열해서 선택하게 함
혼란스러울 때는 추측하지 말고 멈추기
규칙 2: 단순함 우선
LLM은 과도하게 설계하는 경향이 있다. 할인 계산을 요청하면 Strategy 패턴 + 팩토리 메서드 + 설정 파일이 돌아온다.
# 과도한 설계 (변경 전)
class DiscountStrategy(ABC):
@abstractmethod
def calculate(self, price: float) -> float: ...
# 실제로 필요한 것 (변경 후)
def apply_discount(price, pct):
return price * (1 - pct / 100)판단 기준: "시니어 엔지니어가 보면 너무 복잡하다고 할까?"
규칙 3: 외과적 변경
버그 수정을 요청하면 버그를 고치면서 인접 함수에 타입 힌트를 추가하고, 따옴표를 바꾸고, 변수명을 변경한다. 4줄짜리 diff가 40줄이 된다.
이 규칙은 다음을 요구한다:
반드시 필요한 부분만 변경
인접 코드, 주석, 포맷은 건드리지 않음
변경된 모든 줄이 사용자 요청으로 직접 추적 가능해야 함
규칙 4: 목표 중심 실행
LLM은 코드를 작성하고 끝냈다고 선언한다. 테스트도, 검증도 없다.
이 규칙은 모호한 작업을 검증 가능한 목표로 변환한다:
"버그 수정" → "버그를 재현하는 테스트를 작성하고, 그것을 통과시켜라"
설치 방법
# Claude Code 플러그인 (권장)
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
# 직접 다운로드
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md개인적인 생각
4가지 규칙 중 외과적 변경이 일상적인 개선 효과가 가장 크다.
과도한 설계는 한눈에 보인다. 잘못된 가정은 디버깅 중에 발견된다. 하지만 무관한 코드 변경은 리뷰를 통과한다. 특히 큰 diff에서 포맷 변경과 로직 변경이 섞여 있을 때, 어느 것이 의도적인지 알 수 없다.
한계: 이 규칙들은 행동 경향을 수정하지만 능력의 상한선은 바꾸지 않는다. 모델이 코드베이스 아키텍처를 이해하지 못하면 4가지 규칙으로도 구할 수 없다.
1개 파일, 제로 설정, 즉각적인 효과. 설치할 가치가 있다.
