왜 필요한가?
Andrej Karpathy가 지적한 LLM 코딩의 반복적인 문제 — 조용한 가정, 과잉설계, 본래 작업과 무관한 주변부 수정, 모호한 “성공”의 정의 — 를 한 장짜리 CLAUDE.md로 정리한 플러그인입니다. 코드 작업 전반에 영향을 주는 네 가지 원칙을 Claude Code에 주입해 PR 노이즈를 줄입니다.
Karpathy가 지적한 문제
출발점은 Andrej Karpathy가 X(구 트위터)에 올린 글입니다. 그는 코드 작성에 LLM을 쓰면서 반복적으로 관찰한 실패 패턴을 세 가지로 정리했습니다.
- ① 조용한 오판 — 모델이 사용자 대신 틀린 가정을 하고 확인 없이 그대로 진행. 혼란을 드러내거나 명확화를 요청하지 않고, 불일치·트레이드오프를 제시하지도, 필요할 때 되밀지도 않는 경향.
- ② 과잉설계 — 코드와 API를 필요 이상으로 복잡하게 만들고, 추상을 부풀리며, 데드 코드를 정리하지 않음. 100줄이면 될 일에 1000줄짜리 구조를 얹는 식.
- ③ 부작용성 수정 — 충분히 이해하지 못한 주변부 코드·코멘트를 작업과 무관하게 바꾸거나 삭제.
해법의 방향으로, Karpathy는 LLM이 명확한 성공 기준을 주면 그것을 충족할 때까지 스스로 루프하는 데 탁월하다는 점을 지적합니다 — 지시하지 말고 검증 가능한 기준을 주라는 것. 플러그인의 네 가지 원칙(Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution)이 이 세 가지 문제와 해법 방향에 각각 대응합니다. 원문 맥락은 링크된 게시물에서 직접 확인할 수 있습니다.
네 가지 원칙
-
Think Before Coding (코딩 전에 생각하기)
모호한 요청을 조용히 한 가지 해석으로 밀어붙이지 않도록 강제합니다. 가정을 명시하고, 여러 해석이 있으면 드러내고, 더 단순한 길이 있으면 제안하고, 헷갈리면 멈추고 물어보게 합니다.
-
Simplicity First (단순함이 먼저)
요청받지 않은 기능, 단일 사용처용 추상화, 일어날 수 없는 시나리오용 에러 핸들링을 차단합니다. “200줄이 50줄이면 될 코드라면 다시 써라”가 원문 표현. 시니어 개발자가 과하다고 할지 스스로 점검하게 합니다.
-
Surgical Changes (최소 수정)
요청한 변경에 필요한 라인만 건드리게 합니다. 근처 코드·코멘트·포맷을 “개선”하지 않고, 기존 스타일에 맞추며, 자기 변경이 만든 고아 심볼만 정리하고 기존 데드 코드는 언급만 하고 지우지 않습니다.
-
Goal-Driven Execution (목표 기반 실행)
“검증하고 반복”이 가능한 성공 기준으로 작업을 변환합니다. “버그 고쳐” → “버그를 재현하는 테스트 작성 후 통과시킬 것”, “리팩터 해” → “리팩터 전후 테스트 통과 보장” 식으로. Karpathy가 말한 “LLM은 명확한 성공 기준을 주면 스스로 루프한다”를 코드 규칙으로 풀어낸 것.
제대로 작동하고 있는지 확인하는 신호
아래가 보이면 규칙이 잘 먹히고 있는 것입니다.
- 요청하지 않은 변경이 diff에 섞이지 않음 — 요청한 변경만 나타남
- 과잉설계로 인한 재작성이 줄어듦 — 처음부터 단순한 코드로 나옴
- 실수가 나온 뒤가 아니라 구현 전에 명확화 질문이 옴
- drive-by 리팩터나 “개선”이 없는 최소 PR
알아두면 좋은 점
- 이 가이드라인은 속도보다 신중함에 무게를 둠. 오탈자 수정, 한 줄 변경 같은 단순 작업에는 판단에 맡기고 모든 작업에 완전 적용하지 않아도 됨
- 기존
CLAUDE.md에 병합해 쓰도록 설계됨. 프로젝트 고유 규칙(TypeScript strict, 테스트 정책 등)은 별도 섹션으로 아래에 추가 .cursor/rules/karpathy-guidelines.mdc가 함께 커밋되어 있어 같은 프로젝트를 Cursor로 열어도 동일 규칙이 적용됨- 라이선스: MIT