Tarragon

"寫作"

• 2026-04-29 正向改寫要保留對照論據、不能空降結論 把「X、不是 Y」改成正向陳述時、若直接刪除「不是 Y」會讓結論失去推理依據、變成空降斷言。對照論據（Y 是讀者直覺會想到的替代方案）跟結論（X）是同一個推理單元、抽掉一半就不成立。正向改寫的合法做法是補解釋、改成對照表、或保留 Y 當對比錨點 — 直接拿掉是 worst。
• 2026-04-29 Multi-pass review 的 scope 要蓋『同類風險區』、不是『改動區』 做 multi-pass review 時、預設用『我這次改過的檔』當 scope 是便利選擇；但同一原則違反通常分布在整個 corpus、改動區只是冰山一角。Scope 該由『同類風險的內容範圍』決定 — 跑某條原則的 pass、就要掃所有適用該原則的檔、不是只掃我自己改過的。改動區 scope 是 #67 在 review 流程的具體展現、會讓 multi-pass 退化成 self-edit pass。
• 2026-04-29 適用範圍要展開成 file enumeration、口語描述不夠 原則的『適用範圍』寫成口語描述（『所有教學文件的論證段落』）時、執行 review 的人要當場推導『具體哪些檔屬於這個範圍』、推導步驟容易漏；改寫成 enumerated file list（具體列出 file paths）就能避免 enumeration 不完整。Enumerate 的合法形式是『可被 grep / find 重現的具體 file 集合』、不是『口語類型描述』。本卡是 #95 的下游具體化、跟 #82 互補：enumerate 是字面層、enumeration completeness 是行為層判準。
• 2026-04-30 Metadata surface 要納入寫作 review 範圍 寫作 review 的 surface 包含正文與 metadata surface：title、description、frontmatter、heading、link label、MOC 索引條。正文通過 positive wording 或 multi-pass review 只代表 body surface 收斂；讀者入口與索引入口也要跑同一套 frame，才能讓文章在第一眼、搜尋與跨篇路由上維持同一個概念錨點。
• 2026-04-30 素材庫比例要支撐主情境的反向驗證 當文章只展示少量主情境時，素材庫需要保留更多 field cases 或 source cards 來支撐反向驗證、壓力變體與後續擴寫。合理比例是主文章情境 4-5 個、來源素材約 2-3 倍，讓每個主情境背後至少有 2-3 個來源可回查。
• 2026-05-06 設計檢討用當下三軸論證、不依賴 hindsight 本卡提倡用「當下成本對稱條件下選了限制更高的選項」當設計缺陷的判定方式、避免 hindsight 論述把需求演化誤判成設計缺陷。當下三軸論證（成本對稱性 / 可逆性 / 領域先驗）讓判斷不依賴結局發生、且歸因偏向工具預設與制度而非個人預見性。
• 2026-05-06 口語化修辭在判斷工具型段落會稀釋技術精度 技術文章的「判斷工具型段落」（讀者用來判斷自己 case 的論述）用「一輩子」「碰巧能用」「立刻撞牆」「沒事」這類口語修辭、會稀釋精度。修法是把口語修辭翻譯回技術屬性語言。但 hook / 引言 / narrative 段落用口語仍然合理——這是情境化的取捨、不是精度永遠優於可讀性。
• 2026-05-06 地區用語對齊：寫作前先確定讀者的中文語料 繁中 vs 簡中的用詞差異不只是字形（屏 / 螢幕、視頻 / 影片）、更是技術術語跟業務情境的精度差。寫作前要先確定讀者的中文語料、避免用對方語料中不存在或意思偏移的詞。常見漂移：硬體（屏 / 螢幕）、檔案系統（文件 / 檔案）、概念詞（默認 / 預設）、修辭詞（質量 / 品質）、混雜情境的英文中文比例。
• 2026-05-06 商業邏輯論述要 self-contained：不依賴 code 才能被理解 技術文章在「不放 code 的段落」仍然要 self-contained——商業邏輯論述不能預設讀者已經看過 code、用「那個 payload 第二段」「剛才的變數」這類 reference 等於把理解門檻轉嫁給讀者去翻 code。修法是把 reference 翻譯成「用名詞 / 角色 / 條件描述」的 self-contained 句子、即使讀者跳過所有 code block 也能理解論述。
• 2026-05-06 Multi-pass review 的 frame 顆粒度盲點：抽象規則 → 具體訊號的轉譯不完整 Multi-pass review 跑了 4 輪、字句層問題（口語修辭 / 地區用語 / 依賴 code / 廢話前綴）仍漏 catch——揭露 frame 顆粒度盲點：抽象規則（如「機會成本語氣」「正向陳述」「最重要的話優先說」）沒被轉譯成具體訊號（如 grep keyword bank：「一輩子 / 碰巧 / 撞牆 / 下次 X 時 / 不是 A 而是 B」）。修法是把每條規則展開成可 grep 的 keyword bank、加 reader simulation 輪、加 self-criticism 輪。
• 2026-05-19 教材目標先於決策框架 教材的核心目標是讓讀者學會某個領域的心智模型、操作語意與演進路徑；服務能力、風險、成本與決策是教學中的必要概念框架。當決策框架取代教材目標，文章會變成選型分析或治理文件，讀者知道怎麼判斷，卻仍缺少領域學習路線。
• 2026-05-19 教材完整性要用讀者旅程驗證 教材完整性要用讀者旅程驗證；章節數、案例數或 vendor 覆蓋度只能判斷素材量。成熟教材要能回答不同讀者從哪裡開始、按什麼順序讀、讀完能做什麼。LLM 與 Go 目錄顯示，讀者旅程、學習梯度與主題導讀是教學設計完成度的核心訊號。
• 2026-05-19 貫穿式案例是服務教材的教學骨架 服務型教材需要一條可重播的貫穿式案例，把資料庫、快取、queue、觀測、部署、可靠性、資安、事故與容量串成同一個服務演進路徑。沒有貫穿式案例時，章節會各自正確但讀者難以理解能力之間如何交接。
• 2026-05-19 服務頁教材合約 服務頁是一篇能獨立教會讀者某個服務能力的教材，產品資訊與選型摘要只是教材材料。成熟服務頁要達到單篇技術教材的討論細節與漸進教學，但章節結構要依分類責任、服務對象與使用情境設計。
• 2026-05-19 Sibling Coverage Asymmetry Blindspot：Priority 評估漏掉的「對稱性維度」 當批量 A 跟批量 B 是 sibling（同類 vendor / 同類角色）、A 後寫超過 B、心智模型容易 collapse 到「A 是 reference / B 是 baseline」、忽略 *B 才應該 ≥ A coverage* 的對稱性 priority。Case：MySQL 18 篇 / PG 11 篇後、推薦下一步把 PG 排除、列 DynamoDB / Aurora / SQLite 等「新領域擴張」、user 自己 catch 才發現 PG 還沒對齊。機制：sequential point-in-time coverage 評估 vs cross-sectional sibling symmetry 評估、後者預設不在 priority 列表維度。修法：priority candidate list 必須跑 sibling symmetry audit。
• 2026-05-19 Sibling Vendor Cross-Link 雙向性 Audit：寫 Vendor Batch 結束必跑 當寫 sibling vendor batch（A vs B）、cross-link 容易單向 — A 提 B 多次、B 沒回提 A、形成 navigation asymmetry。Case：MySQL 18 篇對 PG sibling cross-link 9 條、PG 對 MySQL cross-link 0 條。機制：寫第二個 batch 時 reference 第一個 batch 是自然行為、但 reverse direction 必須主動補。修法：vendor batch 結束跑 bidirectional link audit、`A → B` 跟 `B → A` 對比、缺一邊就補。
• 2026-05-19 Vendor Feature 時間敏感性：Claim Verification 必跑、寫作日期必標 寫 vendor article 時、feature limitation claim（『不支援 X』『最多 Y』『預設 Z』）有時間敏感性 — vendor 持續演進、寫作後 N 個月可能 invalidate 整段 audit 邏輯。Case：PlanetScale FK 不支援是 2022 年的事實、2023 末 Vitess 18 加 FK 支援、寫作時若不 verify、Phase 1 audit「FK audit + 全 drop」整段過時。機制：LLM training cutoff vs vendor changelog 速度差、且 LLM 預設不標 claim 的時間性。修法：每篇 vendor article 標 *Last verified* date、limitation claim 必要時加 *as of N* 註、claim 反轉 invalidates 整段 audit 時必須重寫不是修補。
• 2026-06-01 字句層 review：keyword bank 命中是候選、不是判決 跑了字句層 grep keyword bank、命中『不是 A 而是 B』、卻把它判成『可接受的反例對照』放行；違規由讀者 catch。揭露 keyword bank 的第二層盲點：偵測（grep 命中）跟判定（這個命中是不是違規）是兩個認知步驟、reviewer 容易把命中合理化成合規而放行。判定準則：否定句構若在『建立核心概念』就改正向、只有在『明示反例段落』才保留。另有一類贅語（訴諸群體『很多人卡在』）連關鍵詞都沒有、keyword bank 結構上抓不到、要靠 reader-simulation 語意 pass。
• 2026-06-01 教材用中性陳述、不對讀者喊話 教材的 register 是中性陳述概念、不是對讀者說話。三種對讀者喊話的形式 —— 安撫情緒（很多人卡在）、第二人稱代入（你天天寫）、祈使控制閱讀（先讀懂 / 別搞混）—— 表面不同、共同違反是把讀者當成要管理的對話對象、而非把概念講清楚。問題不在精度（「你天天寫的 int count」精度完全正確）、在 stance。修法是換成中性陳述（常見的 int count）或描述性名詞標題（簽章的型別與名字拆解）。邊界：hook / narrative 段落的輕度第二人稱可幫讀者進入、不一律禁。
• 2026-06-01 教材給技術理由、不替方案下品質評價 教材該陳述「為什麼這樣設計」，不對方案下品質評價。自評誇飾（教科書級 / 堪稱經典 / 完美契合 / 漂亮地解決）讀起來像作者在誇自己方案、傳遞的是滿意度而非概念，且品質評價會頂替掉真正的技術理由 —— 寫了「X 是教科書級的適配」就少寫了「X 為什麼適配」。修法是把評價換成機制 / 條件。邊界：帶判讀條件的適配性陳述（三條件齊備時 HOF 比列舉更省）是判準、不是誇飾，保留。
• 2026-06-01 教材把設計選擇講成選擇、不講成必然或天性 本質主義 / 必然性框架（天生 / 本質就是 / 必然 / 唯一）把一個設計選擇講成自然法則、抹掉設計能動性，讓讀者以為沒得選。它是『機會成本語氣 vs 絕對主義』違反的一個 subtype —— 不是命令式絕對（應該做 X）、而是必然性絕對（X 本來就這樣）、更隱形。sharp feature 是常局部牴觸作者自己在別處的條件性立場。修法是把必然框架還原成條件性：X 在『選了某前提』之後才以此形式成立。邊界：物理 / 法律 / 合規事實可講必然。
• 2026-06-01 Review 漏抓先分 design gap 與 execution gap、再決定改框架還是改執行 Review 漏抓某類問題時，有兩個不同成因：design gap（框架根本沒有對應 frame）跟 execution gap（框架有 frame、但 reviewer 沒跑）。修法相反 —— design gap 要改框架（補 frame / keyword）、execution gap 要改執行（真的跑完該跑的輪）。診斷前先分清：把 execution gap 誤判成 design gap 會 framework bloat（一直加 frame 卻沒解決偷跑子集）、把 design gap 誤判成 execution gap 會永遠漏同類。常見陷阱是『加 keyword』感覺像進步、但對沒跑的輪毫無幫助。
• 2026-06-05 教材的『重點 / 總結』段是內容發散的訊號、該重組正文不該補丁 教材尾端的『重點』『一句話總結』段、若功能是重述前面已講過的內容、就是正文組織不佳的補丁。讀者需要回頭被提醒、代表概念在正文裡散掉了 —— 該做的是重拆正文段落、把概念在它該出現的位置一次講清、而不是另開總結段替發散的正文善後。判準：刪掉總結段後正文若仍站得住、證明總結本就冗餘；若站不住、是正文要重組、不是總結要補。處理總結段內容時先分『提醒 vs 概念』—— 純提醒（養成習慣 / 回頭確認）刪、有概念價值的（為何這樣設計）併回它本該所屬的正文位置。
• 2026-06-14 register 違規：偵測可機械化、判定要靠文體異源的眼睛 寫作規範的違規分兩類：形式違規（emoji / 編號 / broken link）可完全機械判定、該進工具鏈；register / 品味違規（概念前置 / 否定起手 / 喊話 / 誇飾）的判定有不可消除的品味核心。「不是 X、而是 Y」的陷阱是偵測可機械化（grep 抓得到句型）偽裝成判定可機械化、誘導無限投入更精緻的判定方法（grep → 概念位置 → 行為測試）、但判定始終在品味側、始終放水。更深一層：產出這類違規的 LLM 跟審查它的 LLM 共享文體直覺、同源自審對 register 違規有結構上限、加再多輪次都跨不過。結構解是引入文體異源的視角（人類冷讀 / reader-simulation / 對抗文體 reviewer）、並接受 100% 自動 catch 不可能。
• 2026-06-14 重點優先陳述是跨語言的資訊結構原則、不是中文句型問題 正向陳述優先的本質是資訊結構效率：讀者拿到核心概念的認知步驟越少越好。「不是 X、而是 Y」表達能力差、是因為它讓讀者先處理一個被否定的錯誤理解 X 才拿到正確的 Y、重點後置多繞一步。這個缺陷跨語言成立——英文 not X but Y、日文 X ではなく Y 同樣高頻、換語言不打破（證偽過的反例假設）。判別線是「核心概念在不在最前」、統一了 #94（重點先行合法）與 #149（重點後置違規）、且可操作。LLM 系統性放水的根因是高頻偏置（把語料高頻句型評為表達好、高頻不等於資訊結構優、跨語言）。主解是強制執行重點位置判準、#165 的異源視角降為補充。
• 2026-06-18 多輪審查要有冷讀者 frame：知情 reviewer 看不見行話洩漏 多輪審查模擬讀者時要分兩種：知情讀者（讀完全部、走旅程）與冷讀者（經搜尋或直連落在單篇、零脈絡）。知情 reviewer 會自動腦補脈絡，結構性看不見洩漏撰寫者預設前提的行話。原子 / Zettelkasten / glossary 等可被直連抵達的內容，必須額外跑冷讀 frame。
• 2026-06-18 原子筆記要有向上的議題入口：讀者要知道為何讀這張、何時會撞到 承載知識的原子筆記不是字典條目。每張卡（或其上層）要回答「你在討論什麼議題、撞到什麼問題，才需要這個知識」——從情境進入，而非從定義進入。做法是建『議題 hub』上層筆記討論問題、再分流到術語卡，術語卡頂部回指議題。
• 2026-06-29 Description 是未來自己的 recall trigger、不是文章摘要 文章的 description 欄位要讓未來的自己在掃列表時判斷「我現在遇到的問題，該不該回來讀這篇」——像 skill 的 description 讓系統決定何時載入一樣。摘要式 description 只回答「這篇在講什麼」，recall trigger 回答「你在什麼情境下需要這篇」。
• 2026-06-25 列舉與數字殘留在定義型文件會製造維護債務 定義型文件（規則、規格、常駐名單）中的冗餘列舉（A-G）和描述性數字（9 個函式、428 行）是撰寫過程中的推理殘留——作者先算出範圍再寫定義，但最終文件只需要定義本身。列舉讓每次擴充都要回頭更新引用處，數字讓每次重構都要校準計數，兩者都是維護成本但不增加閱讀價值。判斷標準：如果拿掉列舉或數字，讀者理解不受影響 → 刪除。
• 2026-06-26 讀者是缺經驗的專業人士、不是外行人 技術教材的讀者定位應該是「在這個領域缺乏經驗的專業人士」，不是「完全不懂的外行人」。寫法是補足經驗缺口、不是從零科普。宣導式語氣（跑得好好的、你可能不知道）預設讀者無能，實際上會降低教材的可信度。
• 2026-06-26 技術教材要內嵌管理層可彙報的資訊 技術文章的讀者不只要知道怎麼做，還要能向上彙報為什麼做、花多久、花多少。成本量級、時程估算、進度指標與需簽核的決策點應該嵌在技術段落旁邊，而非集中在另一篇溝通指南裡。
• 2026-06-26 多輪審查缺 outside-in 讀者 frame：六個系統性盲點 review 框架的所有 frame 從已寫的內容出發（inside-out），缺從讀者完整需求出發的 frame（outside-in）。六個盲點全部由使用者而非 reviewer 發現：宣導語氣、管理層資訊缺失、接手情境遺漏、工具指引缺失、深度不拆分、讀者定位未預設。
• 2026-06-26 操作指引的「怎麼做」要帶環境專屬的工具路徑 操作型教材說「拍下現況」「匯出資料庫」「建立備份」時，不同執行環境（container / VM / 共享主機）的工具路徑完全不同。只寫動作不寫工具，讀者知道該做什麼但做不到。這個缺口在 fact-check 和 steelman 審查裡結構性隱形，因為動作本身在邏輯層是正確的。
• 2026-06-26 常識是相對於讀者背景的、不是作者背景的 知識卡的建卡判準不能用「這個夠不夠常見」——對 PHP 工程師是常識的 .htaccess，對 Node.js 工程師完全陌生；對後端工程師是常識的 DNS TTL，對前端工程師需要解釋。建卡看的是目標讀者群裡最不熟悉的那個人能不能理解，不是作者自己覺得夠不夠普遍。
• 2026-06-29 一篇文章只承擔一種功能：SOP 跟 retrospective 混寫兩邊都做不好 文章同時塞操作步驟（SOP）和批次驗證紀錄（retrospective）時，機器讀者找不到可執行的步驟、人類讀者不知道哪段是給自己看的。
• 2026-06-29 Report 卡的論述基礎記結論和 evidence 來源、不記檢討過程 report 卡的論述基礎與限制段寫「從哪來、evidence 邊界是什麼」，不寫「怎麼發起的、用了什麼工具分析」。過程是作者的工作紀錄、結論才是讀者需要的判讀前提。
• 2026-03-12 經驗分享文章的寫作準則 整理自測試經驗記錄的多次修改過程，歸納六條寫作準則與檢查清單，避免常見的語氣、敘事與技術描述問題