How to Write Specifications That AI Coding Tools Actually Follow

The quality of AI-generated code is directly proportional to the quality of the specification. Here's how to write specs that produce production-grade results instead of fragile prototypes.

Vague prompts produce vague code. Here's how to write specifications for Cursor, Replit, and other AI coding tools that produce production-grade results — including the 7 sections every spec needs.

The difference between a vibe-coded prototype that works and one that falls apart is almost never the AI tool. It's the prompt.

"Build me a booking app" produces a demo. A detailed specification produces a product. The AI tool is the same in both cases. The input determines the output.

I've seen this pattern across hundreds of projects. Founders who start with a clear specification build faster, encounter fewer regressions, and arrive at production quality with less rework. Founders who improvise prompt-by-prompt spend weeks fixing issues that a specification would have prevented.

Here's how to write specifications that AI coding tools actually follow — and that produce code worth launching.

Why Specifications Matter More With AI Tools

With human developers, you can have a conversation. You can say "build a booking system" and the developer asks clarifying questions: "How many users? What happens on cancellation? Do you need payments?" The developer fills in the gaps through dialogue and experience.

AI tools don't ask clarifying questions. They fill in every gap with their best guess — and their guesses are based on the most common patterns in their training data, not on your specific business. A "booking app" prompt produces a generic booking system. It won't include your cancellation policy, your pricing tiers, your timezone handling requirements, or the specific edge cases that matter for your business.

The specification replaces the conversation. It gives the AI the context that a human developer would acquire through questions — upfront, in writing, before a single line of code is generated.

The 7 Sections Every Specification Needs

1. User Roles and Permissions

Who uses this application and what can each person do?

Be specific. Don't write "there are admin and regular users." Write:

Admin users can: create and edit service listings, view all bookings across all providers, manage user accounts, access revenue dashboards, configure system settings.

Provider users can: view their own bookings only, update their availability, see their own earnings, mark bookings as completed.

Customer users can: browse services, make bookings, view their own booking history, cancel bookings (with 24-hour notice), update their profile.

This precision prevents the AI from generating an admin panel that regular users can access, or a dashboard that shows one provider's data to another.

2. Data Model

What data does the application store and how does it relate?

Define every table (or collection), every field, and every relationship. Include data types, required vs optional fields, and constraints.

For example: "Users table: id (UUID, primary key), email (string, unique, required), name (string, required), role (enum: admin/provider/customer, required), created_at (timestamp). Bookings table: id (UUID, primary key), customer_id (UUID, foreign key to Users), provider_id (UUID, foreign key to Users), service_id (UUID, foreign key to Services), start_time (timestamp, required), end_time (timestamp, required), status (enum: pending/confirmed/completed/canceled, default: pending)."

This level of detail means the AI generates a database schema that matches your business model, rather than guessing at field names, types, and relationships.

3. API Endpoints

What endpoints does the application need, what do they accept, and what do they return?

For each endpoint: the HTTP method, the path, the required authentication, the request body schema, the response schema, and the error responses.

"POST /api/bookings — Requires customer authentication. Body: { service_id: UUID, provider_id: UUID, start_time: ISO datetime, end_time: ISO datetime }. Returns 201 with booking object on success. Returns 400 if time slot is unavailable. Returns 401 if not authenticated. Returns 403 if user is not a customer."

Specifying endpoints prevents the AI from inventing its own API structure — which leads to inconsistent naming, missing authentication, and endpoints that return too much or too little data.

4. Business Rules

This is the most important section and the one most specifications miss. Business rules are the logic that makes your application yours — not a generic version of the same idea.

Examples of business rules that must be explicit:

"Bookings can only be made during provider availability hours." "Customers can cancel bookings with more than 24 hours notice for a full refund. Cancellations within 24 hours incur a 50% fee." "A provider cannot have overlapping bookings." "Subscription payments are processed on the 1st of each month. Failed payments trigger a 7-day grace period before access is revoked." "Provider earnings are calculated as 80% of the booking price. The platform retains 20%."

Without these rules, the AI generates generic logic — or no logic at all. It won't implement cancellation policies, fee calculations, or scheduling constraints unless told to. And the business logic it generates by default is almost always wrong for your specific business.

5. Edge Cases

What should happen in unusual but realistic scenarios?

"What if two customers try to book the same slot simultaneously?" (The first to confirm gets it; the second sees an 'unavailable' message.) "What if a provider marks a slot as unavailable after a customer has booked it?" (The booking stands; the provider must contact the customer to reschedule.) "What if a payment webhook arrives before the checkout redirect completes?" (The webhook updates the database; the redirect checks the database for current status.) "What if a user changes timezone between booking and the appointment?" (All times stored in UTC; displayed in user's current timezone.)

Edge cases are where AI tools fail most consistently. They require real-world understanding that the AI doesn't have. Your specification provides that understanding.

6. Security Requirements

What must be protected and how?

"All API endpoints require authentication except: GET /api/services (public listing) and POST /api/auth/login." "Provider data is isolated — a provider can never see another provider's bookings or earnings." "Payment processing uses Stripe webhooks with signature verification. No client-side payment state." "Passwords hashed with bcrypt. Session tokens expire after 24 hours." "Admin endpoints require admin role verified server-side on every request."

Without explicit security requirements, AI tools default to minimal security — or worse, client-side security checks that can be bypassed.

7. UI Components and Flows

What screens does the application have and how do users navigate between them?

You don't need pixel-perfect mockups. You need a list of screens, the components on each screen, and the navigation flow. "Dashboard shows: upcoming bookings (sorted by date), today's earnings, quick actions (new booking, view schedule). Clicking a booking shows the booking detail screen. The booking detail screen shows: customer name, service, time, status, and action buttons (confirm, cancel, complete)."

This prevents the AI from generating UI that doesn't match your mental model — a common source of back-and-forth prompting that wastes time.

The Specification Workflow

Here's how I use specifications with AI tools across every build.

Step 1: Write the spec. Using the 7 sections above, document the complete application. This takes 2-4 hours for a typical SaaS product. BuildKits can generate a starting point that you refine.

Step 2: Include the spec in the AI's context. In Cursor, add the spec as a .cursorrules file or reference it in your project documentation. In Replit, include it in the project README. The AI should reference the spec for every code generation.

Step 3: Prompt against the spec, not from scratch. Instead of "build a booking system," prompt: "Implement the POST /api/bookings endpoint as described in the specification, including the time slot availability check and the authentication requirement." The AI generates code that matches the spec rather than inventing its own interpretation.

Step 4: Validate against the spec. After the AI generates code, check it against the specification. Does the endpoint accept the right inputs? Return the right outputs? Enforce the right business rules? Handle the right errors? The spec is your acceptance criteria.

Step 5: Update the spec as requirements change. When the product evolves, update the specification first, then prompt the AI to implement the changes. This prevents the drift that causes codebase destruction — every change is grounded in an updated specification.

What Happens Without a Specification

Without a spec, AI coding follows a predictable degradation pattern.

Days 1-3: Rapid progress. The AI generates features fast. The app looks impressive. Everything works.

Days 4-7: Inconsistency creeps in. Different prompts produce different patterns. The API isn't consistent. The data model has redundancies. Business logic is scattered across files.

Days 8-14: Regressions begin. New features break old ones. The AI doesn't remember what it built yesterday. Fixing one thing breaks another.

Days 15+: The wall. The codebase is tangled. Every prompt makes it worse. The founder is stuck between an app that's 80% done and production that requires a rebuild.

A specification doesn't guarantee a smooth build. But it prevents the specific degradation patterns — inconsistency, regressions, and business logic gaps — that cause most vibe-coded projects to stall.

Frequently Asked Questions

How long should a specification be?

For a typical SaaS product: 3-8 pages. Complex enough to cover the 7 sections, concise enough that you and the AI can reference it quickly. Don't write a novel — write precise requirements. A well-structured 5-page spec is more useful than a 30-page document.

Can I use AI to write the specification?

Yes — with caveats. AI can help structure the spec and suggest requirements you might miss. But the business rules, edge cases, and security requirements must come from you (or someone who understands the business). AI can write the format; you fill in the substance.

Should I write the spec before or after prototyping?

Either works. If you're exploring an idea, prototype first, then write a spec for the production build based on what you learned. If you have a clear vision, write the spec first and use it to guide both prototyping and production. The spec for the production build is what matters — the prototype is a learning tool.

What's the difference between a spec and a prompt?

A prompt is a single instruction for a single task. A spec is a complete description of the entire application. Prompts implement parts of the spec; the spec ensures all the parts fit together. Using prompts without a spec is like building a house without blueprints — each room might look fine, but the house doesn't hold together.

Does BuildKits replace a Discovery Sprint?

BuildKits generates a specification you can use immediately with AI tools — it's designed for founders who want to start building now. A Discovery Sprint (£5,000) produces a more comprehensive specification that includes business audit, competitive analysis, technical feasibility, and a detailed plan reviewed by someone with 18 years of production experience. BuildKits is the starting point; the Discovery Sprint is the full treatment.

---