GitHub 스타 6,000개를 모은 파일에는 코드가 한 줄도 없었다

GitHub에서 요즘 가장 빠르게 스타를 모으고 있는 저장소 하나가 있습니다. 이름은 "Karpathy-Inspired Claude Code Guidelines." 마크다운 파일 딱 하나, 65줄짜리 텍스트로 이루어진 프로젝트인데요. 1월 말 공개 직후 3,000개였던 스타가 2월 중순 현재 6,200개를 넘어섰어요.

마크다운 65줄이 개발자 수천 명의 마음을 사로잡은 겁니다.

라이브러리도 아니고, 프레임워크도 아닙니다. 런타임 코드가 단 한 줄도 없어요. 그저 AI 코딩 에이전트에게 "이렇게 행동하라"고 적어둔 행동 지침서일 뿐이에요. 수십억 달러를 들여 훈련시킨 거대 언어 모델의 행동을 교정하는 데, 고작 65줄의 평문 텍스트면 충분하다는 건 대체 어떤 의미일까요?

여기엔 AI 코딩의 현재 주소와 미래가 고스란히 담겨 있습니다. 거대한 배를 움직이는 건 엔진의 크기가 아니라 작은 키(rudder)의 방향이라는, 꽤 불편하면서도 흥미로운 진실이요.

---

Karpathy의 고백,

2주 만에 뒤집힌 코딩 워크플로우

이 프로젝트의 출발점은 Andrej Karpathy입니다. OpenAI 공동창립 멤버이자 Tesla AI 디렉터 출신. 2025년에는 '바이브 코딩(vibe coding)'이라는 용어를 만들어 콜린스 사전 '올해의 단어'에까지 이름을 올린 인물이에요.

2026년 1월 말, Karpathy는 X(구 트위터)에 1,000단어가 넘는 장문의 글을 올렸습니다. 제목 없이 "A few random notes from Claude coding"으로 시작하는 이 글은 Anthropic, xAI 등 주요 AI 기업 엔지니어들의 반응을 즉각 끌어냈어요.

핵심은 이겁니다. 2025년 11월까지 Karpathy의 코딩 워크플로우는 '수동 코딩 80%, AI 에이전트 20%'였는데, 12월이 되자 비율이 완전히 뒤집혔어요. AI 에이전트 80%, 수동 편집 20%. 불과 몇 주 만에 20년간 유지해온 코딩 방식이 근본적으로 바뀐 겁니다.

Karpathy 본인도 이 변화가 불편하다고 인정했어요. 자존심이 살짝 상한다고요. 예전에는 코드를 직접 짜는 게 자부심이었는데, 이제는 AI에게 영어로 지시하는 게 일이 되었으니까요. 코드를 타이핑하는 프로그래머에서, 영어로 프로그래밍하는 지휘관으로 역할이 바뀐 셈입니다.

그런데 이 변화에는 그림자도 따라왔습니다.

Karpathy는 AI 코딩 에이전트의 근본적인 문제점을 세 가지로 집어냈어요. 첫째, 모델이 개발자 대신 '잘못된 가정'을 세우고 거기에 확인도 없이 돌진한다는 것. 둘째, 코드를 과도하게 복잡하게 짜는 습관이 있다는 것. 1,000줄이면 족한 걸 1,000줄로 짓는데, 지적하면 바로 100줄로 줄여요. 처음부터 그렇게 하면 되잖아요. 셋째, 작업 범위를 벗어난 코드나 주석을 슬쩍 건드리는 부작용이 있다는 것.

AI 코딩 에이전트는 빠르고 유능하지만, 성급한 주니어 개발자처럼 행동합니다. 질문을 안 합니다. 혼란을 숨겨요. 트레이드오프를 제시하지 않죠. 반박해야 할 때도 순순히 따릅니다. Karpathy의 표현을 빌리면, "아직 좀 아첨꾼(sycophantic)"이에요.

바로 이 문제의식에서 65줄짜리 마크다운 파일이 태어났습니다.

---

65줄의 정체,

네 가지 원칙이 전부였다

Karpathy의 글이 올라오자마자, 한 개발자가 그 내용을 Claude Code용 가이드라인 파일로 변환했어요. GitHub 사용자 forrestchang이 만든 andrej-karpathy-skills 프로젝트가 바로 그것입니다. 이 프로젝트의 핵심은 CLAUDE.md라는 단일 마크다운 파일이에요.

65줄 안에 담긴 원칙은 정확히 네 가지입니다.

읽어보면 특별할 게 없어요. 시니어 엔지니어가 주니어에게 으레 하는 이야기와 다르지 않습니다. "추측하지 마", "간단하게 짜", "건드리지 말라는 건 건드리지 마", "결과를 확인해." 소프트웨어 엔지니어링의 기본 중의 기본이에요.

그런데 이 당연한 원칙들이 GitHub 스타 6,000개를 끌어모은 이유가 뭘까요?

AI 모델에게 '당연한 것'은 당연하지 않기 때문입니다.

인간 개발자는 경험과 맥락을 통해 "이건 건드리면 안 되겠다"는 판단을 암묵적으로 내립니다. 한데 LLM(대규모 언어 모델)은 그런 암묵지가 없어요. 모든 토큰을 확률적으로 생성할 뿐이거든요. 명시적으로 "하지 마"라고 적어주지 않으면, 모델은 자기 나름의 최선을 다해 코드를 '개선'합니다. 요청하지도 않은 리팩토링을 벌이고, 관련 없는 주석을 삭제하고, 1,000줄짜리 추상화 레이어를 쌓아올리는 식으로요.

65줄의 마크다운은 이 간극을 메웁니다. 인간에게는 뻔한 이야기지만, AI에게는 행동의 경계를 그어주는 울타리인 셈이에요.

---

작은 키, 거대한 배

수십억 달러짜리 모델을 움직이는 법

여기서 한 발짝 물러서 생각해봐야 할 지점이 있습니다.

Anthropic이 Claude 모델을 훈련시키는 데 들인 비용은 정확히 공개되지 않았지만, 업계 추산으로는 수억 달러에서 수십억 달러에 이릅니다. 수천 명의 엔지니어가 수년간 모델의 출력을 세밀하게 개선해왔어요. RLHF(인간 피드백 기반 강화학습), 헌법적 AI, 레드팀 테스트 등 온갖 기법을 동원해서요.

그런데 누군가가 와서 마크다운 파일 하나, 65줄의 텍스트를 올려놓으니까 '이게 모든 걸 바꿨다'고 합니다.

네덜란드의 개발자 Michiel Beijen은 자신의 블로그에서 이 상황의 아이러니를 정확히 짚었어요. 회사에서 열린 AI 워크숍에서 이 확장 프로그램을 처음 접한 Beijen은, 원본 저장소가 하루 만에 스타 3,500개에서 3,900개로 뛰는 걸 목격했습니다. 직접 내용을 살펴보니 마크다운 65줄이 전부였어요.

Beijen은 Claude Code를 사용하지 않았기 때문에, Codex CLI를 써서 이 가이드라인을 VS Code와 Cursor용 확장 프로그램으로 변환했습니다. 재밌는 건 코드를 작성하는 것보다 마켓플레이스에 플러그인을 게시하는 과정이 훨씬 더 손이 많이 갔다는 점이에요. VS Code 마켓플레이스에서는 'Verified Publisher'가 아니라 경고 표시가 뜨는데, 인증을 받으려면 최소 6개월간 확장 프로그램을 하나 이상 게시한 뒤에야 신청 자격이 주어집니다. Cursor가 사용하는 Eclipse Foundation의 Open VSX 레지스트리에 등록하는 절차는 더 번거로웠고요.

그리고 Beijen은 솔직한 질문을 던집니다.

수백만, 수천만 달러를 들여 모델을 훈련시킨 회사가 있는데, 누군가 와서 "코딩 전에 생각해"라고 60줄 적어놓으면 그게 진짜 차이를 만든다고요?

거대한 유조선에 비유하면 이렇습니다. 수십억 달러를 들여 엔진을 만들고, 선체를 깎고, 연료를 채웠어요. 한데 이 배의 항로를 결정하는 건 결국 작은 키(rudder)입니다. 엔진이 아무리 강력해도 키가 없으면 배는 원하는 곳에 도달하지 못해요.

CLAUDE.md 같은 규칙 파일은 바로 그 '키'에 해당합니다. 모델의 지능(엔진)은 이미 충분히 강력해요. 부족한 건 방향성이에요. "어디로 갈지"가 아니라 "어디로 가지 말지"를 알려주는 것. 이게 컨텍스트 엔지니어링(context engineering)의 핵심입니다.

---

실제로 효과가 있긴 한 걸까?

비결정적 모델 앞에서의 솔직한 고백

Beijen은 직접 확장 프로그램을 설치하고 사용해봤습니다. 간단한 리팩토링을 시도했는데, 모델이 변경에 상당히 신중해진 느낌은 받았다고 해요.

그런데 결과가 더 나아졌는지는 확신하지 못합니다.

이건 LLM의 본질적 특성과 맞닿아 있어요. 모든 대규모 언어 모델은 비결정적(non-deterministic)입니다. 같은 입력을 넣어도 매번 다른 출력이 나올 수 있어요. 온도(temperature) 파라미터를 0으로 설정하더라도 완전한 재현성은 보장되지 않습니다.

이 비결정성 때문에 규칙 파일의 효과를 정량적으로 측정하기가 몹시 어려워요. A/B 테스트를 하려면 동일한 조건에서 반복 실험이 가능해야 하는데, LLM은 매 실행마다 미세하게 다른 경로를 탑니다.

그렇다면 6,200명 넘는 개발자가 스타를 누른 이유는 뭘까요? 전부 착각일까요?

반드시 그렇지는 않습니다. 효과를 측정하기 어렵다는 것과 효과가 없다는 건 전혀 다른 이야기니까요.

Martin Fowler의 Thoughtworks 블로그에서 최근 발행한 "Context Engineering for Coding Agents" 글은 이 메커니즘을 잘 설명합니다. 핵심 정의는 이렇습니다. 컨텍스트 엔지니어링이란 "모델이 보는 것을 큐레이션해서 더 나은 결과를 얻는 것"입니다. 모델의 가중치를 바꾸는 게 아니에요. 모델이 작업을 시작하기 전에 읽는 '맥락'을 정교하게 설계하는 거예요.

CLAUDE.md에 "200줄로 쓸 수 있는 걸 200줄로 썼다면, 다시 써라"고 적어두면 어떤 일이 벌어질까요? 모델이 매 코드 생성 시점에서 이 지침을 참조합니다. 항상 완벽하게 따르지는 않겠지만, 지침이 없을 때보다는 과도한 코드를 생성할 확률이 분명히 줄어듭니다.

규칙 파일의 가치는 100% 보장이 아니라, 확률의 미세한 이동에 있습니다. 동전을 던졌을 때 앞면이 나올 확률을 50%에서 55%로 바꾸는 것. 한 번의 시도에서는 차이를 느끼기 어렵지만, 수백 번 반복하면 결과의 분포가 확연히 달라지는 것처럼요.

---

컨텍스트 엔지니어링의 시대가 열리다

CLAUDE.md는 시작일 뿐이다

65줄짜리 마크다운 파일은 빙산의 일각입니다. 2026년 들어 AI 코딩 도구 생태계에서 가장 뜨거운 키워드는 단연 '컨텍스트 엔지니어링'이에요.

Claude Code를 기준으로 살펴보면, 개발자가 모델에게 맥락을 제공하는 방법이 급속도로 다양해지고 있습니다. CLAUDE.md는 그 첫 번째 단계일 뿐이에요.

HumanLayer 블로그의 분석에 따르면, 프론티어 씽킹 모델(최신 추론 모델)이 합리적으로 따를 수 있는 지침의 수는 대략 150에서 200개 정도입니다. 모델이 작아질수록, 추론 능력이 낮을수록 이 숫자는 급격히 줄어들어요. CLAUDE.md를 수백 줄로 부풀리면 오히려 성능이 떨어지는 역설이 발생합니다.

결국 좋은 CLAUDE.md의 핵심은 '얼마나 많이 쓰느냐'가 아니라 '얼마나 정교하게 덜어내느냐'입니다.

이 원칙은 65줄짜리 Karpathy 가이드라인이 인기를 끈 이유이기도 해요. 짧으니까요. 네 가지 원칙, 65줄. 모델의 컨텍스트 윈도우를 거의 잡아먹지 않으면서 행동의 방향만 살짝 틀어줍니다.

Claude Code의 창시자인 Boris Cherny는 Karpathy의 글에 대한 반응으로 자신의 워크플로우를 공개했는데, 이 워크플로우도 시사하는 바가 큽니다. Cherny는 보통 터미널에서 Claude 인스턴스를 5개 동시에 실행하고, 웹 쪽에서도 5에서 10개를 추가로 돌립니다. 코드를 한 줄 한 줄 타이핑하는 장인이 아니라, AI 군단을 지휘하는 사령관에 가까운 방식이에요.

흥미로운 건 Cherny의 팀에서는 코드의 100%를 Claude Code가 작성한다는 점입니다. Cherny 본인은 2개월 넘게 손으로 직접 편집하는 일조차 하지 않았다고 했어요. 이런 환경에서 CLAUDE.md의 중요성은 더욱 커질 수밖에 없습니다.

코드를 사람이 쓰지 않으니, AI가 어떻게 코드를 쓸지 결정하는 '규칙 파일'이 곧 소프트웨어의 품질을 좌우하는 핵심 자산이 되는 거예요.

---

Hacker News의 냉소,

그리고 그 안의 진실

물론 모든 사람이 열광한 건 아닙니다.

Beijen의 블로그 글이 Hacker News에 올라가자 뜨거운 논쟁이 벌어졌어요. 비판의 목소리는 꽤 날카로웠습니다.

한 댓글은 이 현상을 이렇게 꼬집었어요. "이 마크다운을 인터넷의 아무개가 썼다면 아무도 눈길을 주지 않았을 겁니다. 스타는 텍스트의 품질이나 유용성 때문이 아니라, Karpathy라는 이름 때문에 존재하는 거예요." 권위에 의존한 바이럴 효과라는 지적이지요.

또 다른 댓글은 더 근본적인 의문을 던졌습니다. "이런 규칙 파일들이 돌아다니는 걸 보면 '업무 능력 부족한 동료에게 이해시키려고 고생한 내용'이라는 라벨을 붙일 수 있을 것 같아요. 아마 그걸 만든 사람들 자신이 바로 그 부족한 동료이고, AI 도구를 통해 자기 자신과 일하는 게 어떤 느낌인지 처음으로 경험하는 중일 겁니다."

신랄하지만, 한 가지 핵심을 찌르고 있습니다.

정말 중요한 질문은 "65줄이 효과가 있는가"가 아니라, "왜 이런 기본적인 지침이 필요한 상태에서 우리는 AI에게 코드를 맡기고 있는가"입니다.

또 흥미로운 반론도 있었어요. "이 가이드라인에 적힌 내용은 기본적으로 Claude Code가 이미 하고 있는 행동이에요. 4,000개 스타를 받은 이 저장소는 겨우 2주 된 프로젝트인데, 최신 모델은 이미 충분히 유능한 것 아닌가요?" 실제로 Anthropic은 모델 훈련 과정에서 이런 행동 패턴을 이미 반영하고 있을 가능성이 높습니다. 규칙 파일은 보험에 가까울 수 있어요.

두 입장 모두 일리가 있습니다. 사실 이 논쟁은 AI 코딩 도구의 현재 상태를 그대로 비춰주는 거울이에요.

한편에는 "AI가 코딩의 80%를 해결한다"는 생산성 혁명 서사가 있고, 다른 한편에는 "그 80%의 코드 품질을 누가 보장하느냐"는 현실적 우려가 있습니다. Karpathy 본인도 2026년을 '슬로파칼립스(slopacolypse)'의 해라고 예측했어요. GitHub, Substack, arXiv에 "거의 맞지만 정확하지는 않은" 저품질 AI 생성 코드가 범람할 것이라는 경고입니다.

65줄의 마크다운이 이 슬로파칼립스에 대한 방파제가 될 수 있을까요? 혼자서는 무리입니다. 한데 이 작은 파일이 상징하는 움직임, 즉 "AI의 출력을 인간이 의도한 방향으로 조정하려는 노력"은 분명 올바른 방향이에요.

---

코드를 쓰는 시대에서,

코드를 조종하는 시대로

Karpathy는 이번 글의 말미에서 의미심장한 진단을 남겼습니다.

LLM 에이전트의 능력은 2025년 12월을 기점으로 "일종의 일관성 임계점(threshold of coherence)"을 넘어섰고, 소프트웨어 엔지니어링에 상전이(phase shift)를 일으켰다는 것. 지능의 발전이 통합(integrations), 워크플로우, 조직 구조의 발전 속도를 훌쩍 앞질러 버렸다는 진단이에요.

이 진단이 맞다면, 2026년은 업계가 이 새로운 역량을 "소화하는" 고에너지의 해가 됩니다. 65줄짜리 마크다운 파일의 인기는 바로 그 소화 과정의 한 단면이에요.

개발자들은 이제 코드를 직접 타이핑하는 시간보다, AI가 어떻게 코드를 쓸지 설계하는 시간이 더 길어지고 있습니다. CLAUDE.md를 어떻게 작성할지, Rules 파일을 어떤 구조로 짤지, Skills를 어떤 단위로 나눌지. 이런 결정이 코드의 품질을 결정짓는 시대가 온 거예요.

재미있는 역설이 하나 더 있습니다. Karpathy는 수동 코딩 능력이 서서히 퇴화(atrophy)하고 있다고 고백했어요. 코드를 '읽는' 능력(판별)과 '쓰는' 능력(생성)은 뇌에서 서로 다른 기능이라는 거예요. 계산기의 보급이 암산 능력을 퇴화시켰듯, AI 코딩 에이전트가 코드 작성 능력을 퇴화시킬 수 있다는 경고입니다.

그래서 65줄짜리 마크다운은 역설적으로, 코딩 능력의 퇴화를 막기 위한 최소한의 안전장치이기도 합니다. 개발자가 더이상 모든 코드를 직접 쓰지 않는 시대에, 적어도 "좋은 코드란 무엇인가"에 대한 기준만큼은 인간이 정의하고 명문화해둬야 하니까요.

65줄. 원칙은 네 가지. 런타임 코드는 없습니다.

한데 이 파일은 AI 코딩 시대에 개발자의 역할이 어디로 향하는지를 조용히 보여줍니다. 코드를 쓰는 사람에서, 코드를 쓰는 AI를 조종하는 사람으로. 벽돌을 쌓는 인부에서, 건물을 설계하는 건축가로. 키보드 위의 손가락에서, 키(rudder) 위의 손으로.

거대한 배는 이미 출항했습니다. 방향을 정하는 건, 지금 마크다운 파일을 열고 있는 여러분의 몫이에요.