### 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 能快速理解为什么某些事情是现在这样做的。