From vibes to a spec
On 2 September 2025 GitHub released the open-source Spec Kit and explained why. Vibe coding “can be great for quick prototypes,” it wrote, but is far less reliable for serious applications and existing codebases. Spec Kit runs in four phases: Specify what you are building and why, Plan the technical approach, break it into small testable Tasks, and only then Implement. GitHub’s own line: “we’re moving from ‘code is the source of truth’ to ‘intent is the source of truth’” (GitHub). Amazon’s Kiro and Tessl take similar routes.
What a spec has to contain
In the book I show this on a nail salon that lets clients give several phone numbers. The order “add a second field to the table and a button to the form” described two links out of seven, and the other five broke. The intent would have read differently: a client can enter several numbers and mark the main one; the reminder goes to the main one; old clients keep their numbers after the migration; the accountant’s export opens; all checks are green (chapter “A Goal Instead of an Instruction”). You can walk the chain in the experiment “Seven links behind one phone number”.
Besides the goal, a good intent has limits: what must not be done even for the sake of victory, and where the agent should stop and report (same chapter). Limits are most useful written as prohibitions (chapter “Architecture as a System of Prohibitions”). The usual place is AGENTS.md, a file the agent reads at the start of every session, which agents.md says over 60,000 open-source projects use (same chapter).
What a spec does not solve
In October 2025 Birgitta Böckeler of Thoughtworks tried Kiro, Spec Kit and Tessl and wrote down where they stall. Kiro turned a small bug fix into four user stories with 16 acceptance criteria. Spec Kit produced a pile of markdown, and she wrote, “I’d rather review code than all these markdown files.” And despite all the checklists, the agent sometimes skipped instructions and recreated classes the project already had (Martin Fowler’s site).
The last point does not surprise me. A rule in a text file is a request, and in a long session the agent may forget it (chapter “Architecture as a System of Prohibitions”). A spec works when its points become checks, and when the tests are written or approved by someone other than the agent writing the code (chapter “The Agent Cheats the Test”). Read the plan before the work starts, while the agent has not yet deleted anything (chapter “A Goal Instead of an Instruction”). Stating a task so it cannot be read two ways is the first module of my vibe coding course.
