안드레이 카파시 LLM 코딩 함정 4원칙 정리한 Claude Code 가이드라인 오픈소스 공개

깃허브에서 multica-ai의 'andrej-karpathy-skills'가 트렌딩에 올랐다. 안드레이 카파시가 LLM 코딩 함정에 대해 남긴 관찰을 4원칙으로 정리한 단일 CLAUDE.md 파일로, Claude Code의 코딩 행태를 교정하는 것이 목표다.

카파시는 LLM이 "사용자를 대신해 잘못된 가정을 만들고 확인 없이 진행하며, 혼란을 관리하지 못하고 명확화를 요청하지 않으며 불일치를 표면화하지 않고 트레이드오프를 제시하지 않고 필요할 때 반박하지 않는다"고 지적했다. 또 "코드와 API를 과도하게 복잡하게 만들고 추상을 부풀리며 죽은 코드를 정리하지 않은 채 100줄이면 충분한 곳에 1,000줄짜리 구현을 올린다"고 했다. 작업과 직교적인 부분이라도 충분히 이해하지 못한 주석과 코드를 부수효과로 바꾸거나 삭제한다는 지적도 덧붙였다.

이를 받아 정리된 네 원칙은 'Think Before Coding'(잘못된 가정·숨은 혼란·누락된 트레이드오프), 'Simplicity First'(과도 복잡화·부풀린 추상), 'Surgical Changes'(직교적 편집·건드릴 필요 없는 코드), 'Goal-Driven Execution'(검증 가능한 성공 조건을 통한 테스트 우선 레버리지)이다.

'Think Before Coding'은 가정을 명시하고, 모호함이 있을 때 여러 해석을 함께 제시하며, 더 간단한 방법이 있으면 반박하고, 혼란이 생기면 무엇이 불분명한지 이름 붙여 멈추라고 요구한다.

'Simplicity First'는 요청 범위를 넘는 기능, 1회용 코드를 위한 추상화, 요청되지 않은 '유연성'이나 '구성 가능성', 불가능한 시나리오를 위한 오류 처리를 금지한다. 200줄로 가능한 코드는 50줄로 다시 쓰라고도 명시한다. 'Surgical Changes'는 인접한 코드·주석·포맷을 '개선'하지 말고 깨지지 않은 것을 리팩터링하지 말며, 자기 변경이 만든 고아 임포트·변수·함수만 정리하라고 안내한다.

'Goal-Driven Execution'은 명령형 작업을 검증 가능한 목표로 변환한다. 예를 들어 '검증을 추가하라'는 '잘못된 입력에 대한 테스트를 작성한 뒤 통과시키라'로, '버그를 고치라'는 '버그를 재현하는 테스트를 작성한 뒤 통과시키라'로 바꾼다. 카파시는 "LLM은 특정 목표를 만날 때까지 루프 도는 데 특히 뛰어나니, 무엇을 하라가 아니라 성공 기준을 주고 지켜보라"고 했다.

설치는 두 가지다. 권장은 Claude Code 플러그인으로 '/plugin marketplace add'와 '/plugin install' 명령으로 마켓플레이스에 추가하면 모든 프로젝트에서 스킬이 적용된다. 두 번째는 CLAUDE.md 직접 적용으로, 새 프로젝트는 raw 파일을 curl로 다운로드하고 기존 프로젝트는 기존 CLAUDE.md에 이어 붙인다.

저장소에는 같은 가이드를 Cursor에서 적용할 수 있는 '.cursor/rules/karpathy-guidelines.mdc' 프로젝트 룰도 함께 들어 있고, 라이선스는 MIT다. 제작자는 별도로 재사용 가능한 스킬로 코딩 에이전트를 실행·관리하는 오픈소스 플랫폼 'Multica'도 운영 중이다.