Move AI coding from prompt experiments to a reviewable engineering workflow.
Language: English | 中文
Start on the Website · English Guide · 中文教程 · Roadmap
English PDF · 中文 PDF · Contributing
AI coding breaks down when it stays at the prompt-to-code level: vague requests produce plausible diffs, long chats lose context, parallel agents collide, and "looks right" replaces verification.
Vibe Coding Guide solves that gap by treating AI coding as an engineering workflow: a repeatable loop for specifying work, feeding agents the right context, reviewing changes, testing behavior, committing safely, and handing work off. It is not a collection of magic prompts; it is the operating system around AI-assisted development:
- specs that turn vague intent into a contract
- durable project context through
AGENTS.md/CLAUDE.md - context-window hygiene, compression, handoff, and reset habits
- subagents, workflow patterns, and multi-agent coordination
- git worktrees for parallel agent development
- reusable skills for repeated tasks
- CI, tests, and review habits for agent-written code
The goal is not to "let AI code for you." The goal is to become a stronger operator of AI coding agents.
| If you are... | Start with | What you should do first |
|---|---|---|
| Skimming before starring | Website | Open the 16-day Feynman checklist and read the first day |
| Reading in English | vibe-coding-guide-en.md | Read chapters 1-5 before copying any workflow |
| Reading in Chinese | README.zh-CN.md | Use the Chinese entry page, then jump into the full guide |
| Using Codex, Claude Code, Cursor, or Aider | Chapters 1-5 | Write one real spec and one project AGENTS.md / CLAUDE.md |
| Running multiple agents or sessions | Chapters 6-9 | Learn subagents, workflow patterns, .gitignore, and worktrees |
| Rolling this out to a team | Chapters 10-13 | Turn repeated work into skills and add CI/testing guardrails |
| Auditing your own habits | Chapters 14-16 | Compare your current workflow against the anti-pattern checklist |
flowchart LR
A["Spec"] --> B["Context"]
B --> C["Agent Plan"]
C --> D["Implementation"]
D --> E["Diff Review"]
E --> F["Tests and CI"]
F --> G["Commit"]
G --> H["Docs and Handoff"]
H --> A
Vibe Coding works when this loop is explicit. Every phase should leave evidence in files, diffs, command output, tests, or commits.
| Ordinary prompt guide | Vibe Coding Guide |
|---|---|
| Optimizes a single request | Optimizes the whole engineering loop around the request |
| Asks "what should I type?" | Asks "what system makes agent work reviewable?" |
| Focuses on phrasing | Focuses on specs, context, files, git, CI, tests, and handoff |
| Measures success by a plausible answer | Measures success by a diff that satisfies acceptance checks |
| Treats chat history as memory | Moves durable knowledge into AGENTS.md, specs, docs, and skills |
| Relies on manual recovery | Uses worktrees, commits, resets, and review gates to recover cleanly |
| Concept | Plain meaning | Why it matters |
|---|---|---|
| Spec | The contract for what the agent should change | Prevents vague work and gives you acceptance criteria |
| Context | The files, rules, history, and examples the agent can use | Keeps the agent focused on the right local reality |
| Agent plan | The proposed route before edits begin | Lets you stop bad direction before it becomes code |
| Subagent | A separate worker for isolated search, review, or analysis | Keeps the main session from filling with unrelated context |
| Workflow | A deterministic sequence of steps around the agent | Makes collaboration repeatable instead of improvised |
| Worktree | A separate checkout for parallel work | Lets multiple agents move without stepping on each other |
| Skill | A reusable task procedure | Turns repeated prompts into maintained operating knowledge |
| CI/testing | Automated evidence that work still behaves | Replaces "looks right" with repeatable verification |
30-minute orientation
- Read chapters 1-2 to understand the role shift from typing code to directing agent attention.
- Skim chapter 3 and write a tiny
AGENTS.md/CLAUDE.mdfor one repository. - Open the website checklist and write a three-minute explanation of the core loop.
First real project
- Write a lightweight spec for a small change.
- Ask the agent for a plan before edits.
- Review the diff, run verification, and commit.
- Record one mistake or local convention back into project docs.
Parallel agent practice
- Read chapters 6-9.
- Give broad discovery to a subagent or separate session.
- Put risky implementation in a dedicated git worktree.
- Merge only after review and tests pass.
Team adoption
- Read chapters 10-13.
- Convert one repeated workflow into a skill.
- Add CI rules to the project agent guide.
- Build a small case library for evaluating agent behavior.
| Phase | Chapters | Outcome |
|---|---|---|
| Foundations | 1-5 | Write better specs, maintain project context, and manage long sessions |
| Coordination | 6-9 | Use subagents, workflow patterns, .gitignore, and worktrees |
| Reuse and guardrails | 10-13 | Create skills, separate prompt layers, add CI/CD, and test agent behavior |
| Judgment | 14-16 | Build durable habits and spot failure modes early |
| Chapter | Topic |
|---|---|
| 1 | What Vibe Coding is and how your role changes |
| 2 | Specs as the starting point for useful agent work |
| 3 | What belongs in AGENTS.md / CLAUDE.md |
| 4 | Cold-starting new and inherited projects |
| 5 | Context management, compression, handoffs, and resets |
| 6 | Subagents and context isolation |
| 7 | Workflow patterns and multi-agent collaboration |
| 8 | .gitignore as repository hygiene |
| 9 | Git worktrees for parallel agent development |
| 10 | Skills as reusable task workflows |
| 11 | System prompts vs user prompts |
| 12 | CI/CD guardrails for agent-written code |
| 13 | Testing ordinary code and testing agent behavior |
| 14 | Advanced operating principles |
| 15 | A complete multi-day workflow example |
| 16 | Anti-patterns checklist |
.
├── index.html # GitHub Pages checklist and reader entry
├── assets/ # Site styles, script, and visual asset
├── docs/
│ └── roadmap.md # Public roadmap and contribution priorities
├── .github/workflows/
│ └── docs.yml # Docs-only sanity checks for local links
├── README.md # English front door
├── README.zh-CN.md # Chinese front door
├── README_zh.md # Legacy Chinese entry link
├── CONTRIBUTING.md # Contribution guide
├── vibe-coding-guide-en.md # Full English tutorial
├── vibe-coding-guide-en.pdf # English PDF
├── vibe-coding-guide-zh.md # Full Chinese tutorial
└── vibe-coding-guide-zh.pdf # Chinese PDF
This is a documentation-first repository. The full bilingual guides and PDFs are already included, and the GitHub Pages site provides a 16-day Feynman-style learning checklist with local browser progress.
There is currently no package manager setup because the site is plain static HTML/CSS/JavaScript. The CI added here only checks repository-facing documentation links; it does not build or publish a package.
Good contributions make the guide more concrete, verifiable, and useful in real workflows. See CONTRIBUTING.md and docs/roadmap.md before opening a pull request.
This repository uses a dual-license model:
- Documentation, guides, PDFs, and written instructional content are licensed under CC BY 4.0.
- Website code, scripts, styles, and other software source files are licensed under the MIT License.
If a file does not say otherwise, use the license that matches its primary purpose: written guide content uses CC BY 4.0; executable or reusable code uses MIT.