andrej-karpathy-skills는 AI 코딩 도구가 코드를 작성할 때 따라야 할 "행동 규칙"을 적은 단 한 장의 마크다운 스킬이다. 본인 프로젝트 폴더에 CLAUDE.md를 두거나 플러그인/스킬로 설치하면, Claude Code가 매 작업마다 그 규칙을 먼저 읽고 일을 시작한다. 코드도, 실행할 프로그램도, 빌드도 없다. 그냥 텍스트 파일인데 별 16만 개를 받았다.
일반 코딩 가이드가 "이런 함수를 써라"는 기술 매뉴얼이라면, 이 레포는 "막히면 멋대로 가정하지 말고 되물어라, 100줄로 될 일을 1000줄로 만들지 마라"는 행동 헌법이다.
핵심은 밀도다. 거대한 가이드 모음집이 아니라 4개 원칙만 있는데, 그 4개가 AI 코딩 도구를 써본 사람이라면 누구나 겪은 "정확히 그 통증"에 직격으로 대응한다. 노이즈 비율이 극단적으로 낮은 것 — 그게 이 레포의 본질이다.
CLAUDE.md), Cursor용(.cursor/rules/karpathy-guidelines.mdc), 플러그인용(skills/karpathy-guidelines/)으로 동시 제공한다.Claude Code, Cursor, Copilot, Codex를 써본 사람이라면 다음 네 패턴에 모두 공감한다. Karpathy의 원문은 모델이 "사용자 대신 잘못된 가정을 세우고 그냥 달려버리며, 코드와 API를 과하게 복잡하게 만들고, 죽은 코드를 안 치운다"고 짚는다. 이 레포는 그것을 "질환 → 처방" 4쌍으로 압축했다.
모호한 요청을 받으면 되묻지 않고 자기가 가정을 잡아 코드를 짠다. 5분 후 결과를 보면 "내가 원했던 거랑 완전 다른데?"가 된다. 모순을 표면화하지 않고, 선택지를 안 보여주고, 반박해야 할 때 반박하지 않는다.
요청이 모호하면 먼저 되묻는다. 여러 해석이 가능하면 선택지를 보여주고 결정을 받는다. 트레이드오프(이쪽을 얻으면 저쪽을 잃음)가 있으면 명시한다.
필요 없는 추상화를 만들고, 미래의 가상 요구를 위한 유연성을 미리 박고, 불가능한 시나리오용 에러 처리까지 더한다. 결국 100줄이면 끝날 일이 1000줄이 된다.
매번 자문한다 — "시니어 엔지니어가 이걸 보고 '과하다'고 할까?" 지금 요구되지 않은 미래 기능용 추상화는 금지. 문제를 푸는 최소한의 코드만 남긴다.
"이 함수 한 줄만 고쳐줘"라 했는데 옆 주석을 지우고, 변수명을 바꾸고, "죽은 코드처럼 보이는" 라인을 삭제한다. 알고 보면 그게 외부 모듈에서 쓰던 코드였다. 이걸 drive-by refactoring이라 부른다.
요청한 라인 외에는 건드리지 않는다. 외과의가 수술 부위만 정확히 자르듯, 작업과 직교(orthogonal)한 영역은 손대지 않는다. 리팩토링이 필요해 보여도 별도 작업으로 제안만 한다.
"검증 로직 추가해줘"라고 하면 "검증"이 길이 체크인지, 타입 체크인지, 보안 체크인지 AI가 제멋대로 정한다. 결과가 의도와 다를 확률이 매우 높다.
명령("이걸 해줘") 대신 성공 기준("이 테스트가 통과해야 한다")을 준다. 그러면 AI가 그 기준을 만족할 때까지 알아서 루프를 돈다. 이 가이드의 가장 강력한 통찰이다.
| 비교 대상 | andrej-karpathy-skills의 차별점 |
|---|---|
| 일반 CLAUDE.md 템플릿 | "빌드 명령·코딩 스타일" 같은 기술 정보가 아니라 AI의 행동 실패 패턴을 직접 교정한다 |
| 긴 회사 코딩 컨벤션 문서 | 수백 줄 규칙 대신 65줄에 4원칙만. 밀도가 높아 모델이 실제로 따른다 |
| "하지 마라" 식 금지 목록 | "이런 상황에서 이렇게 행동하라" + "왜"를 함께 적어 엣지 케이스에서도 응용 가능 |
| 도구별 개별 설정 | Claude Code·Cursor·플러그인 3경로를 같은 내용으로 동시 커버 (CLAUDE.md / .mdc / skills/) |
이 레포에는 프로그래밍 언어 스택이 없다. 대신 같은 행동 규칙을 여러 도구·여러 활성화 방식으로 패키징한 "전달 형식 스택"이 있다. 그게 이 레포의 진짜 구성이다.
| 요소 | 역할 | 상세 |
|---|---|---|
| CLAUDE.md | 핵심 규칙 본문 | 4원칙을 담은 마크다운. 프로젝트 루트에 두면 Claude Code가 자동 로드 |
| CURSOR.md | Cursor 설정 가이드 | Cursor에서 같은 규칙을 적용하는 셋업 문서 |
| .cursor/rules/ karpathy-guidelines.mdc | Cursor 룰 파일 | Cursor의 Project Rules 형식(.mdc)으로 변환된 동일 규칙 |
| skills/ karpathy-guidelines/ | 스킬 패키지 | 플러그인/스킬로 설치될 때의 진입점 |
| .claude-plugin/ | 플러그인 메타 | Claude Code 플러그인 마켓 설치를 위한 설정 |
| EXAMPLES.md | 예제 모음 | 각 원칙별 "잘못된 코드 vs 올바른 코드"를 짝지은 학습 자료 |
| 대상 | 관계 |
|---|---|
| Claude Code | CLAUDE.md를 세션 시작 시 읽는 호스트 도구 |
| Cursor | .cursor/rules/*.mdc를 Project Rule로 읽는 호스트 IDE |
| Anthropic Agent Skills | 스킬 형식으로 조건부(코딩 작업 감지 시) 로드되는 메커니즘 |
※ 위 디렉토리 구성은 README/레포 페이지에서 확인. 일부 내부 파일 세부(plugin.json 키 등)는 미확인이라 일반 플러그인 규약 기준으로 표기.
두 부탁을 비교해보자.
① "이 API에 캐싱 추가해줘" (명령형)
② "이 API 응답이 100ms 이하가 되도록, 기존 테스트 다 통과 유지하면서 고쳐줘" (선언형 + 검증 기준)
①은 AI가 "캐싱"을 뭐로 해석할지 모른다. ②는 AI가 시도 → 테스트 → 실패 → 재시도 루프를 혼자 돌릴 수 있다. 사람이 매번 끼어들 필요가 없다.
이 통찰의 함의는 깊다. 테스트 주도 개발(TDD)이 AI 에이전트와 원래부터 합이 좋다는 뜻이다. 사람에게 TDD는 부담이지만, AI는 "테스트가 통과하면 끝"이라는 종료 조건을 받아 루프를 도는 걸 매우 잘한다.
이 가이드의 영리한 점: 가이드 자신이 자기 한계를 표면화한다. 본문에 "이 가이드라인은 속도보다 신중함 쪽으로 치우쳐 있다. 사소한 작업(오타·명백한 한 줄 변경)은 판단력으로 처리하라"는 취지의 메타 규칙이 들어 있다.
안전벨트 규정과 같다. "타면 매라"가 일반 규칙이지만, 주차장에서 1m 옮기는 데도 매야 할까? 규칙 본문이 "예외는 판단으로"라고 미리 명시해 두면 사용자가 안 헷갈린다. 이 한 줄이 원칙 1(Think Before Coding)을 가이드 스스로 실천한 셈이다.
구조의 핵심은 "하나의 규칙 → 세 가지 통로"다. CLAUDE.md(Claude Code 자동 로드), .cursor/rules/*.mdc(Cursor Project Rule), skills/(플러그인·스킬 조건부 로드). 같은 4원칙을 도구마다 알맞은 포맷으로 복제해 둔 것이 이 레포의 설계 결정이다.
배울 것: 시스템 프롬프트를 쓸 때 "하지 마라"보다 "이 상황에서는 이렇게 행동하라"가 훨씬 강력하다. 금지 목록은 나열한 케이스만 막지만, 행동 규칙은 모델이 새 상황에 응용한다.
배울 것: 단순히 "이렇게 해라"가 아니라 "AI가 이런 실수를 자주 하니까 이렇게 해라"는 구조. 이유와 함께 적힌 규칙은 모델이 엣지 케이스에서도 의도를 추론한다.
배울 것: "시니어 엔지니어가 이걸 보고 '과하다'고 할까?" 같은 자문 질문을 규칙에 심으면, 모델이 그 질문을 스스로에게 던지며 자가 검증한다.
배울 것: "무엇을 해라" 대신 "성공 기준을 줘라". 검증 가능한 종료 조건을 주면 AI가 자율 루프를 돈다. TDD와 AI 에이전트의 천연 궁합을 이해하는 것이 핵심.
배울 것: 모든 규칙엔 트레이드오프가 있다. "이 가이드는 X쪽으로 치우쳐 있다"를 본문에서 미리 인정하면 사용자가 헷갈리지 않는다. 가이드가 자기 자신에게 원칙 1을 적용한 사례.
배울 것: 같은 지식을 CLAUDE.md / .mdc / Skill로 동시에 패키징하는 Progressive Disclosure 전략. 항상 켜둘지(루트 CLAUDE.md), 필요할 때만 켤지(Skill)를 선택해 토큰을 관리한다.
이 레포는 실행 바이너리가 없어 하드웨어 요구사항이 사실상 없다. 대신 이 규칙을 읽어줄 호스트 도구가 필요하다.
| 항목 | 최소 | 권장 |
|---|---|---|
| 호스트 도구 | Claude Code 또는 Cursor 중 하나 | 둘 다 (같은 규칙 공유 가능) |
| 설치 방식 | CLAUDE.md 한 장 복사 | 플러그인 설치(전 프로젝트 일괄 적용) |
| 디스크 | 수 KB (텍스트 파일) | 동일 |
| 네트워크 | 최초 다운로드 시에만 | 플러그인 마켓 접근 |
| 계정 | 호스트 도구의 구독/계정 | 동일 |
| 방법 | 활성화 시점 | 장단점 |
|---|---|---|
| ① 루트 CLAUDE.md | 매 세션 항상 | 가장 단순. 항상 켜진 안내문. 프로젝트마다 복사 필요 |
| ② 플러그인 설치 | 모든 프로젝트 동시 | 한 번 설치로 전역 적용. 복사 불필요 |
| ③ 스킬(조건부) | "코딩 작업" 감지 시만 | 토큰 절약. 항상 박혀 있지 않음 |
# 방법 ②: 플러그인 설치 (권장)
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
# 방법 ①: 프로젝트에 CLAUDE.md만 내려받기
curl -o CLAUDE.md \
https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md
# Cursor 사용자: 같은 규칙을 .mdc 룰로
# .cursor/rules/karpathy-guidelines.mdc 로 배치하면 동일 동작※ 플러그인 마켓 슬러그는 README 기재값(forrestchang/andrej-karpathy-skills)을 그대로 표기. 본인 환경에서 명령 형식은 최신 Claude Code 문서로 재확인 권장.
본인 사이드 프로젝트에 이 CLAUDE.md를 받아 두고, 평소 하던 작업(예: 새 API 엔드포인트 추가)을 시켜본다.
아래 3가지 부탁을 명령형/선언형 두 버전으로 적어본다. 선언형에는 항상 검증 가능한 테스트 조건을 붙인다.
# 명령형 (AI가 해석 떠넘김)
"에러 처리 보강해줘"
# 선언형 (성공 기준 명시)
"네트워크 타임아웃·4xx·5xx 각각에 대해
사용자에게 보이는 메시지가 다르게 나오도록 고치고,
tests/error_cases.test 가 전부 통과하게 해줘"레포의 EXAMPLES.md에서 각 원칙별 "나쁜 코드 vs 좋은 코드"를 읽고, AI에게 일부러 모호한 요청을 던져 4가지 질환을 실제로 재현해 본다. 그다음 규칙을 적용해 차이를 기록한다.
React 컴포넌트·SQL 쿼리·K8s manifest 등 본인이 자주 다루는 영역에 대해 "AI가 자주 망치는 4패턴 + 처방"을 직접 적어 CLAUDE.md로 만든다. Karpathy 패턴을 자기 도메인에 이식하는 연습.
최근 PR 3개를 입력으로 받아 4원칙 각각의 위반을 점수와 함께 리포트하는 작은 스크립트를 만든다. 입력은 git diff, 출력은 마크다운 리포트.
# detect_violations.py (개념 골격)
git diff main...HEAD # 입력
→ 변경 라인 수 vs 요청 범위 비교 # Surgical 위반 점검
→ 신규 추상화/클래스 수 카운트 # Simplicity 위반 점검
→ 테스트 동반 여부 확인 # Goal-Driven 점검
→ markdown 리포트 출력| 요일 | 학습 내용 | 실습 |
|---|---|---|
| 월 | 레포 통독 (README + CLAUDE.md) | 4원칙을 한 문장씩 본인 말로 요약 |
| 화 | 질환 4가지 직접 재현 | 모호한 요청으로 AI 실수 유도·기록 |
| 수 | CLAUDE.md 적용 전후 비교 | 같은 작업 diff 크기 측정 |
| 목 | EXAMPLES.md 정독 | 나쁜/좋은 코드 짝 5개 필사 |
| 금 | 회고 | "내가 가장 자주 겪는 질환" 1개 선정 |
| 요일 | 학습 내용 | 실습 |
|---|---|---|
| 월 | 명령형/선언형 개념 | 일상 부탁 5개를 양쪽으로 변환 |
| 화 | 검증 기준 설계 | "성공 = 테스트 통과"로 작업 정의 |
| 수 | TDD × AI 에이전트 | 테스트 먼저 주고 AI에게 루프 돌리기 |
| 목 | Goal-Driven 실전 | 실제 버그를 선언형으로 의뢰 |
| 금 | 실패 루프 관찰 | AI가 스스로 재시도하는 과정 기록 |
| 요일 | 학습 내용 | 실습 |
|---|---|---|
| 월 | "행동 헌법" 패턴 | 금지형 규칙을 행동형으로 다시 쓰기 |
| 화 | "왜"를 함께 적기 | 각 규칙에 실패 사유 한 줄 추가 |
| 수 | 자가 점검 질문 심기 | 규칙마다 자문 질문 1개 삽입 |
| 목 | 트레이드오프 명시 | "이 가이드는 X쪽으로 치우침" 한 줄 |
| 금 | 내 도메인 4원칙 완성 | 과제 4 결과를 CLAUDE.md로 정리 |
| 요일 | 학습 내용 | 실습 |
|---|---|---|
| 월 | 3가지 적용 방식 비교 | 루트/플러그인/스킬 직접 설치 실험 |
| 화 | Cursor 룰(.mdc) 변환 | 같은 규칙을 .cursor/rules로 이식 |
| 수 | Progressive Disclosure | "항상 vs 조건부" 로드 토큰 비교 |
| 목 | 위반 탐지기 (과제 5) | git diff → 리포트 스크립트 완성 |
| 금 | 팀 표준화 | 팀 공유용 행동 규칙 1장 작성 |
| 키워드 | 설명 |
|---|---|
| CLAUDE.md | Claude Code가 프로젝트 폴더에서 세션 시작 시 자동으로 읽는 마크다운 설정 파일. 이 레포의 핵심 산출물 |
| 스킬 (Skill) | 특정 조건에서 자동 로드되는 행동 지침 묶음. SKILL.md/skills 디렉토리로 패키징 |
| Think Before Coding | 원칙 1. 가정하지 말고 되묻고, 선택지와 트레이드오프를 표면화하라 |
| Simplicity First | 원칙 2. 문제를 푸는 최소한의 코드. 투기적(speculative) 기능·추상화 금지 |
| Surgical Changes | 원칙 3. 요청한 부분만 정확히. 무관한 코드·죽은 코드는 건드리지 않기 |
| Goal-Driven Execution | 원칙 4. 명령 대신 검증 가능한 성공 기준을 주고 루프를 돌게 하라 |
| drive-by refactoring | 요청과 무관한 부분을 "지나가다 김에" 고치는 AI의 나쁜 습관 (질환 3) |
| 명령형(imperative) | "이렇게 해라"는 절차 지시. AI가 해석을 떠안아 결과가 어긋나기 쉬움 |
| 선언형(declarative) | "이 조건이 만족되게 해라"는 결과 지시. AI가 자율 루프를 돌 수 있게 함 |
| TDD | 테스트 주도 개발. 종료 조건이 명확해 AI 에이전트와 합이 좋음 |
| 성공 기준 (success criteria) | "이 테스트가 통과해야 한다" 같은 검증 가능한 종료 조건. Goal-Driven의 핵심 |
| 자율 루프 | AI가 성공 기준을 충족할 때까지 시도-검증-재시도를 사람 개입 없이 반복 |
| Progressive Disclosure | 필요한 시점에만 정보를 끌어오는 설계. 스킬 조건부 로드가 이를 구현 |
| 행동 헌법 | "하지 마라" 목록이 아닌 "이 상황에서 이렇게 행동하라"는 규칙 구조 |
| 트레이드오프 표면화 | 선택의 득실을 숨기지 않고 사용자에게 드러내는 것. 원칙 1의 핵심 동작 |
| .mdc (Cursor rule) | Cursor의 Project Rules 파일 형식. 같은 규칙을 Cursor에 이식할 때 사용 |
| 컨텍스트 엔지니어링 | AI에게 줄 컨텍스트(규칙·예시·기준)를 설계하는 기술. 이 레포가 가르치는 메타 스킬 |