決策 / 選項文件品質
每次撰寫提出選擇與建議的工程決策、探討或選項文件時，都必須遵循這些規則。讀者是一位忙碌且毫無背景知識的團隊成員；文件必須易於瀏覽、簡潔且可驗證。
目標讀者：假設零背景知識
- 假設讀者完全不了解團隊內部的隱性知識。對於每個使用到的術語、縮寫、服務名稱、工具和模式（例如 CDC、Debezium、Kafka、SNS、SQS、outbox、邏輯複寫、Temporal），都要加以解釋或提供超連結。「沒有人知道這些東西是什麼意思。」
- 在依賴某個東西之前，先以簡單明瞭的語言解釋它是什麼以及它的作用。最好使用簡單的短語加上連結，而不是只用術語。
- 除非有人要求，否則不要新增獨立的詞彙表章節；而是應該在行內為術語提供連結。
寫作風格
- 開門見山，先提出重點 (BLUF)。先陳述主要結論，然後再詳細說明。
- 簡短。一句話勝過一段落。如果某個章節看起來像一大塊文字，就刪掉它。沒有人會閱讀長文件。
- 使用簡潔語言。避免 AI 廢話、聽起來「不錯」的填充內容、描述文件本身的演進、或在文件內為自己的推理辯護（例如，永遠不要寫「直接證據，而非理論」）。
- 任何地方都不要使用破折號。不要使用全大寫來強調（請改用粗體）。不要使用裝飾性編號或中間點分隔符，以免看起來像機器生成的。
- 使用「我們」來指稱團隊將要進行的工作；使用「我」來表示作者的意見或傾向。必須清楚區分兩者。
結構
- 將建議 / TL;DR 放在最前面。 幾行文字：說明傾向與關鍵原因（以項目符號呈現），將其定位為一份在團隊提出意見後會改變的動態文件的初步看法。當確實存在時，要明確表達你的不在意與靈活性；但仍要說明偏好及其原因。
- 每個選項使用一個可折疊的區塊 (toggle)。 摺疊狀態的行顯示簡短標籤 + 一句簡潔明瞭的概述。展開後：包含一個簡單圖表、運作方式、重用了哪些既有元件（附證明連結）、哪些是全新開發、規模/權衡、以及一小段程式碼或配置草稿。保持摺疊狀態的表面易於掃讀。
- 保持同級章節的平行結構（一致性非選項）。 選項/工具/候選方案是兄弟關係，因此每個選項必須遵循相同的模板：相同的子章節標題與順序、圖表/媒體/程式碼草稿的呈現方式、相同的詳盡程度。先確定模板（從最完善的章節取得），然後套用到所有選項；當你新增或編輯某個章節時，必須重新調整其他章節。永遠不要讓每個章節各自發展成不同的形狀，結構不一致會顯得很草率，並破壞了文件的主要目的（易於並排比較）。這是一個反覆出現的失敗模式：在分享之前務必檢查。
- 選項應根據一個清晰的軸線進行分組（例如 何時 發生某事，或 如何 發生）。切勿將兩個軸線混為一談，或創建有重疊的虛假同級分類。如果某個東西是另一個選項的實作細節（例如一個執行器、一個目標位置），請將其納入，而不是列為同級選項。
- 說明共享/最困難的核心，而不僅僅是選項，並為其繪製單獨的草圖（處理完整的生命週期，例如建立/更新 和 刪除）。
- 使用圖表 (mermaid) 來說明；保持準確（不要將表格畫成一個獨立的資料庫等）。
- 結尾邀請反饋（「其他想法？」）；切勿突然結束。
- 保持元數據最少，只包含需要的部分（通常只是工單連結）。刪除作者不關心的狀態/樣板文字。
選項的全面性
- 窮舉所有選項，而不僅僅是常見的兩三個。真正的問題有很多解決方案；也要包含那些明顯不好的選項，這樣才能看到全局（將它們標記為較弱或基線方案）。
- 始終承認「什麼都不做」的基線方案，並說明其後果。
- 從真實來源（文件、Stack Overflow、Reddit、供應商/模式參考資料）進行研究，以找出選項和正確的術語。僅依賴維基百科是偷懶的預設行為；要找到相關的主要來源。
- 正確命名既有的設計模式並提供連結；不要誤用模式名稱。在引用某個模式之前，先確認它確實適用。
證據（核心規則）
- 關於系統已具備能力的每個主張，都必須附上證明連結（原始碼檔案 + 行號、基礎架構配置、工單）。不得有假設或含糊其辭。
- 如果某個主張無法用連結證明，則標記為未經驗證，而不是將其陳述為事實。
- 親自閱讀實際的檔案/基礎架構來驗證。不要將子代理的發現陳述為事實而不親自閱讀；要區分「我讀過了」和「某個代理報告了」，並在必要時說明信心程度。
- 永遠不要默默地前後矛盾。當某次檢查改變了先前的說法時，要指出之前哪裡錯了、為什麼錯了，並進行修正。
- 在被質疑時，要挑戰前提和你自己的結論；重新驗證，而不是辯護。
- 為每個識別碼、檔案名稱、工單、PR 和參考資料提供超連結；永遠不要留下裸露的 ID 讓讀者去尋找。
選項文件的內容
- 將困難的共享核心（無論選擇哪個選項都需要完成的工作）與其外圍的包裝/機制分開，並說明哪個部分才是真正的工作量和風險所在。
- 提出優缺點，且必須有根據。不要過度宣稱（例如「大部分的工作和幾乎所有的風險」→ 應修改為準確的措辭）。
- 指出每個選項重用了哪些（已存在的）東西，以及哪些是全新開發的。
流程
- 進行最小化、有針對性的編輯。不要為了小改動而重寫整份文件。
- 對於敏感措辭，先在聊天中展示草稿並進行迭代，然後再套用。
- 對於附帶的審查/Slack 訊息：保持極度簡短且真誠地邀請（人們很忙，不想閱讀）；除非被問到，否則不要聲稱事情緊急或不緊急；用最重要的框架來引導審查者。
最終檢查清單
在分享文件之前，請確認：
- 主要觀點 / 建議放在最前面，且簡短扼要。
- 每個「我們有什麼」的主張都附有證明連結；未經驗證的主張已明確標記。
- 專業術語已解釋或提供連結；毫無背景知識的讀者也能理解。
- 選項已根據一個清晰的軸線分組；每個選項都是可折疊的，並附有簡潔的單行摘要。
- 沒有破折號、全大寫強調、自我敘述或 AI 廢話。
- 「我們」和「我」使用正確；傾向已說明，但靈活性清楚。
- 文件邀請反饋，且沒有突然結束。