Skip to content

Commit 051c91f

Browse files
Lling0000Lling0000
committed
Polish README entrypoints and GitHub metadata
1 parent e408831 commit 051c91f

5 files changed

Lines changed: 348 additions & 144 deletions

File tree

‎README.en.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
<div align="center">
2+
3+
# Vibe Coding Guide
4+
5+
**Move AI coding from prompt experiments to a reviewable engineering workflow.**
6+
7+
Language: English | [中文](./README.md)
8+
9+
[Start on the Website](https://lling0000.github.io/Vibe_coding_guide/) ·
10+
[English Guide](./vibe-coding-guide-en.md) ·
11+
[中文教程](./vibe-coding-guide-zh.md) ·
12+
[Roadmap](./docs/roadmap.md)
13+
14+
[English PDF](./vibe-coding-guide-en.pdf) ·
15+
[中文 PDF](./vibe-coding-guide-zh.pdf) ·
16+
[Contributing](./CONTRIBUTING.md)
17+
18+
[![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-Reader%20%26%20Checklist-0f766e?logo=githubpages&logoColor=white)](https://lling0000.github.io/Vibe_coding_guide/)
19+
[![Docs CI](https://github.com/Lling0000/Vibe_coding_guide/actions/workflows/docs.yml/badge.svg)](https://github.com/Lling0000/Vibe_coding_guide/actions/workflows/docs.yml)
20+
[![English Guide](https://img.shields.io/badge/English%20Guide-16%20chapters-111827)](./vibe-coding-guide-en.md)
21+
[![Chinese Guide](https://img.shields.io/badge/Chinese%20Guide-16%20chapters-2563eb)](./vibe-coding-guide-zh.md)
22+
[![Topic: AI Coding](https://img.shields.io/badge/topic-AI%20Coding-b84d37)](https://github.com/topics/ai-coding)
23+
[![Content: CC BY 4.0](https://img.shields.io/badge/content-CC%20BY%204.0-6b7280)](./LICENSE-CONTENT)
24+
[![Code: MIT](https://img.shields.io/badge/code-MIT-blue.svg)](./LICENSE)
25+
26+
</div>
27+
28+
---
29+
30+
## What This Is
31+
32+
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.
33+
34+
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:
35+
36+
- specs that turn vague intent into a contract
37+
- durable project context through `AGENTS.md` / `CLAUDE.md`
38+
- context-window hygiene, compression, handoff, and reset habits
39+
- subagents, workflow patterns, and multi-agent coordination
40+
- git worktrees for parallel agent development
41+
- reusable skills for repeated tasks
42+
- CI, tests, and review habits for agent-written code
43+
44+
The goal is not to "let AI code for you." The goal is to become a stronger operator of AI coding agents.
45+
46+
## Start Here
47+
48+
| If you are... | Start with | What you should do first |
49+
|---|---|---|
50+
| Skimming before starring | [Website](https://lling0000.github.io/Vibe_coding_guide/) | Open the 16-day Feynman checklist and read the first day |
51+
| Reading in English | [vibe-coding-guide-en.md](./vibe-coding-guide-en.md) | Read chapters 1-5 before copying any workflow |
52+
| Reading in Chinese | [README.md](./README.md) | Use the Chinese entry page, then jump into the full guide |
53+
| Using Codex, Claude Code, Cursor, or Aider | Chapters 1-5 | Write one real spec and one project `AGENTS.md` / `CLAUDE.md` |
54+
| Running multiple agents or sessions | Chapters 6-9 | Learn subagents, workflow patterns, `.gitignore`, and worktrees |
55+
| Rolling this out to a team | Chapters 10-13 | Turn repeated work into skills and add CI/testing guardrails |
56+
| Auditing your own habits | Chapters 14-16 | Compare your current workflow against the anti-pattern checklist |
57+
58+
## The Engineering Loop
59+
60+
```mermaid
61+
flowchart LR
62+
A["Spec"] --> B["Context"]
63+
B --> C["Agent Plan"]
64+
C --> D["Implementation"]
65+
D --> E["Diff Review"]
66+
E --> F["Tests and CI"]
67+
F --> G["Commit"]
68+
G --> H["Docs and Handoff"]
69+
H --> A
70+
```
71+
72+
Vibe Coding works when this loop is explicit. Every phase should leave evidence in files, diffs, command output, tests, or commits.
73+
74+
## How This Differs From a Prompt Guide
75+
76+
| Ordinary prompt guide | Vibe Coding Guide |
77+
|---|---|
78+
| Optimizes a single request | Optimizes the whole engineering loop around the request |
79+
| Asks "what should I type?" | Asks "what system makes agent work reviewable?" |
80+
| Focuses on phrasing | Focuses on specs, context, files, git, CI, tests, and handoff |
81+
| Measures success by a plausible answer | Measures success by a diff that satisfies acceptance checks |
82+
| Treats chat history as memory | Moves durable knowledge into `AGENTS.md`, specs, docs, and skills |
83+
| Relies on manual recovery | Uses worktrees, commits, resets, and review gates to recover cleanly |
84+
85+
## Core Concepts
86+
87+
| Concept | Plain meaning | Why it matters |
88+
|---|---|---|
89+
| Spec | The contract for what the agent should change | Prevents vague work and gives you acceptance criteria |
90+
| Context | The files, rules, history, and examples the agent can use | Keeps the agent focused on the right local reality |
91+
| Agent plan | The proposed route before edits begin | Lets you stop bad direction before it becomes code |
92+
| Subagent | A separate worker for isolated search, review, or analysis | Keeps the main session from filling with unrelated context |
93+
| Workflow | A deterministic sequence of steps around the agent | Makes collaboration repeatable instead of improvised |
94+
| Worktree | A separate checkout for parallel work | Lets multiple agents move without stepping on each other |
95+
| Skill | A reusable task procedure | Turns repeated prompts into maintained operating knowledge |
96+
| CI/testing | Automated evidence that work still behaves | Replaces "looks right" with repeatable verification |
97+
98+
## Learning Paths
99+
100+
**30-minute orientation**
101+
102+
1. Read chapters 1-2 to understand the role shift from typing code to directing agent attention.
103+
2. Skim chapter 3 and write a tiny `AGENTS.md` / `CLAUDE.md` for one repository.
104+
3. Open the website checklist and write a three-minute explanation of the core loop.
105+
106+
**First real project**
107+
108+
1. Write a lightweight spec for a small change.
109+
2. Ask the agent for a plan before edits.
110+
3. Review the diff, run verification, and commit.
111+
4. Record one mistake or local convention back into project docs.
112+
113+
**Parallel agent practice**
114+
115+
1. Read chapters 6-9.
116+
2. Give broad discovery to a subagent or separate session.
117+
3. Put risky implementation in a dedicated git worktree.
118+
4. Merge only after review and tests pass.
119+
120+
**Team adoption**
121+
122+
1. Read chapters 10-13.
123+
2. Convert one repeated workflow into a skill.
124+
3. Add CI rules to the project agent guide.
125+
4. Build a small case library for evaluating agent behavior.
126+
127+
## Chapter Map
128+
129+
| Phase | Chapters | Outcome |
130+
|---|---:|---|
131+
| Foundations | 1-5 | Write better specs, maintain project context, and manage long sessions |
132+
| Coordination | 6-9 | Use subagents, workflow patterns, `.gitignore`, and worktrees |
133+
| Reuse and guardrails | 10-13 | Create skills, separate prompt layers, add CI/CD, and test agent behavior |
134+
| Judgment | 14-16 | Build durable habits and spot failure modes early |
135+
136+
| Chapter | Topic |
137+
|---:|---|
138+
| 1 | What Vibe Coding is and how your role changes |
139+
| 2 | Specs as the starting point for useful agent work |
140+
| 3 | What belongs in `AGENTS.md` / `CLAUDE.md` |
141+
| 4 | Cold-starting new and inherited projects |
142+
| 5 | Context management, compression, handoffs, and resets |
143+
| 6 | Subagents and context isolation |
144+
| 7 | Workflow patterns and multi-agent collaboration |
145+
| 8 | `.gitignore` as repository hygiene |
146+
| 9 | Git worktrees for parallel agent development |
147+
| 10 | Skills as reusable task workflows |
148+
| 11 | System prompts vs user prompts |
149+
| 12 | CI/CD guardrails for agent-written code |
150+
| 13 | Testing ordinary code and testing agent behavior |
151+
| 14 | Advanced operating principles |
152+
| 15 | A complete multi-day workflow example |
153+
| 16 | Anti-patterns checklist |
154+
155+
## Repository Structure
156+
157+
```text
158+
.
159+
├── index.html # GitHub Pages checklist and reader entry
160+
├── assets/ # Site styles, script, and visual asset
161+
├── docs/
162+
│ └── roadmap.md # Public roadmap and contribution priorities
163+
├── .github/workflows/
164+
│ └── docs.yml # Docs-only sanity checks for local links
165+
├── README.md # Chinese default front door
166+
├── README.en.md # English front door
167+
├── README.zh-CN.md # Chinese compatibility front door
168+
├── README_zh.md # Legacy Chinese entry link
169+
├── CONTRIBUTING.md # Contribution guide
170+
├── vibe-coding-guide-en.md # Full English tutorial
171+
├── vibe-coding-guide-en.pdf # English PDF
172+
├── vibe-coding-guide-zh.md # Full Chinese tutorial
173+
└── vibe-coding-guide-zh.pdf # Chinese PDF
174+
```
175+
176+
## Project Status
177+
178+
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.
179+
180+
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.
181+
182+
## Contributing
183+
184+
Good contributions make the guide more concrete, verifiable, and useful in real workflows. See [CONTRIBUTING.md](./CONTRIBUTING.md) and [docs/roadmap.md](./docs/roadmap.md) before opening a pull request.
185+
186+
## License
187+
188+
This repository uses a dual-license model:
189+
190+
- Documentation, guides, PDFs, and written instructional content are licensed under [CC BY 4.0](./LICENSE-CONTENT).
191+
- Website code, scripts, styles, and other software source files are licensed under the [MIT License](./LICENSE).
192+
193+
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.

0 commit comments

Comments
 (0)