카파시의 CLAUDE.md, GitHub 22만 스타 돌파 — AI 코딩 에이전트를 다루는 단 한 가지 원칙
AI 코딩 에이전트를 실전에 들이고 환호했던 것도 잠시, 요즘은 ‘이 녀석을 어떻게 통제해야 하나’로 골머리를 앓고 있다. 잠깐 한눈판 사이에 멀쩡한 코드를 통째로 날려 먹거나, 묻지도 않고 지 맘대로 대공사를 시작하거나, 세션 바뀌면 방금 전까지 하던 얘기도 리셋되어 버린다. (진짜 속 터지는 순간이 한두 번이 아니다.)
이 지긋지긋한 문제에 대해 안드레이 카파시(Andrej Karpathy)가 던진 CLAUDE.md는 그야말로 사막의 오아시스였다. 그 결과가 GitHub 역사상 손에 꼽히는 성장 속도인 22만 스타라는 압도적인 숫자로 터져 나왔다.
실패 모드 4가지, 그리고 그에 대한 규칙
CLAUDE.md의 핵심은 간결하다. 카파시는 AI 코딩 에이전트가 빠지는 네 가지 고장 패턴을 정의하고, 각각에 대한 대응 규칙을 명문화했다.
첫째, “묻고 가정하지 마라.” 에이전트가 불확실한 상황에서 임의로 결정을 내리는 것을 금지한다. 파일 위치, API 스펙, 네이밍 컨벤션—모르면 물어봐야 한다. 추측해서 코드를 작성하면 디버깅에 몇 배의 시간이 든다.
둘째, “최소한의 것부터.” 한 번에 전체 아키텍처를 바꾸지 말고, 가장 작은 단위의 변경부터 시작하라는 원칙이다. AI 에이전트는 “개선해 줘”라는指令을 받으면 과도하게 확장하려는 경향이 있다. 이를 작동 단위로 제한하는 것이다.
셋째, “불필요한 추상화 금지.” 세 줄짜리 함수를 인터페이스-구현체-팩토리 패턴으로 확장하는 일이 없어야 한다. 동작하는 코드를 과도하게 일반화하는 것은 AI 코딩의 가장 흔한 부작용 중 하나다.
넷째, “불확실하면 명시하라.” 에이전트 스스로 확신이 없을 때, 사용자에게 그 사실을 명확히 전달해야 한다. 틀린 답을 당당하게 우기는 것보다 “잘 모르겠다”고 솔직히 이실직고하는 게 백배천배 안전하다.
왜 22만 명이 공감했을까
사실 까놓고 보면 대단히 새로운 규칙도 아니다. 숙련된 개발자라면 피눈물 흘리며 배운 기본 상식들이다. 문제는 AI 에이전트 녀석들이 이 상식을 아주 기가 막히게 피해 가며 사고를 친다는 점이었다. 그리고 그 트롤링이 너무나 일관적이라, 수만 명의 개발자가 “맞아, 나도 당했어!” 하고 격하게 고개를 끄덕인 거다.
r/claudecode 서브레딧에서도 반응은 반반이었다. 실전에서 효과적이라는 평가와 함께, “CLAUDE.md에 ‘실수하지 마’라고 적었다”는 자조적 유머도 등장했다. 결국 CLAUDE.md는 에이전트에게 지시를 내리는 메타 프롬프트이자, 개발자의 기대치를 명확히 설정하는 문서라는 두 가지 역할을 동시에 수행한다.
더 깊이 보면, CLAUDE.md의 성공은 “프롬프트 엔지니어링”이라는 개념이 단순한 질문 작성을 넘어 시스템 설계로 진화했음을 보여준다. 좋은 프롬프트는 질문이 아니라 제약 조건(constraint)의 집합이다.
AI 에이전트 제어의 더 큰 그림
CLAUDE.md 현상은 단일 도구의 성공이 아니다. AI 생태계 전체가 직면한 동일한 문제를 다른 각도에서 풀고 있는 여러 시도 중 하나다.
OpenClaw 커뮤니티에서는 에이전트의 메모리 아키텍처를 통해 같은 문제에 접근하고 있다. 시스템 상태(코드, 설정)와 조직 지식(교훈, 아키텍처 결정)을 분리하여, 에이전트가 구식 정보를 참조하는 문제를 해결하려는 시도다.
로컬 LLM 커뮤니티에서는 모델 자체의 정확도 향상을 통해 접근한다. Qwen3.6-35B(MoE) 벤치마크에서 MoE 모델이 빠르지만 코드 생성에서 미묘한 버그를 만들어내고, Dense 모델이 느려도 정확하다는 트레이드오프가 확인된 것도 같은 맥락이다.
공통 분모는 하나다. AI를 정확하게 통제하는 방법. 모델 성능 향상은 점진적이지만, 프롬프트 설계와 에이전트 아키텍처에서 실질적 생산성 차이가 벌어지고 있다.
정리
CLAUDE.md는 22만 스타를 받은 GitHub 리포 그 이상이다. AI 코딩 에이전트 시대의 개발자 매뉴얼이자, “AI에게 맡기되 통제는 사람이 한다”는 원칙의 구현체다.
매일 AI 에이전트와 함께 일하는 개발자라면, 이 네 가지 규칙을 자신의 워크플로에 적용해 볼 가치가 있다. 묻고, 최소한부터 시작하고, 과도한 추상화를 피하고, 불확실하면 명시하라. 에이전트가 아니라 사람이 지켜야 할 규칙일 수도 있다.
그리고 혹시 CLAUDE.md를 아직 안 읽었다면, 지금 읽어라. 5분이면 된다. 22만 명이 틀리지는 않는다.
참고: Reddit r/ClaudeCode, r/LocalLLM, r/OpenClaw 커뮤니티의 2026년 6월 2일 트렌드를 바탕으로 정리했다.