Skip to content

Blog

Agents stall on unclear requirements, and a spec file fixes it

A pilot team blamed the agent until it looked at what the agent was handed. The fix was one spec file in the repo, with QA's test cases written before any code.

Written by

Specification and review

Published: 21 July 2026 Updated: 1 min read

A pilot team I worked with this summer spent its first weeks convinced the agent was the bottleneck. Faster model, better prompts, more context. The code still came back not quite right.

The requirements lived in three places

So we looked at what the agent was being handed. Their requirements lived in three places at once: a page in Confluence, a frame in Figma, and the part nobody wrote down, the verbal track in the handover meeting where the real explaining happened. A human picked up the gaps from the room. An agent cannot sit in the room.

The team named it themselves. Their number one bottleneck was not coding speed. It was unclear requirements.

One spec file replaced the user story

The fix was one artifact. They replaced the user story with a spec: a single Markdown file, committed to the repo next to the code, version-controlled, and reviewed in a pull request like anything else. It holds the current state, the change, the patterns to follow and the decisions still open.

The part that did the most work: QA writes the test cases into the spec before a line of code exists. Test design moved to the front instead of being discovered afterwards.

Every stage reads the same file

From there the line runs. Spec, then a refinement step, then planning, then implementation, then review, then a short retro on how the agents did. Every stage reads the same file.

Coverage fell out of the spec

The proof showed up fast. One developer on a different team generated 250 end-to-end tests from a spec while sitting in meetings. It was not a test-writing project. The coverage fell out of the spec, because the spec was good enough to carry it.

The handover meeting existed because the documentation was incomplete. Agents made that impossible to ignore.

Where do your requirements actually live, and could an agent read all of it?

Further reading

  1. YAGNI still holds, for a different reason Cheap code tempts teams to generate the flexible version just in case. But writing was never the only cost. Reading, debugging, and changing the code still cost a human, and YAGNI now protects those. 2 min readShort post
  2. Verification in a Software Factory When generating code gets cheap, a Factory's throughput depends on how well the system can establish that a change is acceptable, safe, and worth shipping. 3 min read
  3. An autonomous agent has to verify its own work Agent-built features can look finished and be broken. The user will not check, so the agent has to, and that changes how you build one. 2 min readShort post

All 23 posts on Specification and review

ClientsClient work

Scaling needs named owners

Coding agents scale across teams when named people own the platform, the team practice, the guardrails, and the measurement. Rollout & scale is where that ownership is built and handed to internal owners, in your stack.

Training on this topic: Agentic Engineering for Developers and QA
See Rollout & scale

Want to check one team first? The self-check: twelve yes or no questions, three minutes, instant result, no account. Take the self-check