AI 코딩 에이전트가 똑똑해질수록, 우리는 오히려 더 많은 시간을 되돌리는 데 쓰고 있습니다.
분명 “버그 고쳐줘”라고 했는데, 돌아온 diff에는 타입 힌트 추가, 주석 정리, 변수명 리팩토링까지 딸려옵니다. “할인 계산 함수 하나 만들어줘”라고 했더니 Strategy 패턴에 Factory까지 갖춘 200줄짜리 클래스가 나타납니다. 익숙한 풍경 아닌가요?
Tesla의 전 AI 디렉터이자 GPT의 아버지라 불리는 Andrej Karpathy가 정확히 이 문제를 짚었습니다. 그리고 그의 관찰을 코드로 옮긴 오픈소스 프로젝트 하나가, 공개 며칠 만에 GitHub Star 11만 개를 돌파했습니다.
바로 **andrej-karpathy-skills**입니다.
Karpathy가 지적한 LLM의 세 가지 고질병
Karpathy는 X(트위터)에서 LLM 코딩 에이전트의 문제를 이렇게 요약했습니다.
“모델들은 당신을 대신해서 잘못된 가정을 세우고, 확인도 없이 그냥 달려갑니다. 혼란을 관리하지 않고, 명확화를 요청하지 않으며, 모순을 드러내지 않고, 트레이드오프를 제시하지 않습니다.”
“코드를 지나치게 복잡하게 만들고, API를 부풀리고, 추상화를 남용합니다. 100줄이면 될 것을 1000줄로 구현합니다.”
“이해하지 못하는 주석이나 코드를 슬쩍 바꾸거나 삭제합니다. 요청한 작업과 전혀 관계없는데도요.”
한 줄로 줄이면 이렇습니다 — LLM은 묻지 않고, 과하게 만들고, 건드리지 말아야 할 것을 건드린다.
해결책: 네 가지 원칙, 파일 하나
andrej-karpathy-skills는 이 문제를 CLAUDE.md라는 설정 파일 하나로 해결합니다. 핵심은 네 가지 행동 원칙입니다.
1. Think Before Coding — 코딩 전에 생각하라
가정하지 마라. 혼란을 숨기지 마라. 트레이드오프를 드러내라.
LLM에게 “유저 데이터 내보내기 기능 추가해줘”라고 하면, 보통은 아무 질문 없이 JSON/CSV 두 가지 포맷에 전체 유저 덤프까지 구현해 버립니다. 이 원칙이 적용되면 LLM은 먼저 이렇게 물어봅니다:
- 범위: 전체 유저? 필터된 일부?
- 형식: 파일 다운로드? API 응답? 백그라운드 작업?
- 필드: 어떤 유저 필드를 포함할지? 민감 정보는?
가정이 아닌 질문으로 시작하게 만드는 것입니다.
2. Simplicity First — 단순함 우선
문제를 푸는 최소한의 코드. 추측성 기능은 없다.
할인 계산 함수 하나를 요청했는데 Strategy 패턴 + Factory + Config 시스템이 나오는 일을 방지합니다. 원칙은 명확합니다:
- 요청하지 않은 기능은 추가하지 않는다
- 단일 용도 코드에 추상화를 만들지 않는다
- 200줄이 50줄이 될 수 있다면, 50줄로 다시 쓴다
테스트 기준: “시니어 엔지니어가 이거 너무 복잡하다고 할까?” — 그렇다면 단순화합니다.
3. Surgical Changes — 수술적 변경
꼭 필요한 것만 건드려라. 네가 만든 쓰레기만 치워라.
“빈 이메일 크래시 버그 고쳐줘”라고 했는데 돌아온 diff에 docstring 추가, 유저네임 검증 추가, 타입 힌트 추가가 딸려오는 일을 막습니다.
- 인접 코드를 “개선”하지 않는다
- 기존 스타일과 맞추되, 자기 취향으로 바꾸지 않는다
- 관련 없는 데드 코드를 발견하면 — 삭제하지 말고 언급만 한다
테스트 기준: “변경된 모든 라인이 유저의 요청으로 직접 추적 가능한가?“
4. Goal-Driven Execution — 목표 기반 실행
성공 기준을 정의하라. 검증될 때까지 반복하라.
이것이 Karpathy의 핵심 인사이트입니다:
“LLM은 특정 목표를 만족할 때까지 반복하는 데 뛰어납니다. 무엇을 하라고 지시하지 말고, 성공 기준을 주고 지켜보세요.”
명령형 작업을 검증 가능한 목표로 변환합니다:
| 이렇게 말하는 대신… | 이렇게 변환합니다 |
|---|---|
| ”검증 추가해" | "잘못된 입력에 대한 테스트를 쓰고, 통과시켜" |
| "버그 고쳐" | "버그를 재현하는 테스트를 쓰고, 통과시켜" |
| "X 리팩토링해" | "리팩토링 전후로 테스트가 통과하는지 확인해” |
설치 방법: 3가지 경로
이 프로젝트의 매력은 설치가 놀라울 만큼 간단하다는 점입니다.
방법 1: Claude Code 플러그인 (추천)
Claude Code 안에서 두 줄이면 끝입니다.
# 마켓플레이스 추가
/plugin marketplace add forrestchang/andrej-karpathy-skills
# 플러그인 설치
/plugin install andrej-karpathy-skills@karpathy-skills한 번 설치하면 모든 프로젝트에서 자동 적용됩니다.
방법 2: CLAUDE.md 직접 추가 (프로젝트별)
프로젝트 루트에 파일 하나를 받으면 됩니다.
# 새 프로젝트
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# 기존 CLAUDE.md가 있는 경우 (뒤에 이어붙이기)
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md방법 3: Cursor 사용자라면
.cursor/rules/karpathy-guidelines.mdc 파일을 프로젝트의 .cursor/rules/ 디렉토리에 복사하세요. alwaysApply: true로 설정되어 있어서 별도 설정 없이 자동 적용됩니다.
혹은 ~/.cursor/skills에 넣어두면 모든 프로젝트에서 글로벌하게 사용할 수 있습니다.
프로젝트별 커스터마이징
이 가이드라인은 프로젝트 고유 룰과 합쳐서 사용하도록 설계되었습니다. CLAUDE.md 아래에 프로젝트별 섹션을 추가하면 됩니다:
## Project-Specific Guidelines
- TypeScript strict mode 사용
- 모든 API 엔드포인트는 테스트 필수
- 에러 핸들링은 src/utils/errors.ts 패턴을 따를 것작동하고 있다는 신호
이 가이드라인이 제대로 먹히고 있다면, 다음과 같은 변화를 체감할 수 있습니다:
- diff가 깨끗해집니다 — 요청한 변경만 보입니다
- 첫 시도에 단순한 코드가 나옵니다 — 과도한 추상화 때문에 되돌리는 일이 줄어듭니다
- 실행 전에 질문이 옵니다 — 실수 후 되물어보는 게 아닌
- PR이 미니멀해집니다 — 드라이브바이 리팩토링이 사라집니다
마무리: 규칙 하나가 만드는 차이
솔직히 말하면, 이 프로젝트의 본질은 마크다운 파일 하나입니다. 66줄짜리 텍스트입니다.
하지만 그 66줄이 11만 명의 개발자에게 공감을 얻었다는 건, 우리 모두가 같은 좌절을 겪고 있었다는 뜻이기도 합니다. AI 코딩 에이전트는 이미 충분히 똑똑합니다. 부족한 건 지능이 아니라 절제입니다.
코드를 잘 쓰는 것보다 쓰지 않아야 할 코드를 쓰지 않는 것이 더 어렵습니다.
그리고 그건, 사람이든 AI든 마찬가지입니다.