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 편집자가 검토했어요. 칼럼은 어떻게 만드나요
andrej-karpathy-skills: a CLAUDE.md from Karpathy's notes
One bug fix used to come back as a 40-line diff. After adding this file, one developer says the diff is clean.
- Who
- Made by forrestchang, now under the multica-ai organisation. For anyone who hands code work to Claude Code or Cursor.
- When
- Published 27 January 2026, the day after Karpathy's post on X. No release tags; last change 20 April 2026 (Cursor support).
- Where
- Claude Code (as a plugin or a project CLAUDE.md) and Cursor (a .cursor/rules file). Plain local files, no server.
What was hard
Hand an agent one small feature and it quietly picks one reading of the request and runs with it. It builds a 1,000-line structure where 100 lines would do, and rewrites comments and code that had nothing to do with the task, so you end up reviewing the diff line by line. That is exactly what Karpathy complained about on X.
What it does about it
It turns Karpathy's observations into four principles in one CLAUDE.md that the agent reads on every task. The agent states its assumptions and asks when something is unclear, adds no features or abstractions nobody asked for, and keeps every changed line tied to the request. The last principle carries the main idea: instead of telling the model what to do, give it success criteria it can check, such as a test, and it will loop until it meets them.
What people made with it
After a few weeks with the plugin, Surgical Changes helped most; Simplicity First needed working around in code that truly needs abstractions.
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.
With a fifth rule (Claude interviews you, decisions go into SPECIFICATIONS.md) they built an XPBD simulator in JAX; Claude's question led to a Jacobi solver.
I know nothing about physics engines, I built a working rigid body simulator in JAX with Claude.
How it runs inside
- 1
You → marketplace.json
/plugin marketplace addThe README's first command registers this repository as a marketplace named karpathy-skills..claude-plugin/marketplace.json - 2
marketplace.json → karpathy-guidelines
/plugin install → ./skills/karpathy-guidelinesplugin.json's skills entry points at this folder, which installs as a skill for every project..claude-plugin/plugin.json - 3
karpathy-guidelines → Claude Code
Use when writing, reviewing, or refactoring codeThe skill's description tells Claude Code to load the four principles when it writes, reviews or refactors code.skills/karpathy-guidelines/SKILL.md - 4
CLAUDE.md → Claude Code
CLAUDE.md at the project rootWithout the plugin, the file fetched with curl is read by Claude Code as that project's instructions.CLAUDE.md - 5
Claude Code → Questions and a small diff
State assumptions → minimal edit → verifyIt asks when unclear, touches only the requested lines, and loops on a 'step → verify: check' plan until it passes.CLAUDE.md
What goes in, what comes out
Is it for you
Good for
- Your Claude Code diffs keep growing with refactors and reformatting you never asked for
- You hand over vague tasks and want the interpretation confirmed before any code
- Your team needs a shared base for its CLAUDE.md to add project rules on top of
- You work in both Claude Code and Cursor and want the same rules in each
Not for
- Per the README it leans toward caution over speed; for trivial fixes it says to use judgment.
- Project-specific rules (language, tests, error handling) are yours to add.
- Cursor does not read .claude-plugin or CLAUDE.md, so it needs .cursor/rules/karpathy-guidelines.mdc copied in.
Reviewed by Devalley’s editor before publishing. How the column is made