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 (목표 지향 실행)

강한 성공 기준을 주면 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 코딩 워크플로우를 어떻게 바꾸는지 경험해 보세요.

출처:

• forrestchang/andrej-karpathy-skills (GitHub)
• Karpathy 원문 X 포스트
• Level Up Coding 분석