Stop Handing AI Agents Wishes: A Spec-First Process for Small Teams
Stop handing AI agents wishes: a spec-first process for small teams with adversarial review by two model families, runtime tests, human merges and memory.
This article is published in English.
Sources: *A small dev team, a stack of AI agents, and the spec-first process that keeps them honest.*
Picture an AI agent that builds a feature in twenty minutes. The pull request looks lovely: tidy diffs, green tests, a courteous summary. It's also wrong, in a way that takes a team three days to untangle.
The model in that story wasn't bad. It did what it was told. The problem was the instruction, which was a wish. "Build a page that shows X" is a wish, and a fast, literal contractor will satisfy a wish by guessing everything left unsaid. The guesses will be plausible, because plausibility is the thing these systems produce.
One small team now refuses to build anything until it's described in writing and that description has survived rough treatment before a line of code exists. People call the approach spec-driven development. It's what makes agents trustworthy for a group with more software to build than people to build it. The humans decide, review and merge. The agents do the typing. That arrangement only works when the agents get something better than a wish.
What a spec contains
Nothing gets built until a short markdown document exists that settles three things, in this order:
- The current problem and the reason it deserves attention.
- What will be true afterward, described so a user could check it?
- What must stay exactly as it is while the work happens?
The last item carries surprising weight. A big part of any solid spec is simply marking the area the change is not allowed to touch. The rest is scenarios, meaning every edge case the author can imagine, each written in an if-this-then-that shape.
Specs are written as deltas, never as universal documents. Here is current behavior, here is exactly what will differ. A spec that tries to describe everything ends up describing nothing.
Two AIs attack the spec first
When the draft is done, two AI reviewers get it. They come from separate vendors and separate model lineages, and their only assignment is to find ways the plan could go wrong. The team nicknamed the session a pow-wow. Mixing lineages is deliberate: reviewers from one family tend to overlook the same things, the way siblings back each other's stories. Disagreement is what you're after.
Findings go back into the spec. An objection becomes a requirement. Only when the spec stops bleeding is a builder agent dispatched.
That ordering has a story behind it. Once, a builder was sent off while a review was still running. The review returned findings that invalidated half the build, and the team paid for that code twice. Since then the rule is firm. A builder waits until both reviewers have reported and each accepted finding has been written into the spec, even when skipping ahead looks harmless.
The pow-wow has paid off in unexpected ways. A spec once named an existing permission helper and assumed, from the name alone, what it checked. One reviewer opened the code and found something much narrower: it applied only to the original requester, and only in a single state. Function names can mislead. Hence a firm habit: read the implementation before a spec mentions it. That habit has rescued more weekends than any lint rule.
The pipeline, start to finish
For a change of any real size, the sequence is:
spec → adversarial review → apply findings → build → diff review → runtime testing → human testing → human merge
A few steps deserve comment.
The builder is given the spec and nothing else. It never sees a chat log or a casual add-on request. Whatever the builder must know has to be written into the document, because anything absent is fair game for guessing.
Runtime testing checks what the software does, not what the files look like. Passing tests alone say little. In one early incident, a validation message was supposed to show up on screen but never did, since the code that drew it could not be reached. Diffs and tests were both fine. Nobody had tried doing the wrong thing as a user, and a diff cannot display a message that doesn't exist. Now faults are injected deliberately: send in junk, confirm the error is actually visible, and only then mark the work tested.
The human step is someone clicking through the app like an impatient user, and that's the point. One class of bug escapes every automated review: the feature works, yet a person can't find it. Missing create screens, dead-end navigation. Annoyed clicking acts as the acceptance test and earns more trust than any summary.
Merging stays with a person. Agents neither merge nor deploy. Speed is fine, but the pull request has to tell the truth about which checks ran and which were skipped, and the orchestrator labels skipped gates as such right there. When most of the team is machines checking machines, honest records are everything.
The amount of process follows the size of the change. A tiny text correction becomes a direct PR. Security, permissions and data-model changes go through everything. Imposing heavy process on trivial work kills it, and trusting light process with serious work kills the project.
Once a change ships, its spec is filed with the code. The repo slowly builds a written record of decisions, so the question of why something works a certain way often has an answer dated before the code itself.
Review by two models that didn't write the code
The pow-wow targets the plan. Finished code meets a separate panel, and this is the part another team should adopt first.
The builder is a workhorse, picked because it keeps going and costs little per token. Money for premium intelligence is saved for review, in the form of two frontier models from two separate labs, neither related to the builder. Their jobs differ on purpose. One sits in the senior engineer seat, reading the diff against the spec line by line and then working hands-on with the running build, trying to break the feature. The other is a mandatory pass, and no substantial change merges without its sign-off, however small it looks.
Two labs instead of two copies of the strongest model? Related models share instincts. A reviewer tends to excuse code written like itself and trip over code from an outsider. If both point at one line from different directions, it's almost certainly a defect. If they contradict each other, the spec had a gap, which is better discovered from two models than from a user.
The seats aren't permanent. One reviewer was benched after it spent its entire output repeating a single finding more than a hundred times. Large reasoning models can loop when given a diff-sized prompt. The seat was swapped and the gate stayed.
The agent that holds it together
None of this is exotic. Specs, reviews and testing are old ideas in new clothes. What's harder to predict is how much orchestration matters, and how much agent it takes to hold the pipeline together.
The team runs Hermes Agent, an open-source agent framework from Nous Research, as orchestrator. It doesn't mainly write code. It runs the process, which may be the more valuable job. Three properties make that work.
Memory. Most assistants open every chat with amnesia and a friendly tone. Hermes retains context between sessions, so decisions stick. It knows the risk tiers, knows builders never grade their own work, and knows the pow-wow precedes every dispatch, because a past mistake was written down. If a hurried person wants to bypass a gate, the agent refuses: the process is enforced by whoever remembers it perfectly.
Learning. A failure turns into a postmortem, and the postmortem becomes a skill, which in Hermes means a procedure document loaded into later sessions when it applies. After six months the agent holds a pile of hard-won notes drawn from real incidents and reads the relevant ones first. Knowledge that lived in one worn-out engineer's head now lives in version control.
Delegation. Building and reviewing are handed to subagents. Because Hermes works with any provider, roles can be mapped to models freely: an economical workhorse builds and the costly smart models review. If a model is having a rough month, you replace it and nothing else changes.
What it buys and what it costs
There's no productivity percentage here. Numbers like that can't be checked, and nearly everyone publishing them is selling something. These are the claims that can be defended:
- Weekly shipping happens even though no human codes full time.
- Blast radius is contained at spec time, before containment gets expensive.
- Anyone asking why the software behaves a certain way can find it written down.
- The human's job changes shape, from keyboard time to decisions and clicking.
It's a better role and a tougher one. Writing a precise spec means knowing what you want before seeing it. With implementation cheap, exactness became the scarce skill.
The downsides are real. Spec writing demands discipline, and the pull to cut corners on a supposedly small change is how this kind of process falls apart. AI reviewers can bury you in minor complaints, so sorting them is a skill to develop. In weeks when requirements are already obvious, the pipeline feels sluggish. And it needs attention: left alone, it decays like any human process.
Whether AI can write the code is no longer the question, because it can. What matters now is whether you can state precisely what the software should do and keep to your own process when time is short. Without that, no model helps. It simply delivers your confusion sooner.