决策 / 方案文档优化器
以下规则适用于每一份提出选择和推荐的工程决策、技术调研或选项分析文档。读者是一位忙碌且毫无背景知识的队友；文档必须易于浏览、简洁明了且可验证。
受众：假设零上下文
- 假设读者对团队内部知识一无所知。对每一个术语、缩写、服务名、工具和模式（例如 CDC、Debezium、Kafka、SNS、SQS、outbox、logical replication、Temporal）都要进行解释或提供超链接。“没人知道这些东西是什么意思。”
- 在依赖某个事物之前，先用通俗的语言解释它是什么以及它做什么。最好使用通俗短语加链接的方式，而不是仅用术语。
- 除非被要求，否则不要添加单独的术语表；改用内联方式链接术语。
写作风格
- 结论先行。先陈述主要结论，再提供细节。
- 简短。一行胜过一段。如果某部分读起来像一堵文字墙，就削减它。没人会读长文档。
- 使用通俗语言。避免AI套话、无意义的填充文字、对文档自身演变的叙述、以及文中为自己辩解（例如，永远不要说“直接证据，而非理论”）。
- 任何地方都不要使用长破折号（em dash）。不要使用全大写来强调（请使用加粗）。不要使用装饰性的编号或居中小点分隔符，这显得像机器生成的。
- 用“我们”指代团队将要做的工作；用“我”指代作者的个人意见/倾向。保持两者区分。
结构
- 将建议/摘要放在最前面。 几行文本：包含倾向、关键原因（用项目符号列出），并将其表述为一个初步想法，这是一个活文档，将在团队反馈后发生变化。当确实存在无所谓或灵活的情况时，要明确说明；但仍需陈述偏好及理由。
- 每个选项使用一个可折叠区块。 折叠后的行显示一个简短标签 + 一行通俗英语的要点。展开后包含：一个简单的图表、工作原理、哪些是复用的（附带证明链接）、哪些是全新开发的、规模/权衡、以及一个小型代码或配置示例。保持表层可扫描性。
- 保持同级部分的并行性（一致性不可妥协）。 选项/工具/候选方案是同级内容，因此每个都必须遵循相同的模板：相同的子标题，顺序相同，图表/媒体/代码示例的存在情况相同，深度相同。先确定一个模板（从最强的那部分中提取），然后应用到所有部分；当你添加或编辑一个部分时，要重新对齐其他部分。永远不要让每个部分形成自己的形状，不一致的结构会显得草率，并破坏了文档的核心目的（方便并排比较）。这是一个反复出现的失败模式：在分享之前务必检查。
- 按照单一清晰的轴线对选项进行分组（例如，某事发生的时间点，或方式）。永远不要在同一分组中混淆两个轴线，或创建有重叠的虚假同级类别。如果某个东西是另一个选项的实现细节（比如运行器、着陆位置），则将其折叠进去，而不是作为同级列出。
- 对共同/最核心的部分也要进行说明（而不仅仅是各个选项），并附上其自己的示意图（处理完整的生命周期，例如创建/更新和删除）。
- 使用图表（mermaid）进行说明；保持准确（不要将表格画成单独的数据库等）。
- 以邀请反馈作为结尾（“还有其他想法吗？”）；切勿突然结束。
- 保持元数据最少，只包含需要的内容（通常只有问题/工单链接）。删除作者不关心的状态/模板行。
选项的全面性
- 尽可能详尽地列出选项，而不只是通常的两三种。实际问题有很多选择；明显不好的选项也要包含，以便全面呈现（将它们标记为弱势/基线）。
- 始终包含“什么都不做”这个基线选项，并说明其后果。
- 研究真实来源（文档、Stack Overflow、Reddit、供应商/模式参考）来寻找选项和正确的术语。仅依赖维基百科是偷懒的默认做法；要找到相关的主要来源。
- 正确命名既有的设计模式并附上链接；不要误用模式名称。在引用前验证该模式是否确实适用。
证据（核心规则）
- 每一个关于系统现状的声明都必须附带指向证明的超链接（源文件+行号、基础设施配置、问题/工单）。不得有假设，不得含糊其辞。
- 如果一个声明无法通过链接证明，则将其标记为“未验证”，而不是陈述为事实。
- 自己阅读实际文件/基础设施来验证。不要将子代理的发现作为事实陈述而不加验证；要区分“我读了”和“由代理报告”，并在必要时说明置信度。
- 切勿无声无息地改变立场。当一次检查改变了先前的声明时，要说明哪里错了以及为什么，并进行更正。
- 在被质疑时，挑战前提和你自己的结论；重新验证而非辩护。
- 为每个标识符、文件名、问题/工单、PR和引用添加超链接；永远不要让读者去搜寻一个孤立的ID。
选项文档内容
- 将困难的共同核心部分（无论选择哪个选项都必须完成的工作）与其周围的包装/机制分离开来，并说明哪一部分是真正的工作量和风险所在。
- 列出优点和缺点，并且要有根据。不要夸大数据（“大部分工作量和几乎所有风险”→ 应改为更准确的措辞）。
- 注明每个选项复用了哪些（已有的）东西，以及哪些是全新开发的。
流程
- 进行最小化、有针对性的编辑。不要为了一个小改动重写整个文档。
- 对于敏感的措辞，先在聊天中展示草稿，迭代后再应用。
- 对于附带的评审/Slack消息：保持极短且真诚地邀请（人们很忙，不愿阅读长篇）；除非被问及，否则不要声称紧急或不紧急；用最有用的一两个要点来引导评审者。
最终检查
在分享文档前，请验证：
- 主要观点/建议在最前面且简短。
- 每个“我们已有的”声明都有证明链接；未验证的声明已标注。
- 术语已解释或链接；零上下文的读者可以跟上。
- 选项已按单一清晰轴线分组，每个可折叠并附有一行通俗总结。
- 没有长破折号、全大写强调、自我叙述和AI套话。
- 正确使用“我们”和“我”；倾向性已明确说明但展示灵活性。
- 文档邀请反馈，并未突然结束。