會誤解處補正向知識、不把誤會當敘事中心
論述基礎與限制
本卡的論述基於 1 個 batch（遠端 agent 工作機教材7 篇文 + 7 張卡的三輪 review、一次抓到 6 處同構的澄清式框架）抽出來的觀察。具體限制：
- 命中詞是 starting set、不是窮舉：「最容易誤解 / 常見的誤判 / 要抵抗直覺 / 值得記 / 會困惑的現象」是這批出現過的、不代表「把誤會當敘事中心的完整形式庫」。新變體（「你以為 X 其實 Y」「乍看…實際」「反直覺」）出現時要持續擴充；同義變體多、grep 抓不全、要靠語意判定。
- 界線是本卡的核心、不是附註：具體第一人稱實測敘事（「本輪一度以為沒 Esc、實際是鍵列可捲動」）跟真實診斷區分（逾時 vs 被拒是真實的網路層事實）不是違反 —— 誤判它們會把正向診斷知識一起砍掉。判定靠「概念位置」不靠「有沒有提到誤判」。
- 修補有效性未獨立驗證：改成正向先行後讀起來更聚焦、但「framing 跟讀者實際理解之間的相關性」沒做使用者測試。
讀者使用本卡時、先判斷這處是「教一個真實區分 / 記一段真實經歷」還是「把假想誤會當主題句立起來再打掉」——後者才套用。
核心原則
文章與個別知識的目的是釐清觀念、把知識串起來讓讀者融會貫通。 若某處會讓人誤解、正解是補上讓誤解無從發生的正向知識（先給正確心智模型與支撐它的機制）、而不是喊「這容易誤會 / 別搞混 / 你以為的其實不對」。「容易誤會」的框架把 misconception 放在正確模型之前、先把讀者放進「你會錯」的位置、還常提醒讀者一個他本來不會有的困惑 —— 目標該是讓讀者融會貫通、不是提醒他「不需要特別認知的內容」。
關鍵的認知轉換是：「這容易誤會」是一個訊號、標示作者這裡沒把機制講夠 —— 它不是一段該寫進文章的澄清。 補救是把知識補到位讓警告沒必要存在、而不是把警告寫得更清楚。
下面幾種形式是這批觀察到的 pattern —— 不是窮舉：
| 澄清式框架的形式 | 具體案例 | framing 的問題 | 正向改法 |
|---|---|---|---|
| meta 標記「最容易誤解」 | 「這是最容易誤解的一點」「認證模型跟直覺不同」 | 把誤解重新推上台面、不傳遞知識 | 刪 meta、讓前面已給的正確模型自己站住 |
| 誤解當主題句起手 | 「要點破一個實測會誤解的心智模型：…」 | 正確模型被冒號擠到後面、讀者先被放進「你會錯」 | 機制直述先行：「這個 env-var 模型的直接後果是…」 |
| 錯誤信念當句子主詞 | 「『放私有 repo 應該安全』是常見的誤判」 | 先立一個誤解再打掉、正確知識被推到第二句 | 直述正確知識：「私有 repo 降低曝露、但不消除：…」 |
| 喊話式抵抗直覺 | 「選型時要抵抗『功能多所以好』的直覺」 | 以讀者誤判當敘事骨架、兼帶喊話 | 給正向判準：「選型判準是這個場景會不會用到」 |
具體 case
case 1：meta 標記「最容易誤解」
澄清版：認證形態是「長效 token 的環境變數注入」、而不是「一次登入、狀態存在本地之後都在」。這是最容易誤解的一點。
問題：前面已經正面把模型講清楚（env-var 注入 vs 持久登入），尾巴的「這是最容易誤解的一點」不傳遞任何新知識、只是把誤解重新推上台面。刪掉不損失資訊。
正向版：（刪除尾句）認證形態是「長效 token 的環境變數注入」、而不是「一次登入、狀態存在本地之後都在」。
case 2：誤解當主題句起手
澄清版：這裡要點破一個實測會誤解的心智模型：認證綁在「每次 run 有沒有注入 token」、不綁在 session 或登入態上。
問題：正確模型（認證綁 token 注入）被「要點破一個會誤解的心智模型」這個 framing 擋在後面、讀者先被放進「你會誤解」的位置。同一機制的 sibling 段處理得更好：直接「env-var 模型的直接後果是…」機制先行、不喊誤解。
正向版：這個 env-var 模型有一個直接後果：認證綁在「每次 run 有沒有注入 token」、不綁在 session 或登入態上。
case 3：錯誤信念當句子主詞
澄清版：「放私有 repo 應該安全」是常見的誤判。 私有降低曝露、但不消除：有讀取權的協作者、CI、fork、git 歷史永久留存都是曝露面。
問題：以一個錯誤信念當句子主詞開場、先立誤解再打掉。正確知識（曝露面清單）被推到第二句之後。而曝露面清單本身就讓「私有 = 安全」的誤解無從發生、不需要先把誤解說出來。
正向版：私有 repo 降低機密曝露、但不消除：有讀取權的協作者、CI、fork、git 歷史永久留存都是曝露面。
沒這樣做的麻煩
資訊結構效率低、讀者先處理錯的東西
把誤解放在正確模型之前、讀者的認知路徑變成「先讀一個錯的 → 再讀為什麼錯 → 才拿到對的」。正向先行讓讀者第一步就拿到正確模型、認知步驟更少。這跟 #166 重點優先 是同一個資訊結構效率問題、只是這裡被後置的是「正確模型」、被前置的是「假想誤會」。
提醒讀者一個他本不需要有的困惑
沒讀過這篇的讀者本來不會「以為私有 repo 安全」、不會「以為認證綁 session」。文章先把這個誤解植入、再打掉、等於憑空製造一段讀者要處理的噪音。教材該補的是讓概念串起來的知識、不是替讀者預演他不會犯的錯。
用喊話代替把機制講清楚
「這容易誤會」常是作者沒把機制講夠的偷懶訊號 —— 與其解釋「為什麼是 env-var 注入而非持久登入」（機制），不如喊一句「這很容易誤會」（stance）。留著這個 framing、缺的那段機制就一直不會被補上。
同義變體多、grep 抓不到
「最容易誤解」有關鍵詞、但「要點破一個會誤解的模型」「常被直覺帶偏」「你以為 X 其實 Y」句式發散、無固定詞。grep keyword bank 結構上抓不全、只能靠 reader-simulation 語意 pass（「這段在補正向知識、還是在提醒讀者會犯錯？」）。
跟其他抽象層原則的關係
- #150 教材用中性陳述、不對讀者喊話：兩卡相鄰但軸不同。#150 是 stance 軸（陳述概念 vs 對讀者說話）、把「別搞混」當祈使喊話的一例。本卡是 知識供給 軸：核心不是「把喊話改中性」、而是「『容易誤會』標示了一個知識缺口、要補正向模型」。「別搞混」在 #150 的修法是刪 stance、在本卡的修法是補上讓人不會搞混的機制 —— 同一個句子、兩個維度的問題。
- #166 重點優先陳述是跨語言的資訊結構原則：本卡是 #166 在「誤會 vs 正確模型」這組對象上的具體化。#166 的判別線「核心概念在不在最前」直接適用：把假想誤會前置、正確模型後置、就是重點後置。本卡補的是 #166 沒點名的一個高頻後置源 —— 把 misconception 當敘事中心。
- #210 壓縮結論剝奪推導路徑：「這容易誤會」是壓縮結論的一種 —— 作者已走完「讀者需要 X 知識才不會誤解」的推導、只輸出最後一步的警告、丟掉了 X 本身。本卡的修法（補回正向模型）正是 #210 說的「還原推導路徑」。
- 讀者不需要知道的資訊不該出現在最終文件：兩卡都判「讀者不需要這個」、但對象不同。那張卡是 meta 資訊（寫作動機、邊界聲明）—— 純刪。本卡是 假想誤會 —— 不是純刪、是換成正向知識（刪掉警告的同時要確認機制補到位）。修法動作不同：一個是刪、一個是「刪 framing + 補 / 確認知識」。
判讀徵兆
| 徵兆 | 該做的行動 |
|---|---|
| 段首 / 小節開場出現「最容易誤解 / 常見的誤判 / 要點破」 | 誤會當敘事中心 —— 刪 framing、確認正確模型已先行且機制夠 |
| 句子主詞是一個錯誤信念（「『X 應該 Y』是誤判」） | 先立誤解再打掉 —— 改成直述正確知識、讓誤解無從發生 |
| 出現「要抵抗 / 別被…的直覺」 | 喊話式抵抗 —— 改成正向判準（「判準是 X」） |
| grep 命中誤會類詞（最容易誤 / 誤判 / 要點破 / 會困惑） | 候選、非判決 —— 逐處判「補正向知識」還是「提醒讀者會錯」 |
| 自問「拿掉這個誤會 framing、正確知識還在不在」 | 在 → 刪 framing；不在 → 這處沒給知識、要補的是機制不是警告 |
| 這處是具體實測敘事 / 真實診斷區分 | 合規 —— 保留（那正是要補的正向知識） |
適用範圍與邊界
- 適用：概念建立段、機制解釋段、判斷工具段的開場 —— 這些地方的責任是把正確模型講清楚、把誤會當主題句立起來純屬負擔。
- 不適用（本卡的核心界線）：
- 具體第一人稱實測敘事：「本輪一度以為沒 Esc、實際是鍵列可捲動」是真實經歷的教訓、教的是「以互動為準」的判讀、不是提醒讀者一個假想困惑。work-log / 實作記錄的事件敘事以直覺作對照合理。
- 真實診斷區分：逾時 vs 被拒、症狀層 vs 根因層、OOM vs 其他 SIGKILL —— 這些是真實存在的技術事實、教它們就是「補上讓讀者理解的正向知識」。以正向方式供給（這是什麼、怎麼判別、機制為何）、提到常見誤判只作對照不主導、即合規。
- 邊界：判別線是「這處在補正確模型、還是把假想誤會當敘事中心」—— 後者才改。真實的誤判對照（明示「反例：…」）跟「」內引用合規。
Self-case：本卡的觸發來源
本卡觸發於使用者要求對 遠端 agent 工作機教材批次 補多輪審查時、明確指出的一條原則：「有部分章節提到容易誤會之類的說法、不應該這樣寫 —— 每個文章或個別知識的目的是釐清觀念、如果有什麼會讓人誤解、那是我們需要補上對應知識讓讀者理解、而不是單純澄清這樣不可以。目標是讓讀者把知識串起來融會貫通、而不是提醒讀者他不需要特別認知的內容。」
三輪 review 在該批 catch 到 6 處同構框架（container 文「最容易誤解的一點」、handson「要點破一個會誤解的心智模型」、runtime-secret 卡「是常見的誤判」、home-vs-vps「常被三個直覺帶偏」、mobile「要抵抗…的直覺」、handson/tailscale「最容易誤判方向 / 一個常見的誤判方向」）、全改正向；同時把診斷型知識（逾時 vs 被拒、症狀層 vs 根因層）判為合規保留。
對應本卡：澄清式框架是獨立於 stance（#150）跟重點位置（#166）的知識供給議題 —— 一個句子可以 register 中性、重點也在前、卻因為「把讀者本不需要有的誤會當敘事中心」而該改成補正向知識。