Vibe Coding Blueprint

---

name: vibe-coding-blueprint description: "A document-driven AI programming methodology. Use when: (1) starting a new code project, (2) adding a new feature module, (3) debugging a bug, (4) code becomes messy and needs refactoring, (5) user mentions vibe coding, document-driven, small-step iteration. Core: plan-first, iterate in small steps, documents as memory, human in command."

---

Vibe Coding Blueprint

A document-driven AI programming methodology. AI is like a "highly capable but occasionally careless new hire." Your role is Architect and Decision Maker — not overseer.

AI handles high-speed code output

You handle judgment, decisions, and root cause diagnosis

The steering wheel stays in your hands

---

Core Philosophy

AI code generation is powerful but fragile. Without structure, it produces code that works once but becomes unmaintainable over time. This methodology solves that through documents as memory — a self-referential documentation system that lets AI resume from any state without losing context.

---

The Workflow

Phase 0: Check Project Documentation Status

Important: At the start of every conversation, check if the project already has documentation:

1. Check if docs/README.md exists 2. Check if docs/ARCHITECTURE.md exists 3. Check if docs/PROJECT_STRUCTURE.md exists 4. Check if main source folders have FOLDER.md

If documentation exists:

Project documentation detected:
docs/README.md
docs/ARCHITECTURE.md
docs/PROJECT_STRUCTURE.md
[list of FOLDER.md files]
I will read these docs first to understand the project context before starting work.

If no documentation:

No documentation structure found.
Please choose:
A) Initialize documentation (recommended) — generate a complete documentation structure
B) Skip initialization — start working directly without docs
Choose [A/B]:

---

Phase 1: Blueprint — Design the Architecture First

Goal: Think through the entire system architecture in your head, then output it to a formal document.

Steps: 1. Define the core problem the system solves 2. Break down core modules 3. Map data flow and key dependencies 4. Output to docs/ARCHITECTURE.md

Output file: docs/ARCHITECTURE.md

---

Phase 2: Establish Fractal Documentation Structure

Goal: Build a self-referential documentation system. AI can return to any prior state and continue working.

#### Three-Layer Documentation System

Layer 1 — Root documentation

docs/
├── README.md              # Root doc, declares update mechanism
├── ARCHITECTURE.md       # System architecture overview
├── PROJECT_STRUCTURE.md   # Project structure guide (quick navigation)
└── superpowers/
    └── DAILY.md           # Daily change log

Layer 2 — Folder-level docs (one FOLDER.md per folder, ≤3 lines)

# [Folder Name] Architecture
Role: [One-line description]
Contains: [file name] - [function], [file name] - [function]
> ⚠️ If this folder changes, update this document

Layer 3 — Code file header (3 lines)

// input:  [what this file depends on externally]
// output: [what this file provides to others]
// pos:    [this file's role in the local system]
// ⚠️ When this file is updated, update its header and the parent FOLDER.md

Self-reference mechanism: Local changes propagate to global; global changes propagate to local. When any file changes, it automatically triggers a cascade of documentation sync.

---

Phase 3: Develop Module by Module (Core Loop)

Each feature module follows these steps:

#### Step 1: Design the Plan First (Plan-Before-Code)

Do not write code immediately. Have AI output the technical implementation plan first, then you review and adjust.

Prompt template:

Before implementing [module name], please output the technical implementation plan:
1. Data model design (table schema or type definitions)
2. Core interfaces (function names, params, return values)
3. Dependencies on other modules
4. Key implementation details
5. Potential pitfalls
I will review and confirm before you start coding.

Your (human) responsibilities:

Review if the plan is sound

Adjust permission and boundary design

Confirm tech stack choices

Add missing edge cases

#### Step 2: Break Into Small Tasks

Split the module into small, independently completable tasks.

Each small task includes:

✅ Clear objective

✅ Technical approach

✅ Implementation steps

✅ Verification method

#### Step 3: Implement One Small Task at a Time

Order: Foundation → Business logic → UI layer

After completing each small task, immediately: 1. Update the code file's header comments 2. Update the parent folder's FOLDER.md 3. Run verification (unit test, demo page, or manual test)

Prompt template (after verification):

Verification passed. Now please:
1. Update [filename] header comments (if implementation changed)
2. Update docs/[folder]/FOLDER.md (if interfaces changed)
3. If there are cross-folder dependencies, sync related docs

#### Step 4: End-to-End Integration

After all modules are complete, run end-to-end tests.

---

Phase 4: Debugging (Human-in-Command Moment)

Most important principle: When the same problem remains unfixed after 2–3 iterations, stop immediately. This signals the model is trapped in a wrong framework.

#### Debugging Steps

Step 1: Recognize danger signals

Model has modified the same issue 2–3+ times without resolution

Fixing one thing breaks another (patch on patch)

Code is getting messier, not cleaner

Step 2: Human diagnoses root cause

Read error messages, but don't stop at surface level

Use logs, breakpoints, and code tracing to find the real cause

Ask: Which module did the problem occur in? Why did it happen? What is the root cause?

Step 3: Tell the model the root cause explicitly

❌ Don't say: There's a bug here, please fix it ✅ Say: Your previous assumption was wrong. The real problem is: [specific description of root cause, including why]. Based on this understanding, please re-implement.

Step 4: Let the model re-generate based on correct understanding

---

Phase 5: Iteration

| Scenario | Entry | |---------|-------| | New feature | Back to Step 1 — treat it as a mini project; note existing stack in "System background" | | Performance/UX issue | Debugging mode — describe problem + paste relevant code | | Messy code | Redesign module boundaries, then start adding features |

---

Human-AI Role Table

| Phase | Your Role | AI's Role | |-------|-----------|-----------| | Planning | Architecture decisions, permission boundaries, tech choices | Plan review, feasibility analysis, detail supplementation | | Code | Plan review, code review, key troubleshooting | Heavy lifting (CRUD, interface docs, field sync) | | Root cause | Root cause analysis, problem diagnosis | Fix based on your guidance | | Testing | Test design, edge case supplementation | Test script generation, demo pages |

---

Common AI Pitfalls & Solutions

1. API Hallucination

AI invents APIs, library functions, or interfaces that don't exist. Solution: Emphasize in prompts "use only APIs from official documentation." Verify against official docs when needed.

2. Repeated Patching on Wrong Assumptions

AI keeps modifying code based on a wrong foundational assumption, making things worse. Solution: Diagnose the root cause yourself, then explicitly tell AI what the wrong assumption was.

3. Over-Engineering

AI generates excessive design patterns, factory functions, and decorators. Solution: Delete freely during code review. Keep code simple.

4. Missing Edge Cases

AI only implements the happy path; null checks, exceptions, and concurrency are neglected. Solution: Enumerate edge cases in prompts upfront, or supplement during the testing phase.

---

Prompt Template Library

Start a New Project

I want to start a new project: [project description]
Please help me output the project architecture doc first:
1. Core module breakdown
2. Data flow relationships
3. Tech stack recommendations
I will confirm before you set up documentation structure and start coding.

Add a New Feature

I want to add [new feature] to [existing module].
Please output the technical implementation plan first.
I will confirm before you start coding.

Debugging Request

I'm encountering a problem:
Symptom: [description]
Expected: [expected behavior]
Actual: [actual behavior]
I've tried: [attempts so far]
Before fixing, please analyze possible causes. I'll tell you the root cause and then we'll fix it.

Sync Docs After Update

[module name] is complete. Please sync:
1. Header comments in [filename] (if interfaces changed)
2. docs/[folder]/FOLDER.md
3. docs/ARCHITECTURE.md (if significant changes)
4. docs/PROJECT_STRUCTURE.md (if new modules added)

Initialize Documentation for Existing Project

This is an existing project without documentation. Please initialize its documentation structure.

> Note: Initialization starts by exploring the actual project structure, not assuming a specific layout (like src/), then generates documentation matched to the real structure.

---

Efficiency Target

If this methodology is followed strictly, content you genuinely need to write yourself should be < 5%:

Minor wording adjustments

Root cause analysis and problem diagnosis

Boundary case decisions

Code review and architecture adjustments

AI handles the remaining 95%: heavy lifting, repetitive work, high-speed code generation.