How Karpathy Solved the #1 AI Problem
A 65-line text file just became the most popular repo on GitHub. The reason it worked has very little to do with code.
In January, Andrej Karpathy (the guy who helped start OpenAI and ran AI at Tesla) wrote a short post on X about how his programming workflow had changed.
He admitted that over the previous two months he’d gone from writing about 80% of his code himself to letting an AI agent write about 80% of it. After two decades of programming a certain way, the whole thing had flipped.
But here’s the part that caught everyone’s attention. He wasn’t selling the magic. He was complaining.
The AI kept making the same kinds of mistakes. It would quietly assume things on his behalf and run with them. It would overcomplicate code that should’ve been simple. It would “improve” things he hadn’t asked it to touch. It wouldn’t push back when it should. It wouldn’t say “I’m confused” when it was.
You’ve probably felt this too, even if you’ve never written a line of code. You ask an AI for something, it gives you something almost right but subtly off, and you sit there wondering whether to correct it or just do it yourself.
That feeling, the almost, is the #1 problem with AI right now.
The day after Karpathy’s post, a developer named Forrest Chang took the complaint and turned it into a 65-line text file called CLAUDE.md. He dropped it on GitHub at github.com/forrestchang/andrej-karpathy-skills.
It now has over 57,000 stars. The combined ecosystem of mirrors and forks is past 220,000. It is the most popular file in the entire AI tooling world right now. More popular than agent frameworks built by full teams with millions in funding.
A small text file. Sixty-five lines.
The Four Rules
The file gives an AI coding agent four simple instructions:
Think before coding. Don’t assume. If something’s unclear, stop and ask. If there are two ways to read the request, name them both. Push back when you should.
Simplicity first. Write the minimum code that solves the problem. No extra features. No “flexibility” nobody asked for. If you wrote 200 lines and it could have been 50, rewrite it.
Surgical changes. Touch only what you have to. Don’t “improve” the code next door. Match the existing style even if you’d do it differently. Every line you change should trace back to what was asked.
Goal-driven execution. Define what success looks like before you start. “Add validation” becomes “write tests for invalid inputs, then make them pass.” Vague goals make vague work.
That is the whole file.
Now read those four rules again and tell me what’s actually in them. Because none of it is technical. There’s no clever trick. No prompt-engineering wizardry. If you replaced “code” with “report” or “design” or “email,” every rule would still work.
What Karpathy described is the difference between treating AI like a vending machine and treating it like a contractor.
Vending Machine vs. Contractor
When you put a coin in a vending machine, you expect a snack. You don’t tell it your dietary restrictions. You don’t explain the context of your day. You don’t define what good looks like. You push a button and hope.
Most people use AI exactly like that. They type a one-line request, get back something almost right, and conclude the technology is impressive but not quite there yet.
When you hire a contractor, a good one, you do the opposite. You explain the project. You say what you’re trying to accomplish. You tell them your constraints. You define what done looks like. You set expectations about how much initiative to take. Then they go do the work, and you get something good.
Karpathy’s file is, essentially, an onboarding document for a contractor.
It says: here is how I want you to behave, here is the kind of work I value, here is what I do and don’t want you to do on your own initiative. It works because that’s the conversation we should be having with AI to begin with.
The mistake almost everyone makes isn’t that they don’t know the right prompts. It’s that they don’t give AI enough context, and they don’t give it enough direction.
They say “write me a marketing email” instead of “write a marketing email to existing customers who haven’t logged in this month, in the same voice as the last three campaigns, with one specific offer and one specific call to action, and keep it under 150 words because longer ones underperform for us.”
They say “help me think through this decision” instead of “I’m weighing two job offers, here are the details of both, here’s what matters to me, play devil’s advocate against the option I’m leaning toward.”
They say “build this feature” instead of “build this feature, here’s the existing code style, don’t touch anything outside this file, here’s what success looks like before you start.”
The difference between those two modes isn’t talent. It isn’t access to better models. It’s whether you took five minutes to build the machine, to tell the AI what good looks like, what bad looks like, and how to operate inside your particular world.
This Should Sound Familiar
If you’ve been reading this newsletter for a while, those four rules of Karpathy’s should sound familiar.
Think before coding is clarity. State your assumptions, surface tradeoffs, don’t move until you understand the problem.
Simplicity first is focus. Solve the actual problem, not the imaginary one.
Surgical changes is shared ownership. Respect the system you’re working in. Don’t touch what you don’t have to touch.
Goal-driven execution is vision. Tie the work to a real outcome before you start. “Make it work” is not a goal.
And the rule running underneath all of them, don’t hide your confusion, push back, ask the question, is courage.
Those five words are the Product Driven Model. Vision, focus, clarity, shared ownership, courage. It’s the framework I built from twenty years of running engineering teams, and the spine of the book I wrote about it.
The world’s most famous AI researcher just wrote a viral text file telling Claude Code to behave like a Product Driven engineer.
I’m not saying that to take a victory lap. I’m saying it because it should tell you something about the actual problem.
AI Didn’t Cause the Cracks. It Just Made Them Easier to See.
That line is from the introduction of my book, written months before Karpathy’s post. I keep coming back to it because every story like this one proves it again.
The teams that built clarity into how they work were already shipping better software. They were already asking why before how. They were already defining outcomes before tickets. They were already doing surgical work instead of sprawling rewrites.
Now those same behaviors are the difference between an AI that ships great code and an AI that ships fast, confident garbage.
And the teams that don’t build those behaviors in get the same thing they were already getting. Just faster.
Vague requirements still produce vague work. Now they produce 200 lines of it in three seconds.
A team that doesn’t ask why still doesn’t ask why. Now it doesn’t ask why with five agents running in parallel.
A culture that punishes pushback still punishes pushback. Now the AI doesn’t push back either, and nobody notices until production breaks.
AI is a force multiplier. It multiplies whatever culture you already have.
Build the Machine
Take ten minutes this week and write down what you want your AI tools to always do. Your version of Karpathy’s file. It doesn’t matter if you’re a developer, a marketer, a CEO, or a founder writing the first version of a business plan.
What’s the vision behind the work? What does focus look like, what are you not doing? Where do people lack clarity right now? Where does your team stay quiet when they should be pushing back?
Save it as a single document. Paste it into new chats, or use it as the system prompt in the tools that allow one. Update it as you notice patterns of frustration.
Then take a second pass and ask the bigger question: if I’m willing to write this down for the AI, why am I not writing it down for the humans?
Because the humans need it more. The AI will read your file and follow it. The team needs the file, the leader who lives it, and the courage to say something when it’s missing.
The most viral file on GitHub right now is not a piece of software. It’s a one-page instruction sheet. The reason it went viral is because everyone who reads it has the same reaction: oh, I should have been doing this the whole time.
The AI was capable all along. We were just forgetting to tell it what we wanted.
Kudos to Karpathy
This is exactly what we coach our team members at Full Scale to do every day. State the assumption. Ask the question. Push back when something doesn’t make sense. Define what good looks like before you start. Stay surgical. Tie the work to the outcome.
It’s how we hire, it’s how we onboard, and it’s how the engineers our clients love most actually behave on a real product team.
Kudos to Karpathy for pointing out, in 65 short lines, why this matters so much. The way you program an AI to think is the same way you build a team that thinks. He just made it obvious to a much bigger audience than I could have on my own.
If you want the full playbook for building this into your team, Product Driven is available as a free digital copy or audiobook at fullscale.io/product-driven.
And if you need affordable, senior software developers who already think this way, that’s literally what we do. Take a look at what we’re building at fullscale.io.
Karpathy figured out you can’t get great output from a smart system without telling it what good looks like.
Engineering leaders have been figuring that out for a lot longer.
The ones who already did are the ones winning right now. ✌️