카파시의 CLAUDE.md가 깃허브 별 22만 개를 돌파함. 이게 왜 잘 먹히는지 알려줌.

forrest chang라는 개발자가 다음 날 이 글을 읽고, karpathy가 언급한 4가지 실패 유형을 파악해서 하나의 CLAUDE.md 파일로 정리했음. 1월 27일에 깃허브에 바로 올리더라.

합쳐서 별 22만 개 찍히면서 깃허브 역사상 가장 빠르게 성장한 레포 중 하나가 됨.

이게 실제로 해결하는 문제는 claude code가 세션을 시작할 때마다 아무것도 모르는 '콜드 스타트' 상태라는 거임. 네 스택이 뭔지, 과거에 어떤 결정을 내렸는지, 지난주에 뭘 배제했는지, 왜 이 방식을 골랐는지 전혀 모르니까 지 맘대로 추측해서 멀쩡한 코드까지 다 뜯어고치는 거지. karpathy가 정확히 짚었듯이, 모델들이 지들 멋대로 가정하고 확인도 안 한 채로 그냥 밀어붙이는 거임. 지들이 헷갈리는 것도 관리 안 하고, 물어보지도 않고, 앞뒤 안 맞는 거 뻔히 보이는데도 그냥 넘어가거나, 아니어야 할 때 반박도 안 함.

CLAUDE.md는 claude code가 세션 시작할 때마다 읽는 일반 텍스트 파일임. 안에 들어있는 4가지 규칙은 이거임.

• 묻고, 추측하지 마라. 불분명한 게 있으면 코드 한 줄 짜기 전에 먼저 물어봐. 의도나 아키텍처, 요구사항에 대해 혼자 짐작해서 조용히 처리하지 마.

• 가장 단순한 해결책부터. 작동하는 최소한의 것만 구현해. 네가 요청하지도 않은 추상화는 갖다 붙이지 마.

• 관련 없는 코드는 건드리지 마. 지금 작업이랑 상관없는 파일이면 그냥 둬.

• 불확실한 건 확실하게 표시해. 확신이 안 서면 진행하기 전에 말부터 해. 확실하지도 않은데 확신하는 게 모르는 걸 인정하는 것보다 훨씬 더 큰 피해를 주니까.
  이게 70줄 정도 되는 파일 내용 전부임.

난 지금 Magichour랑 klings API 연동하는 프로젝트에 이거 쓰고 있는데, 비디오 생성 파이프라인이 워낙 복잡하고 상태 관리 로직이 많아서 claude가 중간에 갑자기 딴짓하면서 코드 다 뜯어고치기 딱 좋거든. 개발자 22만 명이 별 박은 이유가 다 있음. claude code 일주일 넘게 써본 놈들은 다 이런 실패 유형 때문에 데여본 적 있을 거고, 매번 빡치면서 수동으로 패치하고 있었을 테니까.

다들 다음엔 어떤 모델로 갈아탈지 토론하고 있을 때, 진짜 실력 차이는 지금 눈앞에 있는 모델한테 얼마나 정확하게 지시하느냐에서 나오는 거임.

너네도 써봤냐? 이 4가지 규칙으로도 커버 안 되는 실패 유형 뭐 있는지 궁금하네.

작성자: /u/soldierlanderr
[링크] [댓글]