**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.
**Note**: The following experience sharing is not universally applicable. Please adopt it dialectically in specific practices combined with your scenario.
The core of this philosophy is to build an AI system capable of **self-optimization**. Its recursive nature can be broken down into the following steps:
> Further reading: [A Formalization of Recursive Self-Optimizing Generative Systems](./i18n/en/documents/Methodology%20and%20Principles/A%20Formalization%20of%20Recursive%20Self-Optimizing%20Generative%20Systems.md)
* Feed the newly generated, more powerful products (including new versions of `Ω-Prompt`) back into the system, again for optimizing `α-Prompt`, thereby initiating continuous evolution.
Through this continuous **recursive optimization loop**, the system achieves **self-transcendence** in each iteration, infinitely approaching the preset **expected state**.
* [**Visual Studio Code**](https://code.visualstudio.com/): A powerful integrated development environment, suitable for code reading and manual modifications. Its `Local History` plugin is particularly convenient for project version management.
***Virtual Environment (.venv)**: Highly recommended for one-click configuration and isolation of project environments, especially for Python development.
* [**Cursor**](https://cursor.com/): Has already captured user mindshare and is widely known.
* [**Warp**](https://www.warp.dev/): A modern terminal integrated with AI features, effectively improving command-line operations and error troubleshooting efficiency.
* [**Neovim (nvim)**](https://github.com/neovim/neovim): A high-performance modern Vim editor with a rich plugin ecosystem, the first choice for keyboard-driven developers.
* [**LazyVim**](https://github.com/LazyVim/LazyVim): A configuration framework based on Neovim, pre-configured with LSP, code completion, debugging, and other full-featured functionalities, achieving a balance between out-of-the-box usability and deep customization.
* [**Claude Opus 4.5**](https://claude.ai/new): A powerful AI model, offered through platforms like Claude Code, and supporting CLI and IDE plugins.
* [**gpt-5.1-codex.1-codex (xhigh)**](https://chatgpt.com/codex/): An AI model suitable for handling large projects and complex logic, usable through platforms like Codex CLI.
* [**Droid**](https://factory.ai/news/terminal-bench): Provides CLI access to various models including Claude Opus 4.5.
* [**Kiro**](https://kiro.dev/): Currently offers free access to the Claude Opus 4.5 model, and provides client and CLI tools.
* [**Gemini CLI**](https://geminicli.com/): Provides free access to the Gemini model, suitable for executing scripts, organizing documents, and exploring ideas.
* [**antigravity**](https://antigravity.google/): Currently a free AI service provided by Google, supporting Claude Opus 4.5 and Gemini 3.0 Pro.
* [**AI Studio**](https://aistudio.google.com/prompts/new_chat): A free service provided by Google, supporting Gemini 3.0 Pro and Nano Banana.
* [**Gemini Enterprise**](https://cloud.google.com/gemini-enterprise): Google's AI service for enterprise users, currently available for free.
* [**GitHub Copilot**](https://github.com/copilot): An AI code completion tool jointly developed by GitHub and OpenAI.
* [**Kimi K2**](https://www.kimi.com/): A domestic AI model suitable for various general tasks.
* [**GLM**](https://bigmodel.cn/): A domestic large language model developed by Zhipu AI.
* [**Qwen**](https://qwenlm.github.io/qwen-code-docs/zh/cli/): An AI model developed by Alibaba, its CLI tool offers free usage quota.
* [**Augment**](https://app.augmentcode.com/): Provides powerful context engine and prompt optimization features.
* [**Windsurf**](https://windsurf.com/): An AI development tool offering free credits to new users.
* [**Ollama**](https://ollama.com/): A local large model management tool that allows easy pulling and running of open-source models via the command line.
* [**Mermaid Chart**](https://www.mermaidchart.com/): Used to convert text descriptions into visual diagrams like architecture diagrams and sequence diagrams.
* [**NotebookLM**](https://notebooklm.google.com/): A tool for AI interpretation of materials, audio, and generating mind maps.
* [**Zread**](https://zread.ai/): An AI-driven GitHub repository reading tool that helps quickly understand project code.
* [**tmux**](https://github.com/tmux/tmux): A powerful terminal multiplexer that supports session persistence, splitting panes, and background tasks, ideal for server and multi-project development.
* [**DBeaver**](https://dbeaver.io/): A universal database management client that supports various databases and offers comprehensive features.
* [**Prompt Library (Online Table)**](https://docs.google.com/spreadsheets/d/1ngoQOhJqdguwNAilCl1joNwTje7FWWN9WiI2bo5VhpU/edit?gid=2093180351#gid=2093180351&range=A1): An online table containing a large number of ready-to-use prompts for various categories.
* [**Third-party System Prompt Learning Library**](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools): For learning and referencing system prompts of other AI tools.
* [**Skills Maker**](https://github.com/yusufkaraaslan/Skill_Seekers): A tool for generating customized skills based on requirements.
* [**Meta-Prompts**](https://docs.google.com/spreadsheets/d/1ngoQOhJqdguwNAilCl1joNwTje7FWWN9WiI2bo5VhpU/edit?gid=1770874220#gid=1770874220): Advanced prompts for generating prompts.
* [**General Project Architecture Template**](./i18n/en/documents/Templates%20and%20Resources/General%20Project%20Architecture%20Template.md): Can be used to quickly set up standardized project directory structures.
* [**Meta-Skill: Skills of Skills**](./i18n/en/skills/claude-skills/SKILL.md): A meta-skill for generating skills.
* [**tmux Shortcut Cheatsheet**](./i18n/en/documents/Tutorials%20and%20Guides/tmux%20Shortcut%20Cheatsheet.md): Reference documentation for tmux shortcuts.
* [**LazyVim Shortcut Cheatsheet**](./i18n/en/documents/Tutorials%20and%20Guides/LazyVim%20Shortcut%20Cheatsheet.md): Reference documentation for LazyVim shortcuts.
* [**Erge's Java Advanced Path**](https://javabetter.cn/): Contains detailed configuration tutorials for various development tools.
* [**Virtual Card**](https://www.bybit.com/cards/?ref=YDGAVPN&source=applet_invite): Can be used for registering cloud services and other scenarios requiring international payments.
* [**Meta-Prompt Library**](https://docs.google.com/spreadsheets/d/1ngoQOhJqdguwNAilCl1joNwTje7FWWN9WiI2bo5VhpU/edit?gid=1770874220#gid=1770874220): A collection of advanced prompts for generating prompts.
* [**Meta-Skill**](./i18n/en/skills/claude-skills/SKILL.md): A skill for generating skills.
* [**Skills Library**](./i18n/en/skills): A modular skill repository that can be directly integrated.
* [**Skill Generator**](https://github.com/yusufkaraaslan/Skill_Seekers): A tool to convert any material into agent-usable skills.
* [**Online Prompt Database**](https://docs.google.com/spreadsheets/d/1ngoQOhJqdguwNAilCl1joNwTje7FWWN9WiI2bo5VhpU/edit?gid=2093180351#gid=2093180351&range=A1): An online table containing hundreds of user and system prompts for various scenarios.
* [**Third-party System Prompt Repository**](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools): Gathers system prompts from various AI tools.
***Internal Project Documentation**:
* [**prompts-library Tool Description**](./libs/external/prompts-library/): This tool supports converting prompts between Excel and Markdown formats, and includes hundreds of selected prompts.
* [**coding_prompts Collection**](./i18n/en/prompts/coding_prompts/): Dedicated prompts for the Vibe Coding process.
* [**System Prompt Construction Principles**](./i18n/en/documents/Methodology%20and%20Principles/System%20Prompt%20Construction%20Principles.md): A comprehensive guide on how to build efficient and reliable AI system prompts.
* [**Development Experience Summary**](./i18n/en/documents/Methodology%20and%20Principles/Development%20Experience.md): Includes practical experience on variable naming, file structure, coding standards, and architectural principles.
* [**General Project Architecture Template**](./i18n/en/documents/Templates%20and%20Resources/General%20Project%20Architecture%20Template.md): Provides standard directory structures and best practices for various project types.
* [**Augment MCP Configuration Document**](./i18n/en/documents/Tutorials%20and%20Guides/auggie-mcp%20Configuration%20Document.md): Detailed configuration instructions for the Augment context engine.
* [**system_prompts Collection**](./i18n/en/prompts/system_prompts/): System prompts used to guide AI development, including multiple versions of development specifications and thinking frameworks.
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:
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.
- A systematic prompt toolchain: `i18n/en/prompts/system_prompts/` defines AI behavioral boundaries, `i18n/en/prompts/coding_prompts/` provides full-link scripts for demand clarification, planning, and execution.
Templates and Resources/Code Organization.md, Templates and Resources/General Project Architecture Template.md, Methodology and Principles/Development Experience.md, Methodology and Principles/System Prompt Construction Principles.md, and other knowledge bases.
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`):
| 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 |
2. [02-Development Environment Setup](./i18n/en/documents/Starting%20Vibe%20Coding%20from%20Scratch/02-Development%20Environment%20Setup.md) - Copy prompts to AI, let AI guide you through environment setup
3. [03-IDE Configuration](./i18n/en/documents/Starting%20Vibe%20Coding%20from%20Scratch/03-IDE%20Configuration.md) - Configure VS Code editor
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](https://github.com/EnzeD/vibe-coding/tree/1.1.1) of this guide, but we believe it is currently less powerful than Codex CLI or Claude Code)*
- 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.
- 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":
- 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.
- 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.
- 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.
- 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.
- **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.
- **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`.
- **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.
We warmly welcome all forms of contributions. If you have any ideas or suggestions for this project, please feel free to open an [Issue](https://github.com/tukuaiai/vibe-coding-cn/issues) or submit a [Pull Request](https://github.com/tukuaiai/vibe-coding-cn/pulls).
Before you start, please take the time to read our [**Contribution Guide (CONTRIBUTING.md)**](CONTRIBUTING.md) and [**Code of Conduct (CODE_OF_CONDUCT.md)**](CODE_OF_CONDUCT.md).
