Spec Before Code, Then Less of It: Right-Sizing Process for AI Agents

For five months, every change on this project started with a written spec. Then we deliberately stopped doing that for most work, and delivery didn't slow down. Both halves of that story are worth telling.

Phase one: everything gets a spec

From March to August, every change followed the same path: brainstorm, then a written design spec, then a test-first task plan, then execution. We ran it largely through an open-source skills plugin for Claude Code. Across the three app repositories that produced about 120 specs and 115 plans, covering authentication, over-the-air updates, a feature-toggle system, deep links, push notifications, code-quality tooling, preview deployments and multi-factor authentication gates.

Execution was usually handed to subagents, and each one left a paper trail:

• a brief and a report for every task
• a review diff for every range of commits
• a whole-branch review by the strongest available model
• a final "polish wave"

One early lesson was to batch two to four plan tasks per subagent dispatch. One task per dispatch spent more on context than on work.

What it bought us was real. On large features the agent built the right thing, not just a plausible thing. Designs were reviewable before any code existed, and the plans became a record of why the code looks the way it does.

The cost

The cost showed up on small work. For a one-line ticket, the ceremony costs more than the change.

The plugin also told the agent at the start of every session to use a skill if there was "even a 1% chance" one applied. In practice, a plain bug report could trigger a brainstorming session.

The one-paragraph change

In mid-August we added a short section to our global instructions:

Skills are tools, not obligations. Invoke one when it genuinely fits the task at hand; otherwise just do the work.

It also said when each kind of process belongs:

• brainstorming only when the request is open-ended or genuinely ambiguous about what to build
• a written plan only when asked for, or when the work spans enough steps that the human would want to review the approach first
• debugging and test-first skills used freely, because they earn their cost

It ended with "When in doubt, act." We also switched off half a dozen process skills.

After that, formal specs became rare: three plans in the following two months. Over the same stretch the portal alone merged 115 pull requests in a single month.

What replaced the spec

The context a spec used to carry moved into places that already existed:

• The ticket became the spec for most work. The agent reads it from a local mirror and re-fetches it before triage (Part 5).
• API spec files, one per module, became the contract of record: 25 module files, many marked "verified live" with a date (Part 6).
• Design notes for each change request record what is ASSERTED, DECIDED and still OPEN (Part 8).
• Session notes are a running log per module, kept in a gitignored scratch folder.
• Memory holds the durable lessons (Part 4).

Writing a separate spec on top of all that would mostly have copied text from one place to another.

Asking replaced planning for small forks

When a change had a real decision in it, the agent asked instead of writing a plan:

• Multiple-choice questions with a recommended option first, such as "Fixes only (Recommended)" or "Fixes plus the new details screen". The developer sometimes answered with free text that widened the scope, which is exactly what the question is for.
• "Is X missing?" before "build X". The agent returns an evidence-based audit, and the developer replies "go".
• A stated interpretation of an ambiguous "go" before acting on it: "'go' most likely means the first option, so I'll commit and open the PR."

Big work still gets written down, as a brief

Work that spans several sessions still gets a written plan, but its shape changed. Instead of a spec, it gets a brief:

• decisions marked "do not reopen"
• sources and shared vocabulary
• work packages, each with an owner
• the report format each worker should return

After the brief comes a read-only first phase, then a phase document with a file ownership table. Part 9 covers how that runs across parallel sessions.

A planning artefact can also drive delivery directly. A module-by-module status and effort estimate, kept as a shared document, led to one session told to "follow the artifacts". It shipped 11 pull requests in about a day, one for every module whose API was ready.

The process we kept on purpose

Two-pass design survived every simplification. Pass 1 designs the target screen without looking at the current API. Pass 2 reconciles the design with the real contract and turns the gaps into requests for the backend team. It's cheap, and it stops designs from quietly shrinking to fit whatever the backend happens to offer today (Part 8).

How we decide now

• Is the work open-ended or new? Brainstorm, then write a spec.
• Does it span many steps or several sessions? Write a brief and run it in phases.
• Is it a ticket with a clear defect? Use the ticket, a failing test and a pull request.
• Is it a question? Answer it.

The amount of process should match how uncertain the work is, not habit. Uncertainty drops as the harness grows, so the process can shrink with it.

What to copy

• Start heavy while the codebase and the rules are young. The specs teach you what the harness needs.
• Write down when each kind of process applies, in your global agent instructions.
• Move context into artefacts that exist anyway, like tickets, API specs and design notes, instead of duplicating it in specs.
• Keep the one or two process rules that prevent expensive mistakes, and drop the rest.