Andrej Karpathy, co-founder of OpenAI and former head of AI at Tesla, made a viral tweet listing the top mistakes that AI coding agents make. A developer called Forrest Chang turned those observations into a single CLAUDE.md file. In under a week, over 43,000 developers installed it. That is not hype. That is a real signal that most people are hitting the same walls when working with AI agents.
I use Claude Code every day to build client systems. I have run into every problem Karpathy describes: the agent assumes what you want instead of asking, overbuilds simple features, touches code it should not touch, and loops endlessly instead of working toward a clear goal. This file addresses all four. Here is what it does, how to install it, and why the bigger idea behind it (the LLM Wiki) might matter even more.
The backstory: Karpathy's viral tweet
The whole thing started with a detailed tweet from Karpathy analysing how AI agents fail. It was not vague. He listed specific failure patterns: models making wrong assumptions without checking, not managing their own confusion, not seeking clarifications, not surfacing inconsistencies, defaulting to bloated implementations, changing code they do not understand, and failing to define what "done" looks like.
The tweet gathered nearly 8 million views. Then Forrest Chang took those observations and distilled them into a CLAUDE.md file that you drop into any Claude Code project. The repo, andrej-karpathy-skills, crossed 43,000 GitHub stars in its first week. Credit goes entirely to Forrest for packaging this so cleanly.
The four principles
The file boils down to four rules. Each one targets a specific category of failure that Karpathy identified. These principles are worth learning regardless of whether you install the file, because they apply to any AI agent you work with.
1. Think before coding
Karpathy's most common failure category: the model makes wrong assumptions on your behalf and runs with them without checking. It does not manage its confusion, does not seek clarification, and does not surface inconsistencies.
Without this rule, Claude assumes what you want. With it, Claude asks first.
This sounds obvious, but in practice the difference is dramatic. In a side-by-side comparison (shown in the video below), a vanilla Claude Code session was asked to add a light mode toggle to a rubric app. It confirmed the toggle was added, but the feature was not actually working. The Karpathy-configured Claude Code session completed the same task in a single prompt, with correct colours across all UI elements, because it thought through the problem before touching code.
The core idea: it is almost always better to have your agent ask clarifying questions before it starts building. One good question up front saves five rounds of revision later.
2. Simplicity first
Karpathy observed that AI agents default to implementing "inefficient, bloated, and brittle constructions," sometimes over a thousand lines of code. Only when you challenge them do they realise the same thing can be done in 100 lines or fewer.
Without this rule, Claude overbuilds. With it, Claude writes the minimum.
The reason is structural. These models are trained on production codebases, so they default to production-scale patterns. When you ask for a simple feature, they apply enterprise architecture to a weekend project. The CLAUDE.md file constrains this by prioritising the simplest viable implementation.
In the same comparison, both agents were asked to add a search bar that filters a tab list. The Karpathy session added 20 lines of code that worked correctly. The vanilla session added over 50% more code and the feature did not function.
3. Surgical changes
Karpathy flagged that agents "still sometimes change or remove comments in code that they don't like or don't sufficiently understand, even if it is orthogonal to the task at hand."
Without this rule, Claude "improves" things you did not ask for. With it, Claude changes only what you requested.
This is one of the sneakiest failure modes. The agent writes extra code, refactors surrounding functions, reorganises imports, reformats files. It looks helpful, but it is productivity for productivity's sake. If the job takes two lines, two lines is the right answer.
When asked to swap a font from Outfit to Inter, the Karpathy session found every instance and replaced it, touching nothing else: no reformatting, no reorganising Google Fonts URLs. The vanilla session broke something during the process and spent additional tokens debugging its own mistake.
4. Goal-driven execution
Karpathy's key insight here: "LLMs are exceptionally good at looping until they meet specific goals." Instead of telling the agent what to do (imperative), define what done looks like (declarative) and let it find the path.
Without this rule, you command every step. With it, you set the goal and Claude explores the best approach.
The shift from imperative to declarative prompting is significant. When the Karpathy session was given the goal "let the user select an icon for each agent" with no specification of where icons should live or how many options to provide, it figured out the UI placement, designed the icon picker, and implemented it cleanly on the first attempt.
How to install it
Two options:
- Fresh install: Give Claude Code the GitHub repo link: github.com/forrestchang/andrej-karpathy-skills
- Download directly: Get the skill from skills.sh
If you already have a CLAUDE.md file (and you should), do not replace it. Instead, give Claude Code a prompt explaining that you are providing a set of guidelines called "Karpathy Skills" and ask it to suggest how to integrate them into your existing setup. This way, you keep your project-specific configuration and layer the Karpathy principles on top.
The LLM Wiki: Karpathy's bigger idea
The skills file is tactical. Karpathy's broader idea is strategic, and it changes how you think about AI and documents entirely.
Right now, most AI workflows rely on RAG (Retrieval Augmented Generation). You upload documents, ask a question, and the AI searches through your files, grabs relevant chunks, and generates an answer. It works for simple questions, but every question starts from zero. There is no memory, no accumulation. Nothing compounds.
Karpathy's LLM Wiki flips this. Instead of searching raw documents every time, you have the AI read your documents once and build a structured wiki out of them: a persistent knowledge base made of interlinked Markdown files. When you add a new source, the AI reads it, extracts key ideas, integrates them into the wiki, updates existing pages, creates new pages for new concepts, links related ideas, and flags contradictions. Over time, the wiki keeps growing and getting richer. The connections are already built. The synthesis is already done.
Karpathy describes it like this: "Think of Obsidian as the IDE, the LLM as the programmer, and the wiki as the codebase. You rarely write the wiki yourself. The AI does the writing and organising. You focus on what goes in and what questions to ask."
The three layers of the LLM Wiki
The system has three layers:
Layer 1: Raw sources. Your original documents: PDFs, articles, meeting notes, whatever you are working with. These are read-only. The AI reads them but never changes them. This is your source of truth.
Layer 2: The wiki. A folder of Markdown files that the AI creates and maintains. It contains an index page, concept pages, entity pages, summaries, and comparisons. All interlinked, all maintained by the AI.
Layer 3: The schema. A rules document that tells the AI how to structure the wiki, how to handle new sources, and how to format everything. If you are using Claude Code, this is your CLAUDE.md file.
The schema covers five things: the purpose of the wiki, the folder structure, the ingest workflow (what happens when you add a new source), page formatting rules (summaries, source citations, cross-links), and question-answering behaviour (consult the wiki first, cite sources, flag uncertainty).
Jamie from Teachers Tech published a starter schema template that you can download and customise: LLM Wiki CLAUDE.md Template. The only line you need to change is the purpose statement. Everything else works as-is.
What it looks like in practice
The practical setup is simpler than it sounds. You need Obsidian (free, works with plain Markdown files) and a coding agent like Claude Code. Create three folders: raw/ (for source documents), wiki/ (where the AI builds pages), and templates/ (optional). Drop the schema CLAUDE.md file in the root.
Then you simply tell Claude Code: "I just added a new source to the raw folder. Please read it and update the wiki." The AI reads the document, creates structured wiki pages, builds links between concepts, and updates the index. Add a second source and it does not just create new pages, it updates existing ones with the new information. Ask a question that requires connecting ideas across multiple sources and the AI pulls from the wiki, not the raw files. The synthesis is already done.
Karpathy also introduced the idea of "linting" your wiki. Just like a code linter checks for problems, you can periodically ask the AI to audit the whole wiki. It will find contradictions between pages, claims that might be outdated, orphan pages with no links, and concepts mentioned but lacking their own page.
Here is a full walkthrough of building an LLM Wiki from scratch:
What this means for your AI setup
Both ideas, the skills file and the LLM Wiki, point in the same direction: the quality of your AI output depends less on the model and more on the instructions you give it. A CLAUDE.md file is not configuration. It is architecture. It defines how your agent thinks, what it prioritises, and where it stops.
For anyone using Claude Code regularly, the Karpathy skills file is worth trying. It is a single file, it is free, and the downside is zero. For anyone accumulating knowledge over time (research, client work, project documentation), the LLM Wiki pattern is genuinely one of the most practical AI workflows available right now. Your data stays on your computer in plain text files that you own.
I use a similar pattern in the systems I build for clients. Every AI system I deliver includes a structured CLAUDE.md that encodes project context, voice rules, and operational constraints, because the alternative is an agent that guesses. And guessing at scale is expensive.
If you want a system that is configured this way from the start, with the right instructions baked into the architecture, the AI Automation Systems service is built around exactly this approach. And if you want to learn how to set up Claude Code properly for your own workflow, the AI Training sessions cover CLAUDE.md configuration as part of the curriculum.
Sources and credits:
- andrej-karpathy-skills repo by Forrest Chang
- Download the skill on skills.sh
- LLM Wiki CLAUDE.md Template by Teachers Tech
- What is Andrej Karpathy's CLAUDE.md File? (The AI Studio, Medium)
- Andrej Karpathy's LLM Wiki Knowledge Base (MindStudio)