카파시가 경고한 AI 코딩의 악습 4가지, 10만 스타 CLAUDE.md의 정체

이 저장소를 한 문장으로 요약하면 이렇다. AI 코딩의 병목이 이제 모델 성능보다 행동 통제 쪽으로 옮겨갔다는 사실을 가장 압축적으로 보여주는 repo다. Claude Code, Cursor, Codex 같은 도구를 이미 쓰고 있는데 결과가 자꾸 과장되거나 주변 코드까지 망가진다면, 이 repo가 왜 뜨는지 이해할 필요가 있다.

1. 왜 이 저장소는 코드보다 규약이 더 중요한가?

결론부터 말하면, andrej-karpathy-skills는 기능을 추가하는 소프트웨어가 아니라 에이전트의 잘못된 습관을 교정하는 운영 규약이다. 저장소 루트에는 README, CLAUDE.md, CURSOR.md, EXAMPLES.md, 플러그인 메타데이터, 그리고 하나의 SKILL.md만 있다. GitHub API 기준 저장소 크기도 20KB에 불과하다 (출처: GitHub API).

왜 이런 형태가 지금 먹히나

AI 코딩 에이전트의 가장 흔한 실패는 “모르는 걸 모른다고 하지 않는 것”과 “시킨 것보다 더 많이 하는 것”이다. 이 repo는 그 실패를 아주 짧은 규칙으로 겨냥한다. Karpathy가 지적한 문제를 그대로 받아, 가정을 먼저 드러내고, 단순하게 풀고, 주변 코드를 건드리지 말고, 검증 가능한 목표로 바꾸라고 요구한다 (출처: README).

이건 프롬프트 팁이 아니라 control layer다

그래서 이 repo를 “Claude Code 잘 쓰는 법” 정도로만 읽으면 절반만 이해한 셈이다. 더 정확한 해석은 프롬프트를 코드처럼 버전 관리하는 control layer다. 이 관점은 AI 앱은 프롬프트가 아니라 하네스로 완성된다에서 다룬 하네스 개념과 닿아 있다. 모델 위에 규칙, 실행 경로, 검증 루프를 얹어야 결과가 안정된다는 얘기다.

문서형 repo인데도 폭발한 이유

흥미로운 점은 이 저장소가 “뭔가를 실행하게 해주는 코드”보다 “뭔가를 덜 하게 만드는 지침”으로 더 강한 반응을 얻었다는 사실이다. 2026년 5월 2일 기준 별 105,196개, 포크 10,413개, 워처 560개를 기록했는데, 이는 대형 프레임워크급 수치다 (출처: GitHub, GitHub API). 문법 생성보다 행동 억제가 더 급한 문제라는 시장 신호로 읽는 편이 정확하다.

2. 네 가지 원칙은 정확히 무엇을 막나?

저장소의 핵심은 4개 원칙뿐이다. 길게 보면 평범해 보이지만, 실제론 AI 코딩 에이전트의 대표적 사고 유형을 정확히 찌른다.

Think Before Coding은 조용한 오해를 막는다

첫 번째 원칙은 구현 전에 가정과 해석을 드러내라는 요구다. “export 기능 추가” 같은 요청을 받았을 때 AI가 파일 포맷, 데이터 범위, 민감정보 포함 여부를 멋대로 가정하지 말라는 뜻이다. 이 부분은 EXAMPLES.md에서 가장 설득력 있게 드러난다. 잘못된 예시는 곧바로 CSV/JSON export를 짜고, 올바른 예시는 먼저 scope와 privacy를 묻는다 (출처: EXAMPLES.md).

Simplicity First는 오버엔지니어링을 막는다

두 번째 원칙은 단일 할인 함수 하나를 만들라는 요청에 Strategy Pattern과 설정 객체를 꺼내는 식의 과잉 설계를 금지한다. 이건 클로드 코드 완전 정복 같은 상위 도구 설명보다 더 실무적이다. 모델이 “좋은 설계처럼 보이는 복잡함”을 너무 쉽게 정답으로 착각하기 때문이다.

Surgical Changes는 이 repo의 진짜 킬러 기능이다

세 번째 원칙은 요청받지 않은 코드, 주석, 포맷, 인접 로직을 건드리지 말라고 못 박는다. 개인적으로 이 저장소의 폭발력은 거의 전부 여기에 있다고 본다. 최근 연구도 비슷한 방향을 지지한다. 2026년 4월 arXiv 논문은 규칙 파일이 전체적으로는 도움을 줄 수 있지만, 개별 규칙 중 확실히 유익한 유형은 “하지 말 것” 형태의 negative constraint였고 긍정적 지시어는 오히려 성능을 해칠 수 있다고 보고했다 (출처: Do Agent Rules Shape or Distort?).

Goal-Driven Execution은 작업을 검증 가능하게 바꾼다

네 번째 원칙은 “버그를 고쳐줘”를 “실패하는 테스트를 만든 뒤 통과시켜라”로 번역하는 습관이다. 이건 모델의 창의성을 올리는 장치가 아니라, 끝났다고 착각하는 지점을 늦추는 장치다. 특히 장기 작업에서 효과가 크다.

(출처: README, EXAMPLES.md, arXiv 2604.11088)

3. CLAUDE.md, SKILL, Cursor rule은 어떻게 다르게 배포되나?

이 repo를 얕게 보면 “그냥 CLAUDE.md 하나 올려둔 거 아닌가?” 싶다. 하지만 실제로는 같은 원칙을 여러 실행면에 맞게 포장해 둔 저장소다. 그게 adoption의 핵심이다.

프로젝트 단위라면 CLAUDE.md다

루트 CLAUDE.md는 Claude Code 프로젝트 규칙 카드에 가깝다. 새 프로젝트엔 raw 파일을 내려받아 쓰고, 기존 프로젝트엔 append하는 방식까지 README에 적혀 있다 (출처: README).

재사용하려면 SKILL.md와 plugin metadata다

skills/karpathy-guidelines/SKILL.md와 .claude-plugin/plugin.json은 같은 규칙을 재사용 가능한 스킬로 만든다. Anthropic 공식 문서도 SKILL.md가 Claude Code의 재사용 단위이며, 플러그인 스킬은 별도 namespace로 동작한다고 설명한다 (출처: Claude Code Skills Docs).

Cursor 사용자는 .cursor/rules가 핵심이다

이 저장소의 CURSOR.md는 Cursor 쪽 적용 경로를 분명히 나눈다. Cursor는 .claude-plugin/이나 CLAUDE.md를 기본적으로 읽지 않기 때문에, .cursor/rules/karpathy-guidelines.mdc를 복사하는 것이 정석이다. 이 rule 파일은 frontmatter에 alwaysApply: true가 있어 자동 적용된다 (출처: CURSOR.md, Cursor rule file, Cursor Docs).

Codex는 아직 mainline보다 community port에 가깝다

여기서 중요한 반전이 하나 있다. 현재 main 브랜치에는 Codex 전용 메타데이터가 없다. 대신 Add Codex skill metadata and docs 같은 PR이 열려 있고, 2026년 5월 1일에는 Codex skill edition PR도 올라왔다 (출처: PR #104, PR #120). 즉, 이 repo는 이미 범용 행동 규약으로 소비되고 있지만, cross-agent productization은 아직 진행형이다.

(출처: README, Claude Code Skills Docs, Cursor Docs)

4. 왜 이렇게 빨리 10만 스타를 모았나?

핵심은 새 기능이 아니라 이미 everybody가 겪고 있던 통증을 너무 정확한 언어로 정리했다는 점이다.

타이밍이 정확했다

이 repo는 2026년 1월 27일 생성됐고, 2026년 5월 2일 기준 105,196 스타를 기록했다. 대략 석 달 남짓한 시간에 문서형 repo가 얻기엔 비정상적으로 빠른 확산이다 (출처: GitHub API). 이 시기는 Claude Code, Cursor, Codex 계열 에이전트 사용이 본격화되며 “AI가 일을 빨리 하긴 하는데 자꾸 옆길로 샌다”는 불만이 누적되던 시기와 정확히 겹친다.

길이가 짧아서 퍼지기 쉬웠다

CLAUDE.md는 65줄, SKILL.md는 67줄, README는 171줄이다. 복잡한 제품이 아니라 복사 가능한 doctrine이기 때문에, 사용자는 이해보다 적용을 먼저 할 수 있다. Karpathy LLM 위키 개념편에서 다뤘던 file-over-app 철학과도 닮았다. 코드를 설치하는 대신 텍스트를 버전 관리 가능한 제어층으로 쓰는 방식이다.

설치 경로가 도구별로 분리돼 있었다

많은 가이드 repo는 아이디어는 좋은데 “그래서 어디에 두라는 거지?”에서 막힌다. 이 저장소는 README, CURSOR.md, plugin metadata, SKILL.md를 따로 둬서 그 마찰을 줄였다. 아이디어보다 packaging이 adoption을 밀었다고 보는 게 더 타당하다.

그러나 product maturity는 아직 낮다

흥미롭게도 GitHub 페이지 기준 공개 릴리스는 없고, main 브랜치 커밋 수는 28개에 불과하다 (출처: GitHub). 즉, 엄밀히 말하면 이건 “완성도 높은 제품”보다 “폭발적으로 전파된 운영 원칙”에 가깝다. 이 차이를 놓치면 과대평가하기 쉽다.

5. 진짜로 코딩 품질을 높인다는 근거가 있나?

여기서부터는 냉정해야 한다. 이 repo 자체에는 A/B 테스트나 eval harness가 없다. 그래서 외부 근거를 봐야 한다.

가장 좋은 데이터는 ‘효율은 오르지만 품질은 보장되지 않는다’는 쪽이다

Augment Code가 OpenClaw PR 40개에 세 종류의 에이전트를 돌린 외부 실험은 꽤 흥미롭다. Karpathy 스타일 규칙을 AGENTS.md에 추가하자, Claude Code와 Codex 모두 평균 비용과 소요 시간이 줄었다. 예를 들어 Claude Code는 비용 -10%, 시간 -7%, Codex는 비용 -8%, 시간 -7% 방향으로 개선됐다 (출처: Augment Code OpenClaw benchmark).

하지만 품질 점수는 자동 상승하지 않았다

같은 실험에서 코드 품질은 Auggie와 Codex는 거의 변화가 없었고, Claude Code는 오히려 소폭 하락했다. 해당 글도 이유를 “이미 강한 시스템 프롬프트를 가진 에이전트에 추가 제약을 더 얹으면 탐색 폭이 줄 수 있다”라고 해석한다 (출처: Augment Code OpenClaw benchmark). 이건 중요한 포인트다. 이 repo는 성능 booster가 아니라 trajectory regularizer에 더 가깝다.

최근 연구는 ‘하지 말라’가 특히 강하다고 본다

앞서 언급한 arXiv 2604.11088은 규칙 파일이 전체적으로 7~14포인트의 성능 개선을 보였지만, 랜덤 규칙도 전문가 규칙만큼 도움이 된 경우가 있었고, 개별 규칙 유형 중에서는 negative constraint만 뚜렷하게 유익했다고 본다 (출처: Do Agent Rules Shape or Distort?). 이 관점에서 보면 Surgical Changes는 이 repo의 감성 포인트가 아니라 실제로 일반화 가능성이 가장 높은 부분일 수 있다.

(출처: Augment Code OpenClaw benchmark, arXiv 2604.11088)

6. main 브랜치 기준으로 아직 부족한 점은 무엇인가?

좋은 repo지만, 그대로 제품처럼 믿고 가져다 쓰기엔 빈칸이 분명하다.

첫째, 라이선스 신호가 깔끔하지 않다

README와 plugin.json, SKILL.md에는 MIT가 적혀 있다. 하지만 2026년 5월 2일 확인한 GitHub API의 license 필드는 null이고, 루트 contents에도 LICENSE 파일이 없다 (출처: GitHub API, plugin.json). 당장 위험하다고 단정할 일은 아니지만, 기업 도입 관점에서는 legal clarity가 덜 정리된 상태라고 보는 게 맞다.

둘째, 릴리스와 changelog가 없다

GitHub 페이지 기준 공개 릴리스가 없다. 즉, “어느 시점의 어떤 버전을 팀 표준으로 쓸 것인가”가 애매하다 (출처: GitHub). 현재는 최신 main을 보는 방식이라 reproducibility가 약하다.

셋째, cross-agent 지원은 기대만큼 mainline에 올라오지 않았다

Codex 관련 PR이 활발한 건 사실이지만, 그 자체가 main 브랜치의 native support를 뜻하진 않는다. OpenClaw, OpenCode, Codex 등으로 확장되는 흐름은 커뮤니티 수요의 증거이지, 제품 완성도의 증거는 아니다. Oh My OpenAgent 솔직 후기처럼 멀티 에이전트 세계를 본 적이 있다면 이 차이가 더 중요하게 보일 것이다.

넷째, 효과를 증명하는 자체 eval이 없다

외부 벤치마크와 논문을 끌어와야만 설명이 가능하다는 건 장점이 아니라 공백이다. 이 repo가 다음 단계로 가려면, 최소한 “이 규칙을 켠 상태와 끈 상태에서 어떤 작업군이 좋아지고 어떤 작업군이 느려지는가”를 저장소 내부에서 보여줄 필요가 있다.

7. 지금 복사해서 써도 되는 사람은 누구인가?

모든 팀에 정답은 아니다. 이 repo가 잘 맞는 팀과 애매한 팀은 분명히 갈린다.

잘 맞는 쪽은 ‘과한 수정’에 시달리는 팀이다

버그 하나 고치랬더니 import 정리, 주석 수정, 타입 힌트 추가, 스타일 통일까지 같이 들어오는 상황이 흔하다면 바로 효과를 볼 가능성이 높다. 특히 PR review 비용이 커진 팀, AI가 diff를 더럽혀서 사람 리뷰어가 피곤해진 팀에 잘 맞는다.

덜 맞는 쪽은 가벼운 태스크 위주 팀이다

사소한 오타, 한 줄 문구 수정, 아주 분명한 리네이밍이 대부분이라면 이 repo의 신중함이 오히려 오버헤드가 될 수 있다. 제작자 자신도 README에서 trivial task에는 판단을 쓰라고 적어뒀다 (출처: README).

장기적으로는 behavioral floor로 쓰는 편이 낫다

가장 현실적인 사용법은 이 repo를 팀의 모든 규칙으로 착각하지 않는 것이다. 아래처럼 생각하면 편하다.

한국 독자에게 특히 중요한 판단 기준

한국 팀은 글로벌 팀보다 “리뷰 가능한 작은 diff”에 민감한 편이다. 빠르게 만드는 것만큼 나중에 설명 가능한 변경이 중요하기 때문이다. 그런 문화에선 이 repo가 꽤 잘 맞는다. 반대로 “어차피 throwaway prototype”이 대부분이라면 굳이 엄격하게 쓸 필요는 없다.

8. 한국 개발자는 어떻게 섞어서 적용하면 되나?

핵심은 원문을 통째로 숭배하는 게 아니라, 도구별 표면은 다르게 두고 doctrine은 하나로 유지하는 것이다.

Claude Code 프로젝트라면 CLAUDE.md에 병합한다

가장 간단한 방식은 프로젝트 루트 CLAUDE.md 하단에 이 repo의 원칙을 behavioral floor로 넣는 것이다. 그 위나 아래에 프로젝트 특화 규칙을 적으면 된다. Anthropic 공식 문서도 skills/manifest류를 프로젝트 지식과 절차를 분리하는 식으로 설명한다 (출처: Claude Code Skills Docs).

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

Cursor 팀이면 .cursor/rules에 두는 편이 낫다

Cursor는 공식적으로 Project Rules와 AGENTS.md를 지원하고, .cursor/rules가 버전 관리되는 규칙 경로라고 안내한다 (출처: Cursor Docs). 그래서 Cursor 중심 팀은 CLAUDE.md를 억지로 끼우기보다 .cursor/rules/karpathy-guidelines.mdc를 기준점으로 두는 편이 더 자연스럽다.

mkdir -p .cursor/rules
curl -o .cursor/rules/karpathy-guidelines.mdc https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/.cursor/rules/karpathy-guidelines.mdc

Codex나 다른 에이전트는 원칙만 가져오고 포맷은 현지화한다

Codex를 포함한 다른 에이전트에선 굳이 Claude 포맷을 흉내낼 필요가 없다. Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution라는 doctrine만 유지하고, 각 도구가 읽는 설정면으로 번역하는 편이 낫다. 이런 접근은 AI 앱은 프롬프트가 아니라 하네스로 완성된다에서 말한 “control plane은 같고 runtime은 다를 수 있다”는 원칙과도 맞닿아 있다.

가장 좋은 도입 순서는 한 번에 전사 적용이 아니다

파일 하나 넣고 끝내지 말고, 먼저 noisy한 작업 한 종류에서 diff 크기와 재시도 횟수부터 비교해보는 것이 좋다. 예를 들어 “폼 validation 추가”, “logging 삽입”, “stale refactor 복구” 같은 작업군에서 효과가 빨리 드러난다.

9. 자주 묻는 질문

10. 결론: 이 repo는 도입할 가치가 있는가?

가치는 있다. 다만 이유를 정확히 알아야 한다. 이 repo는 Claude를 천재로 만들지 않는다. 대신 AI 코딩 에이전트를 덜 위험한 동료로 만드는 최소한의 행동 규약을 제공한다. 그리고 그 규약을 Claude plugin, SKILL, Cursor rule, 향후 Codex port까지 이어질 수 있는 포맷으로 잘 포장해 놨다.