User688731625

开发者docs文档模板分享

03/25154 浏览开发心得

包含7类常见开发文档模板，可供开发者/ai参考。

(可直接喂给嗒啦啦)

文档模板库

> **用途**：为项目中不同类型的文档提供标准结构模板。新建文档时复制对应模板，填充内容。

> **设计哲学**：本项目的文档遵循"决策导向"写作风格——每个章节回答一个决策问题，而非描述一个概念。读者读完应该知道"该怎么做"，而非"这是什么"。

---

导览目录

- [写作原则](#写作原则) — 所有文档类型的通用写作规范

- [模板 1: 大纲](#模板-1-大纲) — 系统/功能的设计方向文档

- [模板 2: 待办](#模板-2-待办) — 开发进度追踪文档

- [模板 3: 规范](#模板-3-规范) — 编码/设计的约束性规则文档

- [模板 4: 系统（技术实现指南）](#模板-4-系统技术实现指南) — 指导 AI 实现某个系统的技术文档

- [模板 5: 陷阱记录](#模板-5-陷阱记录) — bug 教训与踩坑记录

- [模板 6: 参考表](#模板-6-参考表) — 术语表、字段表等查阅型文档

- [附录: 文档类型选择指南](#附录-文档类型选择指南) — 不确定该写哪种文档时看这里

---

写作原则

### 原则 1: 决策导向，不要描述导向

```

❌ 描述导向（回答"是什么"）：

"存档系统是一个用于保存和加载游戏进度的模块，它将玩家的状态数据序列化后

存储到持久化存储中，并在游戏启动时反序列化恢复状态。"

✅ 决策导向（回答"怎么做"和"为什么"）：

"使用 clientCloud 云变量存储，不用本地 File API。

原因：WASM 平台本地文件在刷新/清缓存后丢失，这是决定性因素。"

```

### 原则 2: 信息密度优先

- 一句话能说清的不用一段话

- 表格优于段落（便于扫描）

- 决策表优于 if-else 文字（便于查找）

- 删掉"众所周知"、"一般来说"、"需要注意的是"等填充词

### 原则 3: 对比优于单边论述

给出方案时，同时展示被否决的方案和理由：

```markdown

| 因素 | 方案 A | 方案 B（采用） |

|------|--------|--------------|

| 优点 | ... | ... |

| 缺点 | ... | ... |

| 结论 | 不采用，因为 X | ✅ 采用 |

```

### 原则 4: 用 ✅/❌ 标注对错

对于容易踩坑的写法，始终提供正反对比：

```lua

-- ❌ 错误

local x = eventData["X"] -- 缺少类型转换

-- ✅ 正确

local x = eventData["X"]:GetInt()

```

### 原则 5: 标注权威范围

每个文档头部声明：

- **用途**：一句话说明文档目的

- **权威范围**：哪些主题以本文档为准

- **配套文档**：相关文档链接

- **依赖/被依赖**（系统类文档）：声明上下游关系

### 原则 6: 标注待定项

未确定的内容用 `[待定]` 标记，不要编造或留空：

```markdown

- 弩箭上限：[待定，数值平衡后填入]

- 背包容量：无限制（已确定）

```

---

模板 1: 大纲

**用途**：为一个系统/功能确定设计方向。回答"做什么"和"为什么这样做"，不涉及技术实现细节。

**典型文件名**：`大纲/XXX大纲.md`

**代表作**：`大纲/背包系统大纲.md`

---

````markdown

# [系统名称]大纲

> **用途**：指导新对话理解[系统名称]的设计决策与实现方向。

> **权威范围**：[列举本文档管辖的主题]。[系统名称]相关设计的唯一权威；当与其他文档冲突时，以本文档为准。

> 配套文档：[游戏大纲](游戏大纲.md) | [玩法大纲](玩法大纲.md) | [相关文档]

> **依赖**：[本系统依赖哪些系统，各依赖什么]

> **被依赖**：[哪些系统依赖本系统，各依赖什么]

> **详见**：[跨系统依赖表](../系统/跨系统依赖表.md#N-系统名)

---

## 导览目录

- [1. 系统定义与边界](#1-系统定义与边界) — 做什么、不做什么

- [2. 核心设计决策](#2-核心设计决策) — 关键选择及理由

- [3. 分类/模型](#3-分类模型) — 核心概念的分类体系

- [4. 交互方式](#4-交互方式) — 玩家如何与系统互动

- [5. 与其他系统的衔接](#5-与其他系统的衔接) — 跨系统接口约定

- [6. 未确定事项](#6-未确定事项) — 待讨论的设计问题

---

## 1. 系统定义与边界

### 1.1 功能链

[系统名称]的完整功能链：**[动作1] → [动作2] → ... → [动作N]**。

### 1.2 系统边界

[系统名称]**不包含**以下内容（它们是独立系统）：

| 独立系统 | 说明 | 与本系统的关系 |

|---------|------|--------------|

| [系统A] | [一句话说明] | [如何交互] |

---

## 2. 核心设计决策

### 2.1 [决策主题]

**选择**：[方案名称]

| 因素 | 方案 A | 方案 B（采用） |

|------|--------|--------------|

| [比较维度1] | ... | ... |

| [比较维度2] | ... | ... |

**采用理由**：[一句话说明决定性因素]

---

## 3. 分类/模型

| 分类 | 特征 | 典型实例 | 规则 |

|------|------|---------|------|

---

## 4. 交互方式

---

## 5. 与其他系统的衔接

| 方向 | 系统 | 接口 | 说明 |

|------|------|------|------|

| 本系统 → | [系统A] | [函数/数据] | [什么时候调用] |

| → 本系统 | [系统B] | [函数/数据] | [什么时候被调用] |

---

## 6. 未确定事项

- [ ] [问题1]：[简述问题，列出可能的方案]

- [ ] [问题2]：[简述问题]

---

## 变更日志

| 日期 | 变更内容 |

|------|---------|

| YYYY-MM-DD | 初版 |

---

*创建日期：YYYY-MM-DD*

````

---

模板 2: 待办

**用途**：追踪某个领域的开发进度。回答"做了什么"、"还差什么"、"接下来做什么"。

**典型文件名**：`待办/XXX待办.md`

**代表作**：`待办/玩法待办.md`

---

````markdown

# [领域名称]待办

> **用途**：追踪[领域名称]的开发完成度、待规划问题和推进方向，供后续对话核实进度。

> **定位**：进度追踪文档，不是设计权威。记录各系统的规划状态和待讨论要点，具体设计内容以对应的专项文档为准。

> 配套文档：[相关大纲] | [相关规范]

> **更新规则**：每次[领域名称]相关的讨论或开发后同步更新本文档，将已完成项从"待完成"移至"已完成"，更新完成度百分比。

---

## 导览目录

- [1. 各模块完成度总览](#1-各模块完成度总览)

- [2. 待完成模块（按优先级）](#2-待完成模块按优先级)

- [3. 已完成模块](#3-已完成模块)

- [4. 推进方向建议](#4-推进方向建议)

---

## 1. 各模块完成度总览

| 模块 | 完成度 | 状态 | 说明 |

|------|-------|------|------|

| **[模块A]** | 100% | ✅ 完成 | [一句话总结] |

| **[模块B]** | 60% | 🔧 进行中 | [已完成什么、还差什么] |

| **[模块C]** | 15% | 📐 设计完成 | [设计方案见XX文档，代码未写] |

| **[模块D]** | 0% | ⬜ 未开始 | [简要说明] |

**状态图例**：

- ✅ 完成：代码已写、已测试、可运行

- 🔧 进行中：部分代码已写

- 📐 设计完成：设计方案已确定，代码未写

- ⬜ 未开始：设计和代码都未开始

---

## 2. 待完成模块（按优先级）

### P0 — [优先级描述，如"基础设施/后续所有模块的前置依赖"]

#### 2.1 [模块名称]

- **角色**：[一句话说明为什么重要]

- **依赖**：[前置依赖，或"无硬前置依赖"]

- **被依赖**：[哪些模块在等这个]

- **设计状态**：✅ 设计完成 / ⬜ 未设计，详见 [相关文档]

- **已解决的设计决策**：

- [x] [决策1] → [结论]

- [x] [决策2] → [结论]

- **待实现任务**：

- [ ] [具体任务1]

- [ ] [具体任务2]

### P1 — [优先级描述]

#### 2.2 [模块名称]

---

## 3. 已完成模块

### [模块名称]（YYYY-MM-DD 完成）

- **实现内容**：[简要说明做了什么]

- **代码位置**：`scripts/[路径]`

- **已知限制**：[如果有的话]

---

## 4. 推进方向建议

**建议顺序**：[模块A] → [模块B] → [模块C]

**理由**：[为什么按这个顺序]

---

*创建日期：YYYY-MM-DD*

*最后更新：YYYY-MM-DD*

````

---

模板 3: 规范

**用途**：为某个领域制定约束性规则。回答"必须怎么做"和"为什么必须这样"。

**典型文件名**：`规范/XXX规范.md`

**代表作**：`规范/代码书写规范.md`、`规范/存档设计规范.md`

**子类型**：

- **编码规范**（如代码书写规范）：规则密集、条目式、每条带优先级

- **方案规范**（如存档设计规范）：方案选型 + 详细机制 + 防御措施

---

````markdown

# [领域名称]规范

> **用途**：[一句话说明本规范约束什么行为]。

> **权威范围**：[列举管辖主题]。[主题]的唯一权威；当与其他文档冲突时，以[优先级说明]。

> 配套文档：[相关文档链接]

> **依赖**：[如果有的话]

> **被依赖**：[如果有的话]

---

## 导览目录

- [1. [主题A]（P0）](#1-主题ap0) — [一句话简介]

- [2. [主题B]（P1）](#2-主题bp1) — [一句话简介]

- [N. 配套文件清单](#n-配套文件清单)

---

## 文档编写规则

### 写入规则

1. [规则1]

2. [规则2]

### 当前状态

**已完成**：

- [已完成的章节]

**待补充（随开发进度）**：

- [待补充的内容]

---

## 1. [主题A]（P0）

### 1.1 [规则名称]

[规则描述]

```lua

-- ❌ 错误

[错误示例]

-- ✅ 正确

[正确示例]

```

**为什么**：[一句话说明理由]

### 1.2 [规则名称]

| 场景 | 做法 | 说明 |

|------|------|------|

| [场景1] | [做法] | [补充说明] |

| [场景2] | [做法] | [补充说明] |

---

## 2. [主题B]（P1）

---

## N. 配套文件清单

| 文件 | 状态 | 说明 |

|------|------|------|

| [文件名] | 已编写 / 待编写 | [一句话说明] |

---

## 变更日志

| 日期 | 变更内容 |

|------|---------|

| YYYY-MM-DD | 初版 |

---

*创建日期：YYYY-MM-DD*

````

---

模板 4: 系统（技术实现指南）

**用途**：指导 AI（新对话）将某个系统集成到游戏中。回答"代码怎么写"和"集成时注意什么"。

**典型文件名**：`系统/XXX系统.md`

**代表作**：`系统/背包系统.md`、`系统/呼吸系统.md`

**与大纲的区别**：大纲说"做什么"，系统文档说"怎么做"。大纲面向决策者，系统文档面向实现者。

---

````markdown

# [系统名称] - 技术实现指南

> 为《游戏》提供[功能描述]。

> 本文档用于指导新对话将[系统名称]集成到游戏中。

> **依赖**：[系统A]（[依赖什么]）、[系统B]（[依赖什么]）

> **被依赖**：[系统C]（[提供什么]）

> **详见**：[跨系统依赖表](跨系统依赖表.md#N-系统名)

---

## 目录

1. [系统概述](#1-系统概述)

2. [核心架构](#2-核心架构)

3. [数据定义](#3-数据定义)

4. [核心逻辑](#4-核心逻辑)

5. [集成步骤](#5-集成步骤)

6. [常见问题与陷阱](#6-常见问题与陷阱)

---

## 1. 系统概述

| 功能块 | 职责 | 说明 |

|--------|------|------|

| [功能A] | [做什么] | [补充] |

| [功能B] | [做什么] | [补充] |

---

## 2. 核心架构

### 2.1 模块划分

```

scripts/

[SystemName]/

[ModuleA].lua -- [职责]

[ModuleB].lua -- [职责]

```

### 2.2 数据流

```

[触发源] → [模块A] → [模块B] → [输出/效果]

```

---

## 3. 数据定义

### 3.1 [数据结构名称]

```lua

local data = {

field1 = "", -- [类型] [说明]

field2 = 0, -- [类型] [说明]

field3 = {}, -- [类型] [说明]

}

```

### 3.2 [配置/常量]

| 常量 | 值 | 说明 |

|------|-----|------|

| `CONSTANT_A` | `5.0` | [含义] |

---

## 4. 核心逻辑

### 4.1 [逻辑主题A]

```lua

-- 关键逻辑

function SystemName.update(dt)

-- [步骤说明]

end

```

### 4.2 [逻辑主题B]

---

## 5. 集成步骤

### 5.1 GameState 字段

| 字段 | 类型 | 默认值 | 说明 |

|------|------|--------|------|

| `fieldName` | `number` | `0` | [说明] |

### 5.2 初始化

```lua

-- 在 main.lua 的 enterGame() 中：

local SystemName = require("scripts/[Path]/[Module]")

SystemName.init(scene_, gameState_)

```

### 5.3 每帧更新

```lua

-- 在 HandleUpdate 中：

SystemName.update(dt)

```

### 5.4 存档衔接

```lua

-- 存档写入时：

saveData.systemField = SystemName.getState()

-- 存档读取后：

SystemName.restoreState(saveData.systemField)

```

---

## 6. 常见问题与陷阱

| 问题 | 原因 | 解决方案 |

|------|------|---------|

| [现象] | [原因] | [做法] |

详见：[bug.md 陷阱 N](../检查/bug.md#陷阱-n-标题)

---

*创建日期：YYYY-MM-DD*

````

---

模板 5: 陷阱记录

**用途**：记录开发中遇到的 bug 教训，避免重复踩坑。每条陷阱是一个独立的"经验胶囊"。

**典型文件名**：`检查/bug.md`（全项目共用一份）

**代表作**：`检查/bug.md`

**单条陷阱模板**：

---

````markdown

### 陷阱 N: [简短标题]

**现象**：[描述出现的错误行为或异常表现，越具体越好]

**原因**：[为什么会出现这个问题，根因分析]

**错误写法**：

```lua

-- 导致问题的代码

```

**正确写法**：

```lua

-- 修复后的代码

```

**规则**：[一句话总结，方便快速扫描]

````

**编写要点**：

| 字段 | 要求 |

|------|------|

| 标题 | 动词短语或名词短语，一眼看出问题类型 |

| 现象 | 描述玩家/开发者能观察到的外在表现，不是代码分析 |

| 原因 | 必须追到根因，不能停留在"改了就好了" |

| 错误写法 | 可运行的代码片段，标注 ❌ |

| 正确写法 | 可运行的代码片段，标注 ✅ |

| 规则 | 一句话，能贴在显示器上当便签的那种 |

---

模板 6: 参考表

**用途**：集中存放需要频繁查阅的结构化数据。纯查询导向，不需要叙述。

**典型文件名**：`公共/XXX表.md`

**代表作**：`公共/术语表.md`、`公共/GameState字段表.md`

---

````markdown

# [领域名称]表

> **用途**：[一句话说明查阅场景]。

> **更新规则**：[何时更新，谁负责更新]。

> 配套文档：[相关文档]

---

## 格式说明

| 字段 | 含义 | 示例 |

|------|------|------|

| [字段1] | [含义] | [示例] |

| [字段2] | [含义] | [示例] |

---

## [分类A]

| [字段1] | [字段2] | [字段3] | [字段4] |

|---------|---------|---------|---------|

| ... | ... | ... | ... |

---

## [分类B]

| [字段1] | [字段2] | [字段3] | [字段4] |

|---------|---------|---------|---------|

| ... | ... | ... | ... |

---

*创建日期：YYYY-MM-DD*

*最后更新：YYYY-MM-DD*

````

---

附录: 文档类型选择指南

不确定该写哪种文档时，用这张决策表：

| 你要回答的问题 | 文档类型 | 存放目录 |

|--------------|---------|---------|

| 这个功能**做什么**、为什么这样设计？ | 大纲 | `大纲/` |

| 这个功能**怎么做**、代码怎么写？ | 系统（技术实现指南） | `系统/` |

| 写代码时**必须遵守**什么规则？ | 规范 | `规范/` |

| 开发**做到哪了**、还差什么？ | 待办 | `待办/` |

| 遇到了 bug，怎么**避免再犯**？ | 陷阱记录 | `检查/bug.md` |

| 某个术语/字段的**定义是什么**？ | 参考表 | `公共/` |

**文档之间的典型关系**：

```

大纲（设计方向）

↓ 设计确定后

系统（技术实现指南）

↓ 开发过程中

待办（追踪进度）

↓ 踩坑时

陷阱记录（避免再犯）

规范（跨系统的约束规则，与上述流程并行）

参考表（随时查阅的结构化数据）

```