karpathy-ideas
AGENTS.md1 starsChanged yesterdayMITView on GitHub
Instructions for AI agents that read or maintain this repository. Humans: see README.md. An unofficial, curated collection of Andrej Karpathy's public ideas about working with LLMs and AI agents. Each idea is one markdown file in ideas/. Each file has a date, a link to the original source, a summary in our own words, at most one short quote, and practical "Apply" steps. Not affiliated with or endorsed by Andrej Karpathy. Reviewing a whole project? Use checklist.md, not the themes:…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- llms-full.txtllms.txt
- llms.txtllms.txt
- karpathy-ideasSkill
The file
We split this AGENTS.md into the rules it gives an agent
11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 17
Read only the 2-3 theme pages in themes/ that match your task (one line per idea).
- Distinctive: line 20
If you can delegate, let a smaller, cheaper model or subagent do steps 1-2 and return a shortlist of idea links with one line each on why …
- Very specific: line 24
Prefer ideas with status: current.
- Distinctive: line 28
Do not reproduce more of his words than the quote in the file.
- Very specific: line 113
When every Apply step does, drop the per-step labels and put one line right under ## Apply: "Our reading: all steps below go further than …
- Very specific: line 132
Add or edit files in ideas/.
- Very specific: line 133
Run node scripts/build.mjs to regenerate index.md, themes/, llms.txt, llms-full.txt.
- Distinctive: line 134
Never edit those generated files by hand.
- Very specific: line 135
Run node scripts/validate.mjs and npx markdownlint-cli2 "/*.md".
- Very specific: line 137
Add an entry to log.md for each sweep: date, period covered, ideas added and changed.
- Distinctive: line 138
Commit with Conventional Commits (below).
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Instructions for AI agents that read or maintain this repository. Humans: see README.md.
What this repository is
An unofficial, curated collection of Andrej Karpathy's public ideas about working with LLMs and
AI agents. Each idea is one markdown file in ideas/. Each file has a date, a link to the
original source, a summary in our own words, at most one short quote, and practical "Apply"
steps. Not affiliated with or endorsed by Andrej Karpathy.
Reading the collection (for agents that use it)
Reviewing a whole project? Use checklist.md, not the themes: measure each question first,
then open only the linked ideas that point to a gap. For one task, use the steps below.
- Read only the 2-3 theme pages in
themes/that match your task (one line per idea). Readindex.md(every idea, larger) only if you need the whole collection. - Open only the idea files that match your task. If you can delegate, let a smaller, cheaper model or subagent do steps 1-2 and return a shortlist of idea links with one line each on why they fit; the main model reads only those.
- Each idea has a
kind:practice(a way of working you can apply) orview(his opinion or explanation; context, not steps). Theme pages list practices first. For a task, read practices. - Prefer ideas with
status: current. Asupersededidea links to the newer view insuperseded_by; he changed his mind, usually because models improved. - Ideas with
anthropic: trueare dated after he joined Anthropic (2026-05-19) and concern Claude or Anthropic. Weigh them with that in mind. - Do not reproduce more of his words than the quote in the file. Link to the source instead.
llms-full.txtholds every idea in one file, for tools that cannot browse.
Idea file format
File name: ideas/YYYY-MM-DD-short-slug.md (date of the source, lowercase slug, hyphens).
---
title: Give agents success criteria, not steps
date: 2026-01-26
source: x
url: https://x.com/karpathy/status/2015883857489522876
also: []
themes: [agentic-coding, verification]
summary: Agents loop well toward a checkable goal; describe the goal and the test, not the steps.
status: current
superseded_by:
anthropic: false
kind: practice
---
# Give agents success criteria, not steps
Summary in our own words, 40 to 150 words.
## In his words
> "Don't tell it what to do, give it success criteria and watch it go."
> — Andrej Karpathy, 2026-01-26
## Apply
- Concrete step, prompt or setting a reader can use today.
## Context
- When and why he said it, model era, and links to related ideas: [title](2026-03-07-slug.md).Field rules:
source: one ofx,blog,github,talk,hn.url: the primary source,https://.also: other URLs that carry the same idea, as an inline list[url1, url2]or[].themes: one to three slugs from the list below. Do not invent new themes; propose one in an issue instead.summary: one sentence, at most 160 characters. It appears inindex.md.status:currentorsuperseded. Whensuperseded,superseded_byis the file name of the newer idea (without folder), and the newer idea's Context links back.anthropic:trueonly when the date is 2026-05-19 or later and the idea concerns Claude, Anthropic or its products.kind:practicewhen a reader can change how they work because of it (a technique, workflow, prompt pattern, design rule);viewwhen it is mainly an opinion, prediction or explanation. A practice needs an "Apply" section; a view has one only when its steps are concrete, never as filler.- Quote: at most one per file, at most 15 words, in the "In his words" section, exact text, attributed and dated. The section is optional.
Themes
| Slug | Covers |
agentic-coding | coding with agents, workflows, IDEs, review, vibe coding vs agentic engineering |
verification | success criteria, tests, verifiability, eval loops, autoresearch |
context-and-prompting | context engineering, prompting, stating scope, giving intent |
output-and-reading | output formats, simplified English, HTML, diagrams, reading with LLMs |
knowledge-management | personal wikis, notes, compiling knowledge with LLMs |
agent-native-software | Software 3.0, LLM OS, CLIs and docs for agents, products |
llm-psychology | jagged intelligence, ghosts vs animals, sycophancy, how to model LLMs |
security-and-dependencies | supply chain, sandboxing, dependency hygiene |
learning-and-education | learning with LLMs, teaching, skill atrophy |
research-and-training | training, RL, tokenizers, small models, research practice |
ai-progress | views on the field, timelines, society, jobs |
Keep Karpathy's ideas and our procedure apart
- Guide, don't impose: the checklist leads a model through his ideas (his idea with the link, what it looks like in a project, questions to ask, the trade-offs his ideas name), labels anything of ours "Our reading" with its evidence, and leaves every choice to the project's owner.
- Idea files and each checklist item's "His idea", "In a project", "Ask" and "Trade-off / when not" parts contain only what traces to Karpathy's sources (an idea's summary, Apply steps or Context), except parts marked "Our reading" or "our addition". Every item links its ideas.
corrections.mdlists errors in what we told projects to do, with how to recognise and repair them; a revisit reads it first. Add an entry whenever a published instruction proves wrong.- Apply steps are our translation of his idea into practice (README, llms.txt and llms-full.txt
say so). A step marked "Our reading" or "our addition" goes further than the idea itself.
When every Apply step does, drop the per-step labels and put one line right under
## Apply: "Our reading: all steps below go further than the idea itself." Files with mixed steps keep the per-step labels. Each step must follow from that idea; a practice of ours that does not follow from it goes in a procedure section, not in an idea file. - Our own practices (how to run the checklist, record files, report formats) go only in clearly labelled procedure sections, such as "How to run this checklist" and the README steps. Never present them as his ideas.
Writing style
- Plain English, close to ASD-STE100: short sentences, one idea per sentence, active voice, common words, no hype. About 80% strict, so it stays readable.
- Our own words. Never copy his sentences except the one quote.
- Facts only from the source. If you infer, say "Our reading:".
- "Apply" is the most useful part: concrete actions, prompts or settings, not advice to "consider".
Maintaining the collection
- Add or edit files in
ideas/. - Run
node scripts/build.mjsto regenerateindex.md,themes/,llms.txt,llms-full.txt. Never edit those generated files by hand. - Run
node scripts/validate.mjsandnpx markdownlint-cli2 "**/*.md". Both must pass before you commit. - Add an entry to
log.mdfor each sweep: date, period covered, ideas added and changed. - Commit with Conventional Commits (below). One logical change per commit.
Commit messages
Format: <type>(<scope>): <description> — imperative, lowercase after the colon, no final period,
subject at most 72 characters. Blank line, then a body that explains what and why, wrapped at 72.
Types: content (ideas, themes, index), docs (README and other docs), feat (new skill or
script), fix (wrong date, link, attribution, script bug), refactor, ci, chore, revert.
Scopes (optional): idea, theme, index, log, skill, llms, ci, repo.
content(idea): add autoresearch overnight loop
Summarises the 2026-03-07 post in our own words with one short quote
and three Apply steps.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>Commits made with an AI assistant keep the Co-Authored-By trailer. A human reviews every claim.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

