189 lines
7.5 KiB
Markdown
189 lines
7.5 KiB
Markdown
### 1. 产品愿景与 MVP 范围书 (`PRD_MVP.md`)
|
||
|
||
AI 需要知道“终点”在哪里，以及“当前阶段”的界限。
|
||
|
||
- **核心功能清单：** 明确第一阶段（MVP）必须实现的 3-5 个核心功能。
|
||
|
||
- **非目标 (Out of Scope)：** 明确哪些功能在 MVP 阶段**绝对不做**，防止 Claude 在生成代码时过度设计。
|
||
|
||
- **用户故事：** 简单的 `As a [user], I want to [action], so that [value]`，这有助于 Claude 理解业务逻辑的优先级。
|
||
|
||
|
||
### 2. 技术栈与规范定义 (`TECH_STACK.md`)
|
||
|
||
Vibe Coding 最怕 AI 随意引入不兼容的库。
|
||
|
||
- **固定技术栈：** 例如 Frontend (Next.js 14, Tailwind), Backend (Supabase/PostgreSQL), Auth (Clerk)。
|
||
|
||
- **代码风格：** 比如“使用 Functional Components”、“优先使用 TypeScript 严格模式”、“所有的 API 调用必须遵循 RESTful 规范”。
|
||
|
||
- **项目结构：** 预定义文件夹结构（如 `/components`, `/hooks`, `/lib`, `/types`），让 AI 生成的代码能够准确归位。
|
||
|
||
|
||
### 3. 领域模型与数据库 Schema (`DATA_MODEL.md`)
|
||
|
||
这是项目的“骨架”。即便你使用 NoSQL，也要先定义好数据关系。
|
||
|
||
- **实体关系图 (ERD)：** 描述 User, Project, Task 等实体的关系。
|
||
|
||
- **Schema 定义：** 提供 SQL DDL 或 Prisma Schema 示例。
|
||
|
||
- **核心业务状态机：** 如果有复杂逻辑（如订单状态、工作流状态），定义好状态转换矩阵。
|
||
|
||
|
||
### 4. UI/UX 风格与组件指南 (`UI_SYSTEM.md`)
|
||
|
||
为了让生成的页面不至于太丑或不统一：
|
||
|
||
- **设计语言：** 明确使用哪个组件库（如 shadcn/ui, Ant Design）。
|
||
|
||
- **核心页面路由：** 定义 MVP 阶段的所有 URL 路径及对应的功能页面。
|
||
|
||
- **全局布局：** 描述 Header, Sidebar, Footer 的行为。
|
||
|
||
|
||
### 5. 项目骨架设计(`ARCHITECTURE.md`)
|
||
- **技术栈**
|
||
- Backend: Django 4.x
|
||
- 前端交互: HTMX 1.x + Alpine.js 3.x
|
||
- 样式: [Tailwind / 你的选择]
|
||
- 数据库: [PostgreSQL / SQLite]
|
||
|
||
- **目录结构说明**
|
||
[说明每个目录的职责]
|
||
|
||
- **Django App 划分原则**
|
||
- 每个 App 对应一个业务域，不跨域
|
||
- App 列表：accounts / dashboard / [其他]
|
||
|
||
- **模板约定**
|
||
- base.html 定义全局布局和 block 插槽
|
||
- HTMX 局部刷新的模板放在 partials/ 下
|
||
- block 结构：title / content / extra_css / extra_js
|
||
|
||
- **HTMX 使用约定**
|
||
- 所有 HTMX 请求的 view 需判断 HX-Request header
|
||
- 局部响应只返回对应的 partial 模板
|
||
- 示例：
|
||
def my_view(request):
|
||
if request.htmx:
|
||
return render(request, 'partials/xxx.html', context)
|
||
return render(request, 'full/xxx.html', context)
|
||
|
||
- **Alpine.js 使用约定**
|
||
- 只负责纯客户端状态（下拉展开、tab 切换、表单校验提示）
|
||
- 不处理需要服务端数据的逻辑，那部分交给 HTMX
|
||
|
||
- **URL 命名规范**
|
||
- 格式：app_name:resource-action
|
||
- 示例：accounts:login, dashboard:report-list
|
||
|
||
- **环境变量**
|
||
- 使用 .env 文件管理，通过 django-environ 读取
|
||
- 敏感配置不进 settings.py 硬编码
|
||
|
||
### 6. 任务清单(`TASK.md`)
|
||
这是 Vibe Coding 中最关键的"指挥文件"。它不只是任务清单，更是 AI 在每次对话中快速定位上下文的锚点。
|
||
|
||
**分解 User Story 的标准方法**
|
||
每个 User Story 在交给 AI 编码前，需要满足 **INVEST 原则** 中最关键的三条：
|
||
|
||
| 原则 | 实操含义 |
|
||
| ------------------- | ------------------------------------ |
|
||
| **Independent（独立）** | 这个 Story 能单独开发、单独测试，不强依赖其他未完成的 Story |
|
||
| **Small（小）** | 一个 Story 的编码工作控制在一次对话内能完成 |
|
||
| **Testable（可验证）** | 有明确的验收标准，你能用眼睛或操作来判断是否完成 |
|
||
**拆分的实用规则：** 如果一个 Story 的描述里出现了"并且"或"还可以"，就应该拆成两个。
|
||
|
||
|
||
|
||
### 6. AI 指令手册 (`.cursorrules` 或 `AI_INSTRUCTIONS.md`)
|
||
|
||
这是 Vibe Coding 的“灵魂”，专门给 Claude 看的“说明书”。
|
||
|
||
- **角色设定：** “你是一个资深的 Full-stack Engineer，擅长编写可维护的、高性能的 React 代码。”
|
||
|
||
- **禁止事项：** “禁止使用任何未在 TECH_STACK.md 中定义的第三方库。”
|
||
|
||
- **报错处理：** “如果遇到错误，优先检查类型定义，并输出详细的 Debug Log。”
|
||
|
||
## 针对 Vibe Coding 的特化建议
|
||
|
||
### 1. 采用“模块化文档”而非“长篇大论”
|
||
|
||
不要给 Claude 一个 5000 字的文档。将文档拆分为上述的 `.md` 文件。在对话时，使用 `@` 功能（在 Cursor/OpenCode 中）按需引用。例如：“基于 `@DATA_MODEL.md` 实现 `@PRD_MVP.md` 中的用户注册流程。”
|
||
|
||
### 2. 准备“上下文脚手架”
|
||
|
||
在开始第一行代码前，先让 Claude 生成一个 `README.md`，概括整个项目的架构。这会成为后续对话中最重要的上下文参考。
|
||
|
||
### 3. 动态更新的“决策记录” (`ADR.md`)
|
||
|
||
在 Vibe Coding 过程中，AI 可能会建议一些架构改动。一旦你接受了某个改动，**立即**记录在 `Architecture Decision Records (ADR)` 中。这样当你在后续对话中开启新 Session 时，可以把这个文档丢给它，避免它推翻之前的设计方案。
|
||
|
||
---
|
||
|
||
## 建议的执行流程
|
||
|
||
1. **初始化阶段：** 编写上述 5 份 Markdown 文档。
|
||
|
||
2. **环境对齐：** 将文档喂给 Claude，问它：“基于这些文档，你认为实现 MVP 的第一步是什么？请列出任务清单。”
|
||
|
||
3. **循环迭代：** 按照 `任务清单 -> 生成代码 -> 测试反馈 -> 更新文档` 的循环进行。
|
||
|
||
```
|
||
准备阶段（你现在所在的位置）
|
||
↓
|
||
① 整理 TASK.md，按 P0/P1/P2 排优先级
|
||
↓
|
||
② 从 Phase 1 挑第一个 Story 开始
|
||
↓
|
||
③ 每次开启新对话，给 AI 提供以下上下文包：
|
||
- TASK.md（让 AI 知道全局和当前任务）
|
||
- 相关模块的 PRD 片段
|
||
- 对应的 UI HTML 原型
|
||
- Tech Stack 文档
|
||
- 相关的 Data Model
|
||
↓
|
||
④ AI 完成编码后，你验收（对照验收标准）
|
||
↓
|
||
⑤ 验收通过 → 在 TASK.md 勾选 [x] → 进入下一个 Story
|
||
↓
|
||
⑥ 每完成一个模块，检查是否需要更新 Data Model 或 Tech 文档
|
||
```
|
||
|
||
### 给 AI 的标准开场提示词
|
||
|
||
每次开始一个新 Story 时，用这个模板开场：
|
||
|
||
```
|
||
## 当前任务
|
||
我正在开发 [项目名]，现在要实现 US-XXX：[Story 标题]
|
||
|
||
## 上下文文件（我将依次提供）
|
||
1. TASK.md - 了解项目全局状态和本任务优先级
|
||
2. Tech Stack 文档 - 了解技术约束
|
||
3. Data Model - 了解数据结构
|
||
4. 本模块 PRD - 了解功能需求
|
||
5. 本模块 UI 原型 HTML - 了解视觉要求
|
||
|
||
## 本次任务的验收标准
|
||
- [条件1]
|
||
- [条件2]
|
||
|
||
## 约束
|
||
- 只实现本 Story 范围内的功能，Phase 2/3 的内容不要提前实现
|
||
- 如遇到需要修改 Data Model 的情况，先告知我，不要擅自修改
|
||
- 完成后告诉我你新建或修改了哪些文件
|
||
```
|
||
|
||
**TASK.md 是活文档，AI 也要帮你维护它。**
|
||
|
||
每次 Story 完成后，让 AI 顺手输出一行更新指令，比如：
|
||
|
||
```
|
||
请在 TASK.md 中将 US-003 标记为已完成，并在备注中记录：
|
||
"Session 存储改用 httpOnly cookie，与原方案不同"
|
||
```
|
||
|
||
这样你的 TASK.md 不只是任务清单，还成了项目的**决策日志**，下一次换新对话时 AI 能快速理解为什么某些事情是现在这样做的。 |