Specify: Write the Feature Before You Build It

Step 3 of 7.

The task list says "Add a book by hand". That is a pointer, not a description. A team never builds from a pointer like that, and an AI should not either. This lesson is about writing the feature out first, so the work starts from what you meant and does not stop every few minutes to ask.

Our goal: see why a feature is written out before it is built, know what a spec holds, and draft a batch of specs with an AI.

Here is the route:

1. Why teams write the feature down first: guessing and asking both cost time.
2. The same thing happens with an AI.
3. What a spec is.
4. Its parts.
5. A spec, written out.
6. Specifying a batch before you build.

We leave out building from a spec (lesson 11) and writing tests (lesson 12), though the "Done when" lines you write here are what they check against.

Why teams write the feature down first

Picture one developer and one ticket: "Add a book". A one-line ticket has too many readings. Is the ISBN required? Can the same one be added twice? What happens on an empty title? The developer has two choices, and both cost time.

Guess. Pick a reading and start. Nobody can tell which reading is the right one, so it is close to a random pick. Three days later the work reaches review, and it is not what the team meant. It is built again.

Ask. Code until the next question, stop, ask, wait for the answer, then code again. And again. The questions go to the same few people, such as the product owner or the lead, from every developer on the team. One person's waiting becomes the whole team's, and the team slows down.

The way out is old and plain: write the feature down before anyone builds it. The questions are answered once, in one place, before the work starts. The coding takes the same time in both rows. The waiting is what goes, and it grows with the size of the team.

With the feature written down, the work runs in a straight line.

The same thing happens with an AI

An AI session is one more developer on that team, and a new one every time (lesson 08). Without a spec it does what a human does. It guesses, and you find out in review. Or it asks, and keeps asking. It bugs you like a human would, and you do not get a break. You sit and answer questions all day, and in the end you have built one feature. That is no gain over a human, and the speed that made the AI worth using is gone.

With a spec, the AI has the answers before it starts. You are no longer the one it waits for, so you can hand out the next feature without waiting for the last one to finish. One person can run several AI sessions at once, each on its own feature, each from its own spec.

That is where the time goes. Without a spec the AI takes all of your day for one feature. With one, it takes a few minutes of your time per feature, and the rest of the day is yours.

A spec does not remove every question. It removes the ones that were only waiting for you to write the answer down.

What a spec is

A spec (short for specification) is a write-up of one feature, written before any code. It says what the feature does, what it must not do, and how you will know it is done. It is the forks and gaps of lesson 02, settled in advance, in words that cost a minute and not a rewrite.

The parts of a spec

A spec has a few plain sections. You do not always need all of them.

These are the "explain well" list from lesson 05 (what, limits, out of scope, what good looks like), put in a fixed shape. Done when matters most, because it becomes the checks in lessons 11 to 13.

A spec, written out

Add a book by hand is a form, a save and a list, a shape every developer knows, so a few lines are enough. Save it as docs/specs/03-add-book.md, with the task number first, so it matches the task list. Every task gets a spec. The other tasks are written the same way, so we show only this one.

# 03 Add a book by hand

**Goal:** staff can add a book by typing its details, and see all
books in a list.

**Behaviour**
- A form with ISBN, title and author (all required), and a price
  (optional).
- Saving adds the book and returns to the list.
- The list shows books by title, A to Z.

**Rules**
- The ISBN is digits only.
- The same ISBN cannot be added twice.
- The author is plain text for now.

**Out of scope:** editing, deleting, book covers.

**Done when**
- Adding ISBN 9781234567897 titled "A Sample Book" shows it in
  the list.
- An empty title shows an error and saves nothing.
- Adding the same ISBN again shows an error.

Notice what the spec settles: "The same ISBN cannot be added twice" is a fork (lesson 02) that the AI would otherwise have guessed.

Specify a batch before you build

Do not write one spec just before each build. Write the specs for the next few tasks first, as a batch, and then build.

Who writes them. In a team, the analyst, or a senior developer if there is no analyst: whoever knows the product best and can answer the AI's questions. They draft the batch with an AI, and the rest of the team reads the specs before anyone builds. Working alone, you do both jobs. Wear the analyst hat of lesson 03 first, and the developer hat after.

Why a batch, even for one person:

• Decisions are made once. A rule such as "the same ISBN cannot be added twice" is settled in one place, and the specs agree with each other.
• Overlaps and order show up. Read together, the specs reveal that two features need the same thing, or that one must come first.
• Building can start in parallel. With the specs ready, nothing waits for an answer, which is the five agents of the earlier picture.
• A change is cheapest here. Editing a line in a spec takes seconds. Editing finished code takes a rewrite.

Ask the AI to question you before it drafts, and to flag guesses (habits 2 and 3, lesson 05). It may still add things you did not ask for, such as editing or deleting books. A draft is a draft, so cut what you did not want.

💡 Read what you get, and stop early. A spec drafted by the AI is a draft, so check every rule against what you want. And say what the feature does, not how the code works. A spec that lists every line of code is a second copy of the code. Stop when the AI could not guess wrong in a way you would mind.

Where we ended

The project now holds the documents and five specs, one for each task. Only the spec for task 03 is shown in full. The others are drafted the same way.

Before (the end of lesson 08):

bookshop-backoffice/
├── README.md              the project document
└── docs/
    └── tasks.md           the ordered task list

After:

bookshop-backoffice/
├── README.md                  the project document (lesson 08)
└── docs/
    ├── tasks.md               the ordered task list (lesson 08)
    └── specs/                 <- NEW  one file per task
        ├── 01-setup.md            <- NEW  set up the project
        ├── 02-login.md            <- NEW  staff log in
        ├── 03-add-book.md         <- NEW  add a book by hand (shown above)
        ├── 04-scan-barcode.md     <- NEW  scan a barcode to add a book
        └── 05-search.md           <- NEW  search the list

A spec is named by its task number, so the task list and the spec files line up.

Recap

• A spec is a write-up of one feature, made before any code. It settles the forks and gaps the AI would otherwise guess.
• Its parts: goal, behaviour, rules, out of scope and done when.
• Without one, a developer or an AI either guesses, and the work is redone, or keeps asking, and the whole team waits.
• Write the specs for the next few tasks as a batch before building. In a team, an analyst or senior developer drafts them with an AI and the team reads them. Alone, you do both jobs.
• Ask the AI to question you and to flag guesses. A draft is a draft, so read it.
• The "done when" lines are what later steps check the code against.

Questions to think about

The answers are left out on purpose. Try them in your own words first.

1. Why write a spec before any code?
2. What goes wrong when a developer, or an AI, starts from a one-line ticket?
3. What does "done when" give you later?
4. Why read a spec the AI drafted before building from it?
5. Why write the specs as a batch before building, even when working alone?

Next lesson: step 4 and the code. Meet your coding agent, with Claude Code as the example, and set it up for your project.