readable-outputlisted

# Readable Output(白話輸出) ## 核心原則:加一層,不是改一層 技術原文(壓縮筆記、代號、術語、數據)是寫給機器與未來的自己看的:密度高、指涉精確,是未來 session 讀取的 context 與事後追溯的依據。把它改寫成白話 = 稀釋未來 AI 的判斷依據。 **原文一字不動,另外附一段給人讀的白話層。輸出 = 原文 + 白話層。** 這不是文字美化工具。白話層寫得再順,只要動到原文、或補進來源沒有的事實,就算失敗。 ## 一字不動的精確定義 先判斷:**這份技術文字已經存在了嗎?** | 情境 | 怎麼分辨 | 保留的定義 | |---|---|---| | **已存在的稿** | 文字已經寫好並落地(既有文件、已發布的 PR 內文、他人寫的段落) | **逐字元不改**(以 Unicode code point 比對;不動換行、不做正規化)。白話層只能整段加在它之前或之後,**不插入中間、不重排** | | **正在生成的新稿** | 你此刻正從工作筆記寫出 commit、PR 或報告 | **事實不增不減**。筆記的每個命題都要在技術層出現;技術層不得出現筆記沒有的命題 | 同一份東西會先後屬於兩種情境:PR 內文在你寫的當下是生成,落地之後再要動它就是已存在。**判準是這一刻你在寫它還是在改它。** ### 事實的粒度 以**可獨立查證的命題**為單位,不是以 bullet 為單位。`三套件綠;死碼再清 3 項(-212 行)` 是三個命題,不是一條。 ### 三類內容,規則不同 | 類別 | 例 | 規則 | |---|---|---| | **事實** | 減少 212 行、三個套件通過、簽名改變、舊呼叫端需改 | **不增不減** | | **詞義** | bridge 是轉接層、ports 是介面 | **可以加**,但必須來自查證或該詞的通用用法 | | **推論** | 所以之後換供應商會變簡單、所以轉接層只剩一層轉呼叫 | **一律不加**,即使聽起來理所當然 | **判準是來源,不是句型。** 來源已經寫出來的命題一律算事實,**即使它描述的是後果**(筆記寫了舊呼叫端需改,那就是事實,照寫)。推論專指**你自己推導出來、來源沒寫**的東西。 **詞義只能解釋名稱本身**,不得順帶交代這個東西在本專案裡的位置、職責、行為或效果。`port 是介面` 可以;`port 是方便日後替換供應商的介面` 不行——後半句形式上是解釋,實質上夾帶了推論。不確定詞義就標待確認。 **格式欄位不算事實**:conventional commits 的 `type` 是必填、`scope` 是選填,兩者由變更性質決定,不必在筆記裡找到字面出處。但它們不得與筆記矛盾。 ## 白話層怎麼寫 判準:一位高中國文老師第一次讀,每一句都讀得懂。 - 完整句子。不用碎片串(`A + B + C flag`)、箭頭鏈、分號堆疊。 - 查得到的專有名詞(NFKC、OAuth、PR、merge)照用。 - 自創代號展開成它實際指的東西,寫成 **白話說明(原詞:代號)** ——留著原詞才能對回原文;若那個原詞同時也是程式裡的識別字,也才查得到對應的程式碼。 - 只寫來源支持得住的事。來源沒說的因果、影響、完成狀態,一律不補。寧可少寫一句。 ## 代號查證:有界限,不猜 不確定代號指什麼時**不猜**,依序查,查到就停: 1. 任務內的明確定義 2. 專案現行文件(CLAUDE.md、docs/