The problem
A founder came to us after a rough sprint. Their team had used an AI coding agent to build out a multi-tenant billing backend directly from a product brief — no intermediate design step, straight from prompt to pull request. It worked in the demo. Three weeks later, in production, tenants started seeing each other’s invoices under load.
The root cause wasn’t the AI. It was that no one — human or model — had ever written down what “tenant isolation” meant in terms the system could be checked against. The brief described a product. It never described a contract.
The decision
We standardized every architecture engagement, AI-assisted or not, on spec-driven design: before any implementation, we write a specification that a system could in principle be verified against — data ownership boundaries, invariants that must never break, and the explicit failure modes we’re designing for. Not a requirements document. A contract.
This matters more, not less, once AI agents are writing code. An agent will happily produce plausible-looking code for an ambiguous brief — it has no way to know which ambiguities are load-bearing. A written spec removes the ambiguity before generation starts, which is also exactly what turns AI output from “looks right” into something a senior engineer can actually verify in review.
In practice this means:
- Every service boundary gets an explicit ownership statement — which data it owns, which it never touches
- Invariants are written as falsifiable statements, not prose (“a tenant’s query can never return rows outside its tenant_id” — not “the system should keep tenants separate”)
- Failure modes are enumerated before the first line of implementation code
The result
On the rebuild, the same team — using the same AI-assisted workflow — shipped the corrected billing backend in under two weeks, with the tenant-isolation invariant enforced at the query layer and covered by a test that would have caught the original bug on day one. The spec didn’t slow the AI-assisted work down. It gave both the model and the humans reviewing its output something concrete to check against.
We now treat this as the standard, not the exception — see how it shapes our software architecture consulting engagements from the first working session.
June 15, 2026