카파시의 LLM 코딩 지적, CLAUDE.md 한 장으로 정리됐다

카파시는 LLM이 코드를 짤 때 세 가지를 반복한다고 지적했어요. "모델은 사용자 대신 잘못된 가정을 하고, 확인도 없이 그냥 진행해요." 혼란을 관리하지 않고, 명확히 해달라고 요청하지도 않고, 모순이나 트레이드오프를 드러내지도 않는다는 얘기예요. 두 번째는 과잉 설계예요. 100줄이면 될 일을 1000줄 넘게 늘어놓고, 죽은 코드는 정리하지 않는다는 지적이고요. 세 번째는 부수 효과예요. 요청과 무관한 주석이나 코드를 충분히 이해하지 못한 채로 바꾸거나 지운다는 거예요.

CLAUDE.md 네 가지 원칙

저장소는 이 세 가지 문제에 대응하는 원칙 네 개를 담았어요.

원칙	핵심 문구	내용
가정 금지	"Don't assume. Don't hide confusion. Surface tradeoffs."	모델이 조용히 해석을 정하고 진행하는 대신, 불확실한 부분과 트레이드오프를 먼저 드러내게 해요
최소 코드	"Minimum code that solves the problem."	과잉 설계를 막는 원칙으로, "시니어 엔지니어가 보기에 과하다면 단순화하라"는 기준을 제시해요
최소 수정	"Touch only what you must. Clean up only your own mess."	요청과 무관한 코드는 건드리지 않게 하고, 바뀐 줄마다 요청과의 연결고리를 남기게 해요
성공 기준	"Define success criteria. Loop until verified."	명령형 지시를 검증 가능한 목표로 바꿔, 모델이 스스로 반복하며 기준을 확인하게 해요

네 번째 원칙은 카파시의 다른 관찰과도 맞닿아 있어요. 목표만 명확히 주면 모델이 스스로 반복하며 그 목표에 맞춰간다는 거고, "make it work"처럼 느슨한 기준을 주면 계속 되물어야 한다는 지적이에요.

어떻게 써보나

multica-ai/andrej-karpathy-skills 저장소는 두 가지 설치 방법을 안내해요. 권장 방법은 클로드 코드 플러그인이에요. 클로드 코드 안에서 먼저 마켓플레이스를 추가하면 가이드라인이 플러그인 형태로 설치되고, 특정 프로젝트가 아니라 클로드 코드로 여는 모든 프로젝트에서 이 스킬을 쓸 수 있게 돼요. 두 번째는 커서(Cursor)예요. 저장소에는 .cursor/rules/karpathy-guidelines.mdc 규칙 파일이 함께 들어 있어서, 커서에서 프로젝트를 열면 같은 원칙이 그대로 적용돼요. 커서용 설정 방법은 저장소 안 CURSOR.md 문서에 따로 정리돼 있어요.

기존에 CLAUDE.md 파일을 쓰고 있는 프로젝트라면 이 네 원칙을 그 파일에 합쳐 쓰면 되고, 프로젝트별로 지켜야 할 규칙이 따로 있으면 지침 아래에 섹션을 만들어 덧붙이면 돼요. 저장소는 이 가이드라인이 오탈자 수정 같은 사소한 작업까지 전부 무겁게 만들려는 게 아니라, 되돌리기 힘든 실수를 줄이는 데 초점을 맞췄다고 설명해요.

규칙 파일을 만들어 여러 코딩 에이전트에서 공유하는 방식은 특정 모델에만 묶이지 않고 팀의 작업 원칙을 재사용할 수 있다는 장점이 있어요.

저장소를 공개한 글에는 같은 제작자가 만든 별도 오픈소스 프로젝트 Multica 소개도 함께 실렸어요. 재사용 가능한 스킬로 코딩 에이전트를 실행하고 관리하는 플랫폼이라고 소개했는데, CLAUDE.md 저장소와는 별개 프로젝트예요.

에디터의 시선

이 저장소가 흥미로운 지점은 카파시 개인의 관찰을 그대로 규칙화했다는 데 있지 않고, 코딩 에이전트를 실무에 쓰는 사람들이 겪는 문제가 놀랍도록 똑같다는 사실을 보여준다는 데 있어요. 클로드 코드든 커서든, 모델을 바꿔도 "조용히 가정하고 밀어붙인다"거나 "100줄이면 될 걸 1000줄로 부풀린다"는 불만은 어디서나 반복돼요. 특정 모델의 버그가 아니라 LLM 코딩 에이전트 전체가 공유하는 습성에 가깝고, 지침 파일 한 장으로 어느 정도 교정할 수 있다는 게 이번 사례가 보여주는 값이에요.

비슷한 크기의 코딩 에이전트를 실무에 붙여 보면 결론은 늘 비슷해요. 목표를 "잘 돌아가게 해줘"처럼 느슨하게 던지면 에이전트는 되묻는 대신 자기 나름의 해석으로 밀고 나가고, 그 결과물을 검토하는 데 오히려 더 많은 시간이 들어요. 반대로 "이 함수가 이 입력에서 이 출력을 내면 성공"처럼 검증 가능한 기준을 주면 에이전트가 스스로 반복하며 기준에 맞춰가는 걸 확인할 수 있어요. 이번 CLAUDE.md의 네 번째 원칙이 정확히 그 지점을 짚고 있어요.

국내에서 클로드 코드나 커서로 코드를 짜는 팀이라면, 이런 지침 파일을 프로젝트에 넣는 데 드는 비용은 거의 없어요. 다만 효과를 보려면 팀마다 실제로 반복되는 실수 — 죽은 코드를 안 지운다든지, 관련 없는 파일을 건드린다든지 — 를 먼저 정리하고, 그 실수에 맞춰 원칙을 손봐야 해요. 남이 만든 규칙을 그대로 복사해 붙이는 것만으로는 절반만 얻는 셈이에요.

앞으로 몇 주 안에는 이런 식으로 특정 인물의 관찰이나 팀의 경험을 압축한 CLAUDE.md·스킬 파일 공유가 더 늘어날 거예요. 오픈소스 커뮤니티가 프롬프트 대신 규칙 파일을 주고받는 흐름이 자리 잡으면, 결국 앤스로픽 같은 개발사가 검증된 규칙들을 기본 시스템 프롬프트에 흡수하는 수순으로 이어질 가능성이 커요.