TL;DR: AI coding agents did not eliminate the need for software requirements; they moved the requirements into the prompt. If you cannot say what the product should do, who it is for, and how you will know it works, the agent will guess, and it guesses with great confidence. A short user story with results driven acceptance criteria is the fastest way to turn “build me a thing” into a prompt an agent can actually deliver on.
Many people who have never shipped software are now building their own tools from scratch with little or no help from a developer. That is a good thing. What is less good is watching the same people skip the one step that would make the tool work: deciding what it is supposed to do before asking a machine to build it.
In the days now passed, requirements came out of discovery sessions, stakeholder interviews, and market research. We would run a two-day design studio and walk out with a minimum viable product plus two or three releases’ worth of features to design and build. Today, nobody has time for all that noise. Just launch the prompt and pray your very descriptive prose triggers the correct agents, using the proper skills, to produce a near-production prototype you can hype up on Reddit.
That is an exaggeration, but you get the picture. You do not necessarily need the full design studio, all the time. You do need a clear idea of what your software/product should do and how it should behave. This article walks through the lightweight process I use to write a requirements.md file for AI coding agents, and why a humble user story is still the best tool in the box.
Why Do Requirements Still Matter When an AI Is Writing the Code?
Because the agent can only build toward an outcome you have described. Requirements are the statement of what the product is supposed to do and what you expect to happen when someone uses it. Everything else in the build hangs off that statement.
Think of the agent as a very fast contractor who has never seen your house. “Make the kitchen better” gets you a kitchen, and it might even be nice, but it will not be your kitchen. “Replace the island with a peninsula so two people can cook without colliding” gets you something you can inspect and accept or reject.
Good requirements do four jobs at once:
- They state the expected outcome, which is the thing you will measure the result against.
- They lay the groundwork for the technical needs and the experience the user should have.
- They produce success criteria, which become your test cases, whether a human or an agent runs them.
- They inform user stories, which keep the focus on the person using the thing rather than the thing itself.
Skip them to get a quick result, and you often get a quick result that does not do the job. If it does not lead to an efficient outcome, where was the value?
What Is a User Story?
A user story is an informal, one-sentence description of a software feature written from the perspective of the person who will use it. Its purpose is to make the value of the feature obvious, not to specify the implementation.
The classic format, popularized by Mike Cohn and now standard across agile teams, looks like this:
As a [type of user], I want [some capability], so that [some benefit].
Each clause earns its place. The first names who this is for. The second says what they need to be able to do. The third is the one people drop, and it is the most important: it states why, which is what lets you (or an agent) make sensible trade-offs when the details get fuzzy.
In traditional product work, user stories are the raw material feature requirements are built from. They get estimated, prioritized, and bundled into sprints and releases. In the current landscape they still do all of that, with one difference: you can put a story into practice immediately. Write it, hand it to the agent, see what comes back. The feedback loop that used to take a sprint now takes an afternoon.
How Do User Stories Make AI Coding Assistants Better?
A user story forces you to answer three questions the agent would otherwise have to guess at: what is this for, what should happen, and how will it be used. Those three answers are most of what separates a good prompt from a vague one.
- It defines the purpose of the request. The “so that” clause tells the model what problem it is solving, which shapes dozens of small decisions you never explicitly made.
- It tells the model what the expected outcome is. The agent now has a target to build toward and to check its own work against.
- It makes you think about how the feature will actually be used. This is the sneaky benefit. Writing “as a team lead, I want to export last month’s timesheets” makes you realize you never decided what “last month” means for a contractor who started on the 20th.
A story also gives you a place to hang acceptance criteria, which is where the real leverage is.
What Does Acceptance Criteria Add?
Acceptance criteria turn a story into something testable. The Given/When/Then format from Behavior-Driven Development is the one I use, because an agent can read it as a spec and a tester can read it as a checklist. This method relies on expected outcomes, verses actual outcomes, once the feature is tested.
The rule I hold myself to: each criterion must be verifiable by one person in one sitting, and every story gets at least one failure or edge case. Agents are optimistic and programmed to please by nature. If you do not describe the unhappy path, you will not get one.
How Does This Look in Practice?
Here is the whole thing applied to a small, boring, realistic feature: exporting timesheet data from an internal tool.
The prompt many people may write:
Add a CSV export to the timesheet page.
The same request as a user story with acceptance criteria:
## TS-US04: Export monthly timesheets
As a team lead, I want to export my team's approved timesheets for a
selected month as a CSV, so that I can submit them to payroll without
retyping hours.
### Acceptance criteria
- Given I am on the Timesheets page and have selected a month,
When I click "Export CSV",
Then a file named `timesheets-YYYY-MM.csv` downloads containing one row
per person per day, with columns: employee_id, name, date, hours, status.
- Given some timesheets for the month are still unapproved,
When I click "Export CSV",
Then only approved entries are included and a notice shows how many
were excluded.
- Given there are no approved timesheets for the selected month,
When I click "Export CSV",
Then no file downloads and I see "No approved timesheets for March 2026."
- Given the export contains more than 10,000 rows,
When I click "Export CSV",
Then the export is generated in the background and I am emailed a link
within five minutes.
Paste that into Claude Code, Copilot, or whichever agent you favor, and notice what changes. The file naming is decided. The columns are decided. The unapproved-entries question, the one that would have surfaced as a bug report two weeks later, is handled on the first pass. The agent can also write its own tests straight from the criteria, because the criteria are tests wearing a trench coat.
The first prompt produces a button. The second produces a feature.
What Does the Full Process Look Like?
User stories are step two of a four-step loop I run on every project, large or small. The whole thing fits in a single Markdown file that lives in the repo next to the code.
- State the outcome. One paragraph: what the product or feature is for, who it serves, and what is explicitly out of scope. Non-goals are as valuable as goals; they stop the agent from helpfully building things you did not ask for.
- Write user stories. One per capability or feature, each with a stable ID (
TS-US04) so you can reference it later in commits, tests, and conversations with the agent. - Attach acceptance criteria. Given/When/Then, at least one edge case per story, numbers and units wherever a limit exists (“more than 10,000 rows,” not “a lot of rows”).
- Keep a
requirements.mdand point the agent at it. The file becomes the agent’s source of truth. When I ask for a change, I update the file first and tell the agent which IDs changed. No renumbering, ever; retired items get marked withdrawn with a reason.
That is the whole process. It takes less time than the first round of “no, not like that” you would otherwise spend, and it leaves you with something a human developer could pick up without a single interview.
You can reference my past article on setting up agent and project instructions for more information on effective ways to orchestrate your project execution. In addition you can refer to my post about learning some of the fundamentals when using AI and LLM tools for building effective products and software.
Key Takeaways
- AI coding agents moved requirements into the prompt; they did not make requirements optional.
- A user story answers three questions the agent would otherwise guess at: who this is for, what they need to do, and why.
- Acceptance criteria in Given/When/Then form double as the agent’s spec and your test plan, so write them before you prompt.
- Every story needs at least one failure or edge case, because agents only build the unhappy path when you describe it.
- A single
requirements.mdwith stable IDs gives the agent a source of truth and gives you a change history you can actually read.
FAQ
Do I really need user stories for a small personal project? You need the thinking, not the ceremony. Even a two-line story with one acceptance criterion forces you to decide what “done” means before the agent starts. For a weekend tool that takes five minutes and saves you an hour of re-prompting.
Should the user story go in the prompt or in a file?
Both, eventually. Put the story directly in the prompt when you are exploring. Once the project has more than a handful of features, move everything into a requirements.md in the repo and reference stories by ID. Agents handle “implement TS-US04” far better than a paragraph pasted from memory.
What is the difference between a user story and a functional requirement? A user story describes a capability from the user’s point of view and explains why it matters. A functional requirement is a single, testable statement of system behavior, usually written as “The system shall…” Stories tell you what to build and why; functional requirements pin down exactly how the system behaves. For most small projects, stories plus acceptance criteria are enough.
Can I ask the AI to write the user stories for me? Yes, and it is a good way to get a first draft. Give it your one-paragraph outcome statement and ask for stories with acceptance criteria. Then read every line and edit it, because the model will invent scope you never wanted. The value of the exercise is in the deciding, and the deciding is still your job.