7.5 KiB
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 时，可以把这个文档丢给它，避免它推翻之前的设计方案。
建议的执行流程
-
初始化阶段： 编写上述 5 份 Markdown 文档。
-
环境对齐： 将文档喂给 Claude，问它：“基于这些文档，你认为实现 MVP 的第一步是什么？请列出任务清单。”
-
循环迭代： 按照
任务清单 -> 生成代码 -> 测试反馈 -> 更新文档的循环进行。
准备阶段（你现在所在的位置）
↓
① 整理 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 能快速理解为什么某些事情是现在这样做的。