All pages

Agentic development foundations · Lesson 2.3 · 12 min

Specs before code

Write the spec first for anything bigger than a fix, and let the agent work from it.

After this lesson you can tell when a change needs a spec, have the agent draft a product and technical spec pair, edit it into something you'd stand behind, and turn it into cards on the Kanban board that agents can work one at a time.

Time: 12 minutes · Works on: macOS app.

When a brief isn't enough

A brief works for a task one agent can finish in one sitting. Bigger changes need more. A new feature touches several files, makes decisions other code depends on, and takes several sessions, possibly several agents. If you start those with a brief, the decisions get made one prompt at a time, inside conversations nobody will read again.

A spec moves those decisions in front of the code, into a file you can read, edit and keep. Write one when a change:

  • crosses more than a few files,
  • adds a type or interface other code will depend on,
  • changes something stored, such as a database schema or a file format,
  • or will be split across sessions or agents.

Skip it for a single-file fix, a typo, or a dependency bump. A spec has to earn its place.

Two files: product and tech

Split the spec in two, because the two halves answer different questions and get reviewed by different people.

PRODUCT.md says what and why, in terms a user would recognise: the problem, the goals, the non-goals, and what the experience is like. It contains no code.

TECH.md says how: the approach, the code it will touch, the risks, and how it will be tested. Its most useful section is a list of the files and symbols the change will touch. That list makes the plan reviewable, and when several people or agents work on one repository, it shows two changes about to collide before either is written.

Keep them in the repository, in a folder per change, such as specs/invoice-csv-export/PRODUCT.md and TECH.md. Then they're versioned with the code, reviewed in a diff, and readable by any agent on any machine.

A worked example

A short product spec:

# Invoice CSV export — Product

## Problem
Accountants re-type invoice data from the Billing page into spreadsheets.

## Goals
- A "Download CSV" link on the Billing page.
- One row per invoice: date, number, amount in dollars, status.

## Non-goals
- PDF export. Filtering or date ranges.

## User experience
The link sits above the invoice table. It downloads every invoice the
user can see, named `invoices-YYYY-MM-DD.csv`.

And its technical half:

# Invoice CSV export — Tech

## Approach
A new route, `GET /api/invoices.csv`, reuses the query behind
`GET /api/invoices` and streams rows through a small encoder.

## Relevant code
- `server/routes/invoices.ts`: new handler beside `listInvoices`.
- `server/lib/csv.ts` (new): `encodeRows(rows)`, quoting per RFC 4180.
- `web/app/billing/page.tsx`: the link.

## Risks
- Large accounts: stream rows rather than building one string.
- Commas and quotes in customer names: covered by encoder tests.

## Test plan
- `server/lib/csv.test.ts`: quoting, empty input.
- `server/routes/invoices.test.ts`: content type, header row, two invoices.

Each section either records a decision or makes one checkable. The non-goals stop the agent from building filters nobody asked for. The test plan becomes the done-when for every card that follows.

The agent drafts, you edit

Let the agent write the first draft. It's good at reading the code and producing a plausible structure quickly. But the draft is not the spec. The spec is the draft after you've edited it, because the edits are where your intent and judgment go in. Read it the way you'd read a colleague's design document. Strike the goals you don't want. Correct the approach where you know better. Add the risk the agent couldn't know about.

If you approve a draft without changing anything, ask yourself whether you read it.

From spec to cards

A spec is finished when it can be split into tasks that each fit a brief. Each task becomes a card on the project's board, with a goal, a pointer to the spec, and a done-when taken from the test plan. Order them with dependencies, so the encoder card comes before the route card that uses it. Now the work survives any one conversation: you, an agent or a fleet of agents can take the next ready card and know exactly what it means.

Do it in TRMNLY

Take one real feature from idea to cards.

  1. Investigate first. In the Agent tab, open the gear menu and choose the Planner persona under Persona. It reads code but can't write files. Ask: "Read the billing code and tell me what an invoice CSV export would touch."
  2. Draft the spec. Switch the persona back to Default and ask: "Write specs/invoice-csv-export/PRODUCT.md and TECH.md from what you found. The tech spec must have a Relevant code section and a Test plan. Don't write any other code." Approve the two file writes after reading them.
  3. Read and edit it yourself. Open the Files tab, select each file and read the rendered Markdown in the preview. Click the pencil to edit in place and press ⌘S to save.
  4. Send review notes back. For larger changes, stage the spec with git add specs/invoice-csv-export in a pane, open More ▾ → Review, and switch the scope picker to Staged. Click a line, write a note such as "drop this goal, it's a separate feature", add the rest, and press Send to agent. All the notes go back as one message.
  5. Keep it in view. Select TECH.md in the Files tab and use Pin to agent, so every turn in this project sees the plan without you repeating it.
  6. File the cards. Ask the agent: "Split the tech spec into cards on the Tasks board, one per testable step. Put the goal and the relevant test from the test plan in each card's body, link the spec, and add dependencies so they run in order." It uses kanban_add and kanban_depend. Open More ▾ → Tasks to see them.
  7. Check the order. Click the bolt button in the board's filter bar. It shows only cards that are ready to start, meaning nothing they depend on is unfinished. Only the first card should show.
  8. Work one card. Ask "Work card #1 in a new worktree." Creating a worktree asks for your approval. When it's done, review the diff, merge, move the card to Done, and the next card becomes ready.

When the spec changes during the work, and it will, update the files rather than correcting the agent in chat. A correction in chat lasts one conversation. A correction in the spec lasts the whole feature.

Check yourself

  • You can name two signs that a change needs a spec, and one that it doesn't.
  • Your PRODUCT.md has non-goals and your TECH.md has a Relevant code list and a test plan.
  • You changed the agent's draft before calling it done.
  • The board's ready filter showed only the first card of the feature.

Go further