A coding agent can build a feature quickly, but speed does not tell it what the product should become. Spec-Driven Development (SDD) puts the developer’s intent, constraints, and acceptance criteria in written specifications before the agent changes code. The agent handles implementation; the developer retains control of the architecture and decides whether the result is ready.

Why another prompt may not fix the problem

Informal prompting, often called vibe coding, can be enough for a small, disposable task. It becomes less dependable when a project needs consistent design decisions across many files. A request for a button, followed by a complaint that the result is too large, may improve that button. It does not establish a durable rule for the rest of the application.

Repeated corrections also fill the agent’s context window—the limited amount of information it can use at once—with conversational history. As that history grows, the project’s original intent becomes harder to recover. A coding agent can inspect files, run commands, and make changes across a workspace, so an unclear instruction can affect much more than one reply.

Tangled speech bubbles contrast with ordered documents feeding a machine that produces code blocks

▲ Improvised prompts versus structured specs

A specification gives those decisions a more stable home. It states what the feature must do and why, while leaving appropriate implementation choices to the agent. A short edit to a technical constraint can lead to changes across hundreds of lines of code; that leverage makes reviewing the constraint before implementation especially important.

Establish the project constitution

Start with three Markdown files in a version-controlled /specs directory. Together, they form a project constitution: a shared baseline that the developer can revise deliberately as requirements change.

Three document pages support an unfinished building frame as a worker points toward the plans

▲ Three documents of the project constitution

  • mission.md defines the product’s purpose, audience, and intended behavior.
  • tech-stack.md records approved technologies and architectural constraints.
  • roadmap.md divides the work into ordered phases. Small phases containing one to three independently shippable features are easier to inspect than a single broad request.

A worked example used a satirical clinic application for overworked AI agents. Its initial technical choices included TypeScript, Hono for the server, and SQLite for data storage. Those choices belonged in project documents, not just in an agent conversation. The developer reviewed the generated files as Git diffs and committed them before starting feature work.

An agent can help draft the constitution by asking structured questions about scope and technical choices. The developer still needs to settle consequential decisions. The goal is not to specify every variable name; it is to make the mission, boundaries, dependencies, and standards explicit.

Run each feature through three stages

Treat each roadmap phase as a controlled loop rather than a continuous chat. Keep its requirements, task plan, and checks in separate files, then review each stage before moving on.

The spec-driven loop for each roadmap phase No Yes Write the mission, tech stackand roadmap specs Clear the context andcreate a feature branch Write requirements,plan and validation The agent implements the plan Human review passes? Fix the code andsync the spec Commit and mergethe feature Replan, then startthe next phase
▲ The spec-driven loop for each roadmap phase
  1. Specify. Create a feature branch and write requirements.md, plan.md, and validation.md. The requirements define the feature and its limits; the plan orders the work; the validation file states how to judge the result. Ask the agent to clarify unresolved choices before it writes the files.
  2. Implement. Review and commit the feature spec, then direct the agent to execute the plan. Batch execution may suit straightforward scaffolding. Sensitive changes, such as database migrations, warrant smaller task groups and closer inspection.
  3. Validate. Run the planned checks, inspect the code diff, and test the behavior yourself. An agent reporting that its tests passed is not a substitute for human review. Update the spec if the accepted implementation differs from it, then commit and merge the feature.

For an initial server phase, the plan covered dependencies, a development script, a home page, and verification. The agent ran a TypeScript check and tested the local endpoint; the developer also checked the rendered page. During review, the developer moved page sections into separate component files using an editor’s refactoring tools. That manual improvement created a mismatch with the written plan, so the feature documents were updated before the branch was merged.

That last step matters. If code changes but its specifications do not, the next agent session may follow an outdated description of the project. In Claude Code, clearing conversation history with /clear before a new feature phase can help the agent start from the committed project files rather than stale chat context.

Replan between phases, and check large changes twice

The constitution is a baseline, not a ban on change. Between feature branches, pause to review what the project now needs. In the clinic example, a replanning phase added Vitest tests. A separate, simulated stakeholder update said 40% of the application’s users accessed it on mobile browsers, prompting mobile-first styling requirements and viewport changes. Recording such decisions in the technical standards kept later features aligned with them.

Review effort should also match the size of the change. For one larger feature, three parallel agent reviewers examined TypeScript, database architecture, and HTML accessibility. Their findings included a missing SQLite foreign-key enforcement setting and unnecessary runtime dependencies. The agent patched the issues, but its review did not replace the developer’s judgment.

A later build combined several roadmap phases into a ten-task minimum viable product plan. The running application supported the intended booking workflow, yet a reverse check against the requirements found a gap: invalid appointment input returned HTTP 200 where the specification called for HTTP 400. A working interface had not proved that every acceptance criterion was met. Comparing the implementation back to the spec exposed what the first pass missed.

Use the same approach on existing code

A new repository is not required. For an existing project without specifications, have the agent inspect the code, package configuration, README, and task list. Review the resulting mission, tech-stack, and roadmap files against what the application actually does before committing them. From there, the next maintenance task can follow the same specify–implement–validate loop.

Reusable Agent Skills can package repeated work, such as preparing a feature branch and drafting spec files. Because a skill may run commands, inspect its code before installing it. Keeping the project’s decisions in Markdown and Git also makes the workflow easier to carry between agents such as Claude Code and OpenAI Codex; the chat history does not have to serve as the only project record.

Start small and keep the human review

Write the three constitution files, choose one narrow roadmap phase, and define its requirements, plan, and validation criteria before asking an agent to code. Inspect the resulting diff and behavior, bring the documents back into sync with accepted changes, and replan before the next phase. The practical value of SDD is not that an agent becomes infallible. It is that the developer has a written basis for directing its work and catching what it missed.