System Architecture Visualization Generation Mermaid.md 37 KB

Vibe Coding Guide

# Vibe Coding Supreme Super Ultimate Invincible Guide V114514 **The ultimate workstation for bringing ideas to life through AI pair programming** ---

Build Status Latest Release License Main Language Code Size Contributors Telegram Group

[๐Ÿ“š Related Documents](#-related-documents) [๐Ÿš€ Getting Started](#-getting-started) [โš™๏ธ Full Setup Process](#๏ธ-full-setup-process) [๐Ÿ“ž Contact Information](#-contact-information) [โœจ Sponsorship Address](#-sponsorship-address) [๐Ÿค Contributing](#-contributing)

๐Ÿ–ผ๏ธ Overview

Vibe Coding is the ultimate workflow for AI pair programming, designed to help developers smoothly bring ideas to life. This guide details the entire process from project conception, technology selection, implementation planning to specific development, debugging, and expansion. It emphasizes planning-driven and modularization as the core, preventing AI from going out of control and leading to project chaos.

Core Philosophy: Planning is everything. Be cautious about letting AI autonomously plan, otherwise your codebase will become an unmanageable mess.

๐Ÿงญ The Way (Dao)

  • If AI can do it, don't do it manually.
  • Ask AI everything.
  • Context is the primary element of Vibe Coding; garbage in, garbage out.
  • Systemic thinking: entities, links, functions/purposes, three dimensions.
  • Data and functions are everything in programming.
  • Input, process, output describe the entire process.
  • Frequently ask AI: What is it? Why? How to do it?
  • Structure first, then code; always plan the framework well, otherwise, technical debt will be endless.
  • Occam's Razor: Do not add code if unnecessary.
  • Pareto Principle: Focus on the important 20%.
  • Reverse thinking: First clarify your requirements, then build code reversely from requirements.
  • Repeat, try multiple times, if it really doesn't work, open a new window.
  • Focus, extreme focus can penetrate code; do one thing at a time (except for divine beings).

๐Ÿงฉ The Method (Fa)

  • One-sentence goal + non-goals.
  • Orthogonality: functionality should not be too repetitive (this depends on the scenario).
  • Copy, don't write: don't reinvent the wheel, first ask AI if there's a suitable repository, download and modify it.
  • Always read the official documentation; first, feed the official documentation to AI.
  • Split modules by responsibility.
  • Interfaces first, implementation later.
  • Change only one module at a time.
  • Documentation is context, not an afterthought.

๐Ÿ› ๏ธ The Techniques (Shu)

  • Clearly state: What can be changed, what cannot be changed.
  • Debug only provide: Expected vs. Actual + Minimum Reproduction.
  • Testing can be handed over to AI, assertions human-reviewed.
  • Too much code, switch sessions.

๐Ÿ“‹ The Tools (Qi)


๐Ÿ“š Related Documents/Resources


โœ‰๏ธ Contact Information


Project Directory Structure Overview

The core structure of this vibe-coding-cn project primarily revolves around knowledge management and the organization and automation of AI prompts. Below is a reorganized and simplified directory tree with explanations for each part:

.
โ”œโ”€โ”€ CODE_OF_CONDUCT.md           # Community code of conduct, regulating contributor behavior.
โ”œโ”€โ”€ CONTRIBUTING.md              # Contribution guide, explaining how to contribute to this project.
โ”œโ”€โ”€ GEMINI.md                    # AI assistant context document, including project overview, tech stack, and file structure.
โ”œโ”€โ”€ LICENSE                      # Open-source license file.
โ”œโ”€โ”€ Makefile                     # Project automation scripts for code checking, building, etc.
โ”œโ”€โ”€ README.md                    # Main project documentation, including project overview, usage guide, resource links, etc.
โ”œโ”€โ”€ .gitignore                   # Git ignore file.
โ”œโ”€โ”€ AGENTS.md                    # AI agent related documentation or configuration.
โ”œโ”€โ”€ CLAUDE.md                    # AI assistant's core behavioral guidelines or configuration.
โ”‚
โ”œโ”€โ”€ documents/                   # Stores various explanatory documents, experience summaries, and detailed configuration instructions.
โ”‚   โ”œโ”€โ”€ auggie-mcp Configuration Document.md      # Augment context engine configuration document.
โ”‚   โ”œโ”€โ”€ Code Organization.md                # Code organization and structure related documents.
โ”‚   โ”œโ”€โ”€ ... (other documents)
โ”‚
โ”œโ”€โ”€ libs/                        # General library code for internal project modularization.
โ”‚   โ”œโ”€โ”€ common/                  # Common functional modules.
โ”‚   โ”‚   โ”œโ”€โ”€ __init__.py          # Python package initialization file.
โ”‚   โ”‚   โ”œโ”€โ”€ models/              # Model definitions.
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ __init__.py
โ”‚   โ”‚   โ””โ”€โ”€ utils/               # Utility functions.
โ”‚   โ”‚       โ””โ”€โ”€ __init__.py
โ”‚   โ”œโ”€โ”€ database/                # Database related modules.
โ”‚   โ”‚   โ””โ”€โ”€ .gitkeep             # Placeholder file, ensuring the directory is tracked by Git.
โ”‚   โ””โ”€โ”€ external/                # External integration modules.
โ”‚       โ””โ”€โ”€ .gitkeep             # Placeholder file, ensuring the directory is tracked by Git.
โ”‚
โ”œโ”€โ”€ prompts/                     # Centralized storage for all types of AI prompts.
โ”‚   โ”œโ”€โ”€ assistant_prompts/       # Auxiliary prompts.
โ”‚   โ”œโ”€โ”€ coding_prompts/          # Prompt collection specifically for programming and code generation.
โ”‚   โ”‚   โ”œโ”€โ”€ ... (specific coding prompt files)
โ”‚   โ”‚
โ”‚   โ”œโ”€โ”€ prompts-library/         # Prompt library management tool (Excel-Markdown conversion)
โ”‚   โ”‚   โ”œโ”€โ”€ main.py              # Main entry for the prompt library management tool.
โ”‚   โ”‚   โ”œโ”€โ”€ scripts/             # Contains Excel and Markdown conversion scripts and configurations.
โ”‚   โ”‚   โ”œโ”€โ”€ prompt_excel/        # Stores raw prompt data in Excel format.
โ”‚   โ”‚   โ”œโ”€โ”€ prompt_docs/         # Stores Markdown prompt documents converted from Excel.
โ”‚   โ”‚   โ”œโ”€โ”€ ... (other prompts-library internal files)
โ”‚   โ”‚
โ”‚   โ”œโ”€โ”€ system_prompts/          # AI system-level prompts, used to set AI behavior and framework.
โ”‚   โ”‚   โ”œโ”€โ”€ CLAUDE.md/           # (Note: Files and directories under this path have the same name, may require user confirmation)
โ”‚   โ”‚   โ”œโ”€โ”€ ... (other system prompts)
โ”‚   โ”‚
โ”‚   โ””โ”€โ”€ user_prompts/            # User-defined or commonly used prompts.
โ”‚       โ”œโ”€โ”€ ASCII Art Generation.md         # ASCII art generation prompts.
โ”‚       โ”œโ”€โ”€ Data Pipeline.md            # Data pipeline processing prompts.
โ”‚       โ”œโ”€โ”€ ... (other user prompts)
โ”‚
โ””โ”€โ”€ backups/                     # Project backup scripts.
    โ”œโ”€โ”€ One-click Backup.sh                # Shell script for one-click backup.
    โ””โ”€โ”€ Fast Backup.py                # Python script for actual execution logic.

๐Ÿ–ผ๏ธ Overview and Demo

In one sentence: Vibe Coding = Planning-driven + Context-fixed + AI Pair Execution, transforming "idea to maintainable code" into an auditable pipeline, rather than an uniteratable monolith.

What you will get:

  • A systematic prompt toolchain: prompts/system_prompts/ constrains AI behavioral boundaries, prompts/coding_prompts/ provides full-link scripts for demand clarification, planning, and execution.
  • Closed-loop delivery path: Requirement โ†’ Context document โ†’ Implementation plan โ†’ Step-by-step implementation โ†’ Self-testing โ†’ Progress recording, fully reviewable and transferable.
  • Shared memory bank: Synchronize project-context.md, progress.md, etc., in memory-bank/ (or your equivalent directory), allowing humans and AI to share the same source of truth.

3-minute CLI demo (execute sequentially in Codex CLI / Claude Code) 1) Copy your requirements, load prompts/coding_prompts/(1,1)_#_๐Ÿ“˜_Project Context Document Generation_ยท_Engineering_Prompt (Professional Optimized Version).md to generate project-context.md. 2) Load prompts/coding_prompts/(3,1)_#_Process Standardization.md to get an executable implementation plan and acceptance criteria for each step. 3) Use prompts/coding_prompts/(5,1)_{content#_๐Ÿš€_Intelligent Requirement Understanding and R&D Navigation Engine (Meta_R&D_Navigator_ยท.md to drive AI to write code according to the plan; update progress.md and run tests or make test after each item is completed.

Screen recording key points (for replacement with GIF)

  • Screen 1: Paste requirements โ†’ automatically generate context document.
  • Screen 2: Generate implementation plan, check 3-5 tasks.
  • Screen 3: AI writes the first module and runs tests successfully.
  • It is recommended to save the screen recording as documents/assets/vibe-coding-demo.gif and then replace the link below.

Vibe Coding Three-Step Demo

Demo script (text version, can be directly fed to AI)

  • Example requirement: Help me write a weather query service with Redis cache using FastAPI (including Dockerfile and basic tests).
  • Remind AI: Execute according to the prompt order 1โ†’2โ†’3 above; each step must provide acceptance instructions; prohibit generating monolithic files.
  • Acceptance criteria: Interface return example, docker build and pytest all pass; README needs to supplement usage instructions and architectural summary.

To quickly test the waters, paste your requirements as is to AI, chain them together with prompts 1-2-3, and you will get a deliverable process that is implementable, verifiable, and maintainable.


โš™๏ธ Architecture and Workflow

Core Asset Mapping:

prompts/
  coding_prompts/        # Core prompts for demand clarification, planning, and execution chain
  system_prompts/        # System-level prompts constraining AI behavior
  assistant_prompts/     # Auxiliary/cooperative prompts
  user_prompts/          # Reusable user-side prompts
  prompts-library/       # Excelโ†”Markdown prompt conversion and indexing tool
documents/
  Code Organization.md, General Project Architecture Template.md, Development Experience.md, System Prompt Construction Principles.md, and other knowledge bases
backups/
  One-click Backup.sh, Fast Backup.py  # Local/remote snapshot scripts
graph TB
  %% GitHub compatible simplified version (using only basic syntax)

  subgraph ext_layer[External Systems and Data Sources Layer]
    ext_contrib[Community Contributors]
    ext_sheet[Google Sheets / External Tables]
    ext_md[External Markdown Prompts]
    ext_api[Reserved: Other Data Sources / APIs]
    ext_contrib --> ext_sheet
    ext_contrib --> ext_md
    ext_api --> ext_sheet
  end

  subgraph ingest_layer[Data Ingestion and Collection Layer]
    excel_raw[prompt_excel/*.xlsx]
    md_raw[prompt_docs/External MD Input]
    excel_to_docs[prompts-library/scripts/excel_to_docs.py]
    docs_to_excel[prompts-library/scripts/docs_to_excel.py]
    ingest_bus[Standardized Data Frame]
    ext_sheet --> excel_raw
    ext_md --> md_raw
    excel_raw --> excel_to_docs
    md_raw --> docs_to_excel
    excel_to_docs --> ingest_bus
    docs_to_excel --> ingest_bus
  end

  subgraph core_layer[Data Processing and Intelligent Decision Layer / Core]
    ingest_bus --> validate[Field Validation and Normalization]
    validate --> transform[Format Mapping Transformation]
    transform --> artifacts_md[prompt_docs/Standardized MD]
    transform --> artifacts_xlsx[prompt_excel/Export XLSX]
    orchestrator[main.py ยท scripts/start_convert.py] --> validate
    orchestrator --> transform
  end

  subgraph consume_layer[Execution and Consumption Layer]
    artifacts_md --> catalog_coding[prompts/coding_prompts]
    artifacts_md --> catalog_system[prompts/system_prompts]
    artifacts_md --> catalog_assist[prompts/assistant_prompts]
    artifacts_md --> catalog_user[prompts/user_prompts]
    artifacts_md --> docs_repo[documents/*]
    artifacts_md --> new_consumer[Reserved: Other Downstream Channels]
    catalog_coding --> ai_flow[AI Pair Programming Workflow]
    ai_flow --> deliverables[Project Context / Plan / Code Output]
  end

  subgraph ux_layer[User Interaction and Interface Layer]
    cli[CLI: python main.py] --> orchestrator
    makefile[Makefile Task Encapsulation] --> cli
    readme[README.md Usage Guide] --> cli
  end

  subgraph infra_layer[Infrastructure and Cross-cutting Capabilities Layer]
    git[Git Version Control] --> orchestrator
    backups[backups/One-click Backup.sh ยท backups/Fast Backup.py] --> artifacts_md
    deps[requirements.txt ยท scripts/requirements.txt] --> orchestrator
    config[prompts-library/scripts/config.yaml] --> orchestrator
    monitor[Reserved: Logging and Monitoring] --> orchestrator
  end

๐Ÿ“ˆ Performance Benchmarks (Optional) This repository is positioned as a "workflow and prompts" library rather than a performance-oriented codebase. It is recommended to track the following observable metrics (currently primarily relying on manual recording, which can be scored/marked in `progress.md`): | Metric | Meaning | Current Status/Suggestion | |:---|:---|:---| | Prompt Hit Rate | Proportion of generations that meet acceptance criteria on the first try | To be recorded; mark 0/1 after each task in progress.md | | Turnaround Time | Time required from requirement to first runnable version | Mark timestamps during screen recording, or use CLI timer to track | | Change Reproducibility | Whether context/progress/backup is updated synchronously | Manual update; add git tags/snapshots to backup scripts | | Routine Coverage | Presence of minimum runnable examples/tests | Recommend keeping README + test cases for each example project |

๐Ÿ—บ๏ธ Roadmap

gantt
    title Project Development Roadmap
    dateFormat YYYY-MM
    section Near Term (2025)
    Complete demo GIFs and example projects: active, 2025-12, 15d
    Prompt index auto-generation script: 2025-12, 10d
    section Mid Term (2026 Q1)
    One-click demo/verification CLI workflow: 2026-01, 15d
    Backup script adds snapshot and validation: 2026-01, 10d
    section Long Term (2026 Q1-Q2)
    Templated example project set: 2026-02, 20d
    Multi-model comparison and evaluation baseline: 2026-02, 20d

๐Ÿš€ Getting Started (This is by the original author, not me, I updated what I think are the best models)

To start Vibe Coding, you only need one of the following two tools:

  • Claude Opus 4.5, used in Claude Code
  • gpt-5.1-codex.1-codex (xhigh), used in Codex CLI

This guide applies to both the CLI terminal version and the VSCode extension version (both Codex and Claude Code have extensions, and their interfaces are updated).

*(Note: Earlier versions of this guide used Grok 3, later switched to Gemini 2.5 Pro, and now we are using Claude 4.5 (or gpt-5.1-codex.1-codex (xhigh)))*

(Note 2: If you want to use Cursor, please check version 1.1 of this guide, but we believe it is currently less powerful than Codex CLI or Claude Code)


โš™๏ธ Full Setup Process
1. Game Design Document - Hand your game idea to **gpt-5.1-codex** or **Claude Opus 4.5** to generate a concise **Game Design Document** in Markdown format, named `game-design-document.md`. - Review and refine it yourself to ensure it aligns with your vision. It can be very basic initially; the goal is to provide AI with the game structure and intent context. Do not over-design; it will be iterated later.
2. Tech Stack and CLAUDE.md / Agents.md - Ask **gpt-5.1-codex** or **Claude Opus 4.5** to recommend the most suitable tech stack for your game (e.g., ThreeJS + WebSocket for a multiplayer 3D game), save it as `tech-stack.md`. - Ask it to propose the **simplest yet most robust** tech stack. - Open **Claude Code** or **Codex CLI** in your terminal and use the `/init` command. It will read the two `.md` files you've created and generate a set of rules to guide the large model correctly. - **Key: Always review the generated rules.** Ensure the rules emphasize **modularization** (multiple files) and prohibit **monolithic files**. You may need to manually modify or supplement the rules. - **Extremely Important:** Some rules must be set to **"Always"** to force AI to read them before generating any code. For example, add the following rules and mark them as "Always"๏ผš > ``` > # Important Note: > # Before writing any code, you must fully read memory-bank/@architecture.md (including full database structure). > # Before writing any code, you must fully read memory-bank/@game-design-document.md. > # After completing a major feature or milestone, you must update memory-bank/@architecture.md. > ``` - Other (non-Always) rules should guide AI to follow best practices for your tech stack (e.g., networking, state management). - *If you want the cleanest code and most optimized project, this entire set of rule settings is mandatory.*
3. Implementation Plan - Provide the following to **gpt-5.1-codex** or **Claude Opus 4.5**: - Game Design Document (`game-design-document.md`) - Tech Stack Recommendation (`tech-stack.md`) - Ask it to generate a detailed **Implementation Plan** (Markdown format), containing a series of step-by-step instructions for AI developers. - Each step should be small and specific. - Each step must include tests to verify correctness. - Strictly no code - only write clear, specific instructions. - Focus on the **basic game** first; full features will be added later.
4. Memory Bank - Create a new project folder and open it in VSCode. - Create a subfolder `memory-bank` in the project root. - Place the following files into `memory-bank`: - `game-design-document.md` - `tech-stack.md` - `implementation-plan.md` - `progress.md` (create an empty file to record completed steps) - `architecture.md` (create an empty file to record the purpose of each file)

๐ŸŽฎ Vibe Coding Develops the Basic Game Now for the most exciting part!
Ensure Everything is Clear - Open **Codex** or **Claude Code** in the VSCode extension, or launch Claude Code / Codex CLI in the project terminal. - Prompt: Read all documents in `/memory-bank`. Is `implementation-plan.md` completely clear? What questions do you have for me to clarify, so that it is 100% clear to you? - It will usually ask 9-10 questions. After answering all of them, ask it to modify `implementation-plan.md` based on your answers to make the plan more complete.
Your First Implementation Prompt - Open **Codex** or **Claude Code** (extension or terminal). - Prompt: Read all documents in `/memory-bank`, then execute step 1 of the implementation plan. I will be responsible for running tests. Do not start step 2 until I verify the tests pass. After verification, open `progress.md` to record what you've done for future developers' reference, and add new architectural insights to `architecture.md` explaining the purpose of each file. - **Always** use "Ask" mode or "Plan Mode" (press `shift+tab` in Claude Code) first, and only let AI execute the step after you are satisfied. - **Ultimate Vibe:** Install [Superwhisper](https://superwhisper.com) and chat casually with Claude or gpt-5.1-codex using voice, without typing.
Workflow - After completing step 1: - Commit changes to Git (ask AI if you don't know how). - Start a new chat (`/new` or `/clear`). - Prompt: Read all files in memory-bank, read progress.md to understand previous work progress, then continue with step 2 of the implementation plan. Do not start step 3 until I verify the tests. - Repeat this process until the entire `implementation-plan.md` is completed.

โœจ Adding Detail Features Congratulations! You've built a basic game! It might still be rough and lack features, but now you can experiment and refine it as much as you want. - Want fog effects, post-processing, special effects, sound effects? A better plane/car/castle? A beautiful sky? - For each major feature added, create a new `feature-implementation.md` with short steps + tests. - Continue incremental implementation and testing.
๐Ÿž Fixing Bugs and Getting Stuck
General Fixes - If a prompt fails or breaks the project: - Use `/rewind` in Claude Code to revert; for gpt-5.1-codex, commit frequently with Git and reset when needed. - Error handling: - **JavaScript errors:** Open browser console (F12), copy error, paste to AI; for visual issues, send a screenshot. - **Lazy solution:** Install [BrowserTools](https://browsertools.agentdesk.ai/installation) to automatically copy errors and screenshots.
Difficult Issues - Really stuck: - Revert to the previous git commit (`git reset`), try again with a new prompt. - Extremely stuck: - Use [RepoPrompt](https://repoprompt.com/) or [uithub](https://uithub.com/) to synthesize the entire codebase into one file, then send it to **gpt-5.1-codex or Claude** for help.

๐Ÿ’ก Tips and Tricks
Claude Code & Codex Usage Tips - **Terminal version of Claude Code / Codex CLI:** Run in VSCode terminal to directly view diffs and feed context without leaving the workspace. - **Claude Code's `/rewind`:** Instantly revert to a previous state when iteration goes off track. - **Custom commands:** Create shortcuts like `/explain $param` to trigger prompts: "Analyze the code in depth to thoroughly understand how $param works. Tell me after you understand, then I will give you a new task." This allows the model to fully load context before modifying code. - **Clean up context:** Frequently use `/clear` or `/compact` (to retain conversation history). - **Time-saving trick (use at your own risk):** Use `claude --dangerously-skip-permissions` or `codex --yolo` to completely disable confirmation pop-ups.
Other Useful Tips - **Small modifications:** Use gpt-5.1-codex (medium) - **Write top-tier marketing copy:** Use Opus 4.1 - **Generate excellent 2D sprites:** Use ChatGPT + Nano Banana - **Generate music:** Use Suno - **Generate sound effects:** Use ElevenLabs - **Generate videos:** Use Sora 2 - **Improve prompt effectiveness:** - Add a sentence: "Think slowly, no rush, it's important to strictly follow my instructions and execute perfectly. If my expression is not precise enough, please ask." - In Claude Code, the intensity of keywords to trigger deep thinking: `think` < `think hard` < `think harder` < `ultrathink`.

โ“ Frequently Asked Questions (FAQ) - **Q: I'm making an app, not a game, is the process the same?** - **A:** Essentially the same! Just replace GDD with PRD (Product Requirement Document). You can also quickly prototype with v0, Lovable, Bolt.new, then move the code to GitHub, and clone it locally to continue development using this guide. - **Q: Your air combat game's plane model is amazing, but I can't make it with just one prompt!** - **A:** That wasn't one prompt, it was ~30 prompts + a dedicated `plane-implementation.md` file guided it. Use precise instructions like "cut space for ailerons on the wing," instead of vague instructions like "make a plane." - **Q: Why are Claude Code or Codex CLI stronger than Cursor now?** - **A:** It's entirely a matter of personal preference. We emphasize that Claude Code can better leverage the power of Claude Opus 4.5, and Codex CLI can better leverage the power of gpt-5.1-codex. Cursor does not utilize either of these as well as their native terminal versions. Terminal versions can also work in any IDE, with SSH remote servers, etc., and features like custom commands, sub-agents, and hooks can significantly improve development quality and speed in the long run. Finally, even if you only have a low-tier Claude or ChatGPT subscription, it's completely sufficient. - **Q: What if I don't know how to set up a multiplayer game server?** - **A:** Ask your AI.

๐Ÿ“ž Contact Information

Twitter: https://x.com/123olp

Telegram: https://t.me/desci0

Telegram Discussion Group: https://t.me/glue_coding

Telegram Channel: https://t.me/tradecat_ai_channel

Email (may not be seen in time): tukuai.ai@gmail.com


โœจ Sponsorship Address

Please help! My wallet has been drained by AIs. Please sponsor me for membership (you can contact me on TG or X) ๐Ÿ™๐Ÿ™๐Ÿ™

Tron (TRC20): TQtBXCSTwLFHjBqTS4rNUp7ufiGx51BRey

Solana: HjYhozVf9AQmfv7yv79xSNs6uaEU5oUk2USasYQfUYau

Ethereum (ERC20): 0xa396923a71ee7D9480b346a17dDeEb2c0C287BBC

BNB Smart Chain (BEP20): 0xa396923a71ee7D9480b346a17dDeEb2c0C287BBC

Bitcoin: bc1plslluj3zq3snpnnczplu7ywf37h89dyudqua04pz4txwh8z5z5vsre7nlm

Sui: 0xb720c98a48c77f2d49d375932b2867e793029e6337f1562522640e4f84203d2e

Binance UID Payment: 572155580


โœจ Contributors

Thanks to all developers who contributed to this project!


๐Ÿค Contributing

We warmly welcome all forms of contributions! If you have any ideas or suggestions for this project, please feel free to open an Issue or submit a Pull Request.

Before you start, please take some time to read our Contribution Guide (CONTRIBUTING.md) and Code of Conduct (CODE_OF_CONDUCT.md).


๐Ÿ“œ License

This project is licensed under the MIT license.


If this project is helpful to you, please don't hesitate to give it a Star โญ!

Star History

Star History Chart


Made with โค๏ธ and a lot of โ˜• by tukuaiai,Nicolas Zulloand 123olp

โฌ† Back to Top