The Spec Is the Product: Writing Briefs a Cheaper Model Can Actually Execute

The last two posts on this blog both end in the same place: let the architect model write a precise specification, then hand it to something cheaper. Both treat the specification as the easy part. It isn't. It's the entire pattern. Everything downstream, the cost saving, the speed, the reviewer catching drift instead of rewriting from scratch, is downstream of one artifact, and most teams write it badly.

Cheap models don't fail at coding

They fail at guessing. That distinction matters, because it tells you what to put in the brief.

Give a small model a well-bounded function with a clear contract and it will write it correctly. Give it the same function with one unstated assumption and it will make a decision on your behalf, confidently, and you won't find out until review. It isn't being careless. It has been handed a gap and asked to produce output anyway.

So the job of a specification isn't to describe the work. It's to close every gap the implementer would otherwise have to fill in.

In practice there are four, and they're the same four every time:

• Where does this go? Which file, which module, which existing pattern to follow.
• What shape is the output? Signature, types, error cases, return contract.
• What does done mean? Not "it works", a check that passes or fails.
• What am I not allowed to touch? The blast radius.

Leave any one of them open and the implementer will answer it for you.

The five parts of an executable brief

Part	Answers	What it looks like
Boundary	Where does this go?	Exact file paths it may create or modify
Contract	What shape is the output?	Signature, types, error behaviour
Examples	What does correct look like?	At least one input/output pair
Done test	How do I know I'm finished?	A command that exits 0
Prohibitions	What's off limits?	Files, dependencies, patterns to avoid

The first four are what most people already half-write. The fifth is the one that gets skipped, and it's the one that prevents the expensive failure mode: an implementer that "helpfully" refactors something adjacent, or adds a dependency, or rewrites a shared type to make its own task easier.

What this looks like in practice

Here's a brief of the kind that gets handed down every day:

Add rate limiting to the API.

An architect model understands this. An implementer will produce something, probably a middleware, probably in-memory, probably with limits it invented. It may well be good code. It will not be the code you were planning around.

The same task, closed:

FILE: src/middleware/rate-limit.ts (create)
ALSO EDIT: src/app.ts (register middleware only, no other changes)

CONTRACT:
  rateLimit(opts: { windowMs: number; max: number }): Middleware
  - Keys by req.ip
  - On limit exceeded: respond 429, body { error: "rate_limited",
    retryAfter: <seconds> }, set Retry-After header
  - Storage: Redis via the existing client in src/lib/redis.ts

EXAMPLE:
  rateLimit({ windowMs: 60_000, max: 100 })
  → request 101 within the window gets 429 + Retry-After: 60

DONE WHEN:
  npm test -- rate-limit  passes (tests already exist at
  src/middleware/__tests__/rate-limit.test.ts)

DO NOT:
  - Add new dependencies
  - Modify src/lib/redis.ts
  - Touch any other route or middleware

That's maybe ninety seconds of the architect's time. It removes every decision the implementer would otherwise have had to make, and it does something more valuable than that: it makes the review mechanical. You are no longer asking "is this good?" You are asking "does this match?"

Length should track blast radius, not task size

The instinct is to write longer specs for bigger tasks. The better rule is to write longer specs for tasks that can break more things.

A three-hundred-line component that lives in isolation and is covered by tests needs a short brief. A twelve-line change to a shared authentication helper needs a long one. Size tells you how much code comes back. Blast radius tells you how much it costs when the brief was wrong.

Spend specification effort in proportion to what a misunderstanding would cost, not in proportion to how much typing the task involves.

This is also the honest answer to "isn't writing all this slower than just doing it myself?" Sometimes, yes. For a genuinely one-off change with a contained blast radius, write the code. The pattern earns its keep on work that repeats, or work where being wrong is expensive.

Drift is usually a spec bug

When the reviewer keeps catching the same class of mistake, the instinct is to blame the implementer and reach for a bigger model. Nearly always, the brief left something open and every implementer is walking through the same gap.

This is the most useful diagnostic the pattern gives you. Categorise what the reviewer rejects:

1. Same correction, repeatedly, a spec gap. Fix the template, not the model.
2. Different corrections each time, all reasonable-but-wrong, the task was under-specified as a whole; it may not be ready to delegate yet.
3. Corrections that require system context to even notice, this task shouldn't have left the architect tier at all.

Only the third is a case for escalating the model. The first two are cases for editing the brief, and they're by far the more common.

Briefs are reusable, code isn't

The underrated property of a good specification is that it outlives the task.

A brief that produced a correct implementation once is a template. The next endpoint, the next migration, the next adapter, same structure, different nouns. Teams running this pattern for a few months end up with a small library of brief shapes, and the architect's job shifts from writing specifications to selecting and adapting one. That's when the cost curve really bends, more than from any model routing decision.

Keep them. A specs/ directory next to the code costs nothing and quietly becomes the most accurate documentation of intent you have, not what the code does, which you can read, but what it was asked to do, which you can't.

The mistake teams make

They write the specification in the language the architect thinks in.

Prose like "handle the edge cases sensibly and follow the existing patterns" is perfectly clear to a model holding the whole system in context. It's noise to one seeing fifteen lines of a file. The architect's context is exactly what the implementer does not have, and every reference to it is a gap wearing the costume of an instruction.

The test is simple: could someone who has never seen this codebase execute this brief? If not, you haven't written a specification. You've written a reminder to yourself.

The takeaway

The Claude Architect pattern isn't really about model routing. Routing is the easy part, a config change. The work is in producing briefs tight enough that a cheaper model has nothing left to guess at, and that skill is the one that determines whether the whole structure saves you money or just moves the rework downstream.

Close the four gaps. Write the prohibitions. Make done a command, not an adjective. Then keep the brief, because the second time you need it is where the return is.

FAQ

How long should a specification be?

Long enough to close the boundary, contract, examples, done test and prohibitions, and no longer. For most delegated tasks that's fifteen to thirty lines. Scale it with blast radius, not with the size of the output.

What if the implementer keeps getting it wrong?

Check whether it's the same mistake each time. Repeated identical corrections point at a gap in the brief, not a limitation in the model. Escalate to a larger model only when the correction requires system-wide context to spot.

Should I write specs by hand or have the architect model write them?

Have the architect write them, then read them as though you had no context. The failure mode is specifications that reference knowledge only the architect holds, and that's much easier to catch on a read-through than to prompt away.

Pick the task you delegated most often this month and write its brief properly once. If it holds up twice, you have a template, and templates are where this pattern actually pays.