andrej-karpathy-skills: 카파시의 관찰로 만든 CLAUDE.md 한 장
버그 하나 고쳐 달랬다가 40줄 diff를 받던 개발자가, 이 파일을 넣고 「이제 diff가 깨끗하다」고 썼어요
- 누가
- forrestchang이 만든 저장소로, 지금은 multica-ai 조직 아래 있어요. Claude Code나 Cursor로 코드를 맡기는 사람을 위한 규칙이에요.
- 언제
- 2026년 1월 27일 공개, 카파시의 X 글 다음 날이에요. 릴리스 태그는 없고 마지막 변경은 2026년 4월 20일(Cursor 지원)이에요.
- 어디서
- Claude Code(플러그인 또는 프로젝트의 CLAUDE.md)와 Cursor(.cursor/rules 규칙 파일). 서버 없이 내 PC의 파일로만 돌아요.
이게 불편했어요
에이전트에게 작은 기능 하나를 맡기면, 묻지 않고 한쪽 해석을 골라 그대로 달려가요. 100줄이면 될 걸 1000줄짜리 구조로 짓고, 작업과 상관없는 주석이나 코드까지 바꿔 놓아서 diff를 한 줄씩 다시 읽어야 했어요. 카파시가 X에 적은 불만도 바로 이 장면이었어요.
그래서 이렇게 풀어요
카파시의 관찰을 네 원칙으로 옮겨 CLAUDE.md 한 장에 적고, 에이전트가 작업마다 읽게 해요. 코드를 쓰기 전에 가정을 말하고 모호하면 묻게 하고, 요청하지 않은 기능과 추상화를 막고, 바뀐 줄마다 요청과 이어지게 해요. 핵심은 마지막 원칙이에요. 「무엇을 하라」 대신 테스트처럼 확인할 수 있는 성공 기준을 주면, 모델이 그 기준을 넘을 때까지 스스로 반복한다는 거예요.

이걸로 만든 사람들
몇 주 동안 플러그인으로 써 본 개발자가, 네 원칙 중 Surgical Changes가 가장 크게 바꿨다고 썼어요. 다만 추상화가 정말 필요한 코드베이스에서는 Simplicity First를 몇 번 우회해야 했다고 해요.
Before, I’d ask for a bug fix and get a 40-line diff with type hints, reformatted quotes, and renamed variables mixed in with the actual fix. Now the diff is clean.
이 CLAUDE.md에 「Claude가 먼저 인터뷰하고 결정을 SPECIFICATIONS.md에 적는다」는 다섯 번째 규칙을 더해, JAX로 XPBD 강체 시뮬레이터를 만들었어요. 정밀도와 속도 중 무엇이 필요하냐는 Claude의 질문 덕에 Jacobi 솔버를 고르게 됐다고 해요.
I know nothing about physics engines, I built a working rigid body simulator in JAX with Claude.
안에서는 이렇게 돌아가요
- 1
나 → marketplace.json
/plugin marketplace addREADME의 첫 명령이 이 저장소를 karpathy-skills라는 마켓플레이스로 등록해요..claude-plugin/marketplace.json - 2
marketplace.json → karpathy-guidelines
/plugin install → ./skills/karpathy-guidelinesplugin.json의 skills 항목이 가리키는 폴더가 스킬로 깔려, 모든 프로젝트에서 쓸 수 있어요..claude-plugin/plugin.json - 3
karpathy-guidelines → Claude Code
Use when writing, reviewing, or refactoring code스킬 설명이 코드를 쓰거나 리뷰·리팩터링할 때 쓰라고 적혀 있어, 그런 작업에서 네 원칙이 불려 와요.skills/karpathy-guidelines/SKILL.md - 4
CLAUDE.md → Claude Code
프로젝트 루트의 CLAUDE.md플러그인 대신 curl로 받은 파일은 그 프로젝트에서 Claude Code가 지침으로 읽어요.CLAUDE.md - 5
Claude Code → 질문과 작은 diff
가정 말하기 → 필요한 줄만 → verify모호하면 먼저 묻고, 요청한 줄만 고치고, 「단계 → verify: 확인」 계획대로 통과할 때까지 반복해요.CLAUDE.md
넣으면 이렇게 나와요
나한테 맞을까요
이럴 때 좋아요
- Claude Code가 부탁하지 않은 리팩터링이나 포맷 변경을 섞어 diff가 커질 때
- 요구가 모호한 작업을 맡기면서, 만들기 전에 해석을 확인받고 싶을 때
- 팀의 CLAUDE.md에 프로젝트 규칙을 얹을 공통 바탕이 필요할 때
- Claude Code와 Cursor에서 같은 규칙으로 일하고 싶을 때
이건 안 돼요
- README 기준 속도보다 신중함 쪽으로 기울어 있어요. 오타 수정 같은 간단한 일은 판단해서 쓰라고 적혀 있어요.
- 프로젝트마다 다른 규칙(언어, 테스트, 오류 처리 방식)은 직접 덧붙여야 해요.
- Cursor는 .claude-plugin이나 CLAUDE.md를 읽지 않아서, .cursor/rules/karpathy-guidelines.mdc를 따로 복사해야 해요.
발행 전에 Devalley 편집자가 검토했어요. 칼럼은 어떻게 만드나요