Karpathy's Spec-Driven Method: A Better Way to Code With Claude
Andrej Karpathy's three-layer method (spec, verifier, environment) reframes how to work with Claude on coding projects. Here's how it works.
What is Andrej Karpathy’s spec-driven method for AI coding?
Andrej Karpathy’s method is a three-layer approach to working with AI coding models like Claude: write a detailed spec before any code gets written, build a verifier that checks whether the output is actually correct, and set up a persistent environment that carries your instructions, rules, and context across every session. Instead of treating each prompt as a one-off request, you treat the whole project as a system that gets smarter and more reliable the more you use it.
TL;DR
- The method has three layers: spec, verifier, and environment, each solving a different failure mode of typical AI coding sessions.
- A spec means having Claude interview you about your actual goal before touching any code, then breaking the work into checkpoints.
- A verifier is a way for Claude to check its own output, using another model, real data, or tests it can run itself, rather than you eyeballing the result.
- An environment is a standing workspace with your instructions, rules, skills, and knowledge already loaded, so you’re not re-explaining context every session.
- The bigger shift is from improving your prompts to building a system around the model that compounds in usefulness over time.
- This approach applies beyond software: it maps onto AI video editing and agent workflows just as well as writing code.
Why doesn’t just “prompting better” work?
Most people treat an AI coding session like a search query: type a request, get an answer, adjust if it’s wrong. That works for small, self-contained asks. It breaks down on anything with real scope, because the model is guessing at intent from a single message and has no way to check its own work against a standard you actually care about.
Karpathy’s framing treats this as a systems problem, not a prompting problem. The failure isn’t that Claude misunderstood one sentence. It’s that there was never a shared, explicit definition of “done” in the first place, and no mechanism for Claude to catch its own mistakes before handing them back to you. The three layers each target one part of that gap.
How does the spec layer work?
The spec layer replaces “give a task and hope” with a conversation. Instead of writing a single prompt and letting the model run, you have Claude interview you first: what are you actually trying to build, what constraints matter, what does success look like. That interview produces a written spec, a document both of you can refer back to.
From there, the work gets broken into smaller checkpoints rather than one big attempt. This matters for two reasons. First, smaller checkpoints are easier to verify individually, so errors get caught early instead of compounding through a long, unsupervised run. Second, a checkpoint structure gives you natural places to redirect the model if it’s drifting off course, without having to scrap everything and start over.
In practice, this looks like asking Claude to draft a plan or spec document before writing any code, reviewing that plan yourself, and only then letting it proceed step by step.
How does the verifier layer work?
The verifier layer is about giving Claude a way to check its own output rather than relying entirely on your manual review. Before any work starts, you define what a good result actually looks like in concrete terms. Then you give the model a mechanism to test its own output against that definition.
That mechanism can take different forms depending on the project: another AI model reviewing the output, real data the result can be checked against, or tests the model can run on its own and iterate against. The common thread is that verification happens without you as the only bottleneck. Claude can catch its own mistakes and correct them before you ever see a broken result, which cuts down the back-and-forth cycle of “here’s what’s wrong, try again.”
This is arguably the layer most people skip. It’s easy to write a spec. It’s harder to build an actual feedback loop that doesn’t depend on a human reading every output line by line.
How does the environment layer work?
The environment layer is what makes the first two layers durable instead of a one-time effort. Rather than re-explaining your rules, your project context, and your preferences every time you open a new chat, you build a workspace where all of that is already present: instructions, documented knowledge, reusable skills, and standing rules the model should follow.
This is the layer that turns individual sessions into a compounding system. Every project you build inside that environment inherits the same context, so you’re not starting from zero each time. Over time the environment itself becomes an asset, arguably more valuable than any single conversation with the model, because it encodes everything you’ve already taught it.
A concrete version of this: setting up a dedicated project folder, pulling in a shared repository of reusable configurations or “skills,” and having the model install dependencies and load in relevant context automatically at the start of a new project, rather than you manually restating requirements each time.
Is this method only for writing code?
No. The underlying logic (spec first, build in a verification loop, persist context in an environment) applies to any repeated AI workflow, not just software. The same three layers show up in AI-driven video editing workflows, where a model is given editing “skills,” a consistent project structure, and rules about pacing, framing, and content style so it can produce consistent output across many videos without being re-briefed from scratch each time. The same idea applies to running AI agents for business tasks like content creation or lead follow-up: define what good output looks like, give the agent a way to check itself, and keep the context and rules persistent rather than rebuilding them every session.
The common thread across all these applications is that the model performs better when it operates inside a structured system, not when it’s just responding to isolated prompts.
Is the spec-driven method worth adopting?
It’s worth it for anything beyond a quick one-off task. If you’re asking Claude to fix a single line or answer a simple question, the overhead of writing a spec and building a verifier is not worth it. But for any project with real scope, multiple steps, or work you’ll repeat across sessions, the upfront cost of defining a spec and setting up verification pays off by catching errors early and reducing how often you have to manually inspect and correct output.
The environment layer is the part with the highest long-term payoff. Once it’s built, every new project benefits from it, and the effort of setting it up once amortizes across everything you build afterward. The tradeoff is setup time versus per-session friction: more time invested upfront, less wasted time re-explaining context and cleaning up misfires later.
Frequently Asked Questions
What are the three layers of Karpathy’s method?
Spec, verifier, and environment. The spec defines what you’re actually trying to achieve and breaks it into checkpoints. The verifier gives the model a way to check its own output against a clear standard. The environment persists your instructions, rules, and context across sessions so you’re not restating them every time.
How is this different from just writing better prompts?
Prompting focuses on getting one interaction right. This method focuses on building a system around the model, spec, verification loop, and persistent context, so results improve consistently across many sessions instead of depending on how well you phrase a single request.
Does the verifier have to be another AI model?
Other agents start typing. Remy starts asking.
Scoping, trade-offs, edge cases — the real work. Before a line of code.
No. A verifier can be another AI model reviewing the output, but it can also be real data the result gets checked against, or automated tests the model runs on its own. The key requirement is that the model has some way to check its work without you being the only reviewer.
Can this method be used for non-coding AI work?
Yes. The same structure (define the goal clearly, build in a way to verify output, keep context persistent) applies to workflows like AI-assisted video editing or running AI agents for business tasks, not just software development.
What’s the biggest mistake people make when trying this?
Skipping the verifier. Writing a spec is straightforward, but many people still rely on manually reviewing every output rather than building an actual feedback loop the model can use to catch its own errors before handing work back.
