Andrej Karpathy의 LLM 코딩 실수를 CLAUDE.md 한 파일로 해결하는 방법
Andrej Karpathy의 LLM 코딩 실수를 CLAUDE.md 한 파일로 해결하는 방법
AI 코딩 에이전트를 쓰다 보면 한 번쯤 경험합니다. 분명 "버그 수정해"라고 했는데, AI가 파일 5개를 리팩토링하고, 주석을 다 바꾸고, 100줄짜리 코드를 1,000줄로 부풀려 놓는 상황. OpenAI 공동 창립자 Andrej Karpathy도 같은 경험을 했고, 그 관찰을 공유했습니다. 그리고 누군가가 이를 CLAUDE.md 한 파일로 해결하는 프로젝트를 만들었습니다. GitHub Stars 14,500개.
Karpathy의 관찰: AI 코딩의 4가지 문제
2025년 12월, Karpathy는 코딩의 80%를 AI 에이전트에 위임하는 실험을 시작했습니다. 전 Tesla AI 디렉터이자 OpenAI 공동 창립자인 그가 2026년 1월 X에 올린 포스트는 조회수 7,500만 뷰를 기록하며 개발자 커뮤니티를 뒤흔들었습니다.
문제 1: 잘못된 가정
Karpathy의 원문을 직접 인용하면:
"모델이 당신을 대신해 잘못된 가정을 세우고 확인 없이 그냥 달려간다. 혼란을 관리하지 않고, 명확화를 구하지 않고, 불일치를 드러내지 않고, 트레이드오프를 제시하지 않고, 밀어붙여야 할 때 밀어붙이지 않는다."
AI에게 "로그인 기능 만들어"라고 하면, OAuth를 쓸지 이메일/비밀번호를 쓸지 묻지 않고 혼자 결정해서 구현합니다. 시니어 개발자라면 반드시 확인할 사항을 AI는 건너뛰는 겁니다.
문제 2: 코드 과복잡화
"코드와 API를 과하게 복잡하게 만들고, 추상화를 부풀리고, 죽은 코드를 정리하지 않는다... 100줄이면 될 것을 1,000줄로 구현한다."
요청하지 않은 "유연성"을 추가하고, 발생 가능성이 없는 시나리오의 에러 핸들링을 넣고, 한 번 쓰는 코드에 추상화 레이어를 쌓습니다. 결과적으로 유지보수가 더 어려운 코드가 됩니다.
문제 3: 관련 없는 코드 수정
"작업과 직교하는 코드나 주석을 이해 부족으로 변경/삭제한다."
PR 리뷰에서 "이 줄은 왜 바꿨지?"라고 묻게 되는 그 상황입니다. 버그 하나 고치라고 했는데 인접 코드의 포맷팅을 "개선"하고, 주석을 재작성하고, 관련 없는 함수를 리팩토링합니다.
문제 4: 선언적 접근의 부재
Karpathy는 해결 방향도 제시했습니다:
"LLM은 특정 목표를 달성할 때까지 루프를 도는 데 뛰어나다. 무엇을 하라고 말하지 말고, 성공 기준을 주고 지켜보라."
"버그 수정해" 대신 "이 재현 테스트를 통과시켜"라고 하면, AI가 독립적으로 반복 작업을 수행할 수 있다는 것입니다.
해결책: andrej-karpathy-skills 프로젝트
forrestchang/andrej-karpathy-skills 프로젝트는 Karpathy의 관찰을 4가지 실행 가능한 원칙으로 체계화하여 CLAUDE.md 단일 파일에 담았습니다.
원칙 1: Think Before Coding (코딩 전에 생각하기)
- 가정을 명시적으로 진술할 것
- 여러 해석이 가능하면 선택지를 제시할 것 (조용히 하나를 고르지 않기)
- 더 단순한 방법이 있으면 밀어붙일 것
- 혼란스러우면 멈추고 물어볼 것
이 원칙은 AI가 "혼자 결정하는 것"을 시스템 수준에서 차단합니다. CLAUDE.md에 이 규칙이 있으면 Claude Code는 불확실한 상황에서 사용자에게 확인을 구합니다.
원칙 2: Simplicity First (단순함 우선)
- 요청된 것 이상의 기능 추가 금지
- 한 번 쓰는 코드의 추상화 금지
- 요청되지 않은 "유연성", "구성 가능성" 금지
- 200줄이 50줄로 줄어든다면 반드시 줄이기
테스트 기준이 명확합니다: "시니어 엔지니어가 이게 과하다고 할까?" 그렇다면 단순화해야 합니다.
원칙 3: Surgical Changes (수술적 변경)
- 인접 코드, 주석, 포맷팅 "개선" 금지
- 깨지지 않은 것 리팩토링 금지
- 기존 스타일에 맞추기 (본인 스타일과 다르더라도)
- 관련 없는 죽은 코드는 언급만 하고 삭제하지 않기
변경된 모든 줄이 사용자 요청에 직접 연결되어야 합니다. 연결되지 않는 줄이 있으면 되돌려야 합니다.
원칙 4: Goal-Driven Execution (목표 지향 실행)
| 기존 지시 | 개선된 지시 |
|---|---|
| "검증 추가해" | "잘못된 입력 테스트를 쓰고 통과시켜" |
| "버그 수정해" | "재현 테스트를 쓰고 통과시켜" |
| "X 리팩토링해" | "전후로 테스트 통과를 보장해" |
강한 성공 기준을 주면 LLM이 독립적으로 루프를 돌 수 있습니다. 약한 기준은 지속적인 명확화가 필요하게 만듭니다.
설치 방법
Option A: Claude Code Plugin (추천)
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
Option B: CLAUDE.md 직접 다운로드
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
30초면 프로젝트에 적용할 수 있습니다.
커뮤니티 반응과 영향
이 프로젝트는 2026년 4월 기준 GitHub Stars 14,500개, Forks 1,000개를 기록했습니다. LobeHub 마켓플레이스, AI Agent Skills, Playbooks.com 등 주요 AI 도구 생태계에 등재되어 있습니다.
커뮤니티에서 "코딩 에이전트 시대의 필수 세팅"이라는 평가를 받고 있으며, 이는 단순히 프롬프트 엔지니어링이 아닌 시스템 수준의 행동 제약이 AI 코딩 품질에 미치는 영향을 보여줍니다.
더 넓은 맥락: Vibe Coding에서 Agentic Engineering으로
Karpathy는 2025년 2월 "vibe coding"이라는 용어를 만들었습니다. AI에게 코딩을 맡기고 결과만 확인하는 방식이었죠. 1년 뒤인 2026년, 그는 "agentic engineering"으로 진화했습니다.
차이점은 명확합니다:
- Vibe Coding: AI에게 맡기고 결과를 본다
- Agentic Engineering: AI에게 명확한 규칙과 성공 기준을 주고, 시스템으로 품질을 보장한다
andrej-karpathy-skills 프로젝트는 이 전환의 실천적 도구입니다. CLAUDE.md 한 파일이 14,500 Stars를 받은 이유는 간단합니다. 시스템 프롬프트가 곧 실력인 시대가 왔기 때문입니다.
결론
AI 코딩 에이전트의 품질은 모델 성능만으로 결정되지 않습니다. 어떤 규칙을 주느냐, 어떤 성공 기준을 정의하느냐가 결과를 바꿉니다. Karpathy의 관찰을 체계화한 이 프로젝트는 30초 설치로 AI 코딩 경험을 개선할 수 있는 가장 실용적인 방법 중 하나입니다.
직접 설치해보고, 네 가지 원칙이 여러분의 AI 코딩 워크플로우를 어떻게 바꾸는지 경험해 보세요.
출처:
