之前对接外包评审时被反复追问详细设计包括哪些内容，才发现行业里九成的人都把概要和详细设计混在了一起。最开始做项目只会照搬模板，把概要里的业务流程复制一遍就交差，评审会上被架构师怼到说不出话，当时只觉得是对方刻意挑刺，压根没分清两层设计的边界。
早先一直默认详细设计就是补全ER图和接口字段，那段时间同时维护两个内部工单系统，两套文档都只填了数据表主键、字段长度、基础入参，上线之后接连出问题。一个是退款接口没写明幂等校验时机，用户重复点击两分钟内扣了两次款，另一个是字典下拉框没标注数据缓存过期时间，凌晨缓存失效后前端直接空白，排查的时候翻遍详细设计文档，找不到任何对应的兜底逻辑，前后花了四个小时回溯代码才补上容错分支，才意识到只写静态结构完全撑不住编码落地，概要设计解决的是系统和系统之间怎么联动、整体技术选型是什么，详细设计要解决的是单模块内部每一步细碎动作怎么执行，二者的适用粒度从一开始就完全错开。
模板永远滞后于实际业务。
照搬模板一定会漏项。
后来才反应过来，编码时需要临时口头确认的所有依据，都属于详细设计的范畴。不是文档排版越规整越好，是开发脱离所有口头沟通、群内答疑，单凭文档就能从零写完代码，不需要找产品、架构核对任何细节，这才是判定内容齐全的硬性标准，不用管网上流传的通用目录。也见过不少团队堆了十几页无关图表，核心执行细节全是空的，最后编码还是要现场扯皮。
身边从测试转开发的同事做法更直白，他写详细设计从来不画多余时序图，只固定补齐四块刚需内容。第一是模块内局部数据流转明细，不是概要里的全局数据流，是当前代码方法内部变量从读取、临时改写、最终入库的全路径；第二是全分支异常兜底，包含参数为空、数据库行锁超时、第三方接口熔断三类底层异常，还有余额校验、权限拦截这类业务异常；第三是操作日志明细，要写明每一步变更对应的日志关键字段、存储数据表，不是笼统写“记录操作日志”；第四是单接口性能硬约束，比如循环查询最大遍历条数、同步接口最大等待时长。
之前总觉得时序图是详细设计标配，实际上半年上线12个业务模块，真正用到时序图的只有2个跨子模块调用的场景。其余纯内部逻辑的模块，时序图画了也没人看，编码时完全不会对照查阅，纯属无效工作量，很多公司模板强制要求添加，只是单纯为了过内控审计，和实际编码落地毫无关系。市面上大部分通用模板，都是为了合规拼凑的，不是为了开发落地。
还有个极易被忽略的隐性内容，新旧版本字段兼容规则。上个月迭代给用户档案表新增隐私备注字段，详细设计里完全没补充低版本客户端兼容逻辑，老旧安卓端不会自动忽略新增字段，提交表单直接触发参数解析报错，影响了近两千存量用户。事后核对设计边界才看清，概要设计只会定义字段用途，跨版本兼容、参数容错全部归属详细设计，几乎所有新人都会直接漏掉这一项。
跑的飞快的项目组，普遍会主动砍掉文档里的目录性冗余内容。反正内控审计需要的合规附录、审批流程图，全部可以上线后批量补填，前期硬塞进文档，只会打乱自己梳理代码逻辑的思路，拖慢整体排期。
当晚整理完剔除冗余项后的详细设计内容清单，盯着文档空白的合规附录栏坐了二十多分钟，鼠标悬在保存按钮上始终没点下去。