Spec-First AI Development in Practice: Kiro, Plan Modes and Spec Kit Compared

From Vibe Coding to Spec-First

The first wave of AI coding was conversational: describe what you want, accept the diff, repeat. It's fantastic for prototypes and throwaway scripts. On a production codebase it has a predictable failure mode: the agent fills gaps in your request with plausible guesses, and you find out in review, or in production, which guesses were wrong.

The industry's answer is spec-first development: agree what to build and how, in writing, before any code is generated. The spec becomes the contract for the agent, the context for the reviewer and the documentation afterwards. Three families of tooling have emerged.

1. Kiro: The Spec Is the Workflow

Kiro, AWS's agentic IDE, makes specs the primary way of working. A feature request becomes three files:

• requirements.md: user stories with acceptance criteria written in EARS notation ("WHEN a customer pauses a delivery THE SYSTEM SHALL move the charge date to the new delivery date"). The structured syntax makes requirements testable and hard to leave vague.
• design.md: the technical design: components, data models, interfaces, error handling, testing strategy, often with diagrams.
• tasks.md: an ordered implementation plan of discrete tasks, each traced back to requirements, which the agent executes one by one.

Two other Kiro concepts matter for teams: steering files (persistent project knowledge: tech stack, conventions, structure) and hooks (agent actions triggered by events, like updating tests when a file is saved).

Strengths: the most rigorous and traceable workflow of the three; requirements are explicit and reviewable by non-engineers. Weaknesses: real overhead for small changes; ties the workflow to a particular IDE.

2. Plan Modes: Lightweight Specs Inside Your Existing Agent

Claude Code and Cursor both have a plan mode: the agent explores the codebase read-only, asks clarifying questions and produces an implementation plan, and only starts editing once you approve it.

In Claude Code, you switch into plan mode (Shift+Tab cycles modes), describe the task and review the plan. Persistent context lives in CLAUDE.md files (project conventions, commands, architecture rules), and repeatable workflows can be packaged as skills or slash commands, so "plan a new queue worker" follows your team's pattern every time.

A good pattern is to have the plan written to a file in the repo, reviewed like any other document, then implemented against:

> Pause subscription from the account page. Read docs/specs/pause.md first.
  Follow the DeliverySchedule patterns. Write the plan to docs/plans/pause-plan.md.
 
[agent explores, asks 3 clarifying questions, writes plan]
 
> The plan looks right, except use the existing feature flag service. Implement it.

Strengths: minimal ceremony; works in the tools engineers already use; scales from a ten-minute fix to a multi-day feature. Weaknesses: rigour depends on team discipline; plans can be skimmed and approved without real review.

3. Spec Kit: Open-Source, Agent-Agnostic Specs

GitHub's Spec Kit is an open-source toolkit that brings a spec-driven process to whichever agent you use: Claude Code, GitHub Copilot, Cursor, Gemini CLI and others. It installs templates and slash commands that walk through a sequence:

1. Constitution: project-wide principles and non-negotiables (testing standards, architecture rules).
2. Specify: what and why, with no technology decisions.
3. Plan: the technical approach, stack and architecture.
4. Tasks: a breakdown of implementable, testable units.
5. Implement: the agent works through the tasks.

The artefacts live as Markdown in the repository. Command names have evolved between releases, so check the current README.

Strengths: agent-agnostic; everything is plain files in git; good for teams using a mix of tools. Weaknesses: it's a process, not a product; adoption depends on people actually following it.

Side by Side

How I'd Choose

• Small team, fast-moving: plan mode plus a well-maintained instruction file. Write a short spec only for work touching money, customer data or complex business rules.
• Growing team with several agents in use: Spec Kit, or your own lightweight templates in the repo, so specs look the same whatever tool produced the code.
• Regulated domains or work needing traceability: Kiro's requirements-to-tasks traceability, or an equivalent template-driven process, is worth the overhead.

What Makes Any of Them Work

The tool matters less than these habits:

1. Review the spec harder than the code. A wrong spec produces confidently wrong code. Ten minutes on the plan saves an hour in review.
2. Make acceptance criteria testable. If a criterion can't become a test, it's not specific enough.
3. Keep specs in the repo. Next to the code, versioned, and linked from the pull request.
4. Point at existing patterns. "Follow the emails worker" gives the agent more useful context than a paragraph of description.
5. Update the spec when reality changes. A stale spec misleads the next agent, and the next engineer.

The Takeaway

Spec-first isn't bureaucracy for AI's sake. It's the discipline good engineers always practised (think before you build, agree on what done means), made explicit because the implementer is now an agent that won't ask unless you let it. Pick the lightest workflow your risk profile allows, and scale formality with the stakes of the change.