Spec-driven development: write the PRD and SRS before the code

An AI coding agent builds what it understands, and it understands only what is written down. So a build starts with documents, in order: a PRD for what you are building and why, an SRS for what the system must do in testable terms, then a plan and the spec files the agent works from. A document is ready when a fresh session that has never seen your conversation can explain the build back to you; Google’s open-source Elephant-Goldfish Model makes that test routine, and it is the routine we run on our own builds.

Why does the document matter more than it used to?

Agents write code faster than people can read it. Dave Rensin’s essay, which the Elephant-Goldfish Model is built on, argues that the written design then matters more than the code: it is the only thing a person can still hold in their head. GitHub makes the same point: with coding agents the specification decides what gets built, and “intent is the source of truth”.

The failure we see most often: someone describes a feature in two paragraphs of chat, and the agent produces a plausible implementation. Later, nobody can say whether it matches what the business asked for, because that was never written anywhere. The code is now the only spec, and it was written by something that guessed.

Anthropic’s Claude Code docs say the same: let the agent jump straight to code and it can solve the wrong problem. Explore first, then plan, then code.

What goes in the PRD, and what goes in the SRS?

Two documents, two jobs, owned by different people.

The PRD (product requirements document) answers a decision-maker’s questions:

• The problem. Who has it, how often, and what it costs them today.
• The outcome. What changes for that person when it works, in their words.
• Scope. What is in the first release and, more usefully, what is out.
• Success. How you will know it worked, with the measure named before the build.
• Constraints. Where the data may live, the Personal Data Protection Law, the languages it must work in, the systems it must sit beside.

The SRS (software requirements specification) turns that into statements an agent can verify. ISO/IEC/IEEE 29148 is the standard behind the format, and the part worth keeping is its bar for a single requirement: singular, unambiguous and verifiable. “The agent should handle Arabic well” fails that bar. “Given a customer message in Saudi dialect, the agent classifies the intent and replies in Modern Standard Arabic” passes, because someone can write the test.

We do not start the SRS until the PRD is signed. If the problem is not agreed, precise requirements only make the wrong thing more precisely.

What are the plan and spec files?

The PRD and SRS describe the product; the plan and spec files describe the build. They live in the repository next to the code, and the agent reads them every session.

The plan says what happens in what order, which existing code is touched, and what is deliberately left alone. The spec files, one per feature, say how that feature works in enough detail that an agent with no memory of your conversations can build it.

GitHub’s Spec Kit uses three files per feature: spec, plan and tasks. Google’s EGM keeps one design document per feature under docs/designs. The names are not the point; keeping the files in version control and reviewing them in a pull request is.

When we take over an existing system we run the process backwards: agents read the code and draft a PRD and SRS, and a person corrects them before anyone changes anything. It is the quickest way we know to learn what a system does, rather than what the last contractor said it did.

What is the goldfish test?

This is the part worth copying even if you install nothing. The Elephant is a long session with everything loaded (history, architecture, user journeys), and it drafts the specification. The Goldfish is a fresh session with no memory of any of that; it reads only the draft and the code, and tries to understand the plan.

If the Goldfish cannot explain the plan from the document alone, the document is not finished. Not the model’s fault. The document’s.

EGM runs several Goldfish with different personas (naive reader, tech lead, design critic, codebase auditor) before any code is written. The human owns the outcome: the AI explores and audits, the engineer decides. EGM is Apache-2.0 and, per its README, not an officially supported Google product.

We run a cheaper version on PRDs and SRSs: open a new session, paste the document, ask it to describe the system and list what is missing. What it finds is usually an assumption that lived in someone’s head.

What does this look like on one feature?

An illustrative case, not a client project: a bilingual agent answering supplier questions about invoices for a finance team.

1. The PRD states the problem: staff answer the same supplier questions by email every day. Out of scope: payments. The success measure is named up front with its definition and sample size.
2. The SRS lists testable requirements: identity check before any amount is disclosed, Arabic and English input, handoff to a person when the agent cannot source an answer.
3. A fresh session reads both and asks what happens when an invoice number matches two invoices. Nobody had decided; the SRS gains a requirement.
4. The plan names the systems to connect and the order of work, with one spec file for the identity check and one for the handoff.
5. The agent builds from the spec files; a person reviews the pull request against the SRS, not the chat history.
6. A month later a drift check finds one spec file has diverged from the code; the team chooses which side to fix.

What can a spec not fix?

• A one-line change. The Claude Code docs put it well: “If you could describe the diff in one sentence, skip the plan.” EGM agrees; its workflow is tools, not a prescription.
• A wrong idea. A precise SRS for a feature nobody needs ships a precise waste. That is what the PRD stage is for, and why the business signs it.
• Drift. Specs rot the moment code changes without them. EGM ships a drift report and suggests running it weekly; without something like it, the spec becomes fiction.
• Rubber-stamp review. A pull request approved without reading the spec is the paperwork of review without the judgement.
• Regulation. Where a sector requires its own documentation or review, that is your compliance team’s call. This note is our reading as builders, not legal advice.

What should you do next?

Pick one feature you are about to build and write its PRD on one page and its SRS on two. Before anyone opens an editor, paste both into a session with no history and ask it to explain the build back, then fix what it could not explain. Build from the result and review the pull request against the SRS. One feature is enough to learn whether the discipline pays for itself.