← ClaudeAtlas

impl-doclisted

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