How to write a functional design an AI can decompose
A functional design that decomposes well into user stories is not written in a special format for machines. It is written the way good analysis has always been written — numbered sections, behaviour instead of screens, exceptions included, actors named — and left with its contradictions intact so the agent can report them instead of silently resolving them.
Teams that start feeding documents to an agent usually ask what format it wants. The honest answer is that format barely matters and precision matters enormously. An agent decomposing an analysis is doing the same job an experienced analyst does when handed someone else’s document: working out what behaviour is being described, what is missing, and what contradicts.
Seven habits make the difference between a backlog you edit and one you rewrite. All seven also make the document better for human readers, which is a reasonable test of whether advice about writing for AI is any good.
1. Number your sections
This is the highest-value habit and it costs nothing. A numbered section becomes a trace on every item derived from it, which gives you two things: from a story back to the paragraph that asked for it, and from a paragraph forward to everything built for it. That second direction is how you find what was silently dropped.
2. Describe behaviour, not screens
“Add a lockout screen” does not say when it appears, how long it lasts, or what the user can do about it. “A customer is locked out for fifteen minutes after five failed attempts, and receives an e-mail” decomposes into a story with criteria you can test. Screens are an implementation of behaviour, and they are the part the team is best placed to design.
3. Put the numbers in
Five attempts. Fifteen minutes. Two seconds. Thirty days. Every unquantified requirement becomes either a question — which costs a round trip — or an assumption, which costs more. If you do not know the number yet, write that you do not know it; that is a decision the document can carry.
4. Write the unhappy paths
Most production bugs live in the cases nobody wrote down: the timeout, the duplicate submission, the empty list, the expired session, the customer who has two accounts. An agent will not invent these, and neither will most developers under time pressure. A section per feature called “what can go wrong” is worth more than any template.
5. Name the actors
The customer, the back-office user, the scheduled job, the external system. These become the “as a …” of your user stories, and — more usefully — they surface the moment two of them need different behaviour from the same feature.
6. Leave the contradictions in
This is the counterintuitive one. The instinct is to tidy a document before submitting it. Resist it. A contradiction the agent reports is a question you get to ask the person who wrote it; one you smoothed over is a decision you made on their behalf without telling them, and it will surface in acceptance as a defect with your name on it.
7. Separate requirement from wish
Documents mix “must”, “should” and “would be nice” in the same paragraph, and a decomposition treats them all as work. Mark them, even crudely. The alternative is a backlog where nice-to-haves have the same weight as regulatory obligations, and the first sprint plan makes that everyone’s problem.
What to check in the result
- Coverage: which numbered sections produced no items? Either they needed none, or something was missed — and you cannot tell without asking.
- Criteria that are testable: if a criterion cannot fail, it is not a criterion.
- Reported contradictions: read these first. They are the highest-value output of the entire run.
- Size: stories that will obviously hit a per-task budget ceiling are stories that should be split now, not discovered later.
What format should a functional design be in for AI decomposition?
Plain text or Markdown is enough; format is not the constraint. Numbered sections, behaviour described rather than screens, quantified rules and explicit exceptions matter far more than any structure or template.
Should I clean up contradictions before submitting the document?
No. A reported contradiction is a question you can take back to the author; a resolved one is a decision you made silently on their behalf. Contradictions are among the most valuable output of a decomposition run.
How long should the document be?
As long as the behaviour needs. Length is not the variable that matters — precision is. A three-page document with quantified rules and named exceptions decomposes better than thirty pages of prose about goals.