# Plan Write

> 开发文档输出。把已讨论确定的方案整理成开发文档，按 docs/development/YYYYMMDD-{简述}/ 目录、按可独立测试合并的里程碑拆分并编号（只有一个里程碑时就只写一份 README.md），只写设计不写实现代码。

- Skill: `baijunjie/plan-write` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add baijunjie/plan-write`
- Raw SKILL.md: https://api.skillmd.com/api/skills/baijunjie/plan-write/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: baijunjie (https://skillmd.com/u/baijunjie)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/baijunjie/plan-write

---


# 开发文档输出

把本次讨论确定的方案**简洁整理**成开发文档，只整理讨论过的内容，不添加额外信息。

开发文档目录默认 `docs/development/`，项目已有自己的约定时按项目的。这里只放**尚未落地**的内容：
方案设计、开发计划、待办清单。**它是临时文档，不是长期资产**——该固化的内容进了产品文档之后删掉。

## 目录与拆分

- 一个开发主题一个目录 `YYYYMMDD-{中文开发简述}`，不要把文档直接放在开发文档目录根下。
  日期是目录的创建日期，不代表开发周期——跨度大、分多次做完的主题同样只有一个目录，后续文档追加进去
- 本次讨论属于某个已有主题时，进那个目录追加或更新文档，不另建目录
- 一份里程碑文档对应一个**能独立测试、能独立合并**的里程碑：这一份做完，代码应当可以自行验证并合入，
  不必等后续文档一起才跑得通
- 拆多细由你裁量：一个里程碑可以横跨数据、逻辑、接口、界面多个层次，也可以只动一个文件。
  不要为凑数硬拆，也不要把彼此独立的两块塞进一份
- 按依赖方向排序，被依赖的里程碑排在前面（通常是数据结构 → 核心逻辑 → 对外接口 → 调用方）
- **只有一个里程碑时，目录下就只放 `README.md`**，总览与该里程碑的内容合在这一份里写
- 拆成两份及以上时，`README.md` 退回纯总览，里程碑内容放进各自的编号文档，
  命名 `[编号]-[中文开发简述].md`（如 `01-订单状态存储与迁移.md`），编号即开发顺序
- 目录下已有 `README.md` 的不重复创建，只更新内容；原先单份的主题这次要加里程碑时，
  把 `README.md` 里的里程碑内容移进编号文档，`README.md` 退回纯总览

## 写什么

**`README.md` 总览**：问题描述、方案概述、关键设计决策及其理由。拆成多个里程碑时在这里维护里程碑清单与进度。

**里程碑文档**（单份时即 `README.md`）：

- 开头点明本里程碑的目标与完成判据，格式为：

  ```
  > 目标: <这一份要做成什么样>
  > 完成判据: <怎么算做完、怎么验证>
  ```

- **技术设计**：讨论中确定的接口签名、数据结构、核心方法定义
- **实现方案**：讨论中涉及的重构策略、方法分解、调用流程框架
- 内容项一律写成带 checkbox 的条目，**落成一项就勾一项**
- 末尾给开发者提示，只到「项目里已经有什么、该复用哪一块」的粒度（无内容的项省略）：
  - **可复用能力**：项目里已有、本里程碑应当直接复用的机制或模块（鉴权、缓存、错误处理、公共组件、
    工具函数等）。指到能力与所属模块即可，不给文件路径；不确定项目里有没有就不写，别猜
  - **开发要点**：需要遵守的开发规范、与现有系统的集成方式，强调已实现的全局功能，防止重复实现
  - **参考文档**：相关技术文档、规范文档的路径

## 不写什么

- **完整实现代码** —— 绝对不写函数体内部逻辑。允许的示例只到方法间调用关系与执行流程，
  且被调用的方法都是本次讨论确定的；含具体业务逻辑、算法实现、第三方库调用的示例一律不写
- **代码落点** —— 不列要改哪些文件、不指定代码放进哪个路径，那是实现阶段由开发者调查确定的
- **讨论之外的内容** —— 严格限制在讨论范围内，不添加任何推测或扩展
- **编码实施指导** —— 不写具体的编码步骤
- **重复描述** —— 各文档之间不出现重复内容；后面的文档依赖前面的就简洁引用，每份只聚焦自己那个里程碑
- 被放弃的实现方案在它所属的里程碑或主题文档里随文稍作说明即可，不另立清单

## 与别处的关系

- **开发文档不进文档索引**，新增或删掉主题目录都不必改索引
- **它是临时文档，任何地方都不许引用它** —— 它随开发结束就消失，引用过去就是等着变成死引用。
  引用是单向的：开发文档可以引用任何别的东西，反过来不行。
  别处需要它里面的内容，直接写进那份文档