I've been doing daily development with Claude Code, and in personal projects I often don't write formal specs at all — I throw together whatever documentation I need in the moment and discard it.
On the other hand, in the team development I do at my company, and especially in high-stakes B2B development for large enterprises, specs are not just essential — I actually feel their importance has increased.
Traditional specs served two purposes:
- An interface for the development team (what to build and how), and
- A single source of truth (SSOT) for explaining product behavior to customers.
Both are interfaces for humans, but the roles are different.
Having worked through various approaches, I think we can redefine the role of specs in an era where coding agents handle implementation — into three distinct functions.
Role 1: Aligning Everyone's Mental Image of "What We're Building"
This role isn't fundamentally different from what traditional specs always did. Engineers, designers, QA — everyone has a different lens. Even looking at the same product, what each person pictures as "the finished thing" can diverge. What you align on matters.
The most important shared foundation for a development team is: "the behavior from the user's perspective, and what the user is trying to solve." I think this is the center pin of the shared mental image.
System behavior and UI specifics can be delegated to separate documents. What the spec should own is "Why / What for whom." The "How" can be separated out.
Coding Agents as Members of the Development Team
A significant change: today's development teams include coding agents like Claude Code. In my case, I delegate most day-to-day implementation to Claude Code — which now carries as much weight as a human reader when it comes to reading specs.
A new requirement has emerged: specs must be human-readable, and simultaneously structured in a way that's easy for humans to pass to coding agents.
When actually handing context to a coding agent, the form that becomes a best practice often isn't a "spec" in the traditional sense. It gets transformed into formats like CLAUDE.md (a file describing project rules and policies), SKILLs (definitions of agent routine tasks), or ADRs (Architecture Decision Records capturing design rationale) before being passed over.
So what we need going forward is specs that are easy for humans to read, and also easy to transform into agent context and processes. The spec format is under pressure to evolve.
Role 2: Closing the Gap Between "What Was Actually Built" and the Mental Image
When you go from spec to actual development, the landing often differs from the mental image. That's because real development involves constraints that create tradeoffs, and tradeoffs require decisions.
When you delegate implementation to coding agents, tradeoffs keep occurring. Agents, when facing technical constraints, sometimes make independent judgments rather than consulting a human, the way a person would. Implicit, unintended tradeoffs happen more easily — and more often than in an all-human team.
The spec serves as the benchmark to avoid "leaving that gap as a gap":
- Having a spec makes it possible to "weigh tradeoffs against the original intent"
- It allows spec changes that occur during development to be tracked as diffs
Role 3: The Authoritative Source for "What Correct Behavior Looks Like for Users"
Generative AI has without question lowered the barrier to describing system behavior from source code. You can have AI inspect the code and hand the explanation directly to the customer.
But generative AI is an inference engine. No matter how much context you give it, the output is inference — not certainty.
"This seems to be X" is fine; "This is X, definitively" is legitimately frightening in a business context. That's why specs fill that role as SSOT.
The Process of Keeping Specs in Sync with Code Becomes Critical
Generating code from specs, and having specs evolve in response to feasible code — both happen with roughly equal frequency.
If specs are the authoritative source for correct behavior, they're meaningless unless they're continuously maintained to keep up with code changes. Before generative AI, this was hard to do consistently, and it was the root cause of many serious accidents.
- The Knight Capital incident: Old code left in the production environment, a divergence between spec and implementation, led to losses exceeding $400 million
- The Cloudflare outage: WAF rule changes applied without being reconciled with existing behavior specifications, causing a major outage
In a world built around coding agents, dynamically syncing specs and code is becoming a real possibility. For example: an agent detects diffs between the spec and code on every PR, automatically drafts spec change proposals. Reviewers review both the code and the spec update simultaneously. I think this is the right time to try workflows like this.
In B2B, specs can be the boundary of the business relationship. Whether you can say "this is the spec" with confidence shapes the trust relationship with the customer.
That's precisely why keeping specs fresh is both a technical challenge and a business challenge.
Summary
- Even as coding agents take over implementation, the role of specs doesn't disappear. Aligning mental images, closing gaps, being the authoritative source for correct behavior.
- In fact, all three of these functions become more important with the involvement of agents.
- Additionally, spec formats will need to take on a new requirement: being easy to hand off to agents. Converters to agent context will also be needed.
- Keeping specs in sync with code changes was historically difficult and caused serious accidents. But now, that sync process is becoming technically feasible.
A Side Note
I've been noticing more and more articles that open with something like "I wrote this without using AI." Isn't that just a pointless and, frankly, uncool line to include? Curious what others think.
