PRD 与文档驱动开发
3.10 项目说明书结构
Tip
学会写标准的README.md,让AI和用户快速理解项目是什么、怎么跑。
1. 为什么要学这个?
你写了一个很牛的代码库,发到GitHub。没人看,没人用,连你自己过两个月再看都忘了怎么跑起来。
因为你没写门面(Storefront)。
当AI接手一个新项目时,它会首先读取README来了解:"这是什么?怎么跑?用了什么技术?"
关键问题:
- README应该包含什么?
- 怎么写Quick Start?
- 为什么README很重要?
README是项目的"只有一句话的推销",如果你不能在3秒内让AI/用户明白这是干嘛的,你就失败了。
2. 核心概念
2.1 代码 vs README
代码 = 卡带里的数据💾
- 虽然重要,但你第一眼看不到
README = 包装盒封面📦
- 封面图:一句话介绍这游戏好玩在哪(Value Proposition)
- 配置要求:Windows还是Mac?内存多少?(Requirements)
- 作弊码:怎么快速通关?(Quick Start)
3. 标准README结构
# [Project Name]
> 一句话标语:解决什么核心问题
## 🛠 Tech Stack
- **Framework**: Next.js 14
- **DB**: Postgres (Prisma)
- **UI**: Tailwind CSS
## 🚀 Quick Start (如何启动)
1. **Clone**: `git clone ...`
2. **Install**: `pnpm install` (Must use pnpm!)
3. **Env**: Copy `.env.example` to `.env`
4. **Run**: `pnpm dev`
## 📂 Project Structure (目录结构)
- `/app`: Frontend pages
- `/lib`: Helper functions
- `/prisma`: DB Schema
## 📝 Features
- [ ] User Login
- [x] Data Visualization
**为什么这对AI很重要?**当你让AI"帮我运行这个项目"时,它会直接照着Quick Start里的指令去执行。如果这里写错了,AI就跑不通。
4. 避坑指南
| ❌ 不要这样做 | ✅ 应该这样做 | 为什么 |
|---|---|---|
| 空荡荡的README | 必须包含Quick Start | AI只能猜怎么跑,通常会猜错命令(npm vs pnpm) |
| 写长篇大论的原理 | 关注Use,而非Theory | 原理去写博客,这里只写怎么用 |
| 截图失效 | 把图片放在assets文件夹里提交 | 图片挂了会让人觉得项目已死 |
5. 真实案例
Story
1991年,Linux 0.01的谦虚门面
1991年8月25日,Linus Torvalds在Usenet新闻组里发了一封邮件,这封邮件本质上就是Linux的第一版README。他写道:"我在做一个(自由的)操作系统(只是个爱好,不会像gnu那么大而专业)...目前移植了bash(1.08)和gcc(1.40),而且能用了。"分析:1)Value:免费OS,移植了常用工具;2)Status:Just a hobby,但能用了(MVP);3)Requirements:386/486 AT clones。这段简短的"说明书",吸引了最初的几个黑客,随后雪球越滚越大。如果他当时发的是几万字的内核原理论文,可能Linux早就淹没在历史的尘埃里了。
Vibe心法:README必须包含Tech Stack和Quick Start——清晰、诚实、简洁,让代码自己说话。
6. 本章小结
- 📦 门面:README是第一印象
- 🚀 Quick Start:必须包含启动命令
- 🛠️ Tech Stack:明确技术栈
- 📂 Project Structure:说明目录结构
- ⚠️ 避免长篇:关注怎么用,不要写原理