Spec-driven development: Why AI coding agents now write the plan before the code

Spec-driven development is a way of building software with AI agents in which a written specification comes first and the code comes second. The spec says what the software should do and why. The agent, and the human, then check the code against that document instead of against a loose chat prompt.

Google’s new Elephant-Goldfish Model plugin for Claude Code is one recent example of the idea.

Telling a builder what to build, in writing

Picture hiring a contractor to renovate a kitchen. You could say “make it nicer” and hope. Or you could hand over a drawing that lists the layout, the appliances, the budget and what must not change. The second route costs more time upfront, but misunderstandings show up on paper instead of inside the walls.

An AI coding agent is the contractor. A short prompt such as “add a login page” leaves hundreds of choices unstated, and the agent fills each one with a guess. Spec-driven development moves those choices into a document that a person can read, correct and approve before work begins.

The loop: Specify, plan, split, build

Most versions of the method follow the same four steps. GitHub described them in a September 2025 blog post by Den Delimarsky, a principal product manager there:

1. Specify: you describe what you are building and why, focusing on users, problems and success criteria. The agent drafts a detailed spec.
2. Plan: you add technical constraints such as the stack, architecture and performance targets. The agent produces a technical plan.
3. Tasks: the agent breaks the spec and plan into small, testable pieces.
4. Implement: the agent works through the tasks, and you review focused changes instead of one large code dump.

Each step produces a Markdown file that feeds the next. The agent gets structured context, and the human keeps a checkpoint at every stage. GitHub’s post stresses that the person’s job is to verify each phase, looking for gaps and missed edge cases.

Where the idea came from

The immediate trigger was what developers call vibe coding: describe a goal, receive code that looks right, then find it does not work. GitHub’s post lists code that does not compile, code that solves only part of the problem, and architecture the team would not have chosen. Its argument is that the problem lies in the approach, not in the agent’s ability to write code.

GitHub released Spec Kit, an open source toolkit, in September 2025 and called it an experiment. Its current documentation describes a five-phase flow (Specify, Plan, Tasks, Implement, Converge) and lists dozens of supported coding agents. The setup command is specify init. The post itself is promotional and contains no benchmarks, so claims about productivity gains remain the vendor’s.

The underlying habit is much older. Software teams have long written design documents before building large features. What changed is that an AI agent can now draft the document, and read it as its working instructions.

Having the spec attacked before it is trusted

A spec is only useful if it is good, and an agent that wrote it in a long session tends to see its own gaps as obvious. Google’s Elephant-Goldfish Model (EGM) repository tackles that weak point directly.

In EGM, the “elephant” is the agent that holds the project context and drafts the spec. The “goldfish” are fresh reviewers that see the draft and its referenced source material but not the earlier conversation. They have no hidden assumptions to lean on, so anything the document leaves unsaid becomes a visible question. The human makes the trade-offs and approves the spec before implementation.

The plugin packages this as seven skills, including Brainstorm, Draft, Review and Drift report. The repository says the host agent must be able to start fresh sub-agents. If it cannot, EGM stops the review instead of falling back to a weaker check. The repository also states that a review does not replace tests or human judgment, and that it is not an officially supported Google product.

GitHub’s Spec Kit and EGM overlap but differ in emphasis. Spec Kit structures the path from spec to tasks to code. EGM concentrates on stress-testing the design document itself.

Trade-offs and limits

Writing and reviewing a spec takes time, and for a small, clear bug fix it is usually overkill. The EGM repository says it is meant for features that need design decisions, not small fixes. GitHub’s own post presents the method for greenfield projects, feature work in existing systems and legacy modernization.

Other limits are practical:

• Cost: multi-agent reviews launch several sub-agents, which draw on the host tool’s model quota, as noted in our news coverage of EGM.
• Document sprawl: GitHub’s post asks for feedback on walls of text and on managing many spec and task files at scale.
• False confidence: a polished spec can still be wrong. Human review stays essential in both projects’ own descriptions.
• Drift: specs go stale as code changes, which is why EGM includes a skill that compares checked-in documents with the current source.

What to watch next

Three questions will decide whether the approach sticks. First, whether teams measure results, since public evidence so far comes mostly from the toolmakers. Second, how tools keep specs and code in sync over months, not days. Third, whether fresh-context review becomes a standard feature of coding agents instead of a plugin.

The practical test for any team is simple: does a reviewer who has never seen the project understand the spec well enough to find its holes? If yes, the agent is far less likely to build the wrong thing.