마크다운 한 장에 22만5천 스타, 카파시의 불만은 네 원칙이 됐다

마크다운 파일 하나만 담은 저장소가 22만5,000개의 스타를 받았다. 이번 주에만 약 4,000개가 더 붙었다. 코드도, 빌드 단계도, 릴리스도, 벤치마크 표도 없다. 있는 것은 네 가지 원칙과, 언어 모델이 코드베이스를 고치라는 요청을 받았을 때 어떻게 행동해야 하는지에 대한 지침뿐이다.

파일 이름은 CLAUDE.md, 저장소는 andrej-karpathy-skills, 관리자는 forrestchang이다. Andrej Karpathy가 LLM의 코딩 행태에 대해 쏟아낸 불만들을, 에이전트가 매 세션 초반에 실제로 읽는 형태로 압축했다. 흥미로운 데이터 포인트는 내용이 아니라 스타 수다. 에이전트의 행동이 지금 비공식적으로, 산문으로, 개인에 의해 패치되고 있다는 사실을 보여주기 때문이다.

카파시의 말로 옮긴 불만

이 저장소가 바탕으로 삼은 원문에서 세 가지 인용.

"모델은 당신을 대신해 잘못된 가정을 세우고, 확인도 없이 그대로 달려간다. 자기 혼란을 관리하지 않고, 명확화를 요구하지 않고, 모순을 드러내지 않고, 트레이드오프를 제시하지 않고, 반박해야 할 때 반박하지 않는다."

"코드와 API를 지나치게 복잡하게 만드는 걸 좋아하고, 추상화를 부풀리고, 죽은 코드를 정리하지 않는다… 100줄이면 될 일을 1,000줄이 넘는 비대한 구조로 구현한다."

"충분히 이해하지 못한 주석과 코드를 부작용 삼아 바꾸거나 지우기도 한다. 과제와 무관하더라도."

에이전트가 쓴 코드를 배포해본 사람이라면 셋 다 알아본다. 가장 흔한 것은 두 번째다. 검증 함수를 요청했더니 추상 기반 클래스와 전략 패턴, 설정 객체, 그리고 일어날 수 없는 상태를 위한 마흔 줄짜리 예외 처리가 돌아온다.

네 가지 원칙이 실제로 말하는 것

코딩 전에 생각하라. 가정을 명시하라. 해석이 여러 개면 조용히 하나를 고르지 말고 나란히 제시하라. 더 단순한 방법이 있으면 반박하라. 혼란스러우면 멈추고 무엇이 불분명한지 말하라.

단순함이 먼저. 문제를 푸는 최소한의 코드. 요청을 넘어서는 기능도, 일회성 코드를 위한 추상화도, 아무도 요구하지 않은 설정 가능성도, 일어날 수 없는 상황을 위한 예외 처리도 없다. 판정 기준은 하나다. 시니어 엔지니어가 이걸 보고 과하다고 말할까?

외과적 변경. 반드시 건드려야 하는 것만 건드려라. 지나가는 길에 옆 코드를 개선하거나 다시 포맷하지 마라. 내 방식이 다르더라도 기존 스타일에 맞춰라. 무관한 죽은 코드를 발견하면 언급만 하고 지우지 마라. 당신의 변경이 고아 코드를 만들었다면 그것만 정리하라. 판정 기준은 모든 변경된 줄이 요청으로 추적되는가다.

목표 주도 실행. 명령형 지시를 검증 가능한 성공 기준으로 바꿔라. "검증을 추가하라"가 아니라 "잘못된 입력에 대한 테스트를 쓰고, 통과시켜라". "버그를 고쳐라"가 아니라 "재현하는 테스트를 쓰고, 통과시켜라".

마지막 하나만이 제약이 아닌 원칙이다. 이것은 레버리지이며, 원문에서 가장 좋은 문장이 따라붙는다. LLM은 특정 목표에 도달할 때까지 반복하는 일을 유난히 잘한다. 무엇을 하라고 말하지 말고, 성공 기준을 주고 지켜보라.

설치, 그리고 그것이 두 줄이라는 사실

경로는 두 가지, 둘 다 사소하다.

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

또는 프로젝트 단위로:

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

저장소에는 Cursor 규칙 .cursor/rules/karpathy-guidelines.mdc도 커밋되어 있어, 프로젝트를 Cursor로 열 때도 같은 지침이 적용된다. MIT 라이선스.

배포 방식이 핵심이다. 2년 전이라면 "모델이 과잉 설계한다"를 고치는 데 파인튜닝이나, 벤더가 내려주는 시스템 프롬프트나, 프레임워크가 필요했다. 지금은 사용자가 저장소에 떨어뜨리는 파일 하나와, 그 머신의 모든 프로젝트에 넣어주는 마켓플레이스 목록이면 된다. 불만과 수정 사이의 피드백 루프가 훨씬 짧아졌고, 스타 수가 지금 이 숫자인 이유도 여기 있다. 이 파일은 행동 변화의 가장 싼 단위다.

그래도 이 구도에는 회의적이다

이 파일 자신의 정신에 맞춰 세 가지 유보를 적는다.

원칙은 테스트가 아니다. "단순함이 먼저"는 선호이지 기준이 아니다. 그걸 읽은 에이전트는 80줄이면 될 곳에 300줄을 내놓는다. 모델이 복잡도를 잴 방법이 없기 때문이다. 파일에서 실제로 작동하는 유일한 원칙인 목표 주도 실행이 통하는 이유는, 선호를 검사로 바꿨기 때문이다. 테스트는 통과하거나 통과하지 못한다.

"외과적 변경"은 에이전트가 잘하는 것과 싸운다. 작은 수정을 부탁했더니 작은 수정이 돌아오면, 비싼 도구로 키 입력 몇 번을 아낀 셈이다. 에이전트의 가치는 당신이 건드리고 싶지 않았던 것을 재구성할 수 있다는 데 있다. 파일의 답은 재구성은 요청받았을 때만 하고 먼저 나서지 말라는 것이다. 합리적이지만, 그 말은 이 지침이 특정 사용자에게 최적화되어 있다는 뜻이기도 하다. 이미 코드베이스가 있고 diff에 강한 의견을 가진 사람.

아무도 효과를 재지 않는다. 저장소는 신호를 나열한다. diff에서 불필요한 변경이 줄고, 재작성이 줄고, 구현 뒤가 아니라 전에 명확화 질문이 나온다. 모두 실재하고 관찰 가능하다. 그러나 대조군이 없다. "가정하기 전에 물어라"라고 적힌 파일을 설치했더니 에이전트가 가정하기 전에 묻기 시작했다. 파일이 그렇게 만든 것인가, 아니면 그걸 적어두는 행위가 원래 있던 행동을 보이게 만든 것인가.

저자는 트레이드오프를 솔직히 밝힌다. 평가할 만하다. 지침은 속도보다 신중함에 기울고, 사소한 작업에서는 스스로 판단하라고 한다. 옳은 단서이면서 동시에 긴장이다. 한 줄짜리 오타 수정을 위해 멈춰 묻는 에이전트는 그냥 고치는 에이전트보다 나쁘다.

내가 실제로 쓴다면 이 버전이다

이 파일의 약점이 네 원칙 중 셋이 선호에 불과하다는 것이라면, 고치는 방법은 그것들을 검사로 바꾸는 것이다. 구체적으로, 실제 저장소에서 버티는 네 줄.

편집 전에 건드릴 파일을 나열하고, 그 목록이 요청이 함축하는 것보다 길면 멈춘다. "외과적 변경"을 기분이 아니라 관문으로 만든다.

끝내기 전에 테스트를 돌리고 출력을 붙인다. "목표 주도 실행"을 협상 불가로 만드는 것이며, 에이전트 앞에 놓을 수 있는 가장 레버리지 높은 지시다.

과제에 그럴듯한 해석이 둘 이상이면 둘 다 쓰고 어느 쪽인지 묻는다. "코딩 전에 생각하라"를 염원에서 대화의 한 턴으로 바꾼다.

그리고 diff 예산. 버그 수정에 약 150줄을 넘게 늘린다면 멈추고 각 추상화를 정당화하라고 요구한다. 투박하지만, 카파시가 지적한 실패 모드, 실제로 시간을 잡아먹는 그 모드를 잡아낸다.

어느 것도 파일에 없고, 있을 필요도 없다. 파일의 일은 태도를 정하는 것이다. 검사는 저장소 주인의 일이다.

스타 수가 실제로 말하는 것

올해 나온 에이전트 도구 대부분은 능력에 관한 것이다. 더 긴 컨텍스트, 더 많은 도구, 병렬 실행. 이 파일은 자제에 관한 것이고, 대부분의 능력 릴리스보다 더 많은 주목을 받았다.

그 격차는 시사적이다. 이 도구에 돈을 내는 사람들은 병목이 더 이상 모델이 무엇을 할 수 있느냐가 아니라, 시키지 않은 일을 그만두게 하는 것이라고 결론지었다. 22만5,000 스타의 마크다운 파일은 불만이 실제로 어디에 있는지에 대한 유난히 명확한 신호다.

연구소들에게는 다소 민망한 신호이기도 하다. 이 범주에서 스타를 가장 많이 받은 저장소가, 모델이 이미 하고 있어야 할 네 가지 일의 목록이다.