impl-doclisted
Install: claude install-skill tmjwjx/tmjwjx-skills
# impl-doc — 实现文档
一句话定位:**说清楚实现逻辑**——怎么用技术把需求实现出来,业务逻辑上如何运转。文档只有这一个中心,与此无关的内容一律不写。
## 不写什么
- **不复述需求**:需求是什么一句话带过,篇幅全部留给「怎么实现」
- **不做选型论证**:不解释为什么选这个框架或中间件,直接讲用了它之后逻辑怎么走
- **不用代码代替说明**:伪代码、代码片段不能代替说明,逻辑必须用自然语言讲
- **具体名称(模块/类/函数/文件/表)可以且应该出现**:它们是定位锚点,让开发知道去哪改;但名称是路标不是内容,围绕名称把逻辑讲清楚才是正文
## 写完必须过的两道(双读者测试)
1. **不懂代码的人**顺着读,能用自己的话复述:"这个功能是这么转的——先……然后……如果……就……"
2. **懂代码的人**读完,能立刻说出:"我要新增几个东西、改哪几处、从哪开始写"
第 1 条不过,是写得太技术;第 2 条不过,是缺了触发入口或落点。任何一条不过就返工。
## 动笔前
1. **列需求点**(R1、R2……),模糊的标"待确认",不要自行发挥。
2. **读代码**(已有代码库时):找到相关模块、类似的既有流程、涉及的数据结构、可能的触发入口。全新开发没有代码可读,跳过这步。
3. **文档里出现的每个名称都必须来自真实代码**。确实是新增的标"(新增)";查不到就标"待确认"并说明它影响哪一段。**编造出来的锚点比不写更坑人**——开发会拿着一个不存在的类名到处找。
## 结构
默认就两块,按需增减,不做面面俱到的模板:
1. **整体思路**(几句话;逻辑复杂时配一张数据流或模块协作图):需求拆成哪几块、数据怎么流动、各块怎么协作。让读者先建立全局。
2. **实现逻辑**(主体,按功能或模块逐块展开)。
小改动可以只有第 2 块,直接从实现逻辑写起。
**另外三样,按需加,不强制**:
- **需求覆盖**:需求点多、怕漏怕多做时,列一张小表:需求点 → 由哪块实现 → 完成的判定标准,判定标准直接写在表里(这就是验收,不单独设验收章节)。作用是让人一眼确认没漏需求、也没多做。这是取代"复述需求"的正确做法。判定标准要写成可直接观察的现象、带具体数值("下单 31 分钟后订单显示已取消,库存加回 1"),不是"功能正常"。
- **失败与并发**:属于每块实现逻辑的一部分(见下),融入流程讲,不单独设章节。
逻辑复杂时可以再加:数据与状态流转、规则判断表、影响面(改了哪些既有模块、对外契约变不变、要不要刷数据、谁需要配合)、不做什么。**能不加就不加。**
## 每块实现逻辑要讲清
- **入口/触发**:谁在什么动作下进入这段逻辑。定时任务写频率,消息驱动写来源,用户操作写是哪个动作。**这是信息量最高的一项,永远不能省**——省了读者就无法定位代码入口。
- **数据**:存到哪张表或哪个结构,关键字段的业务含义(不是字段类型)。
- **流程与失败**:按什么步骤处理,每步的判定条件是什么,状态怎么变化;分支(库存不足)和异常情况(重复提交、并发、超时)怎么走、业务后果是什么,融入流程一并讲,不单独成章。
- **结果**:处理完用户和系统各自看到什么。
- **落点**:涉及哪些模块或文件,各自负责什么。
这五项是**必须回答的问题,不是必填的表格**。能用行文讲顺就行文,信息密的地方才用表格或字段表——连排四五张一模一样的字段卡片,和大段文字一样难读。
## 好坏对照