안드레이 카파시의 LLM 코딩 원칙 담은 CLAUDE.md 가이드라인, 깃허브서 스타 8,900개 돌파

안드레이 카파시(Andrej Karpathy)의 LLM 코딩 문제점 관찰을 바탕으로 한 CLAUDE.md 파일이 깃허브 트렌딩에 진입했다. forrestchang이 개발한 이 프로젝트 andrej-karpathy-skills는 하루 만에 686개의 스타를 받으며 총 8,927개의 스타를 기록했다.

이 프로젝트는 카파시가 지적한 LLM의 코딩 문제를 해결하기 위한 단일 CLAUDE.md 파일로 구성된다. 카파시는 "모델이 사용자 대신 잘못된 가정을 하고 확인 없이 진행한다"며 "혼란을 관리하지 않고 명확화를 요청하지 않으며 불일치를 표면화하지 않고 트레이드오프를 제시하지 않는다"고 지적한 바 있다.

가이드라인은 네 가지 핵심 원칙으로 구성된다. 첫 번째 Think Before Coding은 잘못된 가정, 숨겨진 혼란, 누락된 트레이드오프 문제를 다룬다. 불확실할 때는 추측하지 말고 질문하고, 모호함이 있을 때 여러 해석을 제시하며, 더 단순한 접근법이 있으면 제안하도록 한다.

두 번째 Simplicity First 원칙은 과잉 설계와 비대한 추상화를 방지한다. 요청받지 않은 기능을 추가하지 않고, 단일 용도 코드에 추상화를 적용하지 않으며, 불가능한 시나리오에 대한 에러 처리를 넣지 않도록 규정한다. 200줄이 50줄로 줄어들 수 있다면 다시 작성할 것을 권장한다.

세 번째 Surgical Changes 원칙은 기존 코드 편집 시 인접 코드나 주석, 포맷팅을 임의로 수정하지 않도록 한다. 고장나지 않은 코드를 리팩터링하지 않고, 기존 스타일과 일치시키되 관련 없는 데드 코드는 삭제하지 않고 언급만 하도록 제시한다. 변경된 모든 줄이 사용자의 요청에 직접 연결되어야 한다는 것이 핵심이다.

네 번째 Goal-Driven Execution은 명령형 작업을 검증 가능한 목표로 전환하는 원칙이다. 예를 들어 "유효성 검증 추가" 대신 "잘못된 입력에 대한 테스트를 작성하고 통과시키기"로, "버그 수정" 대신 "버그를 재현하는 테스트를 작성하고 통과시키기"로 변환한다. 카파시는 "LLM은 특정 목표를 충족할 때까지 반복하는 데 매우 뛰어나다"며 "무엇을 할지 말하지 말고 성공 기준을 주고 지켜보라"고 언급했다.

설치 방법은 두 가지가 제공된다. Claude Code 플러그인으로 마켓플레이스를 통해 설치하거나, 프로젝트별로 CLAUDE.md 파일을 직접 다운로드하여 추가할 수 있다. 기존 프로젝트에는 기존 CLAUDE.md에 내용을 이어 붙이는 방식을 지원한다.

가이드라인이 제대로 작동하면 diff에 불필요한 변경이 줄어들고, 과잉 복잡화로 인한 재작성이 감소하며, 구현 전에 명확화 질문이 나오고, 드라이브바이 리팩터링 없는 깔끔한 PR이 생성된다. 이 프로젝트는 MIT 라이선스로 공개되었으며, 프로젝트별 규칙과 병합하여 사용하도록 설계되었다.