Stop Re-Prompting: Why Your AI Coding Tool Needs a Spec
If you're constantly re-prompting Cursor, Claude, or Copilot, the problem isn't the AI — it's the missing spec. Here's how to fix it.
You open Cursor, type a prompt, get code back, realize it's wrong, refine the prompt, get slightly better code, refine again, add more context, get code that's almost right but handles errors wrong, add the error handling requirements, and thirty minutes later you have something that works but looks nothing like what you'd have written yourself.
This is the re-prompting loop, and nearly every developer using AI code generation tools in 2026 has experienced it. The instinct is to blame the AI. But the AI isn't the problem. The missing spec is.
The Re-Prompting Loop
The re-prompting loop looks like this:
- You write a prompt describing what you want.
- The AI produces code based on its interpretation.
- The code is wrong in some way: wrong field names, missing validation, incorrect error handling, wrong assumptions about your data model.
- You add clarification to your prompt.
- The AI produces new code, but now it's lost some context from the previous attempt.
- You add more clarification.
- Repeat until you give up and write it yourself, or accept code that's "close enough."
The fundamental issue is that each prompt is a lossy compression of what you actually need. You're trying to convey your data model, business rules, API contracts, error handling strategy, and coding conventions in a few sentences of natural language. That's not enough information for a human developer to work from, and it's not enough for an AI either.
Why Context Windows Aren't Enough
"But Cursor can see my whole codebase!" True. Modern AI coding tools can index your repository and pull in relevant files. This helps with coding style and existing patterns. But it doesn't solve the fundamental problem.
Your codebase tells the AI how things ARE built. It doesn't tell the AI how things SHOULD be built. When you're implementing a new feature, the AI needs to know:
- What entities are involved and what fields they have
- What the API endpoints should look like
- What validation rules apply
- What error states exist and how to handle them
- What the user flow looks like
- What edge cases matter
None of this exists in your codebase yet. It exists in your head, scattered across Slack threads, in a Figma file, or in a brief ticket description. The AI can't read any of those things.
Context windows give the AI access to your existing code. They don't give it access to your intent.
What AI Tools Actually Need: Structured Context
AI code generation tools produce their best output when given structured, unambiguous context. Not paragraphs of prose. Not a conversation. Structured data that describes exactly what to build.
Here's the difference in practice.
The Prompting Approach
Create an API endpoint for creating a project. It should require
authentication. The project needs a name and description. Return the
created project.
This prompt is missing: field constraints, which organization the project belongs to, what happens if the name is a duplicate, the exact response format, what status code to return, whether the description is required, and dozens of other details.
The AI will fill in every gap with assumptions. Some will be right. Many won't.
The Spec-Driven Approach
endpoint: POST /api/v1/projects
auth: required (Bearer token)
description: Create a new project within the user's current organization
request:
headers:
Authorization: Bearer <token>
body:
name:
type: string
required: true
min_length: 1
max_length: 100
constraints: unique within organization
description:
type: string
required: false
max_length: 2000
visibility:
type: enum
values: [private, team, public]
default: private
response:
201:
id: uuid
name: string
description: string | null
visibility: string
organization_id: uuid
created_by: uuid
created_at: ISO 8601 datetime
updated_at: ISO 8601 datetime
400:
error:
code: "VALIDATION_ERROR"
message: string
fields: object (field-level errors)
409:
error:
code: "DUPLICATE_NAME"
message: "A project with this name already exists in your organization"
When an AI receives this level of detail, the output is dramatically different. Field names match your conventions. Validation is correct on the first try. Error responses use the right format. The AI doesn't have to guess because you've removed the guesswork.
How a Product Spec Gives AI Persistent Understanding
Individual prompts are ephemeral. You type them, the AI responds, and the context starts to degrade as the conversation grows. Specs are persistent. They sit in your repository or your spec tool, and they serve as a single source of truth across every AI interaction.
Consider what happens when you have a complete spec:
Day 1: You give the AI the spec and it generates the API endpoint. The code matches the spec exactly.
Day 2: A different developer gives the AI the same spec and asks it to generate the frontend form. The form fields match the API contract because they're both derived from the same spec.
Day 3: You ask the AI to write tests. It generates tests that validate every response code, every validation rule, and every edge case, because they're all defined in the spec.
Day 14: A new developer joins the team. They read the spec and understand the feature completely, without archaeology through Slack history or guessing at undocumented behavior.
The spec acts as a shared memory between every developer and every AI tool on the team. It eliminates the "it works on my machine" equivalent of "it works with my prompts."
Before and After: A Real Feature
Let's walk through a concrete example. You need to build a comment system on specs.
Without a Spec
Your first prompt:
Add comments to specs. Users should be able to add comments and see
existing ones.
The AI builds a basic CRUD system. But it uses text for the field name instead of body. It stores comments flat instead of supporting threads. It doesn't handle mentions. It returns all comments at once instead of paginating. You spend 40 minutes re-prompting:
Actually, can you use "body" instead of "text"? Also support threaded
replies. And add pagination. And use the same error format as the rest
of the API. And add a "resolved" status for comments. And support
@mentions that link to users...
Each re-prompt risks breaking something that was working before.
With a Spec
You spend 15 minutes writing the spec:
feature: Spec Comments
description: Threaded comments on specification documents
models:
Comment:
fields:
id: uuid
spec_id: uuid, foreign key -> Spec
author_id: uuid, foreign key -> User
parent_id: uuid, nullable, foreign key -> Comment (self-referential)
body: string, required, max 5000 chars, supports markdown
is_resolved: boolean, default false
resolved_by: uuid, nullable, foreign key -> User
created_at: datetime
updated_at: datetime
relationships:
- belongs_to: Spec
- belongs_to: User (as author)
- has_many: Comment (as replies, via parent_id)
indexes:
- spec_id, created_at
endpoints:
GET /api/v1/specs/{spec_id}/comments:
auth: required
query_params:
page: integer, default 1
per_page: integer, default 25, max 100
root_only: boolean, default true # only top-level comments
response:
200:
comments: Comment[] (includes author name, reply count)
total: integer
page: integer
per_page: integer
POST /api/v1/specs/{spec_id}/comments:
auth: required
request:
body:
body: string, required, max 5000
parent_id: uuid, optional
response:
201: Comment (includes author details)
400: validation error
404: spec not found
PATCH /api/v1/specs/{spec_id}/comments/{id}/resolve:
auth: required (author or spec owner only)
response:
200: Comment (with is_resolved: true, resolved_by populated)
403: not authorized to resolve
You give this to your AI tool once. The generated code matches your data model, uses the right field names, supports threading, includes pagination, and handles errors correctly. Total time: 15 minutes for the spec, plus maybe 5 minutes reviewing the generated code.
Practical Tips for Writing AI-Ready Specs
If you want to start writing specs that make your AI tools more effective, here are the practices that matter most:
Be explicit about field names and types
AI tools will use whatever names you specify. If you don't specify, they'll guess. And they'll guess differently every time.
# Good: explicit names and types
user_id: uuid, foreign key -> User
created_at: datetime (ISO 8601)
# Bad: ambiguous
user: reference
date: timestamp
Define error responses, not just happy paths
The happy path is usually easy for AI to get right. The errors are where things diverge. Define every error response explicitly.
errors:
400:
code: "VALIDATION_ERROR"
message: "Name is required"
403:
code: "FORBIDDEN"
message: "You do not have permission to edit this resource"
404:
code: "NOT_FOUND"
message: "Spec not found"
409:
code: "CONFLICT"
message: "A spec with this name already exists"
Include constraints and validation rules
Min/max lengths, uniqueness requirements, format patterns, allowed values. These are the details that AI tools most often get wrong, and the easiest to specify.
name:
type: string
required: true
min_length: 1
max_length: 100
pattern: "^[a-zA-Z0-9][a-zA-Z0-9 _-]*$"
constraints:
- unique within organization
- cannot start with a number
Specify relationships explicitly
Don't make the AI figure out how your entities relate. State it directly.
relationships:
Project:
- belongs_to: Organization (via organization_id)
- has_many: Spec
- has_many: ProjectMember
Spec:
- belongs_to: Project (via project_id)
- belongs_to: User (as author, via author_id)
- has_many: Comment
Keep specs in version control
Specs should live alongside your code. They should be reviewable in pull requests. They should evolve with your product. A spec that's out of date is almost worse than no spec at all.
The Shift From Prompting to Specifying
The developers getting the most value from AI code generation tools in 2026 aren't the ones writing better prompts. They're the ones who have stopped relying on prompts as the primary input.
Instead, they write structured specs that define what to build. They feed those specs to their AI tools as context. And they get back code that matches their requirements on the first attempt.
Intent provides a structured environment for writing these specs: features, user stories, data models, API contracts, and architecture decisions, all in one place. It integrates directly with AI coding tools through MCP, so your specs become persistent context that any AI tool can access.
The re-prompting loop is a symptom of a missing spec. Write the spec, and the loop disappears.