#000-资源库:文档驱动开发工具包

这是《用一份 .md，把想法变成产品》系列的配套资源库。这里汇总了系列文章中提到的所有核心文档模板、Prompt 技巧、工作流清单和决策框架。

💡 建议： 将本页收藏，或将模板复制到你的笔记软件（如 Obsidian/Notion）中，作为日后启动新项目的标准工具包。

1. 核心文档模板

这是文档驱动开发的基石。你可以直接复制以下 Markdown 内容建立新文件。

📄 [intent.md] (意图层)

用途：定义"为什么做"、"给谁做"以及"核心价值"。此文档在项目初期最重要，后期改动最少。

# 项目意图文档 (Project Intent)

## 1. 项目愿景 (Vision)
> 一句话描述这个项目是什么，以及它最终要达成什么样子的状态。
<!-- 示例：构建一个极简的、以内容为中心的个人博客系统，支持自动化部署。 -->

## 2. 目标用户 (Target Users)
*   **主要用户**：[描述]
*   **次要用户**：[描述]

## 3. 核心问题 (Core Problems)
此项目旨在解决什么具体问题？
1.  [问题1]
2.  [问题2]

## 4. 成功标准 (Success Criteria)
如何判断项目成功了？（尽量量化）
*   [ ] 核心功能 X 可用
*   [ ] 性能指标：[如：加载速度 < 1s]
*   [ ] 维护指标：[如：新增文章耗时 < 5min]

## 5. 反向边界 (Non-Goals)
我们**不做**什么？（防止范围蔓延）
*   [ ] 不做 [功能A]
*   [ ] 不支持 [平台B]

📄 [spec.md] (规范层)

用途：定义"做什么"。描述功能需求、用户交互和业务逻辑。

# 功能规范文档 (Product Spec)

## 1. 功能列表 (Features)
### F1. [功能名称]
*   **描述**：[详细描述]
*   **优先级**：P0 (核心) / P1 (重要) / P2 (可选)
*   **依赖**：[依赖的其他功能]

### F2. [功能名称]
...

## 2. 用户旅程 (User Journeys)
描述用户如何与系统交互。
> [用户角色] 进入 [页面] -> 点击 [按钮] -> 系统反馈 [结果] -> 跳转至 [新页面]

## 3. 验收标准 (Acceptance Criteria)
开发完成后，如何验证功能是否达标？
*   [ ] 情况 A 下，系统应显示 X
*   [ ] 情况 B 下，系统应报错 Y
*   [ ] 移动端布局正常

## 4. 非功能需求 (Non-functional Requirements)
*   **性能**：[如：API 响应 < 200ms]
*   **安全**：[如：数据加密存储]
*   **兼容性**：[如：支持暗色模式]

📄 plan.md

用途：定义"怎么做"。描述技术选型、架构设计和数据模型。

# 技术方案文档 (Implementation Plan)

## 1. 技术栈 (Tech Stack)
*   **前端**：[框架/库]
*   **后端**：[框架/服务]
*   **数据库**：[类型]
*   **部署**：[平台]

## 2. 系统架构 (Architecture)
*   **目录结构**：
    ```text
    /src
      /components
      /lib
    ```
*   **关键流程**：[简述核心逻辑流，如认证流程、数据获取流程]

## 3. 数据模型 (Data Model)
<!-- 如果是关系型数据库 -->
### User
| 字段 | 类型 | 说明 |
| :--- | :--- | :--- |
| id | UUID | 主键 |
| name | String | ... |

<!-- 如果是 Markdown/JSON -->
### Article Frontmatter
```yaml
title: String
date: Date
tags: String[]

4. 接口设计 (API Design)

GET /api/posts: 获取文章列表
POST /api/posts: 创建文章

5. 待办事项 (To-Do)

搭建基础脚手架
实现数据层
...


---

## 2. Prompt 工程模板库

让 AI 理解你的文档并生成高质量代码的关键 Prompt。

### 🧩 需求澄清 Prompt
**场景**：当你只有一个模糊想法，想让 AI 帮你完善 `spec.md` 时。

```markdown
我正在开发一个 [项目名称]。
目前我有以下核心意图：
[粘贴 intent.md 内容]

我想添加一个 [新功能名称]。
请作为一名资深产品经理，帮我思考这个功能的细节。
请列出 3-5 个你需要我澄清的问题，以便编写详细的 spec 文档。
不要直接生成文档，先提问。

💻 代码生成 Prompt (标准版)

场景：文档已准备好，让 AI 写代码。

请基于以下文档实现 [功能名称]。

**Context (上下文):**
1. **intent.md (意图)**: [简要概括或粘贴核心部分]
2. **spec.md (规范)**: [粘贴相关功能的 spec 部分]
3. **plan.md (方案)**: [粘贴相关技术方案]

**Constraints (约束):**
*   严格遵循 plan.md 中的技术选型。
*   保持现有的代码风格。
*   不要修改文档中未涉及的文件。

**Task (任务):**
请生成/修改以下文件：
1. [文件路径 1]
2. [文件路径 2]

🔄 文档更新/排错 Prompt

场景：代码写完了，或者发现了 Bug，需要回溯检查。

我目前遇到了一个问题：[描述 Bug 或不一致的地方]。

这是目前的 **plan.md**：
[粘贴 plan.md]

这是实际的 **代码片段**：
[粘贴代码]

请检查代码是否符合 plan.md 的设计？
如果不符合，请告诉我应该修改代码回归文档，还是更新文档以反映新的现实？

3. 工作流清单

在项目的不同阶段，对照此清单操作，确保持续交付。

🚀 新项目启动清单

创建 Git 仓库
创建
编写
编写
编写
首次 Commit：

⚡️ 功能迭代清单

🛡️ Code Review 清单 (含文档)

PR 是否包含文档变更？（如果没有，为什么？）
代码实现是否符合
功能表现是否满足
是否引入了新的技术债？如果有，是否记录在案？

4. 决策框架

如何决定何时使用文档驱动，以及使用什么力度？

⚖️ 文档分级策略 (L1/L2/L3)

级别	包含文档	适用场景	维护成本
L1 轻量级	仅 `intent.md`	探索性原型、一次性脚本、极度熟悉的领域	⭐
L2 标准级	`intent` + `spec` + `plan`	个人项目、中小型应用、本系列博客项目	⭐⭐⭐
L3 重量级	完整文档库 + 自动化检查	团队协作核心系统、开源库、高风险项目	⭐⭐⭐⭐⭐

🌲 决策树：我要写文档吗？

这是一次性的吗？
- 是 -> 直接写代码 (No Docs)
- 否 -> 转 2
这是一个探索性的原型（试完就扔）吗？
- 是 -> 直接写代码 (No Docs) 或 L1
- 否 -> 转 3
项目周期超过 1 周吗？
- 是 -> 必须使用 L2
- 否 -> L1 或 L2 均可
涉及多人协作吗？
- 是 -> 必须使用 L2 或 L3
- 否 -> L2

5. 工具推荐清单

工欲善其事，必先利其器。

IDE / 编辑器
- Cursor (强烈推荐)：原生集成了 AI，支持 @Files 引用文档，非常适合文档驱动流程。
- VS Code + Copilot：经典组合，需配合 Chat 面板使用。
文档管理
- Obsidian：本地 Markdown 管理神器，支持双向链接，适合管理复杂的文档库。
- Typora：所见即所得，适合快速编写 Markdown。
版本控制
- Git：必须使用。
- GitHub/GitLab：用于托管代码和文档。

6. Git 工作流示例

保持文档和代码的同步，Git 是最好的时间机器。

Commit Message 规范

建议遵循 Conventional Commits 规范，并增加文档相关的类型：

docs: update spec for user login (仅文档变更)
feat: implement user login (v0.2) (功能实现)
fix: fix login bug and update plan (修复 + 文档修正)
chore: update dependencies

同步规范

原则：如果是引入新功能，文档变更和代码变更最好在同一个 PR 中，或者文档变更的 Commit 先于代码变更的 Commit。

# 好的实践流程
git checkout -b feat/new-feature
# 1. 修改 spec.md 和 plan.md
git add docs/
git commit -m "docs: spec and plan for new feature"
# 2. 让 AI 基于文档写代码
git add src/
git commit -m "feat: implement new feature based on spec"
git push origin feat/new-feature

7. 博客项目文档示例 (Reference)

摘录自我们实战构建的博客项目，供参考语气和粒度。

示例 1：spec.md (v0.8 多作者系统)

## 新增功能：多作者支持
### 描述
系统需要支持多位作者。每篇文章关联一位作者，并在文章页显示作者简介。

### 用户旅程
1. 用户阅读文章 -> 看到标题下方的作者头像和姓名。
2. 用户点击作者姓名 -> 跳转至 `/authors/[slug]` 页面。
3. 用户在作者页 -> 看到该作者的简介和所有文章列表。

### 验收标准
- [ ] Frontmatter 缺失 author 字段时，默认显示 "Admin"。
- [ ] 点击作者链接路由跳转正确。
- [ ] 作者页面的文章列表按时间倒序排列。

示例 2：plan.md (v0.5 搜索功能)

## 搜索功能实现方案

### 技术选型
*   使用 `Fuse.js` 进行纯前端模糊搜索（无需后端）。
*   在构建时生成 `search-index.json`。

### 数据流
1.  **Build Time**: 扫描 `content/posts/*.md` -> 提取标题、摘要、slug -> 生成 JSON 索引。
2.  **Client Time**: 用户输入 -> Fuse.js 查询 JSON -> 返回匹配结果 -> 渲染列表。

### 组件设计
*   `SearchBox.tsx`: 包含输入框和下拉结果面板。
*   `useSearch`: 自定义 Hook 封装 Fuse.js 逻辑。