Listen to this article
AI may have been used to generate this audio.
Press Space or K to play or pause, and J or L to go back or forward 15 seconds.Sources checked 7 October 2026.
Give an agent a ticket that says “add CSV export” and it can make several decisions before anyone notices a decision was required. It can choose which records to include, who may download them, how dates are formatted and whether an empty result is an error. The code may be perfectly reasonable. The product team may have meant something else.
Writing down those decisions would give the agent a better starting point. The case for abandoning Agile needs more than that.
GitHub’s Spec Kit now takes a feature through specification, planning, tasks, implementation and convergence. It gives the agent written context that survives beyond the conversation that produced it. The order resembles a familiar software project plan. [1]
The resemblance has encouraged a claim that AI is bringing waterfall back. Marc Brooker, writing about Kiro, makes a useful distinction: a specification can remain editable throughout development. He argues for making design explicit without assuming that a team can discover all its requirements before building anything. [2]
What the agent needs before it starts
For the export feature, a useful specification could be half a page. A workspace administrator can export paid invoices from the current workspace. The export uses the active filters. Money retains its currency. A user without permission gets no file. The team still needs to decide what to do with cancelled invoices.
That last sentence matters. A document becomes dangerous when it turns an unanswered question into an apparently settled requirement. An agent can implement the assumption so thoroughly that changing it later touches the database query, tests, help text and interface.
Decision | Write before implementation | Learn from use |
|---|---|---|
Access | Which role can export which records | Whether administrators need delegated access |
File contents | Fields, currencies and filtering rules | Which fields customers use elsewhere |
Completion | A file opens and matches the selected records | Whether the export removes the customer’s manual work |
The specification should distinguish decisions the team has made from assumptions it wants to test. Attaching a test to an assumption does not make the assumption correct. It makes the implementation consistent with it.
The export also exposes a limit to the idea that the agent can write its own requirements. It can suggest sensible defaults. It cannot tell whether the finance team treats a cancelled invoice as a historical record, a mistake to omit, or a separate transaction to reconcile. That decision belongs to the people responsible for the accounts. An apparently complete specification can conceal the fact that nobody asked them.
I would put a name beside that unresolved decision. The document should say who can answer it, which part of the implementation depends on it and what the agent may do while it waits. It could build the permission check and the download interface. It should leave the disputed accounting rule open. This gives the team a useful stopping point before a guess spreads through the code.
A specification can become stale within an afternoon
Suppose the finance team answers after the first implementation. They need cancelled invoices included, with a cancellation date. Editing the prose alone leaves a contradictory system: the document describes one behaviour, the query implements another and the tests may approve the old behaviour. The review has to trace the decision through all three.
Record a changed requirement, the reason for it and the affected behaviour. Keep that record short enough to read during review. A generated history of every conversation would make it harder to find the one sentence that changed the export.
The contract is especially useful when several agents divide the work. An interface agent and a database agent need the same definition of a cancelled invoice. A shared document can help, provided they work from the same revision. A filename such as requirements.md does not guarantee agreement about what is inside it.
Where waterfall would return
A team could ask AI to generate a large requirements document, approve it once and spend a month producing everything inside it. Customer feedback would arrive after the expensive decisions. Faster code generation would shorten part of that schedule while leaving the late discovery intact.
Another team could specify one export, put it in front of the person who requested it, discover that their accounting software needs a different identifier, and revise the specification that afternoon. Both teams wrote documents. Their feedback schedules differ.
The Agile principles already support frequent delivery and changes to requirements, including late changes. They do not prescribe a two-week delay before anyone can learn something useful. [3] A sprint calendar is an organisational choice, and an agent completing a task early is a reason to revisit that choice.
There is evidence that developers are producing these documents at scale. The August SPECMINE preprint collected specification files from tens of thousands of public repositories. It is a corpus for studying the practice, not a trial showing that specifications improve delivery. [4] Counting spec files cannot tell us whether anyone kept them current.
Some work does deserve a longer design phase. A data migration, a permission boundary or a change that is expensive to reverse may need detailed review before execution. The feedback loop there can begin with a dry run, a prototype or a review of real records. “Ship faster” is an incomplete instruction when the first failed trial could damage customer data.
What I would retire first is the ritual that makes a team wait for a scheduled ceremony to resolve a question it can answer today. Keep planning where it reduces risk. Keep specifications where they preserve a decision. Reopen them when customer use contradicts the assumption. Neither a sprint board nor a generated document can do that judgement for the team.
For an agent-assisted project, I would keep the specification beside the code and change both in the same review when behaviour changes. I would also record the unresolved product question that the next release is supposed to answer. If nobody can name that question, making the implementation faster will not supply one.
Sources
One email when we publish. Research, product decisions, and what teams report back.
