Spec-first: writing requirements an agent can build from

Give an agent a one-line ticket and it will fill the gaps with plausible guesses. Some will be right. The rest become rework, review fatigue and bugs. The fix isn't a cleverer prompt; it's a better spec.

What a buildable spec contains

1. Outcome. One paragraph on who this is for and what changes for them.
2. Scope and non-goals. What is in, and — just as important — what the agent must not touch.
3. Contracts. API shapes, events, data models and error cases, written precisely.
4. Acceptance criteria as tests. Given / when / then statements that become automated tests before implementation starts.
5. Constraints. Security, performance, accessibility and compliance requirements, each with a way to check it.
6. Conventions. A pointer to the patterns to follow, ideally an existing module that does something similar well.

Tests first, then code

We usually have one agent turn acceptance criteria into failing tests, a human review those tests, and only then hand implementation to a second agent. Reviewing a test suite is much faster than reviewing an implementation, and once the tests are right, the implementation can be judged mechanically.

A worked example

Here is a trimmed spec we used for a returns feature in ShipTrack. Notice how little is left to interpretation:

• Outcome: shoppers can start a return for an eligible order without contacting support.
• Non-goals: no changes to refund calculation; no new carrier integrations.
• Contract: POST /returns accepts an order id and line items, returns a return id and label URL, and rejects ineligible items with a reason code.
• Acceptance: given an order delivered 10 days ago, when the shopper returns one item, then a label is issued and the order shows "return started". Given an order older than the return window, the request is rejected with WINDOW_EXPIRED.
• Constraints: the tenant is taken from the authenticated session, never the request body; the endpoint answers in under 300 ms at p95.

An agent can build that in one pass, and the harness can tell — without a human — whether it did.

Keep specs small

A spec that needs scrolling is usually two specs. Small specs fit cleanly in an agent's context, produce reviewable diffs and let several lanes run in parallel without colliding.

Specs are living documents

When review finds a gap, we fix the spec as well as the code, so the next agent working nearby inherits the correction. Over time the specs become the most accurate documentation the system has — because the build depends on them being right.