# Dev Plan Format

> Write and revise staged DEVELOPMENT_PLAN markdown docs (docs/*_DEVELOPMENT_PLAN.md) using the DApp-X-style skeleton: decision tables, risk/Q list, schema+SQL, state machines, letter-prefixed checkbox phases, Phase milestones, observable acceptance checklists, and revision history. Use when the user asks for 开发计划, DEVELOPMENT_PLAN, 落地方案整理成开发文档, module/feature implementation plans, or to follow dappx-dev-plan-format / GAME_DEVELOPMENT_PLAN / VEXA_CARD_DEVELOPMENT_PLAN style.

- Skill: `zjkal/dev-plan-format` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add zjkal/dev-plan-format`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zjkal/dev-plan-format/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: zjkal (https://skillmd.com/u/zjkal)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zjkal/dev-plan-format

---


# 开发计划文档格式

把调研方案 / Cursor Plan 整理成**可勾选、可验收、可分期落地**的开发计划 Markdown。  
体例源自 DApp-X 的 `docs/*_DEVELOPMENT_PLAN.md`；**格式规则通用**，项目特有收口项按当前仓库约定改写。

- 空骨架：[references/TEMPLATE.md](references/TEMPLATE.md)
- 在 **dappx** 仓库内写计划时，额外必读：[references/dappx-checklist.md](references/dappx-checklist.md)

## 一、适用范围与命名

| 场景 | 文件 |
| --- | --- |
| 整仓 / APP 主计划 | `docs/DEVELOPMENT_PLAN.md` |
| 管理后台主计划 | `docs/ADMIN_DEVELOPMENT_PLAN.md`（若有独立后台） |
| 单模块展开 | `docs/{MODULE}_DEVELOPMENT_PLAN.md`，如 `GAME_DEVELOPMENT_PLAN.md` |

- **一个模块一份文档**：优先覆盖该模块涉及的后端 + 前端 + 后台全链路；无某端则删章节并顺移编号，不留空章。
- 模块文档展开主计划某阶段时：主计划对应阶段只加一句指向新文档的说明，**禁止两份计划描述冲突**。
- 新项目可先写单份 `docs/DEVELOPMENT_PLAN.md`；模块变复杂后再拆。

## 二、章节骨架（顺序固定）

```text
# {产品或模块}开发计划[· 一期]
> 引用块：技术栈 / 需求来源 / 文档范围 / 落地形态 / 核心原则
## 目录
## 一、范围与关键决策          1.1 已定决策表  1.2 交付内容树  1.3 不在本期范围
## 二、风险与待确认事项        R1~Rn + Q1~Qn
## 三、数据库设计              SQL 原文 + 设计说明（无库可改为「数据与规则设计」）
## 四、业务流程与状态机        text 流程图 + 状态约束表
## 五、后端开发阶段            阶段 X1~Xn（checkbox）
## 六、前端开发阶段            阶段 Xn（checkbox）
## 七、管理后台开发阶段        可选；无则删除并顺移
## 八、工程配套与收口          不可省略
## 九、阶段总览与里程碑        Phase 代码块
## 十、验收清单                可观测结果 checkbox
## 十一、参考与索引            后续分期 + 文档索引 + 修订记录
```

章节之间用 `---` 分隔。获客 / SEO / 运营若属于交付一部分，可并入前端后另开「内容与获客阶段」，或并入第八章前，**编号连续即可**。

## 三、阶段写法（核心）

### 3.1 编号

- 单字母前缀 + 序号：主计划常用 `B`（后端）/ `F`（前端）；模块用模块首字母（`G` 游戏、`V` 卡……）。
- **整份文档内编号连续递增**（后端 1~5、前端 6~7、后台 8、收口 9），便于引用。
- **禁止写人日、工期、排期、估时**；顺序与并行只在第九章 Phase 表达。

### 3.2 阶段结构

```markdown
### 阶段 G4：下注、结算与查询接口

**目标**：打通「用户下注 → 扣款 → 开奖 → 派彩」。此阶段完成后可用接口调试工具完整走通一局。

- [ ] **接口**：`POST /api/games/bet` — 下注
- [ ] **新建**：`app/service/game/GameBetService.php` — 下注主流程
- [ ] **逻辑**：单事务内扣款 + 写流水 + 更新期数汇总
  - 子项写清调用顺序与幂等点
- [ ] **约定**：响应禁止返回用户数字主键（按项目安全规范改写）
```

- `**目标**`：一句话说清**做完能验证什么**。
- 每条 checkbox 以**粗体类型标签**开头（见 3.3）。
- 细节用缩进子项；阶段内可用 `####` 分组。
- 未开工 `- [ ]`；完成改 `- [x]`，子项末尾可补「（已完成）」与实现要点——**完成后不要删细节**。

### 3.3 条目类型标签

| 标签 | 用于 |
| --- | --- |
| `**接口**` | API：`` `METHOD /path` — 说明 ``；后台可追加 `｜权限码` |
| `**新建**` / `**扩展**` | 具体文件路径 + 一句职责 |
| `**逻辑**` | 业务规则、事务、幂等、校验 |
| `**数据库**` / `**种子**` / `**迁移**` | schema / seed / migrations |
| `**模型**` / `**配置**` / `**路由**` | 模型、配置、路由登记 |
| `**前端**` / `**交互**` / `**组件**` | 页面与交互 |
| `**约定**` | 安全 / API / 工程硬约束 |
| `**单测**` / `**验证**` | 测试或「确认既有能力已生效」 |

可按栈增补标签（如 `**队列**`、`**邮件**`），但同一文档内标签集合保持稳定。

## 四、第九章 Phase 里程碑

```text
Phase G-1 (存储与引擎，可并行):
├── G1  数据库、模型与配置
├── G2  判定引擎 + 单测
└── 里程碑：给定固定输入，引擎输出与金样本完全一致

Phase G-2 (主链路):
├── G3  …
├── G4  …
└── 里程碑：用接口调试工具完整走通关键路径
```

代码块后固定两句：

1. **建议实施顺序**（箭头串阶段，标出可并行分支）。
2. **哪个阶段可最先独立开工 / 哪个是重心**，并写原因。

Phase 命名：`Phase {前缀}-{序号}`，括号写主题与并行提示。

## 五、前四章写法

### 5.1 决策前置

1.1 用表列出**已拍板决策**（决策项 → 结论）。与原始需求有差异的必须在此写明，勿散落正文。

### 5.2 风险要有后果

`### 2.x R{n}（高/中/低）{标题}`：问题描述（**具体算例或故障表现**）→ 缓解手段（编号，标明「已纳入设计」）→ 需要确认时用引用块。

- 反例：「汇率波动可能造成损失」。
- 正例：算出「订单 500、汇率 0.05→0.04 时平台净亏约 88」。

`R{n}` / `Q{n}` 须能在后续章节被引用。

### 5.3 数据库给 SQL 原文

直接给完整 `CREATE` / `ALTER`（字段中文 COMMENT），再用散文解释**为什么**（唯一索引、JSON 取舍、单号生成等）。

开头引用块写清本仓库约定，例如：schema 真相源路径、幂等迁移、禁止直接改现网库、金额类型（禁用 `FLOAT`）。无传统 DB 时改为「数据与规则设计」（版本化规则、快照字段、文件 TTL 等），仍要可实施、可测试。

### 5.4 流程用 text 图

用 `text` 代码块画状态机 / 资金或数据流转；表格约束「每状态允许哪些操作」。资金类标出 freeze / settle / adjust 等动作名（按项目实际 API）。

## 六、收口阶段（第八章）必写项

**不可省略。** 写成逐条 checkbox，禁止一句「注意安全」带过。

按**当前项目**映射下列类别（无则删，有则写到具体文件/配置名）：

| 类别 | 写什么 |
| --- | --- |
| 标识与隐私 | 对外 ID 策略、禁止泄露的主键字段 |
| 限流与防刷 | 写接口 / 支付类接口登记方式 |
| 资金或计费类型 | 新增流水类型 / 订阅状态的完整改动面 |
| i18n | 真相源文件与导入/校验命令 |
| 路由与配置登记 | 路由表、任务、队列、进程 |
| 权限与审计 | 后台权限码、操作日志 |
| 联调 | 指向第十章验收清单 |

在 **dappx** 中写计划时，用 [references/dappx-checklist.md](references/dappx-checklist.md) 替换上表为该仓具体路径与七步清单。

## 七、第十章验收清单

按主题分组；每条是**可观测结果**，不是「做了某事」。

- 正例：`申请失败后：余额全额退回、产生「开卡费退回」流水、可重新申请`
- 反例：`实现了幂等处理`

建议分组顺序：资金/计费安全（最高优先级）→ 业务正确性 → 权限与审计（有后台时）→ 性能与稳定性 → 前后端一致性与合规。

## 八、第十一章参考与索引

1. **后续分期**：本期不做 / 下期做；注明「一期已预留字段则下期只增不改」类承诺。
2. **文档与规范索引**：表格「内容 → 权威来源」（rules、schema、技能、相关 docs）。
3. **修订记录**：`日期 | 说明`；结构性改动追加一行。

## 九、写作准则

- **引用既有实现前先核实**，给出准确路径；不存在的类名/配置不要写进计划。
- **解释为什么**，不只罗列是什么。
- **一号发现前置**：改变工作量判断的关键事实（如「下游已就绪只缺写入源」）放在第二章靠前，单独成节。
- 术语全文一致；用户可见文案在计划中用 i18n key 或文案职责描述，不假装已定稿多语言译文。
- 输出语言：若用户要求简体中文，计划正文用简体中文。

## 十、执行流程（Agent）

1. 确认产品/模块名、一期边界、输出路径（默认 `docs/…_DEVELOPMENT_PLAN.md`）。
2. 若仓库已有主计划或模块计划，先读再写，避免冲突。
3. 复制 [references/TEMPLATE.md](references/TEMPLATE.md)，按栈与端裁剪章节。
4. 先填第一、二章决策与风险，再写库表/流程，再拆阶段 checkbox。
5. 写完第九章 Phase 与第十章可观测验收；第十一章挂上本仓权威文档。
6. 若在 dappx：对照 [references/dappx-checklist.md](references/dappx-checklist.md) 补全收口与验收条目。