Vibe Coding Workflow

---

name: vibe-coding-workflow description: Structured 5-phase AI-assisted development workflow (requirements → architecture → code generation → debugging → iteration). Use when the user mentions "vibe coding", wants a structured multi-phase AI collaboration for a software project, says "help me build a project step by step", asks how to start a new feature or project with AI, encounters bugs they can't resolve, wants to refactor messy code, or asks about AI-assisted development workflows. Also use when the user says "Phase 1/2/3/4/5", "requirements doc", "architecture design", or explicitly asks to "follow the workflow".

---

Vibe Coding Workflow

A structured 5-phase workflow for AI-assisted software development, from vague idea to working product.

Phase 1 – Requirements: vague idea → structured requirements doc

Phase 2 – Architecture: project structure, data flow, interface contracts

Phase 3 – Code Generation: module-by-module implementation

Phase 4 – Debugging: full error info + root cause + step-by-step fix

Phase 5 – Iteration: new feature / optimization / refactor → re-enter correct phase

---

Global Principles

You execute, user decides. End every Phase with a clear summary and a list of items awaiting user confirmation. Never auto-advance to the next phase.

Context is first-class. Actively request, reference, and reuse requirements docs, architecture docs, and error logs. Never guess.

Preserve artifacts. All key outputs (requirements, architecture, interface contracts, debug summaries) must be formatted as Markdown for the user to save.

Tool separation. Use conversation for clarification, tech selection, and architecture discussion. Use code editing for creating/modifying files.

If user says "just write the code": State the current Phase and any missing prerequisites in one sentence, then proceed per user's intent — never hard-block.

Phase gate: Use each phase's completion checklist as the only criterion for moving forward.

---

Phase 1: Requirements

Goal: Turn a vague idea into a structured, actionable requirements document.

Complete Steps 1 → 2 → 3 in order. Do not merge or skip steps.

Step 1 — Clarify the Idea

Trigger: User describes an idea in 1–2 sentences without specifying audience, context, or pain points.

Ask:

Who uses this, and in what scenario?

What's the pain point? What's most unacceptable (slow / inaccurate / hard to use)?

Are there reference products or similar tools?

What does a typical usage flow look like?

Do not discuss tech stack yet. Summarize into 2–3 sentences: who + what scenario + what problem.

Done when:

Problem scenario can be clearly stated in 2–3 sentences

No remaining critical questions

Tech stack not yet discussed

Step 2 — Technology Selection

Enter when: Step 1 is complete.

Collect constraints from user:

Preferred language / framework

Target runtime (local / server / serverless / etc.)

Single-user or multi-user

Maintenance expectations (one-off tool vs. long-term product)

Provide 2–3 tech options, each with: rough architecture, key dependencies, runtime model, pros/cons, and best-fit scenario.

Do not choose for the user. Explicitly say: "Please pick an option before I continue."

Done when:

User has confirmed a specific option

Language, runtime, and core dependencies recorded in a short text note

Step 3 — Structured Confirmation

Enter when: Tech stack is confirmed.

Auto-fill the requirements template from the conversation so far:

| Field | Content | |---|---| | System background | | | Goal of this build | | | Users & use cases | | | Inputs / outputs (format + frequency) | | | Boundaries & constraints (including "out of scope") | | | Error handling approach | | | Acceptance criteria (testable, not subjective) | |

Show the filled template to the user. Ask them to correct inaccuracies and fill gaps.

Done when:

Template confirmed by user with no major gaps

At least 3 error scenarios listed

Acceptance criteria are verifiable by test or clear manual steps

User reminded to save this doc to the project

---

Phase 2: Architecture

Goal: Define project structure, module responsibilities, data flow, and interface contracts — before writing any implementation code.

Enter when: Phase 1 requirements doc is confirmed.

Outputs to produce:

1. Directory structure (down to file level) 2. One-sentence responsibility for each directory/file 3. Mermaid flowchart of data flow 4. Interface contracts between modules (function names, params, return types) 5. Weakest point in the design and why

No implementation code in this phase — interfaces and structure only.

Done when:

Directory structure is clear with no overlapping responsibilities

Data flow diagram provided; user reminded it can be rendered in their editor or draw.io

All cross-module calls go through defined interfaces (no ad-hoc cross-layer calls)

User reminded to save architecture doc to repo (e.g. docs/architecture.md)

---

Phase 3: Code Generation

Goal: Implement modules one at a time, consistent with the architecture doc.

Enter when: Phase 2 directory structure and interface contracts are confirmed.

For each module, state before generating:

File path

Module responsibility (copy or summarize from architecture doc)

External interfaces this module depends on

Interfaces this module exposes

One module per generation. Do not attempt to generate the full project at once.

Generation order: 1. Foundation (utilities, data models, storage layer) 2. Business logic 3. UI layer or external adapters

After each module: verify it can be imported and its key functions can be called.

Done when:

All modules implemented and consistent with architecture doc

No new modules or cross-layer calls not defined in architecture doc

Config and constants centralized, not scattered as hardcoded values

User reminded to commit with a message describing which modules were completed

---

Phase 4: Debugging

Goal: Solve problems collaboratively using complete information + root cause explanation + step-by-step execution.

Step 1 — Gather Full Context

Ask user to provide:

Complete error text (start to finish)

Exact steps taken before the error

Expected behavior vs. actual behavior

Already-tried solutions that didn't work

Step 2 — Explain the Error

Describe what the error means in plain language

List 1–3 most likely causes, ranked by priority

Step 3 — Step-by-Step Fix

Provide clear, sequential fix steps

Ask user to report back after each step — do not let them run all steps at once

Step 4 — Summary

After resolution, output:

> Problem: ___; Cause: ___; Fix: ___

Remind user to save this note for future reuse.

If unresolved after 3+ rounds in the same conversation:

Suggest opening a new conversation

Paste the full error and all attempted solutions from scratch

Explicitly request: "Analyze from a completely different angle — do not repeat previous directions"

---

Phase 5: Iteration

Goal: For each type of change, re-enter the correct phase.

| Scenario | Entry point | |---|---| | New feature | Phase 1 (Step 1) — treat as a small project; note existing stack in "System background" | | Performance / UX issue (working but slow/awkward) | Phase 4 — describe the felt problem + paste relevant code | | Messy code structure (works but hard to maintain) | Phase 2 — redesign module boundaries before adding features |

Done when:

Current change type is identified

Relevant phase artifact updated (requirements doc / architecture doc)

User reminded to note the purpose and scope of this iteration in the commit message