Skill: xiaoxiangxie/vibe-coding-blueprint (version 1.0.0)

--- 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) ```markdown # [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)** ```typescript // 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.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)