From Vibe Coding to Spec-First: How Agentic IDEs Are Redefining Engineering Process

Prompt-by-prompt generation has a shelf life. The industry convergence on spec-first development isn’t a trend — it’s the architectural answer to a problem that tooling alone can’t fix: AI that generates code without a reviewed, version-controlled record of what it was supposed to build and why.

AWS made this concrete in April 2026 when it announced the end of Amazon Q Developer’s IDE plugins in favor of Kiro, which it defines as “an agentic development environment built from the ground up for spec-driven development.” The signal isn’t which AI model Kiro runs. It’s that AWS chose to retire a general-purpose coding assistant in favor of a tool that structures every development task as a reviewed specification before a single line of code is generated.

Cursor and Claude Code implement the same primitive with different levels of formality. What all three share is the same loop: research the codebase, produce a plan or spec, require human approval, then generate code against the approved artifact. The differences are a spectrum of durability — how long the spec persists, who can review it, and whether it exists in your repository as a first-class artifact or disappears when the session ends.

Why Vibe Coding Fails at Scale

Vibe coding — the pattern where you prompt an AI with a goal and let it figure out implementation details iteratively through chat — works until it doesn’t. The failure modes are concrete.

Architectural drift

AI agents have no persistent memory of architectural decisions across sessions. A prompt-driven workflow generates code that looks correct in isolation but gradually diverges from the intended architecture as successive edits accumulate without a pinned design document. A new session doesn’t know the database schema decisions from last week, the module boundary rule from two months ago, or the rate-limiting pattern the team standardized.

The fix isn’t a better prompt. It’s a committed design.md or a persistent project context file that the agent reads at the start of every session.

Missed edge cases

Free-form prompts have no enumerated acceptance criteria. “Build a checkout rate limiter” generates code that handles the happy path. The edge cases — what happens when the rate limiter backend is unavailable, what the response looks like for requests missing an account ID — get discovered through testing rather than specified in advance.

EARS notation solves this by forcing every edge case to be written as a requirement before any code is generated.

Untraceable decisions

The most underrated failure mode: intent lives in a chat transcript that is never reviewed, never diffed, and gone when the session ends. Six months later, no one knows why a piece of code works the way it does, what constraints were considered, or what alternatives were rejected. Code review catches what was written; it can’t catch what was never specified.

A version-controlled spec that goes through PR review alongside the code is the structural fix. The diff history becomes the decision log.

graph LR
    subgraph Vibe["Vibe Coding Failure"]
        direction TB
        A["Architectural drift\nno persistent design context"]
        B["Missed edge cases\nno acceptance criteria"]
        C["Untraceable decisions\nchat history disappears"]
    end
    subgraph Spec["Spec-First Remedy"]
        direction TB
        D["design.md + Steering file\npins architecture across sessions"]
        E["EARS unwanted-behavior +\nstate-driven criteria written first"]
        F["Version-controlled spec\nreviewed alongside code"]
    end
    A --> D
    B --> E
    C --> F

Each vibe-coding failure mode maps directly to the spec artifact that closes it. The spec doesn’t make AI faster — it makes the output reviewable.

The Pattern Everyone Converged On

The shared loop across Kiro, Cursor Plan Mode, and Claude Code plan mode is the same:

flowchart TD
    A["Intent\nrequirement or bug report"] --> B["AI researches codebase\nreads files, docs, existing patterns"]
    B --> C["AI drafts plan or spec\nrequirements / design / tasks"]
    C --> D{"Human approval gate"}
    D -->|"Approve"| E["AI generates code\nagainst approved spec only"]
    D -->|"Edit"| C
    D -->|"Reject"| A
    E --> F["PR review and merge\nnormal code review process"]

    style D fill:#4f9cf7,color:#000,stroke:#4f9cf7
    style E fill:#4ade80,color:#000,stroke:#4ade80

Code generation is blocked at the human approval gate. That single gate is the mechanism that transforms AI coding from a productivity tool into a process control.

Every tool in this category blocks code generation until a human approves the plan. For an engineering lead, this reframes the value proposition entirely: spec-first is not primarily about better prompts. It is about inserting a reviewable, version-controllable approval gate into the AI generation loop — the same control you already require for code via PR review, moved upstream to intent.

Why AWS sunsetting Q Developer is the signal that matters

The timeline from the AWS announcement is specific:

• May 15, 2026 — new Amazon Q Developer signups end
• May 29, 2026 — the latest Claude coding models, including Opus 4.7, become available exclusively on Kiro
• April 30, 2027 — end of support for Q Developer IDE plugins and paid subscriptions

Q Developer inside the AWS Management Console and first-party AWS experiences is not affected. This is an IDE-level decision: AWS is retiring the prompt-style coding assistant and directing development work toward a spec-driven tool.

AWS isn’t deprecating a product because a competitor beat it on benchmarks. It’s deprecating the interaction model — prompts as the source of truth — in favor of reviewed specifications as the source of truth.

What a Good AI Coding Spec Actually Looks Like

Kiro formalizes the spec into three files per feature, committed to a structured directory in the repository:

.kiro/specs/
└── checkout-rate-limit/
    ├── requirements.md
    ├── design.md
    └── tasks.md

flowchart LR
    A["requirements.md\nUser stories +\nEARS acceptance criteria"] -->|"Human approves"| B["design.md\nArchitecture, data flow,\nsequence diagrams"]
    B -->|"Human approves"| C["tasks.md\nDependency-ordered\nimplementation task list"]
    C -->|"Human approves"| D["Code generation\nagainst approved tasks only"]

    style A fill:#1e293b,color:#94a3b8,stroke:#4f9cf7
    style B fill:#1e293b,color:#94a3b8,stroke:#4f9cf7
    style C fill:#1e293b,color:#94a3b8,stroke:#4f9cf7
    style D fill:#4ade80,color:#000,stroke:#4ade80

Each phase requires explicit approval before the next begins. Code generation has access only to the approved tasks.md, not to the original chat or intent.

Because the spec is a file in the repository, it goes through the same pull request review, diff history, and CI that code does. A reviewer sees the spec change before the code change. This is the structural difference from chat-history-driven generation: the intent exists in a reviewable artifact, not a transcript that disappears when the session ends.

EARS notation: six templates, testable and lintable

Kiro’s requirements phase uses EARS (Easy Approach to Requirements Syntax), a constrained-English notation created at Rolls-Royce in 2009 for analyzing airworthiness regulations. EARS replaces free-form “the system should be fast and secure” prose with six fixed sentence templates, each anchored on “the system shall”:

Pattern	Template
Ubiquitous	The <system> shall <response>
State-driven	While <precondition>, the <system> shall <response>
Event-driven	When <trigger>, the <system> shall <response>
Optional feature	Where <feature included>, the <system> shall <response>
Unwanted behavior	If <trigger>, then the <system> shall <response>
Complex	While <precondition>, when <trigger>, the <system> shall <response>

The engineering value: every EARS requirement maps to an acceptance criterion (testable) and the fixed keyword grammar — WHEN / WHILE / IF / WHERE + SHALL — is regex-checkable in CI. A linter can reject a requirements.md that contains prose requirements missing a SHALL, or requirements that don’t follow an EARS template.

Here is what a requirements.md looks like using these templates for a checkout rate limiter:

# Requirements: Checkout Rate Limiting

## User Story
As a platform operator, I want checkout requests rate-limited per account
so that a single client cannot exhaust downstream payment capacity.

## Acceptance Criteria (EARS)
- The system shall reject more than 10 checkout requests per account per minute.
- When an account exceeds the limit, the system shall return HTTP 429 with a Retry-After header.
- While the rate limiter backend is unavailable, the system shall fail open and log a degraded-mode warning.
- If a request arrives without an account ID, then the system shall reject it with HTTP 400.

Each criterion is one EARS pattern: ubiquitous, event-driven, state-driven, and unwanted-behavior. All four are testable before a single line of implementation is written. The edge case for a missing account ID exists as a specification, not as something discovered in QA.

Kiro also defines an EARS variant for regression protection in bugfix specs: WHEN [condition] THEN the system SHALL CONTINUE TO [existing behavior]. This forces the existing behavior to be written down before any code changes, making regression testing explicit.

Spec as source of truth vs chat history

The central architectural claim of the spec-first movement is this: the spec — a reviewed, version-controlled document — replaces an ephemeral chat history as the source of truth. That shift has operational consequences.

A chat history is: not reviewed by anyone other than the author, not diffable, not searchable six months later, not checkable against the actual code, and gone when the vendor changes their retention policy. A requirements.md committed to the repository is all of those things.

Three Tools, One Pattern, Different Weights

All three tools implement the spec-first loop. They differ in where the artifact lives and how durable it is:

	Kiro	Cursor Plan Mode	Claude Code Plan Mode
Artifact	Multi-file spec in .kiro/specs/ (requirements.md, design.md, tasks.md)	Editable Markdown plan with file paths and code references	Ephemeral plan + persistent CLAUDE.md
Invocation	Spec workflow per feature	Shift+Tab in agent input	claude --permission-mode plan or Shift+Tab
Persisted by default	Yes — committed to repo	Optional — can be saved to repo	No — plan is a review gate, not a committed document
Enforcement hooks	Kiro Hooks, Steering files, custom subagents	Optional plan file in repo	CLAUDE.md + headless claude -p in CI
Best fit	Spec must outlive the task and be reviewed as a durable artifact	Collaborative planning with editable pre-flight review	Fast approval gate with persistent architectural context

Tool selection is a process decision — how much do you need the spec to persist and be reviewed — not a benchmark decision.

Kiro: the durable committed spec

Kiro runs requirements through design through tasks, with human approval at each phase. The output is three committed files that go through PR review like code. Hooks (automated triggers on file save or commit), Steering files (persistent project-level context that persists across sessions), and custom subagents augment the core workflow.

Kiro is the right choice when the spec needs to be a permanent, reviewable organizational artifact. It is the heaviest implementation by design.

Cursor Plan Mode: the editable pre-flight

Activated with Shift+Tab in the agent input, Cursor researches your codebase, asks clarifying questions, and generates a Markdown plan with file paths and code references. You edit the plan inline — adding or removing to-dos — then build directly from the plan. The plan can be saved to the repository, making it optionally durable.

# In the Cursor agent input:
Shift + Tab            # toggle Plan Mode
# Cursor researches the codebase, asks clarifying questions,
# and emits a Markdown plan with file paths and code references.
# Edit the plan inline (add/remove to-dos), then "build directly from your plan".

Claude Code plan mode: the lightweight approval gate

The lightest-weight implementation. Entered via claude --permission-mode plan or Shift+Tab mid-session, Claude reads files and proposes a plan but makes no edits until you approve:

# Enter plan mode for the whole session:
claude --permission-mode plan

# Or toggle mid-session:
# press Shift+Tab

Durable architectural context is carried in CLAUDE.md, which Claude reads fresh on every tool call:

# CLAUDE.md  (project root — read fresh on every tool call)
## Architecture
- All HTTP handlers live in src/handlers/; no business logic in handlers.
- Rate limiting is centralized in src/middleware/ratelimit.ts. Do not inline limits.
## Conventions
- Errors return RFC 7807 problem+json. Never return bare 500s.

The plan itself is a review gate, not a committed document, unless you explicitly save it. Claude Code optimizes for speed of approval over formality of artifact.

Enforcing Spec Compliance at Org Scale

The enforcement story uses primitives the audience already runs. No new product required.

Spec-as-code review

Because Kiro specs and Cursor plans are Markdown files in the repository, requiring a spec file to change in the same PR as the code is a CODEOWNERS or required-reviewer policy. A CODEOWNERS entry that routes .kiro/specs/ changes to the architecture review team puts spec approval on the same path as code approval.

EARS linting in CI

The fixed EARS grammar — WHEN / WHILE / IF / WHERE + SHALL — is regex-checkable. A CI step that scans requirements.md and rejects criteria missing a SHALL keyword enforces the notation without human oversight of the format.

Event-triggered checks

Kiro Hooks run automated checks on file save, commit, or other events — the native place to run spec-conformance checks. The tool-agnostic equivalent is a pre-commit hook or CI job triggered on changes to the spec directory.

Headless AI conformance gates

Claude Code runs non-interactively with claude -p for CI, pre-commit hooks, or batch processing. This enables an AI conformance gate: does this diff implement what the approved tasks.md describes, and nothing else?

# .github/workflows/spec-conformance.yml
name: Spec Conformance
on: [pull_request]
jobs:
  check-spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - name: Require a spec change alongside code
        run: |
          # Fail if src/ changed but no matching .kiro/specs/**/tasks.md changed.
          git diff --name-only origin/${{ github.base_ref }}...HEAD > changed.txt
          if grep -q '^src/' changed.txt && ! grep -q '^\.kiro/specs/.*tasks\.md' changed.txt; then
            echo "Code changed without a corresponding spec update."; exit 1
          fi
      - name: AI scope check (does the diff match the approved tasks.md?)
        run: |
          git diff origin/${{ github.base_ref }}...HEAD | \
            claude -p "Compare this diff to .kiro/specs/**/tasks.md. List any changes that are NOT in the approved task list. Exit nonzero if out-of-scope changes exist."

This is an illustrative enforcement pattern, not a turnkey workflow. The git diff gate uses standard CI primitives; the claude -p invocation shows the integration shape for AI-powered scope checking. Adapt it to your spec tooling.

ADR integration from design.md

Design decisions captured in design.md map cleanly onto Architecture Decision Records. The alternatives considered and rejected during the design review phase are already in the file. Automating ADR creation from design.md on merge is a one-step CI addition that turns the spec workflow into an automatic decision log.

The Golden Path: Requirement to Merge

For a platform team that has adopted spec-first across their AI tooling, a complete feature cycle looks like this:

1. Requirement — user story and EARS acceptance criteria written in requirements.md; edge cases are specified here, not discovered in testing
2. Design review — design.md reviewed alongside the requirements; architectural decisions and alternatives recorded
3. Task approval — tasks.md reviewed and approved; this is the only artifact the AI implements against
4. AI generates code — implementation runs against the approved task list; the CI spec-conformance gate fails any diff that contains changes not in tasks.md
5. Code review — the PR diff is reviewed; the spec is already in the repo, so reviewers can check code against intent without reading a chat transcript
6. Merge — spec and code land together in the same commit history; design decisions remain in the diff log, not a deleted conversation

The headless claude -p gate in step 4 and the CODEOWNERS policy in step 5 make compliance non-optional. The spec isn’t a good-faith suggestion — it’s enforced by the same infrastructure that enforces code review.

What to Do Monday Morning

The shift from vibe coding to spec-first doesn’t require replacing your toolchain. It requires one discipline change and one CI gate.

Start one feature with an in-repo spec. Pick any active feature and create .kiro/specs/<feature>/requirements.md. Write the acceptance criteria in EARS notation. You don’t need Kiro to do this — a Markdown file with EARS-formatted criteria in your repository is already more auditable than any chat transcript. The act of writing down the IF <missing account ID> THEN reject with HTTP 400 requirement before implementation will surface three edge cases you hadn’t considered.

Add the spec-change-required CI gate. The gate in the workflow above takes twenty minutes to add. After that, every PR that touches src/ without a corresponding spec update fails automatically. No new tool required. Standard CI primitives only.

The first spec-first feature will take longer to specify. The fifth will take less time than a vibe-coded feature required, because the edge cases were specified before implementation rather than discovered through testing after the fact.

Frequently asked questions

What is spec-driven development in AI coding tools?

Spec-driven development is a workflow where an AI agent produces structured artifacts — typically requirements, design, and a task list — that you review and approve before any code is generated. The reviewed spec, not the chat history, is the source of truth. Kiro formalizes this as requirements.md / design.md / tasks.md committed to the repo; Cursor and Claude Code implement lighter “plan before edit” versions of the same loop.

What is EARS notation and why use it for AI coding specs?

EARS (Easy Approach to Requirements Syntax), created at Rolls-Royce in 2009, is a set of six fixed sentence templates anchored on “the system shall” — ubiquitous, state-driven WHILE, event-driven WHEN, optional-feature WHERE, unwanted-behavior IF/THEN, and complex. It forces requirements to be unambiguous, individually testable, and machine-checkable in CI. A vague natural-language prompt has none of those properties.

How do I switch a coding tool into plan or spec mode?

In Claude Code, run claude --permission-mode plan or press Shift+Tab mid-session; it reads files and proposes a plan but makes no edits until you approve. In Cursor, press Shift+Tab in the agent input to enter Plan Mode, which researches your codebase, asks clarifying questions, and produces an editable Markdown plan. Kiro runs the full requirements, design, and tasks workflow with approval at each phase.

How can a platform team enforce that engineers actually write specs?

Use primitives you already have: require the spec file to change in the same PR as the code via CODEOWNERS or required reviewers on .kiro/specs/, lint requirements against the EARS grammar in CI, run conformance checks on commit via Kiro Hooks or a pre-commit hook, and add a headless AI gate using claude -p that flags diffs containing changes not in the approved tasks.md.

Is Amazon Q Developer going away, and do I have to move to Kiro?

Amazon Q Developer’s IDE plugins and paid subscriptions reach end of support on April 30, 2027, with new signups ending May 15, 2026 and the latest Claude coding models including Opus 4.7 available exclusively on Kiro after May 29, 2026. Q Developer inside the AWS Management Console and first-party AWS experiences is not affected. You are not forced onto Kiro specifically — Cursor and Claude Code implement the same spec-first pattern — but the IDE-plugin product is being retired in favor of the spec-driven approach.