This repository is a CLAUDE.md — a single file of behavioural guidelines for a coding agent, derived from Andrej Karpathy’s public observations about where LLMs go wrong when writing code. It is MIT licensed.
The diagnosis it starts from is the useful part. The README quotes Karpathy’s complaint directly: “The models make wrong assumptions on your behalf and just run along with them without checking.” Anyone who has watched an agent confidently build the wrong thing for twenty minutes recognises that sentence.
The four rules
The file encodes four principles, and they are narrow enough to actually change behaviour:
Think before coding. State assumptions, surface multiple interpretations, ask when something is unclear. The README compresses it to: “Don’t assume. Don’t hide confusion. Surface tradeoffs.”
Simplicity first. Write the minimum code that solves the problem — no speculative features, no abstractions invented for a single call site.
Surgical changes. Edit only what the request requires, match the existing style, and mention unrelated dead code rather than deleting it. That last clause is the one that saves review time: an agent that tidies while it works produces diffs nobody can read.
Goal-driven execution. Turn the task into verifiable success criteria — writing a failing test first, for instance. The README’s reasoning is worth keeping: “Strong success criteria let the LLM loop independently.”
Read together, three of the four are about restraint and one is about verification. That is a coherent position, and it is the opposite of how agents behave by default.
Installing it
The plugin route:
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skillsPer project, you can simply download CLAUDE.md into a new project with curl, or append it to one you already have. The repository also ships CURSOR.md and a committed .cursor/rules project rule for Cursor users, an EXAMPLES.md, a Chinese translation, and a skills/karpathy-guidelines folder.
The README is explicit that the guidelines are meant to be merged with your project-specific instructions rather than replacing them — which is the right expectation for a file that says nothing about your stack, your conventions or your test runner.
What it does not claim
This is where the project earns some trust. The README states that the guidelines “bias toward caution over speed,” and that for trivial tasks you should “use judgment” — an admission that always-on caution has a cost. The goal is narrower than it might first appear: reducing expensive mistakes on non-trivial work.
The evidence offered is qualitative. The README points to outcomes like “Fewer unnecessary changes in diffs” and includes no measured results — no benchmark, no before-and-after on a task set. For a file of behavioural instructions that is not unreasonable, since the effect is hard to quantify, but it means adoption is a judgement call rather than a decision you can justify with numbers.
Worth noting too that the README promotes the author’s own separate project, which is normal but useful context when reading a recommendation.
The honest assessment
The value here is not technical sophistication — it is a CLAUDE.md file, and you could write one yourself in an afternoon. The value is that someone distilled a widely-shared frustration into four rules that are specific enough to act on, and short enough that a model will actually follow them.
Two things make it genuinely worth copying rather than admiring. First, “mention unrelated dead code rather than deleting it” is the kind of concrete constraint that most hand-written instruction files miss. Second, the emphasis on verifiable success criteria addresses the real failure mode: an agent that cannot tell whether it is done will either stop too early or keep going.
Take it as a starting point for your own file rather than a drop-in. Merge the four principles into whatever instructions your project already has, drop the parts that fight your workflow, and treat the caution bias as something to tune rather than accept wholesale.
