How to Write a Spec That Both a Human and an Agent Will Understand: A Template + 6 Anti-Patterns

A blueprint lands on the table at seven in the morning. The architect drew a window: here is the outline, here is the width, here is the height of the opening. The height of the sill from the finished floor — not there. Simply not there. The foreman pokes at the blank space with a finger as if it might materialize, dials the architect — ringing. Again — ringing. The concrete is already rolling off the mixer, the bricklayers are standing idle, every minute of downtime burning money. And the foreman does the only thing left to him: sets the sill at the height he has considered “normal” for twenty years. Nine hundred millimeters. Same as always.

Two weeks later the client arrives, stands in front of it, and his face falls. The window cuts the view exactly along the horizon line — low, wrong, nothing like what he had pictured. And he says the sentence the foreman has heard a hundred times and will hear a hundred more: “That’s not what I had in mind.”

This piece is about the cost of that “had in mind.” And the first number here has nothing to do with windows. According to a study by PlanGrid and FMI that surveyed nearly 600 construction executives, suboptimal work — rework, hunting for lost information, and resolving conflicts — consumes roughly $177 billion per year in the United States alone (PlanGrid + FMI, “Construction Disconnected,” 2018). And when that same study asked where rework comes from, the answer was not about materials or laziness: 52% of all rework globally is caused by bad data and miscommunication — that is, the gap between what was in the documents and what the author held in mind and never wrote down (Autodesk / FMI report).

More than half of all rework is not an executor’s error. It is the place where someone should have written something and did not.

Remember that half. It will fire again — in an unexpected place.

Because this story is not about construction. It is about the fact that since 2024 we have begun handing that same gap — between what was written and what was meant — not to foremen but to machines. And the machine, unlike the foreman, does not dial a number to check. It does not hear the ringing. It simply sets the sill — and moves on.

Delegation Without the Right to Guess

This scene is not about a crooked windowsill. It is about a mechanism that can be called “executor common sense” — the silent confidence that whoever we assigned the task to will fill in the missing piece the way we would have filled it in ourselves. The foreman has seen for twenty years what height people prefer for their windowsills. His guess has a reasonable chance of matching yours. This is not magic — it is shared context: you are both people, you both live in rooms with windows, you both have a body roughly one meter seventy tall.

Now remove the shared context. Give the same task to an entity that has never stood by a window, has no body, has no concept of “normal height” — because it has no concept of “normal” at all. It has only a probability distribution over all heights that appeared in the texts it was trained on. That is an AI agent. And when your technical spec has a gap, the agent does not perceive it as a gap. It sees a fork — and confidently walks into one of the corridors. Usually the wrong one.

This is where even experienced people stumble. We are accustomed to a missing detail being saved by a follow-up question. Between humans this is true: give a colleague a rough brief and they will pepper you with clarifications before they start. But a classic agent in execution mode does not ask for clarification by default. It is configured to drive toward a result, not to pause at every ambiguity. So every gap is not a signal to “ask” — it is a silent command to “decide yourself.” And it decides: silently, confidently, not in your favor.

I will work through this with two lenses — construction (because there gaps in a drawing have been counted in dollars for a hundred years) and cognitive (because there is research that shows exactly how an executor breaks under the weight of instructions). Then I will hand you a template, because some of you have to submit a brief to an agent tomorrow and I want you to submit it in a way that avoids rework. The razor thesis: a good spec is not a description of what you want, but a specification of memory for an executor who remembers nothing about you and will infer nothing.

I will name it directly: spec-as-memory. Not a document, not a brief, not “tell it what you need.” Memory. What the executor thinks with instead of you while you are not in the room.

Why This Has Become Urgent Right Now

Technical specs have always been written. Why is this worth discussing in 2026 rather than 2006?

Because the executor has changed. Before 2023 a spec was read by a human, and humans closed gaps with guesswork — badly, expensively (those same $177 billion), but they closed them. Since 2024 AI agents have been rolling off the production line, writing code, building landing pages, producing analytics and content. The shift is not cosmetic: according to Y Combinator partners, in one quarter of the startups in its Winter 2025 batch, 95% of the lines of code were generated by artificial intelligence (TechCrunch, March 2025). Meaning in every fourth new product, almost all the code was written not by a human following a spec but by a machine following someone’s brief.

And here a second structural number surfaces. Researchers at the Sky Computing Lab at Berkeley collected more than 1,600 execution traces from multi-agent systems and carefully hand-analyzed 150 of them with six experts — and built the first taxonomy of failures in such systems, MAST. They sorted failures into three broad categories, and the largest is not “dumb model” and not “complex task.” It is system design and specification problems: roughly 44% of all failures — ambiguous roles, unclear task definitions, missing constraints (arXiv 2503.13657; MAST, UC Berkeley). Another third falls to inter-agent misalignment, another quarter to verification failures. In other words: the single largest class of agent failures is a failure of the technical spec, not the executor.

Now read two numbers side by side. 52% of construction rework — from bad data and miscommunication in documents. ~44% of agent failures, the largest category — from holes in system design and specification. Different centuries, different executors, different measurement methods. The same disease: the executor breaks not where the task is hard but where the task is incomplete. (A fair caveat: these are two different industries measured by different methods — the coincidence does not prove a common cause. But when in two worlds this different the main culprit is the same, it is at least worth suspecting the problem does not lie with the executor.)

Things became urgent because previously a gap in the spec was paid for by the slow expensive guesswork of a human, and now it is paid for by the fast scalable guesswork of a machine. The machine fails more cheaply per instance — and a thousand times more often.

Why an Agent Cannot Do What a Foreman Does

A foreman who hits a gap has three moves: call, recall a similar case, or do “the usual.” The agent has only the third — and even that it performs blindly.

The reason lies in how an executor breaks under the weight of instructions. There is a surprisingly precise piece of research on this called “the curse of instructions.” A team built a benchmark called ManyIFEval — tasks packed with up to ten verifiable instructions simultaneously — and measured how the model’s ability to satisfy all instructions together declines. The picture on multi-instruction sets is harsh: GPT-4o achieves the full set on average in only 15% of cases, Claude 3.5 Sonnet in 44%, even though each individual instruction in isolation is satisfied by both models at 85–90% (Curse of Instructions, OpenReview). And the drop is not random: success on the full set roughly equals success on a single instruction raised to the power of their count. An exponential collapse.

Translating from academic to human. If you write ten equally weighted requirements in your spec as a single flat list, the agent will very likely drop some — and you will not know which one until you see the result. This is not model sloppiness. It is the mathematics of attention: every added requirement is an additional multiplier less than one, and the product inexorably slides toward zero. The same structure as the foreman: give him an oral list of fifteen minor details “by the way, don’t forget” — and he will forget some. The difference is only that the foreman will interrupt you at the third detail and ask you to write it down, while the agent will nod at all fifteen and walk away.

There is a second half to this mechanism, no less important than the first. A gap can not only be missed — it can be filled with someone else’s content. When the agent lacks your information, it does not leave a blank: it substitutes the most probable variant from everything it saw during training. Not your target audience — the “average” internet target audience. Not your currency — the dollar, because there are more dollars in texts. Not your tone — that smooth corporate voice in which most of the world’s landing pages are written. A gap in the spec is not a visible zero. It is a place that quietly fills with averaged debris from other people’s decisions, and you will notice it only when the result comes out strangely generic. “Why is it so bland?” — because you did not say what it should specifically be, and the agent wrote in the most probable thing on your behalf.

Hence the core rule of memory-for-an-agent: the task is not a wish list but a structure with priorities, where critical is separated from desirable, and “never” is stated as explicitly as “do.” And where every blank space you left blank consciously — because you know what will flow into it, and you are fine with that.

The Template: Six Pillars of a Good Spec

Now for the specifics, because without them this is just elegant theory. When GitHub analyzed more than 2,500 configuration files for agents (agents.md, CLAUDE.md, etc.) in public repositories, the most useful tasks turned out to cover six zones — and this holds well beyond code (GitHub Blog: lessons from 2,500+ repositories). I have translated these six zones from developer language into the language of any task — landing page, analytics, text, research.

Pillar	What this means for code	What this means for any task	Check question
Commands	Exact run commands with flags (npm test, not “run the tests”)	Exactly how to verify the result — which tools, which data	”How will the executor know it’s done?”
Verification	Which framework, where the tests live, expected coverage	Acceptance criteria: what = “done correctly"	"What fact will make me say yes or no?”
Structure	Where code, tests, docs live	Where context lives, in what format the result should appear	”Where does this go and in what shape?”
Style	Code conventions + examples	A sample of a good result and a bad one	”What should this look like / not look like?”
Process	Git workflow, how to commit	Stages, check-in points, what to do when stuck at a fork	”What to do when it hits a decision point?”
Boundaries	Files not to touch; “never commit secrets”	Red lines: what never to do	”What would destroy everything even if the rest is perfect?”

Notice the last row. In GitHub’s research, the most common useful constraint in top-level tasks turned out to be exactly “never commit secrets” — that is, an explicitly stated boundary, not a wish. The executor needs to know not only where to go but also where the cliff is. The foreman sees the cliff with his eyes. The agent — only if you drew it.

Picture yourself in this scenario, because you have been there. You open a chat with an agent in the evening, you need a landing page by tomorrow, and you write: “Make a one-page landing for our app. Modern, clean, must convert. Come up with the copy yourself, just make it look great.” You hit Enter and go make tea. Now scroll that message through the six pillars. Commands? None — you did not say how to verify “it converts.” Verification? No criterion; you will only recognize failure by eye. Structure? No specification of where to put it, which stack to use, which sections to include. Style? “Modern” and “great” — two adjectives, zero examples. Process? No “ask if you get stuck.” Boundaries? Empty — which means the agent can fabricate anything about the product, because you did not forbid fabrication. Six pillars, six holes. You will come back from tea to a flawlessly styled landing — about non-existent features, with invented numbers, in that same generic corporate voice, because the blanks were filled with averaged content. And you will tell the machine exactly what the client told the foreman: “That’s not what I had in mind.”

The template rests on three tiers of constraint, which I recommend spelling out in separate blocks: always (do this by default), ask first (stop and clarify here), and never (red line). That is the same mechanism that saves the foreman: not “guess the sill height” but “height 900 mm; if drawings conflict — stop, call; never go below 800.”

Six Anti-Patterns: How a Spec Defeats Itself

Now for the diagnosis. Six ways to ruin a task. Check your last brief against this list.

1. Fog instead of a task. The most common and most expensive. “Make a modern landing,” “write nice copy,” “analyze our customers.” Researchers say directly: most task files fail because they are too vague (O’Reilly Radar). “Modern” — against what benchmark? “Nice” — by whose taste? For a human, fog is an invitation to dialogue. For an agent, fog is permission to take the cheapest interpretation available to it. Fix: replace every adjective with a verifiable number or a sample.

2. Ten requirements in a flat list. Remember the curse of instructions? Many equally weighted items in a single stream — and the model drops some of them. The anti-pattern is not that there are many requirements; it is that they are not structured by priority. Fix: split into “critical / desirable / if time permits,” pull “never” out into its own block, break a monolithic brief into modular sub-tasks.

3. Implicit assumptions. The same windowsill. You “obviously” know the site should work on a phone, that the currency is hryvnias, that the audience is Ukrainians. The agent knows nothing “obviously.” Every silent assumption you carry is a fork where it will flip a coin. Fix: write down everything that seems “obvious.” Obvious to you is invisible to it.

4. A task without an acceptance criterion. The spec describes what to do but does not describe how to know it was done correctly. Without an acceptance criterion, both you and the agent will recognize failure only after the fact — when the client is staring at the window along the horizon line. Fix: for every requirement, one sentence “this is done when…”

5. Context without hierarchy. The flip side of fog: the author dumps a hundred pages of documentation on the agent with no structure, and it drowns. The same O’Reilly piece calls this “too much context without summarization” — burying a task in raw data works just as badly as underproviding (O’Reilly Radar). An executor’s attention is a finite resource, in a human as much as in a machine. Fix: not “here is everything, figure it out” but “the key is here, details are linked, here is the hierarchy.”

6. The spec as a one-shot bullet. The last and most subtle. The task was written once and set in stone — the executor made a mistake, you corrected it in the chat, but the correction was never put back into the spec. Next time the agent will trip over the same obstacle, because its memory is the spec, and the spec was not updated. Fix: every discovered gap goes back into the task text. The spec lives; it is not carved in granite.

Maybe We Just Need Smarter Models?

Here an honest opponent will say: wait. All of this is a temporary problem. The 2024 models could not ask for clarification and broke on ten instructions. The 2026 models already ask back, hold million-token contexts, fill in the missing themselves. Maybe spec discipline is a crutch for the period while agents are dumb, and in two years it will become unnecessary — the way manually managing memory in modern programming languages became unnecessary?

The argument is strong, and I concede part of it: yes, models already ask for clarification better, and yes, the tolerance threshold for fog is rising. But there is a structural limit that raw compute cannot move. The curse of instructions is not a bug of a specific model — it is a property of any executor with finite attention: a product of probabilities each less than one falls exponentially regardless of how many parameters you add. And the specification category in MAST is a share of cause that does not depend on the intelligence of the agent, because it concerns information that is physically absent from the task. A smarter model will guess your intent better. But guessing is exactly the roulette wheel that a good spec is supposed to eliminate. A smart agent with a foggy spec is a brilliant foreman you still did not give the sill height to: it will set it more beautifully than a mediocre one, but just as far from what you wanted.

What would prove me wrong? Data showing that the share of specification failures falls faster than model capability grows — meaning new agents consistently and correctly infer what is missing from a spec rather than simply producing a more polished version of the wrong thing. So far the data say the opposite: the more we delegate to agents, the more expensive each gap in a task becomes, because it multiplies by scale. Spec discipline is not a transitional crutch. It is new baseline literacy — the way knowing how to formulate a search query became literacy twenty years ago.

The Technique That Catches the Gap Before the Concrete Is Mixed

Back to the foreman with the blueprint at seven in the morning — but now from the other side.

The twentieth century taught engineers that a drawing without dimensions is not a drawing, it is a sketch. That a specification is a professional document with acceptance criteria, tolerances, and red lines — not a note saying “make it beautiful.” Construction paid for that lesson with billions in rework and built an entire culture around it: normative control, author supervision, mandatory dimensions on every junction. A gap in a drawing came to be seen as a defect — not of the executor but of the document.

The software and content industry largely forgot that lesson in the era when the executor was a human with common sense. A foggy brief passed through because a human’s guesswork was a free shock absorber. AI agents removed the shock absorber. And suddenly it turned out that the ability to write a task — to describe a desired number instead of an adjective; to pull constraints out separately; to give an acceptance criterion; to put every discovered gap back into the text — is not bureaucracy but a craft. A discipline everyone who delegates to machines will have to learn, and soon everyone will be delegating to machines.

In our practice at Dnister, when a client says “the agent generated the wrong thing,” the cause in the vast majority of cases is not the model but the brief: fog in point one, an implicit assumption in point three, a missing acceptance criterion in point four. The most useful thing we do at the start is not pick “the smartest model” but rewrite the client’s own technical spec together, against the six pillars above. The time savings there are regularly larger than any tool upgrade — because we are treating the cause, not the symptom.

And here is the technique that made it worth reading to the end. Everyone tells you “write in more detail, add context.” That is a half-truth — remember anti-pattern #5, context without hierarchy. The real advice is shorter and sharper, and it is recommended by serious practitioners of agent specification: ask the agent to before executing, restate the task in its own words and separately list every assumption it had to make on its own — marking each one with a tag like [ASSUMPTION: …] (O’Reilly Radar; freeCodeCamp). Not “do it” but first “tell me what you understood and where you made a decision for me.” That restatement is the most precise mirror of gaps that exists. The agent will show you your own implicit assumptions out loud, will name every fork and every corridor it was about to enter. It is the call the foreman could not make to the architect at seven in the morning — except now the executor makes the call, for free, before the concrete is mixed.

The architect never called back. But this time the foreman, before nodding to the mixer, laid the blueprint on the table and said aloud: “So, here is what I understood — window on this wall; sill height is not specified, [ASSUMPTION: I’m setting it at nine hundred, that’s my usual]. And someone in the room finally had time to say the one short word that costs less than all $177 billion combined: “Stop.”

The cheapest call in any project is the one that happens before the concrete. Your agent is ready to make it. All that remains is to write the spec in a way that gives it something to call about.

---

Partnership disclosure: Dnister is a partner of NeuroDrift; references to our practice are used as illustration of the thesis, not as a commercial offer.