Tests First, Prompts Second (Part 1: Before the Code)
When an agent writes the code, test-driven development doesn't start at the code. It starts at the PRD. Part 1 of 2: why the old rules matter more now, and the four steps before any code, with Dossier as the example.
Dossier, my self-hosted job search app, has more than 2,000 tests. I didn't write most of them. An agent did.
That sounds like the start of a story about AI writing your tests for you. It isn't. Almost every one of those tests started as a sentence I wrote first, in a plain document, before there was any code. Some of them still carry that sentence's ID in their name.
In Most days I don't write code anymore I said that I think before there's a repo, and that the documents live in the codebase. I never showed what that looks like. This two-part series does, with Dossier as the example from start to finish.
Here is my claim: when an agent writes the code, test-driven development doesn't start at the code. It starts at the PRD. The same goes for DRY. The old rules didn't lose their value when AI arrived. They became the main part of the job that is still ours.
This first part covers everything before the code: why it matters, the whole process on one page, and the first four steps. Part 2 goes from the tech spec to production.
Why the old rules matter more now
Code got cheap. Wrong code didn't.
A feature that would have taken me two days now takes an agent twenty minutes. But if my instruction was vague, I don't get a vague result. I get a complete, confident result that solves a slightly different problem. The speed is real, and so is the cost of going fast in the wrong direction.
The second problem is that agents add. They solve the problem in front of them, and solving it locally is always easier than finding what already exists. On one of my projects, the same logic ended up in four places, each a little different.
Martin Fowler describes the TDD cycle as red, green, refactor, and he says the most common mistake is skipping the last step. Without it, you end up with a messy pile of code fragments. That is exactly what an agent does by default. It never skips red or green, because those make the task look done. It skips refactor, because nobody asked for it.

And the mess shows up sooner than you expect. In his guide to software architecture, Fowler argues that low internal quality (he calls it cruft) makes software slower to change and full of more bugs, and that care for quality pays back in "weeks not months." With an agent producing code all day, the cruft also arrives in weeks. For me, week four is usually where it starts to hurt.
Then there are the tests themselves. When the same agent writes the code and then the tests, the tests describe the code. They check that it does what it does. When the tests come first, they describe what I meant. That is the real reason TDD matters more with AI: a test written first is my intent, in a form a machine can check. It also gives the agent something it can run by itself, again and again, without waiting for me.
None of this is new. AWS's overview of the software development lifecycle says its main aim is to lower project risk by planning upfront. Planning used to be the boring part before the real work. Now it is most of my work.
In Is Vibe Coding Really That Bad? I said the fair criticism is about builders who don't understand what they shipped. This process is how I make sure I'm still the one who understands.
The whole thing on one page
The process has eleven steps, grouped under the usual lifecycle phases, and it is a loop, not a line.

Steps 1 to 4 are this post. Market research and maintenance both send changes back to the PRD.
Three rules run through every step:
- Every step produces a document, and the document lives in the repo. Not in a chat window, and not in a wiki nobody opens. One step's output is the next step's input, for me and for the agent. In Dossier, that's
docs/prd.mdfor the product anddocs/dev-plan.mdfor the epics and tickets. - Every step is smaller and more concrete than the one before. A product becomes areas, areas become tickets, tickets become tests.
- Every step has a check. A requirement gets an acceptance criterion. The criterion becomes a test case in a ticket. The test case becomes a failing test, and only then does code appear. So every line of code can be traced back to a sentence in a document.
Who does what is simple too. I decide, the agent drafts, I check. That's the same at every step. Only the size of the thing changes.
This part covers steps 1 to 4. Part 2 covers steps 5 to 11.
Step 1: Define the product
Before the PRD there is one page, and it answers four questions. What is the problem? Who has it? Why now? What does success look like?
This is the step where AI helps least and matters most. I use the agent as a sparring partner here, not as a writer. I ask it to attack the idea: who already solves this, why would nobody use it, what is the hardest part. An agent asked to praise your idea will praise it, so don't ask.
For Dossier, that page came down to this:
- Problem: tailoring a resume and cover letter for every job is slow, so people either send a generic one or apply to fewer jobs. And generic AI writing tools happily invent skills, which is risky in an interview.
- Who: one job seeker who can run a Docker container, or has a friend who can.
- Success: from a pasted job posting to a reviewed, downloadable resume and cover letter in under five minutes.
Two principles came out of that page, and every later decision was checked against them. The user owns their data. And the AI never invents experience: every line it writes has to trace back to the profile. Keep that second one in mind. It comes back in every step.
Step 2: Write the PRD
The PRD turns that one page into requirements. Dossier's PRD has 84 of them today, each with an ID and a priority: P0 must ship, P1 should ship, P2 can wait.
The agent is good at drafting a PRD from the one-pager, and even better at finding what is missing: edge cases, error messages, the empty screen nobody thought about. I let it draft, and then I rewrite every requirement that is too vague to check.
That is the one rule I care about most in this step: if you can't write a test for it, it isn't a requirement yet. "The AI should be honest" is a wish. This is a requirement:
APP-9: If a request needs facts not in the profile (e.g. "Mention accessibility" without that skill), the AI declines and explains how to add it to the profile.
You can already see the test inside it. Given a profile without that skill, when the user asks for it, the AI declines and makes no edits. In Dossier's code there is a test with exactly that shape, and it is still named after the requirement: declines with guidance instead of inventing facts (APP-9).

This is where TDD really starts. Not with a failing test in an editor, but with a sentence written so precisely that its test can only look one way.
The other half of a good PRD is the non-goals, and with agents they matter even more. An agent doesn't know where your product ends. If something is useful and close by, it will happily build it. Non-goals are the fence. Dossier's first version listed them plainly: no multiple users, no applying on the user's behalf, no scraping job boards, no email or calendar integration, no mobile layouts, and no billing or analytics.
One more thing helped a lot. Dossier's PRD was written next to a clickable prototype of every screen, before any implementation started. The PRD said what each screen must do, and the prototype showed what it should look like. Together they left the agent very little to guess.
Step 3: See who else is solving it
Next comes market research: who else solves this problem, how they do it, and where they fall short.
An agent is genuinely strong here. It can search, read product pages and pricing, and put it all in a table much faster than I can. What it can't do is judge. It doesn't know which weakness matters to your user, and it will list twenty features as if they were all equally important. So the agent fills the table, and I decide what it means.
The output I want is short. A comparison table, then three lists: what we copy, what we skip, and where we are different.
The important part is that this step loops back. Research almost always changes the PRD. A feature you thought was special turns out to be standard. A competitor's weakness becomes your main goal. So the PRD isn't finished until this step is done.
For Dossier, the result fits into two lines of the PRD's problem section. Generic AI writing tools happily invent skills. Hosted job-search tools want your full personal history, often paid for with ads or data. Those two lines are the product's whole position: self-hosted, your own AI model (even a local one), and nothing invented.
Step 4: Split it into smaller PRDs
A full PRD is too big to hand to an agent in one go, and too big to review in one sitting. So it gets split.
I split by area of the product, not by technical layer. Dossier's PRD has eight areas, and each one has its own ID prefix:
| Area | Prefix |
|---|---|
| Authentication | AUTH |
| Profile | PRO |
| Base resume and themes | RES |
| New application | NEW |
| Application detail | APP |
| Applications list | LST |
| Dashboard | DSH |
| Settings | SET |
The prefix looks like a small detail, but it is what lets a test say (APP-9) and point to exactly one sentence.
In Dossier these areas are sections of one file, not eight files. For new features after the first release, I write a separate short document instead, like the one for the public release and the usage ping. It has the same shape every time: the goal, what is decided, and what is still open.

This is also the first place where DRY shows up, before any code exists. Some things are shared by every area: what a profile is, what a fact is, what "Draft" means as a status. In Dossier, the status model and the data model have their own sections, and the areas refer to them instead of repeating them. The reason is the same as in code: copied text drifts. The day a status changes, you update one copy, forget the other, and the agent reads the old one.
Dossier is DRY even as a product. Its first principle is that the profile is the source of truth: tailoring may rephrase, reorder and select, but it never adds facts. One profile, many resumes. That one sentence later shows up in the AI prompts and in the tests.
Isn't this just waterfall?
Four steps, and not one line of code. I know how this looks.
It's a fair worry. Waterfall's weakness is that each phase waits for the one before it, which leaves little room for change. Two things make this different.
First, the loop runs once for each small PRD, not once for the whole product. When one area is specified, it can move on to tickets and code while the next area is still being written.
Second, the documents change, and they say so. Dossier's PRD listed analytics and telemetry as a non-goal. One line there now notes an exception that was added in version 1.4. Email and calendar integration was a non-goal for v1, and it later shipped as an optional feature. The usage-ping document collected three "Changed on" notes at the top within three weeks. A document that changes is not a failure of planning. A document that is wrong and that nobody updates is.
It isn't slow either. Dossier's PRD is dated 27 September 2026, and the first database migration is from the evening of the same day. With an agent, the documents take hours, not weeks. What they save you is the cleanup in week four.
What we have so far
At the end of Part 1 there is still no code. But there is a lot: a one-page definition, a PRD where every requirement can be tested, a short picture of the market, and the PRD split into areas small enough for an agent to work on.
Most importantly, the tests already exist. Not as code yet, but as sentences that can only be tested one way.
In Part 2, those sentences become a tech spec, epics and tickets, and then failing tests, code, reviews and a release. I'll also show how Dossier turns rules into checks that an agent can't ignore, and why every bug becomes a test first.
Until then, I'm curious: when you build with AI, do your tests come before the code or after? And if you're honest, who writes them?
Sources
- Martin Fowler, Test Driven Development
- Martin Fowler, Software Architecture Guide
- AWS, What is SDLC?
- Dossier on GitHub
Membership
aien.me is supported by its readers. Pick a membership to join them.
- Espresso €2.99/month or €29.99/year A small cup that keeps this blog going ☕ Read every post and get new ones in your inbox.
- Cappuccino €5.99/month or €59.99/year For people who want to build along with me. Get every tutorial, the full source code, and new posts before anyone else.
- Full Pot €11.99/month or €119.99/year You’re keeping the whole pot brewing ☕ Get everything, help choose what I write next, and see your name on the supporters page.
Comments