Vibe Specs: Spec-First AI Development

AI 30 minutes read (About 4532 words)

The AI-Powered Requirements Document: Why You Need a Clear Plan Before Writing Code

image.png|300

Note: The core content was generated by an LLM, with human fact-checking and structural refinement.

Problem with Current AI Coding

One of the most frustrating aspects of AI programming is the AI’s tendency to “go rogue” on complex projects, leading to inconsistency and a loss of control. You might get a perfect function one day, but then ask for a related one, and the AI completely changes the data structure, perhaps nesting a field two levels deep when it was previously on the first level. This can result in a “bug-ridden mess” where individually, pieces of code might seem fine, but together they cause issues due to differing data structures for the same data. This problem is widespread in AI coding tools today.

Large Language Models (LLMs) are prone to happily expanding vague prompts into large amounts of “plausible code” or “slop software” that is ultimately useless. Even well-intentioned programmers find that the AI spends significant time building features that don’t align with their original intentions. As Andrej Karpathy notes, working with AI in professional coding requires keeping a “very tight leash” on the AI, as it can “bullshit you all the time” and “shows little to no taste for good code”.

The underlying issue is that the AI often doesn’t adequately understand the problem’s context. This highlights the importance of “Context Engineering,” a term preferred over “prompt engineering” to describe the sophisticated orchestration involved in filling the LLM’s context window with precisely the right information for the next step. Too little context can cause the LLM to “flail,” while too much or irrelevant context can increase costs and reduce performance. This challenge mirrors issues encountered when delegating tasks to human workers without clear requirements.

Traditional LLM workflows face several specific problems:

  • Chat Drift: Exploratory chat histories, filled with explorations and corrections of blind alleys, can confuse LLMs.
  • Solo Coding: LLM development often remains a solo effort because chat histories are ephemeral and personal, making it difficult to hand off work or resume later.
  • No Version Control: AI conversations are not tracked by Git, making it hard to track requirement evolution or provide context to team members.
  • Feature Creep: Natural language ambiguity can lead the AI to assume and implement more features than intended.
  • Lost Context: Projects can go off course, feeling too effort-intensive to get back on track.
  • Blank Page Paralysis: The initial daunting feeling of not knowing how to start a feature or project.
  • Token Waste: Precious context tokens are burned on exploratory conversation rather than focused implementation.

Core Idea: Control over Correctness

The fundamental insight behind Vibe Specs is that when programming with AI, the most important thing is controlling the AI to prevent it from making mistakes, rather than simply getting a “correct” snippet of code. The concept of “correctness” itself is ambiguous in programming, as there are many ways to implement a feature. The real risk is inconsistency, such as an AI defining a data structure one way in one module and then hallucinating a different structure for the same data in another. We need to enforce control to avoid these “bug-ridden messes”.

Vibe Specs advocates for a “Spec-First” approach (LLM → Spec → Code), where the first interaction with the AI assistant is not to write code, but to help write a specification. This shifts the paradigm from directly prompting the AI for code to first defining clear requirements. Crucially, you don’t write the Spec; the LLM does. Your role is to critique, tweak, and clarify the AI’s generated specification. This multi-turn Spec construction process naturally guides you towards providing the LLM with exactly what it needs, helping you fall into the “pit of success” with context engineering. The Spec then serves as your “north star” throughout the development process.

Vibe Specs Methodology (LLM→Spec→Code)

Vibe Specs extracts the “Specs” idea from tools like Kiro Agent, which is praised for its brilliant core idea despite its practical instability. It offers a lighter, faster workflow that integrates seamlessly with existing tools like Cursor. The methodology employs a simple three-step strategy to clearly define “what is what” for the AI:

  1. Define the “What” and “Why”: As the developer, you define the high-level goals and provide a detailed description of the feature. This step sets the boundary and direction for everything that follows. An initial “Goal Discussion” phase is also added to help align the user and the AI on requirements more precisely. The output of this phase is typically a requirements.md file.
  2. Co-Design the “How”: In this collaborative phase, you work with the AI to design the implementation. You provide architectural constraints, and the AI fills in the details by suggesting technical solutions, key data structures, module splits, and core functions. This translates your intent into a technical blueprint. The output is a design.md file.
  3. Execute the “Action” Step-by-Step: Based on the approved design, you break the work down into small, executable steps. You guide the AI to complete these steps one by one, allowing you to verify each step before proceeding. The output of this phase is a tasks.md file.

This process transforms a vague prompt into a clear, agreed-upon plan, as illustrated by the following comparison:

BEFORE (Immediate Code Generation - Vibe Coding)
You: “Help me create an API route that handles search functionality.”
AI: “I’ll create a search API route for you. Let me implement this with a basic search endpoint that can handle query parameters.”
(AI generates a comprehensive search API with features like full-text search, pagination, fuzzy matching, ranking, and caching layer, potentially using systems you don’t have access to)
You: “Ok, first of all, this isn’t working. Secondly, you used several systems we don’t have access to…”
(Result: Half a workday wasted, frustration, deleting the branch)

AFTER (Spec-First)
You: “Help me create an API route that handles search functionality.”
AI: “I’d be happy to help you create a search API route! Before I start coding, should I create a spec for this task first? This will help us clarify exactly what kind of search functionality you need.”
You: “Yes, let’s do that.”
AI: “Great! Let me ask a few questions to understand your search requirements:

  1. What will users be searching? (products, blog posts, users, etc.)
  2. What fields should be searchable? (title only, title + description, everything?)
  3. Do you need any filters? (category, date range, price range, etc.)
  4. What about search features? (Exact match only or fuzzy/partial matching? Case sensitive or insensitive? Autocomplete/suggestions?)
  5. Performance requirements? (Expected search volume? Need for caching? Response time targets?)
  6. What database/search solution are you using? (PostgreSQL, Elasticsearch, etc.)”
    You: “We’re searching blog posts. Just title and content fields, case-insensitive partial matching is fine. No filters needed yet. Using PostgreSQL. This is for a small blog, so performance isn’t critical.”
    AI: “Perfect! Let me create a spec for this search functionality:”
    (AI generates a clear blog-search-api.md file, 35 lines)
    AI: “I’ve created a spec for your blog search API. Does this capture your intent? Any changes needed?”
    You: “Looks perfect! GO!”
    AI: “Excellent! Now I’ll implement the search API based on our spec.”
    (AI generates a clean, focused pages/api/search.js file, 24 lines)
    AI: “I’ve implemented a clean, focused search API that matches our spec exactly:
    ✅ Simple ILIKE queries on title and content
    ✅ Case-insensitive partial matching
    ✅ Returns title, excerpt, and URL
    ✅ Limits to 20 results
    ✅ Title matches ranked higher
    The implementation is just 24 lines of focused code. Want me to add a simple test file as well?”

This striking contrast shows how the Spec-first approach allows the AI to pause, ask clarifying questions, and ensure it builds the correct thing before jumping into implementation. It respects your time and cognitive load, leading to higher quality code that perfectly matches the requirements.

Key Benefits

The “Spec-First” workflow addresses many common pain points in AI-assisted development, leading to significant efficiency gains. As the author states, “It doesn’t matter how quickly you can create something if it’s useless”. This approach emphasizes that “slow is smooth, and smooth is fast”.

Here are the key benefits:

  • Chat Drift → Stable Documentation: Unlike ephemeral and confusing chat histories, a Spec document (e.g., a .md file) remains stable and serves as a reliable source of truth. This provides structured, dense information that the LLM can parse efficiently.
  • Solo Coding → Team Sport: Specs transform AI development from a solitary endeavor into a collaborative process. You can easily close your chat, take a break, and then hand the same Spec to a completely fresh context window or even to a human colleague, ensuring the work persists beyond the ephemeral chat session.
  • No Version Control → Git-Tracked Requirements: While Git cannot track AI conversations, it can perfectly track the evolution of your WidgetFeature.md Spec document. This means requirements are version-controlled, allowing team members to immediately pick up work with full context.
  • Feature Creep → Defined Scope: Natural language ambiguity often leads LLMs to over-implement features. A precise Spec, like “basic string matching on user names only,” eliminates this ambiguity, preventing unnecessary “feature creep”.
  • Lost Context → Instant Resume: Specs enable you to return to a project after a long break and immediately understand not just what you were building, but why specific architectural decisions were made, making project resumption much smoother.
  • Blank Page Paralysis → Structured Start: The AI becomes your documentation assistant first, and your coding assistant second. It’s significantly easier to critique a proposed Spec than to draft one from scratch, providing a structured starting point for any feature or project.
  • Token Waste → Efficient Context: Instead of burning precious context tokens on exploratory conversations, Specs ensure that tokens are used to generate and parse structured, dense information, leading to more focused and relevant responses.

These benefits collectively contribute to a significant reduction in feature development time, estimated at approximately 60%, and consistently result in higher quality output. As one source notes, “I estimate that I have a ~60% reduction in feature development time, and I come out with a better result far more often”.

Why it Works

The core reason Vibe Specs works is that it addresses the fundamental flaw in traditional AI coding workflows: the AI often doesn’t adequately understand the problem you’re solving because you didn’t adequately explain the problem’s context.

The method embraces “Context Engineering,” which is the “delicate art and science of filling the context window with just the right information for the next step”. It recognizes that providing too little context leads the LLM to “flail,” while too much or irrelevant context can increase costs and decrease performance. The goal is to find that “sweet spot”.

This approach is analogous to how humans delegate tasks effectively: by writing concise specifications, requirements, or Product Requirement Documents (PRDs) that answer basic questions like: “What is the objective?”, “What determines success?”, “What tools should be used?”, “What is out-of-scope?”, and “How will we know when we’re finished?”. By applying this “older, humbler practice” to AI, the result is clear: “Give the AI a crisp spec, and you get crisp, consistent output; give it a vibe, and you get a vibe back”.

The key mechanism is that you don’t write the Spec; the LLM does. This multi-turn Spec construction process naturally guides you toward giving the LLM exactly what it needs, helping you fall into the “pit of success” with context engineering. The AI automatically prompts you to create a Spec before writing any code, ensuring that the first thing you do with your LLM is to write a Spec, not Code.

Evidence

The effectiveness of the Spec-first approach is supported by personal anecdotes, academic research, and industry validation:

  • Personal Results:
    • One developer successfully implemented a complex webserver in a 45-minute interview, finishing 20 minutes early with a perfect implementation, thanks to spending the first 5 minutes writing a Spec with the LLM.
    • In day-to-day development, this approach led to an estimated 60% reduction in feature development time and significantly higher quality results. Tasks that previously took 2-3 hours to implement (and often required rebuilding due to errors) now take 10-20 minutes for planning and 1 hour for correct implementation. This has “literally saved days” of back-and-forth with LLMs.
    • One user switched from Kiro Agent, which was slow and unstable with constant retries and errors, to Cursor using Claude Sonnet 4. They finished a task in 1 hour that they had been stuck on with Kiro for half a day.
  • Academic Evidence: Recent research on LLM-assisted development highlights that specifications are “the missing link” in making LLM code generation reliable. This is supported by works such as:
    • Dreossi, T., et al. (2024). “Specifications: The missing link to making the development of LLM-based software more trustworthy”.
    • Pullum, L., Freeman, L., & Huang, C. (2020). “Verification and Validation of Systems in Which AI is a Key Element”.
    • Batarseh, F. A., Freeman, L., & Huang, C. H. (2021). “A survey on artificial intelligence assurance”.
    • Hand, D. J., & Khan, S. (2020). “Validating and Verifying AI Systems”.
  • Industry Validation:
    • OpenAI’s new Deep Research mode exemplifies this pattern by pausing to ask clarifying questions, tightening the problem definition before consuming compute. It prioritizes understanding before generating answers.
    • Shopify’s approach to their Auto Write feature also began with a comprehensive Spec that aligned AI capabilities with merchant needs.

These examples demonstrate a clear pattern: successful AI features start with clear requirements, not just clever prompts.

Implementation (Quick Start)

Implementing Vibe Speccing is straightforward and can be done in minutes to save hours of development time.

  1. Copy these instructions into your AI IDE of choice (e.g., Cursor settings) or AI Code Helper of Choice (e.g., Windsurf, Claude Code, etc.):
    For ChatGPT, add these rules to Custom Instructions. For Claude, include them in your Project instructions. For Raw API calls, include them in your system prompt. The key is to make the Spec request automatic.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    ## Development Workflow: Spec → Code
    THESE INSTRUCTIONS ARE CRITICAL! They dramatically improve the quality of the work you create.

    ### Phase 1: Requirements First
    When asked to implement any feature or make changes, ALWAYS start by asking: "Should I create a Spec for this task first?"
    IFF user agrees:
    - Create a markdown file in `.cursor/scopes/FeatureName.md`
    - Interview the user to clarify:
        - Purpose & user problem
        - Success criteria
        - Scope & constraints
        - Technical considerations
        - Out of scope items

    ### Phase 2: Review & Refine
    After drafting the Spec:
    - Present it to the user
    - Ask: "Does this capture your intent? Any changes needed?"
    - Iterate until user approves
    - End with: "Spec looks good? Type 'GO!' when ready to implement"

    ### Phase 3: Implementation
    ONLY after user types "GO!" or explicitly approves:
    - Begin coding based on the Spec
    - Reference the Spec for decisions
    - Update Spec if scope changes, but ask user first.

    ### File Organization
    .cursor/  
    ├── scopes/  
    │ ├── FeatureName.md # Shared/committed Specs  
    │ └── .local/ # Git-ignored experimental Specs  
    │ └── Experiment.md
    **Remember: Think first, ask clarifying questions, _then_ code. The Spec is your north star.**

  2. Make sure the rules are labelled “Always Attached” in your AI IDE’s settings.

  3. Start a new AI chat and describe your task, for example: “Help me add user authentication to my app”.

  4. Follow the AI through Spec Creation. The AI will automatically ask smart questions you hadn’t considered, write a clear requirements document, and wait for your approval.

    Example AI questions:

    • “Will users log in with email or username?”
    • “Do you need password reset functionality?”
    • “Should sessions expire?”

  5. Authorize Code. Once you are satisfied with the Spec, simply type “GO!” or explicitly approve, and the LLM will then build exactly what you agreed on.

This entire quick start process typically takes only about 5 minutes of upfront planning but can save hours of rework due to misaligned implementations.

FAQ

Here are answers to common questions about Vibe Specs:

  • Does this work with ChatGPT/Claude/other AI tools?
    Yes! While examples might use Cursor, the Spec-first approach is tool-agnostic. You can implement it by adding the rules to ChatGPT’s Custom Instructions, Claude’s Project instructions, Windsurf/Continue/Cody’s config files, or directly into system prompts for raw API calls. The crucial part is to make the Spec request automatic, not optional.

  • How is this different from traditional documentation?
    Traditional documentation is typically written after implementation to explain what was built. Specs, in contrast, are written before implementation to clarify what should be built. Think of Specs as a collaborative conversation with your future self (and your AI) about intent, while docs are a record of what actually happened.

  • What if I’m working on existing code?
    Specs are incredibly valuable for modifications to existing code. For tasks like “Refactor auth system” or “Fix performance issue,” a Spec clarifies which parts change, which stay, defines success metrics, and outlines constraints. For “Add feature to legacy code,” it documents assumptions and integration points. The AI can even analyze existing code to help write Specs that respect the current architecture.

  • Isn’t this just waterfall development with extra steps?
    No! This approach remains iterative. Unlike traditional waterfall development, which involves weeks on massive requirement documents before coding for months, Vibe Specs suggests spending 5-10 minutes per feature, iterating on the Spec as you learn. Specs can be updated mid-implementation if new constraints arise, and each feature gets its own mini-Spec rather than one giant document.

  • How detailed should Specs be?
    The level of detail should match the complexity and risk of the task. A simple bug fix might need 3-5 bullet points, a new feature 1-2 pages, and an architectural change 2-5 pages with diagrams. A good rule of thumb: if explaining the task to a new team member would take more than 5 minutes, write a Spec.

  • What if the AI writes a bad Spec?
    That’s precisely why you review it! Common issues like vagueness, over-complexity, wrong assumptions, or missing context should be addressed by asking for specifics, breaking down features, correcting assumptions, or adding domain knowledge. Remember, you are the architect; the AI is your drafting assistant.

  • Can I use this for non-coding tasks?
    Absolutely! This pattern works for any complex task requiring clear intent before execution. Examples include writing blog posts (Spec = outline), creating presentations (Spec = key messages), planning projects (Spec = project charter), or designing systems (Spec = design doc).

  • How do I convince my team to adopt this?
    Start with yourself. Use it solo for a week, then share particularly good Specs and their results with your team. Offer to write Specs for shared features and track your velocity improvement. Let the results speak for themselves, encouraging optional adoption rather than mandating it.

  • What about truly exploratory coding?
    Even exploratory coding benefits from lightweight structure. You can write an “Exploration Spec” that defines what you’re trying to learn, set time bounds, and establish success criteria for the exploration. After exploring, you can then write a proper Spec for the actual implementation.

  • Do Specs slow down hot fixes?
    For genuine emergencies, you can skip the Spec. However, once the immediate crisis is averted, it’s beneficial to write a retroactive Spec documenting what was done and why. Use this to plan a proper, long-term fix and address root causes to prevent similar emergencies. Most “emergencies” are often just poorly defined problems.

  • Where do I store Specs in my project?
    A suggested structure is within a .cursor/ directory: committed specs in .cursor/scopes/feature-name.md and git-ignored experimental specs in .cursor/scopes/.local/experiment.md. However, it’s important to adapt this to your team’s existing workflow, ensuring consistency and discoverability.

Future of AI-Assisted Development

The landscape of software development is rapidly changing. In the age of AI-assisted development, every developer will increasingly become their own product manager. The most challenging part is no longer writing the code itself, but rather knowing what code to write. LLMs are incredibly powerful at code generation, and the Vibe Specs pattern ensures that developers don’t abdicate responsibility for defining the objective.

The future of AI-assisted development isn’t about generating more flashy code; it’s about better requirement articulation: LLM → Spec → Code. This paradigm ensures increased development velocity, improved code quality, and the ability to context-switch without losing one’s mind.

AI Agent Evolution (Agentic Software Engineer)

The “Spec-First” philosophy extends beyond current coding assistants to the evolution of AI Agents. The rise of Agentic AI will fundamentally reshape how we work, transforming the role of a “software engineer”. We are moving from being “code writers” to becoming **”Agentic Software Engineers”**—experts who command, coordinate, review, and operate a “military of AI Agents”.

An AI Agent, being a more powerful executor capable of calling tools, accessing files, and executing commands, can be even more disruptive if given vague “vibe” instructions. It might call incorrect APIs, modify unintended files, or get stuck in costly execution loops. In this context, “Vibe Specs” evolves from a “requirements document” into an “action plan” or “task instruction book” for the Agent.

The workflow for AI Agents would look like this:

  • Input: You and the AI Agent collaboratively define a high-level action plan (the Spec) through dialogue, clearly outlining the ultimate goal, key steps, allowed tools, operational boundaries, and success metrics.
  • Execution: The Agent uses this structured plan as its core directive to autonomously decompose and execute tasks.
  • Monitoring: The Spec also serves as the baseline for you to monitor and evaluate the Agent’s performance, clearly showing its progress and adherence to expectations.

The core principle remains: “first define the problem clearly, then proceed to solve it”. “Spec-First” doesn’t become obsolete; instead, it becomes a “safety belt” and “navigation map” in more advanced human-machine collaboration.

To thrive as an “Agentic Software Engineer,” new skills are essential, while others will devalue:

Skills to Upgrade (Skills++):

  • Version Control: Git becomes central to coordinating AI Agent workflows, reviewing their Pull Requests, and rolling back errors. Mastery of Git models will be foundational.
  • Product Thinking: Every engineer will need skills like task decomposition, requirements definition, and interface design to break down vague ideas into manageable tasks for Agents.
  • Code Review: As Agents rapidly generate complex code, your value shifts to reviewing its correctness, maintainability, and security. You’re becoming a “Code Editor” rather than primarily a “Code Writer”.
  • Testing: Writing precise and comprehensive test cases is crucial to constrain and guide Agent behavior, especially when an Agent might “creatively” bypass tests.
  • System Design: Designing systems with clear boundaries, robust interfaces, and high testability becomes critical to manage less reliable Agents and prevent system-wide failures.
  • Operations: You’ll become an “Agent Reliability Engineer,” responsible for designing, deploying, monitoring, and debugging complex networks of Agents, quickly pinpointing issues within Agent behaviors.

Skills to Devalue (Skills–):

  • LeetCode-style algorithm questions: AI can solve most of these instantly.
  • Language syntax fluency: Agents know all syntax details; your ability to read code is more important.
  • Typing speed: AI’s “thinking” and “typing” speed are beyond human capability.

The era of Agentic AI signifies an irreversible transformation. Embracing Agents will be key for companies, and engineers who can master Agents will be at their core.

Quoted Article Links:

More

Recent Articles:

Random Article:

More Series Articles about You Should Know In Golang:

https://wesley-wei.medium.com/list/you-should-know-in-golang-e9491363cd9a

And I’m Wesley, delighted to share knowledge from the world of programming. 

Don’t forget to follow me for more informative content, or feel free to share this with others who may also find it beneficial. It would be a great help to me.

Give me some free applauds, highlights, or replies, and I’ll pay attention to those reactions, which will determine whether I continue to post this type of article.

See you in the next article. 👋

中文文章: https://programmerscareer.com/zh-cn/ai-first/
Author: Medium,LinkedIn,Twitter
Note: Originally written at https://programmerscareer.com/ai-first/ at 2025-08-05 00:26.
Copyright: BY-NC-ND 3.0

wechat
Wechat(微信公众号)
x
#learning
Go 1.25 Release: Features and Innovations Error Handling in Go vs.Zig

Comments

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×