The Specification Frame

AI coding assistants complete prompts statistically. Give one too few of the right words and it fills the gaps with the most common answer from its training data — which is rarely what your domain requires. Tooling can hold a specification; it cannot tell you what belongs in one. The Specification Frame is a disciplined way to write that content, structured so nothing important is left unsaid.

The four elements

Every Specification Frame prompt has four parts, each closing a specific gap between what you asked for and what your domain needs:

The three gaps it closes

The four elements exist to close what the book calls the Specification Gap — the distance between what you intend and what the model produces. It has three components:

• The Domain Gap — your regulatory constraints and proprietary types, which appear in no training data.
• The Context Gap — your actual codebase, which the model cannot infer.
• The Constraint Gap — your team's hard-won invariants, which must be stated to be honored.

These are not abstractions. Independent evaluations through 2026 consistently found that AI coding tools perform markedly worse on existing codebases than on greenfield ones — the difficulty is not writing new code but honoring the implicit conventions, undocumented assumptions, and accumulated context of a system someone else built. That is the Context Gap and the Domain Gap, encountered in the wild.

Why XML structure

The Frame uses XML tags as the separator between elements because the model providers themselves recommend them as the most reliable structural cue — Anthropic's documentation notes XML tags help the model parse complex prompts unambiguously, and similar guidance appears for other frontier models. The directional benefit — that structured prompts outperform unstructured natural-language prompts on code-generation tasks — is supported by published prompt-specificity research.

The quality of your output is bounded by the quality of your constraint. Missing one constraint leaves one failure mode open.

A minimal example

The contrast at the heart of the book: the same task, unspecified and specified.

<!-- The Specification Frame — all four elements -->
<role>
  You are a senior C# engineer on a payments platform.
  Stack: .NET 9. All monetary values use Money<TCurrency>.
</role>
<context>
  Money<TCurrency> is a record; constructed only from decimal.
  Results use Result<T> — never throw for business-rule failures.
</context>
<task>
  Implement Total(List<Tx>) returning Money<GBP>.
</task>
<constraints>
  - Money<TCurrency> for all amounts; never double or float.
  - Round once, at the boundary; banker's rounding.
  - Compilable code only. No pseudocode.
</constraints>

The full structure, the precedence rules for when constraints conflict, the complete Result<T> and Money<T> implementations, and 100+ worked recipes are developed in the book.

Leverage, not magic

It is worth being precise about what the Frame does and does not do, because the honest limit is also the point. The Frame does not make the model smarter. It transmits your specification faithfully — including your mistakes. Specify a wrong rule and the model will implement the wrong rule, often more confidently than a vague prompt would have. In testing, a Frame containing a deliberately wrong constraint produced output that was worse than the unspecified version: the model obeyed the bad instruction exactly.

That is not a weakness to hide; it is the mechanism, shown at its boundary. A technique that only ever improved output would be indistinguishable from luck. The Frame's value is that it is leverage — it does exactly what you specify — which means the discipline of specifying correctly matters more, not less. Two practical consequences follow:

• Frame where being wrong has a cost. Money, security, compliance, concurrency — domains where a missing or wrong constraint becomes a production incident. For trivial, domain-free tasks, the Frame is overhead.
• Specify the right approach before you specify it precisely. A perfect specification of a fundamentally wrong approach is still wrong. The Frame sharpens how; it cannot tell you whether.

A fuller empirical evaluation of where the Frame helps, where it makes no difference, and where it can make things worse is in preparation as a companion paper.