Getting Started beginner 6 min read

How to Write a Spec that the AI Cannot Misunderstand

Hướng dẫn chi tiết về How to Write a Spec that the AI Cannot Misunderstand trong Vibe Coding dành cho None.

How to Write a Spec that the AI Cannot Misunderstand

You’ve likely felt the rush. You open your favorite AI coding assistant, describe a vision for a new feature, and watch in awe as hundreds of lines of code materialize in seconds. This is the magic of Vibe Coding: the ability to translate thought into software at the speed of conversation. But then, the “Aha!” moment turns into an “Oh no” moment. The layout is broken, the logic is circular, or the AI has hallucinated a library that doesn’t exist. You spend the next three hours fighting the AI, trying to “fix” what it built, only to realize you could have written it faster by hand.

The problem isn’t the AI’s intelligence; it’s the Intent Gap. Natural language is inherently ambiguous. When you say “make it look modern,” you might mean minimalism, while the AI thinks you mean neon gradients and glassmorphism. To truly master Vibe Coding, you must graduate from “prompting” to AI-Proof Specification.

This article will show you exactly how to write a spec that acts as a deterministic contract between your vision and the AI’s execution. By the end, you’ll be able to build complex, production-ready features on the first try, every time.

Core Concepts: The Mental Model of AI Orchestration

Before we look at the template, we need to shift our perspective. In traditional software engineering, a specification is for other humans. In Vibe Coding, a specification is an Instruction Set for a Non-Deterministic Processor.

1. The “Hyper-Literate Intern” Rule

Treat the AI as a hyper-literate intern who has read every book on programming but has zero common sense regarding your specific project. If you don’t explicitly forbid a behavior, the intern will assume it’s allowed. If you don’t define a data structure, the intern will invent one.

2. Constraints are Freedom

Beginners often think that giving the AI more “freedom” leads to more creative solutions. In reality, freedom leads to hallucinations. High-quality specifications are 80% constraints and 20% goals. By narrowing the “possibility space,” you force the AI to focus its reasoning on the logic that actually matters.

3. The Single Source of Truth (SSoT)

An unmistakable spec must be the absolute authority. If your spec says “Use Tailwind CSS” but your current codebase uses Vanilla CSS, the AI will face a “Context Clash.” Part of writing a great spec is ensuring it aligns with the existing environment or explicitly instructs the AI to refactor it.

The Anatomy of an Unmistakable Spec

A spec that the AI cannot misunderstand follows a rigid structure. At Todyle, we use a framework called the P.A.C.T. Structure: Purpose, Architecture, Components, and Tests.

I. The Purpose (The “Why” and “Who”)

Don’t just say what to build; explain the goal. This gives the AI a “Reasoning Anchor.” If the AI understands the user’s intent, it can make better micro-decisions when the spec is silent on a minor detail.

  • Bad: “Build a login form.”
  • AI-Proof: “Build a high-security login form for a B2B SaaS platform. The goal is to minimize friction while ensuring MFA (Multi-Factor Authentication) compliance. Target audience: Corporate security officers.”

II. Architecture & Tech Stack (The “How”)

This is where most vibes fail. You must define the “Linguistic Boundaries” of the code.

  • Tech Stack: List the exact versions of frameworks (e.g., React 19, Next.js 15, Tailwind v4).
  • File Structure: Tell the AI exactly where the files should go. Don’t let it guess your folder convention.
  • State Management: Define if you want the state to be local, global (Zustand/Redux), or server-side (React Query).

III. Functional & Visual Components (The “What”)

Break the UI and Logic into atomic units. Use a checklist format. AI models are statistically better at following bulleted lists than long-form paragraphs.

  • Inputs: Type-safe props and validation rules (e.g., “Email must follow Regex X”).
  • States: Loading, Error, Success, and Empty states.
  • Visuals: Specific spacing (e.g., p-4, gap-2), color tokens, and responsive breakpoints.

IV. The Verification Gate (The “Done”)

Define success. Tell the AI what tests it must write or what console logs must appear to prove the code works.

Practical Example: From “Vibe” to “Spec”

Let’s look at a real-world transformation. Imagine you want to build a Feature Toggle Dashboard.

The “Bad” Vibe (The Hallucination Trap)

“Hey AI, build me a cool dashboard where I can turn features on and off for my app. Use a toggle switch and make it look like Stripe. Use a database to save the state.”

Why this fails:

  1. “Cool” is subjective: The AI will pick a random UI kit.
  2. “Stripe-like” is vague: Does that mean the font, the shadows, or the layout?
  3. “Database” is undefined: Should it use Prisma, Supabase, or a JSON file?
  4. No Error Handling: What happens if the toggle fails to update?

The “AI-Proof” Spec (The Deterministic Contract)

# SPEC: Feature Toggle Management System

## 1. Objective
Create a secure management interface to toggle boolean feature flags in real-time. This will allow the product team to enable/disable features without code deploys.

## 2. Tech Stack & Constraints
- Framework: Next.js 15 (App Router)
- Language: TypeScript (Strict Mode)
- Styling: Vanilla CSS (Custom properties for colors)
- Database: Supabase (PostgreSQL)
- Icons: Lucide-React
- Constraints: NO external UI libraries (No Shadcn, No MUI). Build components from scratch.

## 3. Data Schema
Table Name: `feature_flags`
- `id`: UUID (Primary Key)
- `key`: String (Unique, e.g., "beta_search_v2")
- `is_enabled`: Boolean (Default: false)
- `description`: Text
- `updated_at`: Timestamp

## 4. UI Requirements
### Header
- Title: "Feature Management"
- Subtitle: "Control application features in real-time"
- "Add New Flag" button (Primary action)

### Flag List (Main Content)
- Display flags in a vertical list.
- Each row contains:
    - Label (The `key` name in bold)
    - Description (Smaller text, grey color)
    - Toggle Switch: 
        - Track color: #E2E8F0 (off), #10B981 (on)
        - Smooth CSS transition (0.2s)
    - Delete button (Icon only, red on hover)

## 5. Logic & Behavior
- On Toggle: Immediately trigger a Supabase update.
- Optimistic UI: Update the toggle state instantly, but revert if the API call fails.
- Toast Notifications: Show a success toast when a flag is added or updated.

## 6. Verification
- Code must pass `npm run build`.
- Generate a Playwright test to verify that clicking the toggle updates the database value.

Best Practices for Unmistakable Specs

To reach the 1600-word depth of a master orchestrator, we must explore the nuances that separate beginners from pros.

1. The “Negative Constraint” Strategy

One of the most powerful tools in your arsenal is the Anti-Pattern. Tell the AI what not to do.

  • “Do not use any types.”
  • “Do not add any comments; the code should be self-documenting.”
  • “Do not use inline styles.”

By explicitly removing bad options, you increase the probability of a “Clean Code” output.

2. The “Rule of Three” for Examples

If a piece of logic is complex, provide three examples. If you want a specific naming convention for CSS classes, show three.

  • header__title
  • header__nav
  • header__cta

AI models are pattern-matching engines. Once they see a pattern repeated three times, they are locked into that trajectory.

3. Use “Modular Context”

If your project is large, don’t dump the entire codebase into the prompt. Instead, provide “Context Snippets.”

  • “Here is my theme.css. Use only these variables.”
  • “Here is my auth-utils.ts. Use the getCurrentUser() function to protect this route.”

4. The Ambiguity Audit

Before you send your spec, read it through the eyes of a lawyer. Is there anything that could be interpreted in two ways?

  • Vague: “The sidebar should be small.”
  • Specific: “The sidebar should have a fixed width of 240px and collapse to 64px on mobile.”

5. Schema-First Design

Always define your data first. If the AI knows the shape of the data it is receiving, it can accurately infer the logic for the UI components. A missing schema is the #1 cause of “Undefined is not a function” errors in Vibe Coding.

Advanced Technique: The Iterative Spec

In Vibe Coding, your spec is a living document. You don’t just write it once and walk away.

  1. The Draft: You write the initial spec.
  2. The Feedback Loop: The AI generates code. You notice it missed the “Mobile Responsive” part.
  3. The Spec Update: Crucial Step: Do not just tell the AI to “fix the mobile view.” Go back to your original Markdown spec, add the mobile requirements, and ask the AI to regenerate based on the updated spec.

This prevents “Technical Debt” in the conversation history. If you keep asking for small fixes, the AI’s context window gets cluttered with your corrections, leading to lower-quality code over time. By keeping the spec updated, you keep the “Source of Truth” clean.

Conclusion: Orchestration is the New Coding

The era of “Vibe Coding” is often misinterpreted as the era of “no effort.” In reality, it is the era of High-Level Design. Your value as a developer in 2026 is no longer measured by how many lines of boilerplate you can type per minute. It is measured by the clarity of your thought and the precision of your specifications.

A spec that the AI cannot misunderstand is a reflection of a mind that understands the problem deeply. When you write a perfect spec, you aren’t just telling the AI what to code; you are building the architecture of your application in natural language.

Stop vibing in the dark. Start orchestrating with intent. Your specs are your legacy—make them unmistakable.

Your Next Step:

Pick a small feature you’ve been wanting to build. Instead of typing a quick prompt, spend 15 minutes writing a P.A.C.T. spec. Watch how the AI transforms from a confused assistant into a master craftsman. That is the power of Spec-Driven Vibe Coding.