AI 코딩을 잘하기 위한 방법 - andrej-karpathy-skills-화이트래빗스토리

andrej-karpathy-skills 발표 자료

https://www.youtube.com/watch?v=96jN2OCOfLs

노트북LLM 정리

카파시의 20년 경력을 뒤집은 65줄

1. 시작

andrej-karpathy-skills 65줄짜리 마크다운 한 장이 AI 코딩의 흐름을 바꿨다.
"코드를 잘 짜는 AI에게 필요한 건 더 좋은 모델이 아니라, 더 좋은 고삐다."
부제: 4가지 원칙으로 보는 하네스 엔지니어링 시대의 개막

2. 왜 지금 이 이야기를 해야 하는가?

Andrej Karpathy의 Phase Shift (2025.11 → 2025.12)

OpenAI 공동창업자이자 Tesla AI 수석을 지낸 Karpathy는 2025년 11월까지만 해도 코드의 80%를 직접 손으로 쓰고 있었습니다. 한 달 뒤인 12월, 그 비율은 정반대로 뒤집힙니다. 80%가 에이전트 주도 코딩으로 바뀐 것이죠. 그는 이를 "20년 프로그래밍 인생에서 가장 큰 변화"라고 표현했습니다.

점진적 변화가 아니라 상태 전이(phase shift)다.

한 단계 더: 이 전환이 의미심장한 이유는 단순히 "AI가 좋아졌다"가 아닙니다. 이 시점부터 개발자가 직면하는 문제가 *"AI가 코드를 짤 수 있는가"*에서 *"AI가 짠 코드를 어떻게 통제할 것인가"*로 완전히 이동했다는 점입니다.

3. 그런데 왜 AI 에이전트는 자주 망가지는가

Karpathy의 솔직한 실패 관찰 (직접 인용)

"모델들은 사용자를 대신해 잘못된 가정을 하고는, 확인도 없이 그냥 달려나간다. 자신의 혼란을 관리하지 못하고, 명확화를 요청하지 않고, 모순을 드러내지 않고, 트레이드오프를 제시하지 않고, 마땅히 푸시백해야 할 때 푸시백하지 않는다."

"그들은 코드와 API를 과하게 복잡하게 만드는 걸 정말 좋아한다. 추상화를 부풀리고… 100줄이면 될 일을 1000줄짜리 부풀린 구조로 구현한다."

"충분히 이해하지 못한 코드와 주석을 부수 효과로 변경하거나 삭제하는 일도 여전히 일어난다. 작업과 무관한 부분에서도."

한 단계 더: 이건 모델 능력의 문제가 아닙니다. 모델은 훈련 분포 안에서 가장 그럴듯한 다음 토큰을 만드는 데 최적화되어 있고, 그 결과 "있어 보이는 코드"를 향한 편향이 구조적으로 존재합니다. 이걸 모델 학습으로 푸는 것보다 환경으로 막는 게 훨씬 저렴합니다.

4. andrej-karpathy-skills의 탄생

Karpathy의 관찰은 트위터/X에서 바이럴이 됐지만, 그건 통찰이지 도구는 아니었습니다. 개발자 Forrest Chang이 그 관찰들을 정제해 단 하나의 CLAUDE.md 파일로 응축시켰고, 이게 GitHub에서 가장 빠르게 성장하는 레포 중 하나가 됩니다.

핵심 사실

파일 한 개, 마크다운 65줄
4가지 행동 원칙으로 구성
Claude Code뿐 아니라 Cursor에서도 동작 (.cursor/rules/karpathy-guidelines.mdc 포함)
설치는 curl 한 줄

한 단계 더: 이 레포가 흥미로운 이유는 그것이 코드를 공유하지 않는 오픈소스라는 점입니다. 받는 사람이 import하는 라이브러리가 아니라, 받는 사람의 에이전트가 읽고 적용하는 원칙 모음입니다. Karpathy는 이걸 "idea file 패턴"이라고 부릅니다 — 오픈소스의 새로운 형태입니다.

5. 4가지 원칙 - 한눈에 보기

#	원칙	막으려는 것	핵심 질문
1	Think Before Coding	침묵 속의 잘못된 가정	"내가 뭘 해석한 거지?"
2	Simplicity First	부풀린 추상화, 1000줄로 100줄 일 하기	"시니어가 보면 과하다고 할까?"
3	Surgical Changes	무관한 곳까지 손대는 오지랖	"이 변경이 요청과 직접 연결되나?"
4	Goal-Driven Execution	"동작하게 해줘" 같은 약한 기준	"성공을 어떻게 검증할 건가?"

한 단계 더: 이 4가지는 사실 사람 시니어 엔지니어를 평가할 때도 그대로 통용되는 기준입니다. AI에게 강제하는 습관이 인간 팀원에게도 좋은 습관이라는 점이, 이 프레임워크가 단순한 프롬프트 트릭이 아닌 이유입니다.

6. 원칙 1 — Think Before Coding

무엇을 코딩을 시작하기 전에 멈춰라. 불확실한 부분이 있으면 사용자에게 질문하고, 가정을 명시적으로 드러내라.

왜 LLM은 모호함을 만나면 침묵 속에서 한 가지 해석을 골라 달려나갑니다. 그 해석이 틀렸다면 결과물 전체가 잘못된 방향으로 가고, 사용자는 한참 뒤에야 그 사실을 알게 됩니다.

구체적 행동

"Don't assume" — 불확실하면 묻는다
"Don't hide confusion" — 혼란을 감추지 않고 드러낸다
"Surface tradeoffs" — 선택지가 있으면 트레이드오프를 제시한다
"Push back when needed" — 요청이 잘못됐다고 판단되면 반박한다

한 단계 더: 이 원칙의 진짜 가치는 "AI가 더 정중해진다"가 아니라, 불확실성이 비용이 되기 전에 시스템 밖으로 표면화된다는 점입니다. 비용 곡선상 가정 오류를 5분 뒤에 발견하는 것과 5시간 뒤에 발견하는 것은 차원이 다릅니다.

7. 원칙 2 - Simplicity First

무엇을 지금 당장 필요한 만큼만 구현하라. 미래의 가상의 요구를 위한 추상화를 미리 만들지 마라.

왜 LLM은 훈련 데이터의 "교과서적 좋은 코드" 패턴을 따라가려는 경향이 강해서, 항상 디자인 패턴, 인터페이스, 추상 레이어를 과도하게 도입합니다. 100줄이면 끝날 일을 1000줄로 만드는 이유입니다.

테스트 기준

시니어 엔지니어가 이 코드를 보면 과하다고 말할까? 그렇다면 단순화하라.

구체적 행동

미래의 요구를 위한 일반화 금지
사용되지 않는 추상 클래스/인터페이스 금지
"혹시 모르니까"라는 이유로 옵션 추가 금지

한 단계 더: 이 원칙은 사실 YAGNI (You Aren't Gonna Need It)의 AI 시대 버전입니다. 차이점은, 인간 엔지니어는 게을러서 단순하게 짜고 LLM은 부지런해서 복잡하게 짠다는 것. 그래서 LLM에게는 "단순하게 짜라"고 명시적으로 강제해야 합니다.

8. 원칙 3 - Surgical Changes

무엇을 요청받은 부분만 수정하라. 외과 수술처럼.

왜 LLM은 코드를 읽다가 "어, 이것도 좀 정리하면 좋겠는데"라고 판단하면 작업 범위 밖의 코드, 주석, 변수명을 함께 건드립니다. 그 결과 PR 리뷰가 불가능해지고, 회귀 버그의 출처를 추적할 수 없게 됩니다.

핵심 규칙

"Touch only what you must" — 꼭 만져야 하는 것만 만진다
"Clean up only your own mess" — 자기가 만든 것만 청소한다
무관한 리팩토링 금지

테스트 기준

변경된 모든 줄이 사용자의 요청과 직접 연결되는가?

한 단계 더: 이 원칙이 강력한 이유는, 이걸 지키면 자동으로 변경의 가독성이 보장되기 때문입니다. 디프(diff)가 작고 의도가 명확하면 인간 리뷰의 부담이 줄고, AI의 작업을 신뢰하면서도 검증 가능한 워크플로우가 가능해집니다. 즉 이건 단순한 "예의"가 아니라 협업의 인프라입니다.

9. 원칙 4 - Goal-Driven Execution

무엇을 성공 기준을 명확히 정의하고, 검증 루프를 돌려라.

왜 "동작하게 해줘"는 너무 약한 기준입니다. 모델은 그 안에서 무한히 헤매거나, 끊임없이 명확화를 요구합니다. 반면 강한 기준은 모델이 독립적으로 작업하고 스스로 검증할 수 있게 합니다.

약한 기준 vs 강한 기준

약한 기준	강한 기준
"버그를 고쳐줘"	"이 테스트 케이스가 통과하면 완료"
"성능을 개선해줘"	"p95 응답시간이 200ms 이하"
"예쁘게 만들어줘"	"이 시안과 픽셀 단위로 일치"

핵심 패턴

성공 기준 정의
자동화된 검증 (테스트, 린터, 메트릭)
검증 통과까지 루프

한 단계 더: 이 원칙은 사실 "하네스 엔지니어링"의 씨앗입니다. 강한 성공 기준은 결국 자동화 가능한 검증 도구를 만들도록 강제하고, 그 도구들이 모이면 에이전트가 자율적으로 일할 수 있는 환경 — 즉 하네스 — 가 됩니다.

10. 더 큰 흐름 — 엔지니어링 패러다임의 진화

Prompt → Context → Harness 3단 진화

2023~2024 | Prompt Engineering
          | 한 번의 질문, 한 번의 답
          | "역할을 정해라, 단계를 나눠라, 예시를 줘라"
          ↓
2025 중반 | Context Engineering
          | 카파시 발언으로 부상
          | RAG, MCP, 메모리 등 시스템 레벨 컨텍스트 설계
          ↓
2026.02   | Harness Engineering
          | Mitchell Hashimoto (HashiCorp 공동창업자) 블로그
          | 며칠 후 OpenAI "Harness engineering" 공식 발표
          | 에이전트 환경 전체 설계로 확장

한 단계 더: 이 진화는 인터페이스의 변화이기도 합니다. Prompt는 질문, Context는 지식, Harness는 작업장입니다. 작업장 단계에서는 모델 자체를 바꾸지 않고도 산출물 품질을 1~2자릿수 끌어올릴 수 있다는 게 OpenAI 사내 실험에서 입증됐습니다.

11. 하네스 엔지니어링이란

정의

하네스(harness)란 AI 에이전트를 둘러싼 스캐폴딩, 제약, 피드백 루프의 총체다. 모델 외부에 존재하는 모든 것이다. — OpenAI

핵심 통찰 같은 모델이 프로젝트 A에서는 잘 동작하고 B에서는 이상한 결과를 냅니다. 프롬프트를 아무리 튜닝해도 격차가 좁혀지지 않습니다. 원인은 거의 항상 모델이 아니라 환경입니다.

OpenAI의 사내 실험 결과 하네스를 제대로 구성한 환경에서, 약 100만 줄의 프로덕션 소프트웨어를 수작업 코드 없이 AI만으로 생성하는 것이 가능했습니다.

한 단계 더: "harness"라는 단어는 마구를 의미합니다. 말의 능력을 제한하기 위해서가 아니라, 그 능력이 원하는 방향으로 발휘되도록 채우는 것입니다. AI 능력을 줄이는 게 아니라 채널링하는 게 핵심입니다.

12. 하네스의 구성 요소

1. 인스트럭션 파일 프로젝트의 system of record. CLAUDE.md, AGENTS.md, .cursorrules. 프로젝트 구조, 코딩 규칙, 명명 컨벤션을 담습니다. Slack 스레드나 누군가의 머릿속에만 있는 지식은 에이전트에게 보이지 않으므로, 레포 안에 마크다운 문서로 존재해야 합니다.

2. Agent Skills 반복 작업의 절차서. 코드 리뷰 체크리스트, 배포 워크플로우, 특정 프레임워크의 선호 패턴 등. 필요할 때 에이전트가 읽고 실행합니다.

3. 검증 도구 린터, 타입 체커, 테스트, 커스텀 구조 검사기. 단순히 에러를 잡는 게 아니라 에이전트에게 수정 방향을 다시 주입하는 역할.

4. 피드백 루프 검증 실패 → 에러 메시지가 컨텍스트로 재주입 → 에이전트가 자가 수정 → 다시 검증. 이 루프가 닫혀야 자율성이 생깁니다.

한 단계 더: 이 구조는 결국 살아있는 시스템입니다. 프로젝트가 진화하면서 하네스도 함께 진화해야 합니다. 정적 문서로 두면 빠르게 낡아서 무용지물이 됩니다.

13. 왜 하필 65줄인가 — 짧음의 미학

컨텍스트 윈도우는 희소 자원이다

OpenAI 실험에서 발견된 핵심 교훈: "모든 것을 거대한 AGENTS.md 하나에 우겨넣는 전략은 예측 가능하게 실패한다."

왜 실패하는가

컨텍스트 윈도우는 한정되어 있다
모든 게 중요하다고 적으면 모델은 결국 어떤 것도 진지하게 받아들이지 않는다
거친 패턴 매칭으로 회귀해서 규칙을 무시하기 시작한다

그래서 65줄

4개 원칙, 각 원칙마다 짧은 설명과 테스트 기준
전체가 한눈에 들어옴
매 요청마다 컨텍스트에 들어가도 부담 없음

한 단계 더: 좋은 하네스 설계는 덧셈이 아니라 뺄셈입니다. 무엇을 더 적을지가 아니라 무엇을 빼도 되는지를 묻는 것이 시작점입니다. 이 점에서 출판/편집의 직관과 매우 닮아 있습니다 — 좋은 편집자는 "더 쓰자"가 아니라 "이 문장이 꼭 필요한가"를 묻습니다.

14. 피드백 루프의 핵심 — 린터를 컨텍스트 주입기로

OpenAI 실험에서 발견된 가장 강력한 디테일

그들이 만든 커스텀 린터는 단순히 에러를 반환하지 않았습니다. 에러 메시지가 그대로 에이전트의 컨텍스트로 다시 주입되도록 설계됐습니다.

예시: 의존성 방향 강제

Types → Config → Repo → Service → Runtime → UI

이 방향을 위반하는 코드가 생성되면, 린터가 차단하고 동시에 어떻게 고쳐야 하는지를 에이전트에게 알려줍니다.

왜 이게 결정적인가

정적 규칙은 사람이 읽어야 의미가 있음
동적 피드백은 에이전트가 스스로 수정 가능
검증 도구가 교사 역할을 함

한 단계 더: 이 패턴을 일반화하면 — 당신이 이미 가진 모든 검증 도구(테스트, 린터, CI 체크)는 잠재적인 교육 도구입니다. 에러 메시지의 품질이 곧 에이전트의 학습 속도가 됩니다.

15. Idea File 패턴 — 새로운 종류의 오픈소스

전통적 오픈소스 vs Idea File

전통적 OSS	Idea File
코드를 공유	원칙을 공유
import해서 사용	읽고 적용
버전을 따라간다	자기 환경에 맞춘다
라이브러리	가이드

왜 이게 가능해졌는가 LLM 자체가 "원칙을 읽고 코드에 적용"하는 능력을 갖추면서, 지식을 공유하는 것만으로도 동작하는 결과물이 만들어집니다.

예시들

andrej-karpathy-skills — 행동 원칙
Karpathy의 LLM Wiki 패턴 — 마크다운 기반 개인 지식 베이스
각종 SKILL.md 파일들

한 단계 더: 이 패턴은 작은 팀과 1인 운영자에게 특히 강력합니다. 풀스택 인프라를 만들 자원이 없어도, 원칙 한 장만 잘 만들면 같은 효과를 낼 수 있습니다. 출판/콘텐츠/학술 같은 도메인 지식이 깊은 영역에서 특히 그렇습니다.

16. 실전 적용 — 초보자 가이드

1단계: 일단 그대로 써본다

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

프로젝트 루트에 두면 끝. Claude Code가 자동으로 읽습니다.

2단계: Cursor 사용자도 동일 레포에 .cursor/rules/karpathy-guidelines.mdc가 함께 들어 있어 Cursor에서도 같은 가이드라인이 적용됩니다.

3단계: 효과를 확인한다

diff에 불필요한 변경이 줄었는가?
모델이 "이 부분은 어떻게 처리할까요?"라고 물어보기 시작했는가?
새로 생긴 코드가 더 짧고 단순해졌는가?

한 단계 더: 처음엔 그대로 쓰되, 최소 1~2주 사용 후부터 자기 프로젝트에 맞게 가지치기/추가하세요. 너무 일찍 커스터마이즈하면 기준선이 흐려져서 효과를 측정할 수 없습니다.

17. 실전 적용 — 중급자 / 팀 리더 관점

도메인 지식을 하네스로 인코딩하라

당신의 팀이 가진 암묵지를 마크다운 파일로 끌어내는 것이 진짜 작업입니다. 예를 들어:

학술 출판 워크플로우 → JATS XML 검증 규칙, 인용 무결성 체크
콘텐츠 플랫폼 → SEO 규칙, 메타데이터 일관성, 접근성 체크
결제 시스템 → 트랜잭션 무결성, 멱등성 패턴

검증 도구를 컨텍스트 주입기로 진화시켜라

기존 린터/테스트의 에러 메시지를 에이전트가 읽고 즉시 자가 수정 가능한 형태로 다시 씁니다. "Invalid input"이 아니라 "X must be Y because Z, fix by doing W."

측정을 시작하라

AI 작성 PR의 1차 통과율
무관한 변경 비율
명확화 질문 빈도 (높을수록 좋다 — 침묵보다 낫다)

한 단계 더: 작은 팀일수록 하네스 레버리지가 큽니다. 풀타임 시니어를 채용할 자원이 없어도, 시니어가 가진 판단력의 일부를 마크다운으로 인코딩할 수 있다면, 팀의 평균 산출 품질이 시니어 수준에 가까워집니다.

18. 잘 작동하는지 어떻게 아나 — 검증 신호

카파시-스킬스 레포의 README가 제시하는 신호들

신호	의미
diff에 불필요한 변경이 줄어든다	원칙 3 (Surgical Changes) 작동
요청한 것만 변경된다	동상
코드가 더 단순해진다	원칙 2 (Simplicity First) 작동
모호함에 대해 명확화 질문이 늘어난다	원칙 1 (Think Before Coding) 작동
테스트로 검증된 결과물이 늘어난다	원칙 4 (Goal-Driven) 작동

역설적 신호 — 명확화 질문 증가는 좋은 신호다

처음엔 모델이 더 자주 물어볼 겁니다. 이건 퇴보가 아니라 이전엔 침묵 속에 추측했던 것이 표면화되고 있다는 뜻입니다. 비용 곡선상 훨씬 이득입니다.

한 단계 더: 측정 가능한 KPI 없이 하네스를 도입하면 효과를 알 수 없고, 효과를 모르면 진화시킬 수 없습니다. 가장 단순한 것부터: AI PR의 머지 전 수정 횟수.

19. 함정과 흔한 오해

오해 1: "규칙을 다 적으면 좋다" ✗ AGENTS.md를 거대화 → 모델이 모든 규칙을 무시 ○ 짧고 핵심적인 원칙만 + 도메인별로 분리된 SKILL.md

오해 2: "이건 그냥 또 다른 프롬프트 엔지니어링이다" ✗ 프롬프트 = 한 번의 질문 최적화 ○ 하네스 = 환경 전체 설계 (인스트럭션 + 스킬 + 검증 + 피드백 루프)

오해 3: "AI에게 자유를 많이 줄수록 창의적이다" ✗ 자유로운 AI는 그럴듯한 결과를 만들지만, 일관된 결과는 못 만듦 ○ 제약이 자율성을 만든다 — 명확한 기준이 있어야 독립 실행 가능

오해 4: "이건 시니어용 도구다" ✗ 시니어는 어차피 자기 직관이 있어서 효과 체감이 작음 ○ 오히려 주니어와 작은 팀에 효과가 가장 큼 (시니어의 판단력을 인코딩)

한 단계 더: 가장 위험한 함정은 하네스를 만든 후 손대지 않는 것입니다. 코드베이스가 진화하는데 하네스가 그대로면, 6개월 뒤엔 거짓말 모음집이 됩니다.

20. 결론 — 엔지니어 역할의 변화

과거의 시니어 엔지니어

코드를 잘 짜는 사람

현재의 시니어 엔지니어

AI가 코드를 잘 짜는 환경을 설계하는 사람

핵심 역량의 이동

"어떻게 구현할 것인가" → "어떻게 검증할 것인가"
"내가 더 빨리 짠다" → "팀(인간+AI)이 더 빨리 짜게 한다"
"코드 리뷰" → "하네스 리뷰"

작은 팀일수록 큰 레버리지 정적 규칙 한 장, 검증 루프 몇 개만으로도 전통적 풀스택 인프라가 줘야 하는 일관성을 흉내낼 수 있습니다. 자원이 적은 팀일수록 이 패턴의 가성비가 큽니다.

마지막 인사이트

Karpathy가 "20년 만의 가장 큰 변화"라고 한 것은 AI가 코드를 짤 수 있게 됐다는 사실이 아닙니다. 개발의 본질이 "쓰기"에서 "설계와 검증"으로 이동했다는 점입니다. 65줄짜리 마크다운 한 장이 화제가 된 것은, 그 변화의 가장 작고 명확한 증거이기 때문입니다.

미래의 엔지니어는 키보드를 더 빨리 치는 사람이 아니라, AI가 달릴 가장 좋은 트랙을 깔 줄 아는 사람이다.

부록: 추가 학습 자료

GitHub 레포: forrestchang/andrej-karpathy-skills
하네스 엔지니어링: Mitchell Hashimoto 블로그 (2026.02.05)OpenAI "Harness engineering: leveraging Codex in an agent-first world" (2026.02.11)
Mitchell Hashimoto 블로그 (2026.02.05)
OpenAI "Harness engineering: leveraging Codex in an agent-first world" (2026.02.11)
컨텍스트 엔지니어링의 시작: Karpathy의 X/Twitter 발언 (2025 중반)
관련 패턴: Karpathy LLM Wiki Pattern, Garry Tan의 "Thin Harness, Fat Skills"