AI AI Tools Guidebook
AI Tool Tutorials

AI Spec-to-Code: Avoid the Half-Built-Feature Trap

Turn a written feature spec into shipped code without the half-built-feature trap.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

Most “AI builds my feature” stories end with 80% done and the last 20% impossible to finish — because the spec was being written implicitly inside the code, and the agent kept guessing wrong. The fix is upstream: write a one-page spec, force the AI to surface its ambiguities, break it into tickets that each have a real acceptance test, then ship one ticket at a time. This is the workflow that turns “agent demos look great but my real feature is stuck” into actual shipped software.

What this tutorial solves

The half-built-feature trap: an agent appears to build your feature, you celebrate the demo, then over the next week you discover edge cases the spec never covered, scope creep the AI silently introduced, and tests that pass but don’t actually exercise the new behavior. This workflow front-loads the spec rigor that the implicit-spec approach pays for later in panic.

Who this is for

Indie devs, prototypers, and developers building features under deadline pressure. Especially relevant if you’ve shipped 2-3 AI-built features and noticed they all need a “second pass” that takes longer than the first. Less relevant for trivial features (one function, one acceptance test) — for those the overhead isn’t worth it.

When to reach for it

When the feature is big enough to need a one-page spec — typically anything that touches 3+ files, multiple endpoints, or a UI flow with branches. When deadline pressure tempts you to skip planning (“just have the agent write it”). When you’ve been burned before by AI-built features that demoed well and broke on edge cases.

When this is NOT the right tool

Pure research or exploration tasks where the spec doesn’t exist yet. Write a prototype first to learn what’s possible, then derive the spec from what you discovered. Forcing spec-first on exploratory work creates fake clarity and steers you away from learning.

Before you start

  • Have a concrete user story: who is doing what, why, and what success looks like. Vague stories produce vague specs.
  • Know your codebase well enough to predict which files will be touched. The AI will guess; your job is to course-correct.
  • Pick a model with strong code reasoning: Claude Sonnet 4.6 / Opus 4.7+ or GPT-5.5. Smaller models miss the “what’s NOT in the spec” prompt’s intent.
  • Set up a feature branch and a draft PR before any AI involvement. The PR description is your spec’s home.

Step by step

  1. Write the spec FIRST. One page: user story, acceptance criteria, edge cases, what is explicitly out of scope. Out-of-scope is the most-skipped section and the most valuable one.
  2. Paste the spec into the AI. Ask: “List ambiguities and missing details in this spec. Don’t code yet. Just questions.” Sample output you want: “What happens if the user uploads a 50MB image? Is anonymous upload allowed? What’s the error UX for rate-limit?”
  3. Fix the spec based on the gaps the AI surfaced. This is the highest-leverage 10 minutes of the whole task. Every ambiguity now is a half-day of rework later.
  4. Break the spec into tickets. Ask: “Break this spec into 5-8 implementable tickets. For each: title, files likely touched, one-sentence acceptance test.”
  5. Implement one ticket at a time. Hand each ticket to the agent with the spec attached. After each, run the acceptance test. If it passes, commit. If not, fix before moving on.
  6. Run integration tests after all tickets. The full spec’s acceptance criteria become integration tests. Don’t ship until they pass.
  7. Reject scope additions. When the AI suggests “you should also handle X,” check the spec. If X isn’t there, defer it to a follow-up issue. “Just adding this real quick” is how features take 3x estimated time.

Sample spec template

# Feature: <name>
## User story
As a <role>, I want to <action>, so that <outcome>.

## Acceptance criteria
- [ ] Criterion 1 (concrete, testable)
- [ ] Criterion 2
- [ ] Criterion 3

## Edge cases
- What happens when X
- What happens when Y

## Out of scope (explicitly NOT building)
- Feature A (deferred)
- Feature B (different ticket)

## Data model changes
<schema diff or "none">

## API surface
<endpoint changes or "none">

First-run exercise

Pick a feature you shipped recently that had scope creep or late-discovered edge cases. Retroactively write the one-page spec it should have had. Compare to what you actually built. The gap between the two is your “spec discipline” learning material. Then run the workflow on the next real feature and measure: did writing the spec save you net time, or did it feel like overhead? Most devs find the break-even at feature 2.

Quality check

  • Does the spec fit on one page? If it doesn’t, either split the feature or your acceptance criteria are too verbose.
  • Did the AI surface real ambiguities, or did it produce generic “have you considered error handling?” prompts? Generic = your spec was too thin or your prompt didn’t push hard.
  • Do tickets map cleanly to spec sections? If a ticket spans two sections, it’s two tickets.
  • Does each ticket have an acceptance test that can be checked in 30 seconds? If “manual verification” is the test, the spec isn’t tight enough.
  • Did the agent suggest scope additions you rejected? Count them. >3 rejections means your spec is doing its job; 0 means the agent isn’t being ambitious.

Advanced tips

  • For UI features, sketch wireframes (even rough). AI implements UI from a sketch much better than from prose.
  • For backend features, include the data model in the spec. Half the implementation flows from it.
  • Keep the spec as a doc next to the code (e.g., docs/specs/feature-name.md). Update when reality diverges from spec — those updates are the audit trail.
  • For agent-based implementations, give the agent the FULL spec for every ticket, not just the ticket. Without the full spec, the agent reinvents context.

Output checklist

  • One-page spec exists with acceptance criteria and out-of-scope items.
  • AI surfaced ambiguities and you resolved them in writing (not in your head).
  • Tickets list maps cleanly to spec sections, each with a real acceptance test.
  • Each ticket has an acceptance test that ran (not just “looks fine in dev”).
  • Final integration test against the full spec passes.
  • The PR description references the spec; the spec lives in the repo.

FAQ

  • How long does writing a spec take?: 30-60 minutes for a one-day feature. Saves multiples of that downstream in clarity, not just rework.
  • Can AI write the spec?: It can draft. You own the decisions. Specs without ownership produce code without direction. Treat AI as a stenographer at this stage, not an author.
  • What about specs for refactors?: Slightly different shape: “before / after, why, blast radius.” See the AI refactor workflow.
  • What if the spec changes mid-build?: Update the spec doc first, then continue. The spec doc is the source of truth, not your memory.
  • How does this work with Claude Code or Codex?: Same workflow; just paste the spec into the agent’s context (or its rules file) so it has it for every ticket.
  • Isn’t this just waterfall?: One-page specs aren’t waterfall; they’re “definition of done” for one feature. Real waterfall is 30 pages with sign-off gates.

Tags: #AI coding #Tutorial #Workflow

Related Articles