用数据流图讲清检索增强系统的取舍架构图的价值不在于装饰而在于让读者能顺着数据和控制信号找出边界。画图前先回答数据从哪里进来在哪些节点持久化失败后由谁决定重试或回退。一张图只解释一个层级总览图展示用户、网关、检索、模型和数据源的关系详细图再展开检索索引、重排或队列。不要把所有类、字段和监控项塞进同一张图。给箭头加上语义区分同步请求、异步事件、数据写入和观测上报并注明关键输入输出。敏感数据的流向、权限检查和脱敏位置应单独标识不能用模糊的“数据处理”带过。用图辅助评审让产品、研发和运维分别沿图走一遍正常路径和失败路径若有人说不清超时后谁接手接口仍需补充。关注交界处用数据流图讲清检索增强系统的取舍并不适合靠一句经验结论推进。这类问题常出在两个组件的交界处。输入清洗、候选集合、排序依据和生成上下文 如果没有明确归属某一侧的“合理默认值”可能正好成为另一侧的故障来源。处理时先画出数据或控制流标出谁创建、谁修改、谁负责结束不确定的环节先保守处理等证据足够再放宽限制。与其一次性替换整条链路不如先验证最短路径。最短路径通了再把缓存、并发、重试或自动化能力逐项加回去异常会更容易定位。让结果可复查围绕 输入清洗、候选集合、排序依据和生成上下文 的结论应能被别人复查。保留原始样例、关键日志和操作顺序比在文档里写“已验证”更有用。涉及敏感内容时可以保留脱敏后的结构和哈希保证读者仍能判断材料是否来自同一现场。问题处理完后简短说明修改位置、影响范围和未覆盖情况即可。不要把一次偶然成功写成通用规律若还有前提就把前提说清。控制变更范围处理 输入清洗、候选集合、排序依据和生成上下文 时最容易犯的错误是同时改太多东西升级依赖、调整配置、重写逻辑一起发生最后即使变好也无法解释原因。把变更拆开每次只回答一个问题节奏会慢一点但回退和复盘都更轻松。发布或交接之前再检查调用方是否依赖旧行为。对暂时无法覆盖的场景写下限制读者就能判断这套做法是否适合自己的环境。留下可交接的说明处理完成后不需要额外写一套漂亮的总结。把实际改了什么、为何这样改、还剩哪些前提写在变更附近即可。下一次遇到相似问题时这些材料可以作为起点但仍应先确认当前输入和环境是否相同。数据流图的后续判断写作和实施都应把注意力放在能够改变决策的细节上。当前条件下最需要确认的是输入的形状、依赖的默认行为以及失败后是否仍会留下可读线索。若某个结论只在特定机器、特定版本或特定权限下成立就把这个限制写在结论旁边。读者据此调整方案比收到一段泛泛而谈的建议更省时间。当现象无法立即解释时不妨保留暂不下结论的部分。先将已知事实、复现步骤和待确认假设分开后续补到同一处。这样能防止猜测在转述中变成既定事实也能让下一位处理者从最有价值的地方继续。工程文档的作用不是替人做判断而是把判断所依据的材料留下来。