Is the user story template enough for a coding agent?
Stefan-Iulian Tesoi · · 5 min read
No. The user story template records who wants something and why, and a person fills in the rest from context. A coding agent needs the parts it leaves out: which repository, what observable result, and what check proves the result. Keep the "so that" line as the reason, and write the executable detail beneath it.
The template is not wrong. It was built for a reader who would ask questions, and a coding agent mostly does not ask. It guesses, and its guesses compile.
What was the user story template designed for?
To start a conversation, not to replace one. The "As a [role], I want [goal], so that [reason]" user story format was invented at Connextra in the UK in 2001, and Mike Cohn's 2004 book User Stories Applied made it the default way to write a backlog item. Strip out the blanks and what remains, "as a user I want so that", is the skeleton most backlogs still fill in.
In 2001 too, Ron Jeffries described a user story in three parts: the card, the conversation and the confirmation. The card was small on purpose. It held a sentence, and the detail lived in the talk between the person who wanted the feature and the person building it. The confirmation, the tests that proved it worked, came out of that talk.
Cohn's own description of user stories still puts it plainly:
"That sentence is a reminder to have a conversation; the full requirement emerges through the conversation that follows."
A coding agent receives the card. The conversation and the confirmation were never written down, because for twenty-five years nobody needed them to be.
What does the template leave out?
Everything a person supplies from memory. A developer on the team knows which repository holds billing, what "export" means in this product and what done looks like. A coding agent knows what is in the item and in the repository it was pointed at, which may be the wrong one.
| Template slot | What a person fills in from context | What a coding agent needs written down |
|---|---|---|
| As a [role] | Who that is and what they can already do | The role or permission, by name |
| I want [goal] | Where it goes in the product | The repository and the screen or endpoint |
| So that [reason] | How good is good enough | Acceptance criteria someone can run |
| (no slot) | What not to touch | Scope, including what is out of it |
| (no slot) | What has to happen first | Dependencies, already resolved |
The last two rows have no slot at all. Together with the repository, the outcome and runnable criteria, they are the five fields an agent cannot infer, and the sentence holds none of them. Leaving them out does not cause an error. It causes confident, plausible work in the wrong place: a one-line item to add a blog section once produced a blog built in the wrong repository.
Why is the 'so that' line still worth keeping?
Because it is the one part that tells an agent which way to decide when the criteria run out. Every item leaves small choices open: a date format, a sort order, what an empty state says. "So that I can reconcile invoices in our accounting system" settles several of them before anyone asks, because reconciliation needs exact amounts and stable identifiers, not friendly labels.
The reason also serves the reviewer. A change can meet every criterion and still miss the point, and the "so that" line is what a person reads to notice. Drop it and review becomes a checklist. Keep it and review can ask whether the work serves the user it named.
One story rewritten for an agent
The original, typical of the user story examples in most backlogs:
As a finance admin, I want to export invoices, so that I can reconcile them in our accounting system.
Rewritten, with the sentence kept on top:
- Story: the sentence above, unchanged.
- Repository:
billing-service. - Outcome: a finance admin can download one month's invoices as a CSV file from the Invoices page.
- Acceptance criteria: exporting September 2026 returns one row per invoice issued that month, with number, date, net, tax and total; amounts have two decimals and no currency symbol; a user without the finance admin role gets a 403 from the export endpoint; a month with no invoices returns a header row and nothing else.
- Not in scope: PDF export and scheduled exports.
- Dependencies: none.
The sentence still says who and why. The criteria are what Jeffries called the confirmation, written before the build instead of discovered in review. In Laimonade the sentence stays in the description and the criteria are a separate list, and when an agent hands work back it is the criteria that are checked against its commits, not the sentence.
Should teams drop the template altogether?
Only for work with no user in it. A dependency upgrade written as "As a developer, I want to upgrade Node, so that we stay supported" wears the template as a costume, and it pushes the useful detail, which version and which test suite proves nothing broke, further down the item.
Keep the template where three things are true:
- There is a real user whose behaviour will change.
- The reason is not obvious from the goal.
- Small decisions are left open that the reason can settle.
For everything else, write the outcome and the criteria directly. The quickest way to learn which items need what is to hand a few to an agent unedited and read the results, the exercise in teaching a team to write executable items. The wider set of defects that exercise turns up is in a backlog an agent can read.
Frequently asked questions
Does INVEST still apply to agent work?
Yes, every letter of it. Bill Wake's INVEST asks that a story be independent, negotiable, valuable, estimable, small and testable. For an agent, small and testable carry the most weight: small enough to finish in one run, and testable by something that can be executed. Negotiable changes most, because the negotiating has to be finished before the item is handed over.
Should bugs use the same template?
No. A bug report needs steps to reproduce, the expected result, the actual result and the environment, and none of those fit a role, goal and reason sentence. "As a user, I want the export not to crash" adds words and loses the stack trace. Write the reproduction first, then a criterion that fails before the fix and passes after it.
Can an agent turn a story into executable criteria?
It can draft them, and the draft is worth having. An agent reading the repository will often propose sensible criteria for the obvious cases. What it cannot do is decide what the user needed when the story is ambiguous, so a person still accepts or corrects the criteria before the build starts.