Traditional data specs are too brittle for AI. Natural language prompts are too chaotic. We are officially trapped in an architectural gridlock. 🚧
In my last post, I called out our quiet regression into "Prompt-First Chaos"—burying critical business logic inside fragile 500-line prompt strings because our existing technology boundaries failed us.
When I debate this with architectural purists, they always retreat to the same defensive line: “That’s why we use standard Spec-Driven Design (SDD). We enforce strict type schemas, GraphQL definitions, or OpenAPI structures upfront to guarantee deterministic boundaries.”
But here is the hard truth I’ve learned from building in the trenches: Standard Spec-Driven Design completely chokes the moment it collides with agentic AI.
The systemic flaw of traditional SDD is that it forces us to model the structure of a network message, rather than the intent of a business capability. It assumes a predictable execution path pre-mapped by a human developer.
But AI agents don’t think in linear endpoint chaining or matching data shapes. They think in objectives. When you throw a dynamic agent at a traditional structural spec, it breaks down in three specific ways:
The Validation Wall: Standard specs enforce rigid payload validation (regex, enums, exact structures). If an agent passes a logically sound but structurally imperfect property, the system throws a cold 400 Bad Request. Because the spec only defines data shape and not meaning, the error response gives the agent zero semantic context on how to self-correct. The agent hits a brick wall.
The Under-Specified Relationship Trap: Schemas define static objects but fail to capture runtime relational context. A spec might state that a payload requires an approver_id. It does not tell the agent the underlying business rule: if the value exceeds $10k, the approver must have Tier-2 signing authority. To handle that, developers split the logic—hardcoding the API schema but burying the rules in the agent's prompt, fracturing the single source of truth.
The State Illusion of the Prompt Sandbox: Faced with this rigidity, engineers overcorrect. They build a raw prompt sandbox, expose a basic toolbelt of endpoints, and tell the AI: “Execute the corporate purchasing policy.” Now you have flexibility, but zero governance. The agent begins to hallucinate state changes (assuming a step succeeded simply because it outputted text saying it did), skips silent compliance guardrails, and misinterprets ambiguous phrasing based on the context window's state.
The root issue? Both approaches model the wrong thing.
Traditional SDD tries to model technical mechanics (data shapes). Prompt engineering tries to model shifting human instructions. Neither framework captures, version-controls, and governs the actual business capability in a way that is flexible for an autonomous agent, yet completely deterministic for the enterprise codebase.
We have to stop choosing between rigid structural tracks and un-governed text sandboxes. We need a paradigm shift. True design-first architecture means designing the explicit boundaries of what outcome should happen and the context it requires to execute, without hardcoding a fragile path of how the data must look on the wire.
In my next post, I’ll dive into exactly how I break this gridlock using Outcome-Driven Context Modeling (ODCM). We will look at how moving away from structural message schemas and toward deterministic context slices allows you to build version-controlled, agent-ready capabilities.