Vibe Coding 实战手册：从需求到上线的完整工作流

Vibe Coding: A Practical Guide from Requirements to Deployment

You've read the thinkpieces. You know Karpathy said "forget code exists." You know vibe coding is a new human-AI collaboration paradigm. So you fire up Cursor, tell the AI "build me a thing," and...

Either the output misses your intent by a country mile, or the first 80% flies but the last 20% grinds you into dust, or it ships and bugs surface and you look at the code and realize you can't read it anymore.

The gap isn't conceptual. You're missing an operational workflow.

That's what this article provides. I'll walk you through a complete project — from "I have an idea" to "code is live" — covering exactly what to do at each step, what tools to use, and what traps to avoid. This isn't theory. It's a field manual.

Preparation: Lay the Groundwork Before Writing a Single Line

Most people grab a requirement and start coding. That's the single biggest waste in vibe coding.

When you onboard a new teammate, what's the first thing you do? You explain the project background, tech stack, and team conventions. Working with AI is no different.

Before starting a project, do three things:

First, set up your document directory.

Create a docs/ folder in your project root with at minimum:

docs/
├── index.md          # Project entry point — what it is, tech stack, directory structure
├── decisions/        # Architecture Decision Records (ADR)
└── specs/            # Requirement specifications (we'll cover how to write these)

This seems trivial, but it's the Single Source of Truth (SSOT) for everything that follows. In every subsequent AI conversation, you can point to these documents for project context instead of making AI guess from scratch.

Second, write a real README.

Not a template README. A README that answers three questions:

• What problem does this project solve?
• What's the tech stack?
• What's the directory structure?

This README is AI's first entry point into your project. The clearer it is, the less context AI needs to infer later.

Third, confirm your toolchain.

I'll recommend specific tools for each phase below, but confirm one thing now: does your AI coding tool support file references? Cursor's @file, Claude's Project, Copilot's Workspace — whatever you use, make sure you can point AI at your actual project files. This matters more than any prompting trick.

Phase 1: Requirement Precision — Turn "Vibe" into "Spec"

This is the most critical step in the entire workflow. It's also the most frequently skipped.

You say "build me a login feature." That sentence is a vibe. Vague, emotional, imprecise — and that's fine, it's your most natural expression. The problem is letting that sentence enter the code generation pipeline unchanged.

1.1 The Alignment Protocol: Make AI Ask Before It Answers

Rule #1 of vibe coding: don't let AI start writing code immediately.

The right move is putting AI into "clarification mode" first:

"I need a login feature. Before starting, ask me 3-7 key clarifying questions to ensure you fully understand the requirements."

A competent AI should come back with something like:

• What authentication methods? (username/password, SMS verification, third-party OAuth?)
• Is registration part of this scope? What's the registration flow?
• Password policy requirements? (length, complexity, expiration?)
• Is two-factor authentication needed?
• How should login failures be handled? (lockout, CAPTCHA, rate limiting?)
• Should we support "Remember Me"?
• What's the expected concurrent load?

Seven questions answered, and your "login feature" has transformed from one sentence into a complete requirement. This process is called human-AI alignment.

The core principle: clarification first. Accuracy > completeness > speed. Better to spend 10 minutes getting the requirement right than 10 hours fixing a misunderstood implementation.

1.2 Proposition Analysis: Decompose Vague Words into Atomic Propositions

If the clarification round isn't precise enough, there's a second technique: proposition analysis.

Break your requirement into three layers:

Atomic propositions (irreducible basic facts):

• n1: Users log in with email and password
• n2: Passwords must be encrypted in transit
• n3: 5 consecutive failures lock the account for 30 minutes
• n4: Successful login redirects to the dashboard

Compound propositions (combinations of atomic ones):

• c1: (n1, n2, n3, n4) → Users authenticate via email/password, transmission is encrypted, failures trigger lockout, success redirects to dashboard

Modal propositions (involving possibility and necessity):

• m1: The login endpoint must support 500 QPS
• m2: If the database is unavailable, the system should return a "maintenance in progress" page

Why do this? Because every atomic proposition is a verifiable, testable statement. When you write test cases or run acceptance audits later, you check against these propositions directly. Your fuzzy vibe has become an executable, verifiable spec.

Phase 2: Spec Lock — Freeze Understanding on One Page

Clarification done. Propositions decomposed. Now freeze that understanding.

2.1 The One-Page Spec Template

Write a Spec document, constrained to one page (think A4), with these fields:

# [Feature Name] Spec

## One-Line Requirement
One sentence: what does this feature do?

## Objects & Scenarios
Who uses this feature, in what context?

## Constraints
Technical constraints, business constraints, timeline constraints.

## What We're NOT Doing
Explicitly list what's out of scope. Prevent scope creep.

## Minimum Viable Version (MVA)
What absolutely must exist in v1?

## Acceptance Criteria
3-8 checkable criteria for "done."

## Risks & Assumptions
What could go wrong? What are we assuming?

2.2 The Strong Confirmation Point

After writing the Spec, you need to do one critical thing: confirm it.

Not a casual glance and "looks about right." You either reply "ok" to confirm, or you explicitly state "Change A to XXX, remove B, add XXX for C."

This is the only "strong confirmation point" in the entire workflow. Why only one? Because every confirmation burns user cognitive energy. Ask someone to make 50 decisions and decision quality collapses. But at this one point, you must do a thorough, serious confirmation — because everything that follows executes against this Spec.

Golden Rule: One strong confirmation + small commits + trimmable acceptance + always-rollback-ready.

Phase 3: Task Decomposition & Execution — 3 to 8 Tasks, Small Steps

Spec confirmed. Now have AI decompose the work into 3-8 executable tasks. Why 3-8? Fewer than 3 means the granularity is too coarse. More than 8 means the project probably needs to be split into multiple iterations.

3.1 Every Task Needs a DoD

DoD = Definition of Done. Each task explicitly states what "done" looks like.

Example — a "login feature" might decompose like this:

Task 1: User Model & Database Table
- DoD: User model defined, migration executable, includes email/password/status fields

Task 2: Registration API
- DoD: POST /api/register works, parameter validation passes, passwords stored encrypted

Task 3: Login API & Token Generation
- DoD: POST /api/login works, JWT signing functional, failure count correct

Task 4: Login Frontend Page
- DoD: Form renders correctly, submit calls API successfully, error messages display properly

Task 5: Login State Management
- DoD: Auth state persists across pages, expired sessions auto-redirect to login

3.2 Execute Per Task, Self-Check Immediately

Work through tasks one at a time. After each:

1. Run it immediately — does it work?
2. Have AI do a quick self-check ("review the code you just wrote for obvious issues")
3. Confirm it's clean, then move to the next task

Key principle here: Exception Gates. Only interrupt AI's execution rhythm in four scenarios:

• Requirement conflict (Spec contradicts reality)
• New dependency (need an unplanned library or service)
• Contract change (API interface or data structure needs modification)
• Risk escalation (discovered a severe issue that could block deployment)

Everything else — let AI run. Don't ask "is this right?" after every line. That's not vibe coding. That's micromanagement.

Phase 4: The Audit Loop — Generate → Audit → Fix → Re-review → Write-back

All tasks complete. Don't deploy yet. Now comes the step you absolutely cannot skip: audit.

4.1 Why You Can't Skip It

AI-written code has a unique property: it looks dramatically better than it actually is. Clean formatting, elegant naming, thorough comments — but logic gaps, missing edge cases, and security vulnerabilities all hide beneath that polished surface.

You can't catch these issues with your naked eye. You need a systematic audit process.

4.2 The Dual Audit Framework

First pass: Compliance Alignment Review.

Multi-world analysis across 12 dimensions:

• Control flow: Dead loops? Unreachable code?
• Execution model: Race conditions in async operations?
• State management: Are state changes traceable?
• Time handling: Timeouts, timezones, expiration logic correct?
• Error handling: Exceptions properly caught and handled?
• Input validation: All external inputs sanitized?
• Data consistency: Database operations transaction-protected?
• Dependencies: Third-party library versions secure?
• Configuration management: Config separated from code?
• Structural integrity: File organization sensible?
• Performance: N+1 queries? Memory leaks?
• Observability: Sufficient logging for debugging?

Second pass: Security Deep Audit.

Based on STRIDE threat modeling:

• Spoofing: Can identities be forged?
• Tampering: Can data be illegally modified?
• Repudiation: Are operations non-repudiable?
• Information Disclosure: Is sensitive data exposed?
• Denial of Service: Can the system be maliciously overwhelmed?
• Elevation of Privilege: Can users escalate permissions?

4.3 The Closed Loop

Audit isn't one action — it's a closed loop:

Audit → Generate Report → Fix Per Item → Re-review Confirming Fixes → Write-back Changelog

Every step matters. Auditing without fixing is wasted effort. Fixing without re-review is unconfirmed. Re-reviewing without writing back the changelog means the next iteration won't know what changed.

Practical advice: have AI generate a structured audit report where each finding includes — title, severity level (P0/P1/P2), location, evidence, fix recommendation, verification plan. Then process by priority: P0 must be fixed before deployment. P1 should be fixed but can ship with known issues (if time-constrained). P2 gets recorded as tech debt for later.

Phase 5: Document Sync — Keep the Project Alive Alongside the Code

Code written. Audited. Deployed. One more thing: document synchronization.

This is the most commonly ignored step, but it determines whether your project can sustain iterative development.

5.1 DDD: Document-Driven Development

Core principles:

1. Truth-first: When docs and code disagree, code wins
2. Inventory before action: Review what exists before updating
3. Create-or-update: No blank spaces — if something's missing, fill it
4. Consistency over prose: Accurate content beats beautiful writing
5. Executable-first: Docs should guide action, not sit on a shelf

5.2 Minimum Documentation Standard

Every document must have these six fields:

# [Document Title]

Purpose: What problem does this document address
Scope: What's covered
Status: Current state (Draft / Confirmed / Outdated)
Evidence: Information source (code files, meeting notes, Specs)
Related: Links to related documents
Changelog: Change history

5.3 Why This Matters

In vibe coding, your project knowledge lives in two places: code and AI's "memory." AI's memory is unreliable — start a new conversation and previous context is gone. Documentation is AI's external memory.

Before every new iteration, have AI read through the docs/ directory first. Now it's not starting from zero — it's building on existing knowledge. That's the value of SSOT: your project knowledge has a single, authoritative, traceable source.

Common Traps & How to Escape Them

Trap 1: The 80/20 Problem — Last 20% Grinds You to Dust

Symptom: First 80% done in half a day. Last 20% takes three days and counting.

Root cause: Not AI capability — context alignment. The first 80% is fast because Spec aligned core intent quickly. The last 20% is slow because details, edge cases, and exception handling demand fine-grained alignment.

Fix:

• Return to Spec and run a fresh proposition analysis for the remaining 20%
• Don't try to solve everything at once — prioritize remaining issues and tackle them sequentially
• Every "no, that's not what I wanted" is a context gap — write it into the Spec

Trap 2: Context Explosion — The Longer the Conversation, the Dumber AI Gets

Symptom: After 50+ turns, AI starts "forgetting" earlier statements or giving contradictory advice.

Root cause: AI's context window is finite. Longer conversations mean earlier information gets pushed out.

Fix:

• Start a new conversation per phase — write key context to files for the new conversation's AI to read
• Use Spec documents instead of chat history as context source — documents are compressed, structured knowledge, far more efficient than raw conversation
• Cap individual conversations at ~20 turns. Beyond that, archive and restart

Trap 3: AI Over-Execution — You Say One Thing, It Does Ten

Symptom: You said "add a login feature." AI added login, registration, password reset, email verification, OAuth, and two-factor authentication.

Root cause: AI's people-pleasing tendency — it prefers giving "complete" solutions over "just enough" ones.

Fix:

• Explicitly list "What We're NOT Doing" in the Spec
• Add constraints to prompts: "Only implement features listed in the Spec. Do not extend scope."
• Use DoDs to bound each task — if the DoD doesn't require it, don't do it

Trap 4: Deploying Without Audit

Symptom: Code passes smoke tests so you push immediately. Bugs surface in production.

Root cause: AI-generated code "looking good" creates a false sense of security.

Fix:

• Add the audit loop to your workflow checklist — no deploy without audit
• At minimum, run a P0-level audit — security vulnerabilities and fatal logic errors are non-negotiable
• Build the habit: before every commit, ask yourself "have I audited this?"

Tool Recommendations by Phase

Not an exhaustive list — just tools I've actually used and found reliable.

Preparation:

• Document management: Notion or Markdown files in a Git repo
• Project initialization: Let AI understand project background via README and docs/

Phase 1 (Requirement Precision):

• Any major LLM works for clarification dialogue — Claude, GPT-4, DeepSeek all fine
• The key isn't the model — it's whether you can articulate your requirements clearly
• For complex requirements, draft in Notion first, then feed to AI for clarification

Phase 2 (Spec Lock):

• Write Specs in Markdown, store in project's specs/ directory
• Once Spec is confirmed, don't修改 it in conversation —修改 the document, then have AI re-read it

Phase 3 (Task Decomposition & Execution):

• Code generation: Cursor (Claude Sonnet model), Windsurf, Copilot
• Cursor's Agent Mode recommended — auto-reads files, writes files, runs commands
• After each task, run it in terminal to confirm it works

Phase 4 (Audit Loop):

• Audit prompts: "Perform a full audit of the current project, output a structured report"
• Advanced: prepare a dedicated audit prompt template and reuse it every time
• Security audit can use a different model — e.g., Claude for feature development, GPT-4 for security audit (cross-model validation)

Phase 5 (Document Sync):

• DDD document management can run as an independent AI Agent
• After each iteration, have the doc agent scan the project and update docs/
• Git hooks can automatically check whether code changes include corresponding doc updates

Cross-cutting:

• Version control: Git. Commit after every phase.
• Model selection: Simple tasks → Sonnet. Complex reasoning → Opus. Security audit → GPT-4.
• Context management: Claude Project, Cursor Context, or direct file references

Final Word

The complete vibe coding workflow, in one sentence:

Express intent in natural language. Guarantee quality through structured protocols. Ensure trustworthiness through systematic audit. Sustain iterative capacity through documentation.

Sounds like a lot of steps? It will feel like a lot at first. But after two or three projects, this workflow becomes muscle memory. Remember when Git's add/commit/push felt cumbersome? You don't think about it anymore.

Memorize the rhythm: Spec confirmed once → tasks decomposed small → execute one by one → audit loop → document sync. Five phases, each with clear inputs and outputs. Get stuck at any point, come back here, find the relevant section, and follow the instructions.

Not magic. Protocol. Not casual chatting — structured collaboration hidden beneath a natural interface.

Now open your editor and start your first vibe coding project.