Specification Is the New Literacy
When a first implementation takes minutes, the bottleneck is knowing what to build
Revised September 2026. The March version argued that agent-written code is opaque and that behavioral tests replace code review. I no longer think that, and my own practice never matched it. That section is rewritten below, along with a few claims that went further than the evidence.
Something has shifted.
For most of the history of software, the bottleneck was production. You had an idea, you knew what you wanted, and the hard part was making the computer do it. Writing the code, debugging the code, shipping the code. The scarce resource was engineering labor. The expensive skill was implementation.
That constraint is loosening. AI agents can write code fast, write a lot of it, and, increasingly, write it correctly. A first implementation that used to take weeks can take minutes. The rest of the cost hasn’t moved much: integrating the code, evaluating it, running it, and maintaining it cost about what they always did.
The bottleneck has moved. The scarce resource is no longer “can we build this?” It’s “do we know what to build?” And more precisely: can we specify what we want precisely enough that it gets built correctly?
That’s a different skill. I didn’t have it when I started, and building it changed everything about how I work.
When the First Build Is Cheap
When building was expensive, cost itself was a forcing function for specification. You thought carefully about what you wanted because mistakes were costly. Changing direction mid-build meant throwing away weeks of work. The economic pressure created a natural brake: if you couldn’t justify the cost, you didn’t build it. If you were uncertain, you resolved the uncertainty before committing resources.
That natural brake is vanishing. When an AI agent can produce a working implementation in minutes, the cost of building the wrong thing drops to near zero for the first build. But the wrong thing compounds. Architecture decisions made on bad assumptions persist. Wrong data models create downstream problems. Wrong user flows get deployed and create expectations. The first build is cheap. The consequences of building wrong are just as expensive as they ever were.
This is the trap. The feeling of speed masks the absence of specification. You can iterate so fast it feels like you’re converging on the right thing, when what you’re actually doing is building confidently in the wrong direction. Five iterations of the wrong idea, each produced in minutes, isn’t progress. It’s expensive in a way that doesn’t show up on a time sheet.
Testability as Specification
If you cannot describe how to verify something, you have not specified it.
The test is not an artifact that follows specification: it is the act that reveals whether specification has occurred. Attempting to define verification for something undefined exposes the gaps that prose descriptions hide.
The sequence works like this:
Writing test assertions is concrete work. “What does the user see?” “What does the API return?” “What breaks if this input is malformed?” It’s closer to building than to bureaucracy. It feels like making progress, not writing documents. Specification that feels like overhead will be skipped, and skipped specification is how you build the wrong thing fast.
Test the Behavior, Then Read the Code
The March version of this essay compared agent-written code to a neural network’s weights: too opaque to read, so you judge it by behavior alone. The comparison doesn’t hold. Weights are opaque. Agent-written code is source. You can read it, and you should.
What changes is the order of the work. Behavioral scenarios come first, because they’re the part of the specification the agent can’t negotiate with. They tell you whether the system does what you asked. They can’t tell you whether it’s built in a way you can live with: whether the architecture fits the rest of the system, whether the security boundaries hold, whether the next person can maintain it, whether it passes the tests by doing something you’d never approve.
So review doesn’t go away. Scenarios catch wrong behavior. Code review catches the rest, whether a person does it or an agent does and its findings get checked against the code and the data. I rely on both.
Writing the scenarios is still specification work. You decide what “correct” means before you look at what was built.
Context as Specification
The industry is converging on a useful distinction: prompt engineering versus context engineering. Prompt engineering is optimizing the phrasing of a query. Context engineering is building the complete informational environment the agent operates within: the system prompt, retrieved documents, tool definitions, conversation history, injected metadata, prior corrections. (The term caught on in mid-2025, when Shopify’s Tobi Lütke and then Andrej Karpathy argued for it over “prompt engineering.“) The two are not the same thing, and conflating them obscures where specification actually happens.
Context engineering is specification work. Which documents you inject decides what the agent knows about your codebase. Which tools you expose defines the scope of what it can do. Surface the relevant conversation history and architectural decisions and you’re shaping the constraints the agent reasons inside. None of this is infrastructure plumbing. It’s specification that rarely gets written down or treated as such.
Narrow the context to just the current file and you get an agent that optimizes locally, ignores system-wide constraints, and reinvents patterns that already exist elsewhere in the codebase. The fix isn’t to pour everything in. Load the full repository and every past conversation and the signal drowns; the agent attends to whatever is loudest, not whatever matters. What works is deliberate selection with progressive disclosure: a short map of the system up front, and the architectural decisions, prior corrections, and relevant history loaded when a step needs them. That agent knows why the data model looks the way it does, what’s already been tried, and where the system is headed, without carrying all of it all the time.
The context was the specification.
The connection to testability is direct. If you can’t describe how to verify something, you haven’t specified it. And if you haven’t specified the context — if you haven’t decided deliberately what the agent knows and doesn’t know — then you haven’t specified the agent. You’ve just hoped the implicit environment is sufficient. It usually isn’t. The gaps in context become gaps in behavior, and those gaps show up as outputs that are technically correct given what the agent knew and deeply wrong given what you intended.
Context engineering is where the specification conversation has to go next.
The Operator’s New Role
If the first build is cheap, what does the human actually do?
Design scenarios, then review the code. A scenario is an end-to-end user story: “user logs in, navigates to dashboard, creates an entry, entry persists across refresh.” It describes observable behavior, not implementation details. It’s what “correct” looks like from the outside. Review is what “acceptable” looks like from the inside.
Own the verification criteria. The scenarios must live outside the thing being tested. An agent that writes both the code and the tests can game the tests; the simplest implementation that passes a narrow test isn’t necessarily correct. The validation criteria have to be independent of the implementation. Separation of concerns, applied to the specification process itself.
Manage the intent-to-verification loop. Start with fuzzy intent. Sharpen it through test assertions. Discover gaps. Resolve them. Feed the refined spec to the builder. Validate the output against the scenarios. Iterate. This loop is the operator’s core workflow, and it’s entirely a specification activity.
Calibrate confidence. Alongside code review, the operator asks: do my scenarios cover the important behaviors? Are there edge cases I haven’t specified? What would it look like if this were wrong in a way my current scenarios don’t detect?
The hard thinking was always specification — we just used to do it implicitly while writing code. Now an agent writes the first draft of the code, and the thinking has to be explicit.
What This Means in Practice
The shift is already happening. People who are effective with AI coding tools aren’t the best prompters. They’re the best specifiers. They know what they want before they ask for it, can describe the expected behavior in concrete terms, and know what “done” looks like before they start.
People who struggle aren’t struggling with the AI. They’re struggling with the specification. They know they want something but can’t articulate what, precisely. So they iterate in vague directions, hoping to recognize the right answer when they see it. Sometimes that works. Usually it produces something that looks right but is subtly wrong in ways that won’t surface until much later.
The fix isn’t better prompts. It’s better specification habits:
Before asking an AI to build something, describe how you’d test it. If you can’t describe the test, you haven’t specified the thing. That’s not a failure — it’s information. It means you need to think more before you build.
Treat “I’ll know it when I see it” as a specification gap. Recognition has its place. When you’re exploring, seeing a prototype is often the fastest way to find out what you want. But recognition isn’t an acceptance criterion. Before something ships, turn what you recognized into criteria someone else could check, or the next iteration has nothing to converge on.
Write the acceptance criteria before the implementation request. Three bullet points describing what “done” looks like will produce better AI output than three paragraphs describing what you want. Concrete beats comprehensive.
When the output is wrong, ask whether the specification was right. Often the AI built exactly what you asked for. The problem was that what you asked for wasn’t what you wanted. The specification was the failure point, not the implementation.
The Literacy Metaphor
There’s a direct parallel.
Before widespread literacy, the ability to write wasn’t a general skill — it was a specialized profession. Scribes wrote. Everyone else dictated. The bottleneck was production: turning thought into written text.
Then printing collapsed the production cost. Word processors collapsed it further. The internet made distribution essentially free. And the bottleneck shifted from “can I produce text?” to “can I write clearly?” The scarce skill moved from production to composition.
We’re watching the same shift happen with software. The cost of producing a first draft is collapsing. The scarce skill is shifting from implementation to specification. Literacy became a universal requirement not because everyone became a professional writer, but because clear written communication became essential for participating in modern life. Specification literacy is heading the same direction.
Not everyone will be a professional specifier. But everyone who works with AI tools will need to be literate enough to describe what they want in terms that are precise, testable, and verifiable.
What you can’t specify, you can’t build correctly. What you can’t verify, you can’t trust.