# Specs, Not Prompts: Putting Machine-Readable Intent Back at the Center of the Development Lifecycle

> Source: <https://wpcms.computer.org/publications/tech-news/research/specification-driven-agentic-software>
> Published: 2026-11-17 15:45:17+00:00

Most engineering organizations have run the same experiment: hand developers an AI coding assistant, watch generated code volume climb, and discovered that the hard part was never typing. The hard part is knowing whether what came back is correct, secure, consistent with the rest of the system, and maintainable by the next engineer.

The evidence supports that discomfort. In a randomized controlled trial, [METR found that experienced open-source developers took 19% longer to complete real tasks in their own mature repositories when AI tools were allowed](https://arxiv.org/abs/2507.09089), even though those developers estimated afterward that they had been sped up by 20%. METR has since [revised its study design and cautioned against treating that figure as a fixed verdict](https://metr.org/blog/2026-02-24-uplift-update/). The durable finding is the perception gap: teams misjudge their AI-assisted throughput because the cost surfaces later, in review, integration, and rework.

Over the past year, my team built and operated an internal multi-agent development platform across roughly fifteen repositories spanning .NET, Angular, SQL, infrastructure-as-code, and Python. The central lesson: the unit of work that makes agentic development tractable is not the prompt. It is the specification.

A prompt is ephemeral, un-versioned, and scoped to one person's mental model. That works for a single function. It fails when one feature touches an API, a UI, a schema, and a deployment template maintained by different teams.

Three failure modes showed up consistently before we changed our approach:

None of these are model defects you can prompt your way out of. They are specification defects.

We moved to a model where no code is generated until an approved specification exists, stored in the repository alongside the code it governs. The format borrows from arc42, an open template for documenting software architecture. It has six sections: what and why, affected repositories, an implementation plan, an interface contract, configuration changes, and a test plan.

Acceptance criteria are written in Gherkin, the structured Given/When/Then syntax used by behavior-driven testing tools. Architectural decisions are recorded as MADR (Markdown Architectural Decision Records), short files that capture each decision, its alternatives, and its rationale. Three properties of the resulting artifact mattered more than the template itself.

Each specialized agent receives only its section of the spec, not the whole context window. A backend agent working from a defined interface contract cannot invent a route shape, because the route shape is already decided and reviewed.

When two agents disagree, or when generated code diverges from an invariant, the spec settles it. Precedence is explicit and ordered: the current state of the code outranks the pattern file, which outranks the general standard, which outranks generic best practice. Without a declared order, agents cite whichever document supports what they already produced.

Approval happens once, before any code is written, when a change is cheapest to redirect. After approval, execution runs uninterrupted. This inverts the common arrangement, in which humans approve at the end and are effectively reviewing a finished decision.

A [systematic review of 92 primary studies on agentic AI across the software lifecycle](https://arxiv.org/pdf/2605.15245) concludes that output verifiability is the primary enabler of adoption. The phases with real industrial uptake are testing, deployment, and maintenance, because their outputs can be checked objectively through executable feedback.

The review also identifies planner-executor-reviewer as the dominant architecture, with the reviewer supplying verification inside an iterative loop. We converged on the same shape independently, with one rule that matters: **the agent that writes the code never grades it.** Test agents challenge implementation agents through a structured protocol, classifying findings as blocker, warning, or question, with a cap of three rounds before escalating to a human. In one representative feature, that adversarial pass caught a missing ownership check on a delete endpoint before any human opened the diff.

Framework fragmentation complicates this. An IEEE Software review of ten agentic frameworks describes a [maturing but fragmented landscape](https://wpcms.computer.org/csdl/magazine/so/2026/01/11316910/2cQwBaWwLvy) with inconsistent approaches to memory, persistence, and human-in-the-loop control. We addressed portability by keeping agent behavior in Markdown, state in files on disk, and handoffs as artifacts rather than protocol messages. That unglamorous choice has survived two tooling migrations.

The most surprising effect was on documentation. We generate per-repository fact sheets covering endpoints, services, configuration, integrations, and observed coding patterns, and agents read them before writing anything.

Documentation stopped rotting, not because anyone became more disciplined, but because it became load bearing. A stale fact sheet produces visibly worse code, so keeping it current is in everyone's interest. In an AI-assisted lifecycle, documentation is no longer an output of engineering; it is an input to it.

The IEEE Computer Society's discussion of [architecting the AI-first software lifecycle](https://wpcms.computer.org/publications/tech-news/trends/engineering-ai-enterprise) describes humans moving up the value chain while governed agents handle execution. That is accurate but understates the discipline required. Practical guidance for teams attempting this:

Specification-driven development is not a new idea. What is new is that specifications now have a second reader, one that is fast, tireless, literal, and entirely without judgment. Writing for that reader turns out to make the artifact better for the human ones, too.

Ashif Anwar is a Principal Engineer at Wolters Kluwer, where he provides technical leadership for AI-enabled audit and accounting software and cloud-native enterprise platforms. With 12+ years of experience in software engineering and technology architecture, he specializes in Artificial Intelligence, Generative AI, Agentic AI, Microsoft Azure, distributed systems, and intelligent enterprise workflows. He applies emerging AI technologies to complex audit and accounting processes, emphasizing scalable architecture, data integrity, security, and responsible AI adoption. Ashif is a Senior Member of IEEE and a Fellow of BCS, The Chartered Institute for IT. He has published research with IEEE Computer Society and MDPI Accounting & Auditing and serves as a reviewer for IEEE conferences and technical venues.

Disclaimer: The authors are completely responsible for the content of this article. The opinions expressed are their own and do not represent IEEE’s position nor that of the Computer Society nor its Leadership.
