跨段落、跨檔引用一個結構單位（章節、階段、條列項、輪次）時、引用它的語意標題、不引用它的位置編號。「見核心問題」「在操作盤點階段確認」是穩定引用；「見 Stage 3」「Stage 1-3 出現訊號時」是把當下的排列順序寫死進引用點。

編號可以存在、但只承擔兩個角色：當下閱讀的排序導覽（條列 1、2、3）、跟發布方凍結過的外部 contract（RFC 段號、法條條號）。活文件（會演進的規範、skill、教材、設計文件）的編號是結構排列的 derivation — 插入一個新章節、所有後續編號全部位移、散落各處的引用點卻不會跟著動。

這條原則同時定義了標題的責任：每個結構單位都要有說明核心意義的語意標題、讓引用有東西可錨。只有編號沒有語意標題的章節（「Stage 3」「第五章」）、等於強迫所有引用者使用會漂移的錨點。

為什麼編號引用會 silent 失效

編號是 derivation、引用是複本

一個章節的編號由「它前面有幾個章節」決定 — 這是排列的衍生值、不是這個章節自身的事實。把「Stage 3」寫進另一個檔案的引用句、等於把這個 derivation 的快照複製出去當 fact 用；結構一變、所有快照同時過期、而且沒有任何機制通知它們過期了。

失效模式比 broken link 更糟：misdirected、不是 dangling

連結斷掉會報錯；編號錯位會成功解析到錯的內容。讀者照著「見 Stage 3」翻過去、看到的是一個真實存在、語意卻完全不同的階段 — 他沒有任何訊號知道引用已經過期。修復也只能靠人工逐處判讀：grep 找得到所有「Stage」字面、但無法判斷哪些語意還對、哪些已經錯位。

語意標題也會改名 — 兩種斷裂不同級

語意錨的最強反例是「標題也會改名、改名後所有語意引用一樣過期」。這個攻擊成立一半 — 引用確實會過期、但斷裂的型態與偵測條件完全不同。改名讓舊引用斷成 dangling：「見核心問題」找不到目標、grep 與讀者都判得出引用過期了；編號位移斷成 misdirected：成功解析到錯的內容、無人察覺。更關鍵的差異是操作者在場與否 — 改名是對目標單位的顯式操作、改名者當下就知道該掃引用面、修復可以發生在同一個 commit；編號位移是別處插入章節的副作用、被位移的章節沒有人碰過、它的引用過期沒有任何人在場負責。語意錨輸在「也會變」、贏在「變的時候可偵測、有人在場」。

時間維度的累積

寫下引用的當下、編號跟語意完全對得上 — 這正是這個反模式難以自察的原因。漂移發生在後續版本：插入新階段、合併兩章、把一節搬到另一個檔案。文件越活躍、引用點越多、每次重排的人工修復面就越大；漏修一處、就埋下一個 misdirected 引用等讀者踩。

反模式與修法

寫作時的判斷次序：先給結構單位一個承載核心意義的標題（這是標題的本職）、編號只作當下排序；引用時一律取語意名稱；引用點離目標越遠（跨檔、跨 surface）、越是只能用語意錨。

邊界：凍結編號是 fact、可以引用

發布方承諾編號不變的外部規格、編號本身就是 contract：RFC 的 section number、法條的條號、含版本年份的 ISO 條款（如 ISO 9001:2015 — 跨版改版會重編條款、引用時鎖定版本才算凍結）、已出版書籍的章節。這些編號被凍結成 fact、引用它們反而比引用標題穩定（標題可能在翻譯與再版間變動）。內部活文件想獲得同樣性質、要先付出同樣代價：宣告編號凍結、只加不改 — 多數活文件不值得也做不到、所以預設走語意引用。

跟其他抽象層原則的關係

• #156 集合命名用角色、不內嵌數量：命名端 sibling。本卡假設語意標題是穩定 fact、#156 負責讓這個假設成立 — 「核心七問」這種 count-bearing 標題一半是語意、一半是成員數的 derivation、引用端怎麼修都錨在會漂移的字串上。本卡初版的正面範例就用了「見核心七問」而未察覺、由 #156 抓出 — 兩卡是不同認知層的檢查、單獨跑任一個抓不到另一個的違規。
• #44 Single Source of Truth：本卡是 SSoT 在「結構引用」維度的實例。編號是位置的 derivation；把編號寫進多處引用點、等於把 derivation 當 fact 散寫多份複本 — fact（章節的語意身分）只在標題一處、引用就該錨在那裡。
• #93 URL slug 必須顯式定義為 fact：同屬「引用要錨在 fact」家族。#93 把跨工具 identifier 從推導值升級成顯式 fact；本卡把跨段落引用的錨點從位置推導值（編號）換成語意 fact（標題）。兩卡的失效模式同型：推導鏈分歧、silent 失效、compile / lint 階段看不出來。
• #84 Naming 是 iterated artifact：標題是名字。本卡要求標題承載可被引用的語意、等於對標題套用 #84 的 cross-call-site 檢驗 — 從引用者的角度看、這個標題單獨出現時讀者知道它指什麼嗎？只有編號的標題在這個檢驗下直接不及格。
• #97 Metadata surface 要納入寫作 review 範圍：引用句屬於 #97 分類中的 navigation surface（跟 link label、索引條目同層）— 同樣是正文之外、卻直接決定讀者入口正確性的層。重排結構時、review 範圍要把散落各檔的引用句列入掃描面、而不是只改目標檔。

觸發 case

設計一個多階段訪談 skill 時、初版流程四階段、各檔用「Stage 1 的核心七問」「Stage 3 收斂時」互相引用。下一版把流程改成六階段：操作盤點與領域切分插入在前、核心七問從 Stage 1 變成 Stage 3、決策收斂從 Stage 3 變成 Stage 5。

後果具體呈現了上述失效模式：十多處跨檔引用要修、grep「Stage」找得到所有字面、但每一處都要人工判讀語意 — 「Stage 3 收斂時」字面完好、語意卻已指向錯誤階段（舊 Stage 3 是收斂、新 Stage 3 是核心七問）。實際修復中就有兩處漏網、靠第二輪全 repo 掃描才補上。若初版引用寫的是「核心問題」「決策收斂階段」這類語意名稱、這次重排的引用修復成本是零。

判讀徵兆

• 寫出「見 Stage N」「如第 N 點」「上一章提過」「§N」且目標是活文件時 — 改用語意標題引用。
• 章節標題只有編號或編號加泛稱（「階段三」「Part 2」）— 補語意半邊、否則其他文件只能用編號引用該章節。
• Review 掃描可用：rg "Stage [0-9]|第 ?[一二三四五六七八九十0-9]+ ?(章|節|點|步|輪)|§[0-9]" — 命中是候選、要逐處判讀目標是凍結編號還是活文件。
• 結構重排（插入 / 合併 / 搬移章節）的 commit、檢查清單要包含「全 repo 掃引用句」、不是只改目標檔。

集合型結構（問題清單、階段序列、原則組、支柱組）的命名只承載角色與層級、把成員數量留給清單自己呈現。「核心問題」這個名稱承受任意的成員增減；「核心七問」把當前成員數烤進名字、加一問、七就變八：名稱本身先失真、散落各處的引用跟著全部過期。「次要問題」「撞牆階段」「防護底線」同理 — 角色詞完成分層、數量歸清單。

區分核心問題跟次要問題、靠的是「核心 / 次要」這組角色詞；讀者選擇讀哪一組、不需要先知道組內有幾個成員。數字在名稱裡有真實的讀者側價值 — 記憶掛鉤與完整性提示（「五原則我只想起四個、漏了一個」）— 但這個價值在活集合下被漂移風險壓過、只有凍結集合能無風險收割它、這也是品牌名刻意用數字的原因；路由本身、角色詞已經完成。

為什麼數量入名比編號引用更深一層

數量是 membership 的 derivation

一個集合的成員數由「目前有哪些成員」決定 — 跟章節編號由「前面排了幾章」決定同構、都是會隨演進變動的衍生值。差別在寄生位置：編號寄生在引用句、數量寄生在名稱本身。名稱是整個知識系統裡被複製最多次的字串（標題、引用、索引、目錄、對話、commit message 都在複製它）、缺陷跟著名稱繁殖到每一個出現點。

它讓「語意標題是穩定錨」的前提失效

引用該錨在語意標題、因為標題被假設是這個單位的 fact。「核心七問」打破這個假設：標題有一半是語意（核心問題）、一半是 derivation（七）。成員一變、想守住名實一致就得全面改名、改名又回到「散落引用逐處修」的老路；想省事不改名、就留下一個說謊的名字（標題寫七問、實際有八問）、比編號錯位更糟 — 錯在系統的權威命名層。

失真的兩條路都有代價

反模式與修法

寫作時的判斷：命名一個集合時、問「這個數字提供了角色詞沒提供的資訊嗎？」— 答案幾乎都是否。讀者需要知道數量的時刻、是看到清單本身的時刻、清單天然自帶數量。

邊界：三種數字可以留

1. 外部凍結的品牌名：SOLID 五原則、OWASP Top 10、WRAP 四步驟 — 數量由發布方凍結、是名稱 fact 的一部分、跟引用 RFC 段號同理。
2. 數字是概念內容本身：兩次門檻 的二是規則的閾值、不是成員數 — 改了二就是改了概念、這種數字承載語意、該留。
3. 緊鄰清單的行內計數：「確認三件事：」後面直接跟三條列 — 數字跟清單同視野、改清單時順手改數字、漂移會立刻被看見。風險低、但仍是小負債、清單就在下面時「確認下列事項：」更省。
4. 內部宣告凍結的集合：團隊把某個方法論名稱當內部品牌用、可以明文宣告凍結後收割記憶價值 — 代價比凍結編號更嚴：凍結編號還能往後加、凍結數量連加都不能加、成員增減等於名稱重新談判。

判別線是「這個數字是 fact 還是 derivation」：發布方凍結的、概念內容本身的是 fact；內部活集合的成員數是 derivation、不入名。

跟其他抽象層原則的關係

• #155 引用章節用語意標題、不用位置編號：直接 sibling、分工在管線的兩端 — #155 修引用端（錨點選什麼）、本卡修命名端（錨點本身怎麼長）。#155 假設語意標題是穩定 fact、本卡負責讓這個假設成立：count-bearing 標題是「一半 fact 一半 derivation」的混合體、先淨化命名、#155 的引用紀律才有穩定的錨可用。實證：#155 卡初版自己用「見核心七問」當正面範例、修引用端時沒發現錨點內嵌數量。兩卡查的是不同層：引用端的檢查抓不到命名端的缺陷、反過來也一樣。
• #44 Single Source of Truth：成員數量的 truth 在清單本身（數一下就有）；把數量寫進名稱是把這個 derivation 複製成第二個源、且這個源被嵌進最高頻複製的字串裡：是 SSoT 違反裡擴散速度最快的形態。
• #84 Naming 是 iterated artifact：本卡給 #84 的命名 review 加一個檢查維度 — 數量入名是「第一版命名基於當下狹窄 context」的典型產物：寫名字的當下成員剛好七個、七看起來是這個集合的屬性；cross-time 檢驗（成員會不會變）才暴露它是快照。
• #67 寫作便利度跟意圖對齊反相關：「七問」「六階段」順口、有節奏感、好記 — 正是便利驅動的選擇；意圖對齊的名稱（核心問題）平淡但誠實。便利的代價延遲到第一次成員變動才結算。

觸發 case

同一份多階段訪談 skill、同一天內兩次命中：

1. 已發生：skill 初版有「四大支柱」、第二版需求調整後支柱變六個 — 名稱被迫改成「六大支柱」、所有提到四大支柱的地方同步修。改完的新名字仍然內嵌數量、下次支柱增減會原樣重演。
2. 被預見：第二版的「核心七問」「成長六階段」被指出同樣結構 — 核心問題若加一問、「七」就散落在標題、引用、索引、路由表裡等著逐處修。

更深的訊號是第三點：當天稍早為了修「Stage 3」編號引用立了一張卡（引用端）、該卡自己用「見核心七問」當正面範例；在專注檢查引用端時、命名端的同型缺陷完全隱形。確認了這是獨立的檢查維度、不是引用卡的子情況。

判讀徵兆

• 命名或標題出現「N 大 X」「N 問」「N 階段」「N 支柱」「N 原則」「N 步驟」且 X 是內部活集合時 — 抽掉數字、看角色詞夠不夠分層、幾乎都夠。
• Review 掃描可用：rg "[一二三四五六七八九十0-9]+ ?(大|問|階段|支柱|原則|步驟|件事|個維度)" --type md — 掃出來的不全是病灶：外部凍結品牌與概念閾值是 fact、留；內部活集合的成員數是 derivation、改。
• 集合成員增減的 commit、檢查名稱是否還誠實 — 需要同步改名的話、這次改名時順便把數量抽掉、別讓下次再來一遍。

同主題內容要落在兩個 surface（人類教材 ↔ agent 協議、公開文章 ↔ 內部 skill）時、每一份要為自己的讀者與用途重寫、不是把句子搬過去。「各寫一份」的規範如果用複製貼上執行、得到的是最差組合：兩份字面綁定（改一邊、另一邊變成過期複本、且沒有任何機制提醒）、卻又各自沒有為自己的 surface 最佳化（教材句直接當協議用、agent 拿到的是給人類讀的敘述而不是可執行的指令）。

語境化的可操作判準：兩個 surface 之間 grep 逐字相同的完整句、命中就是候選。同一個原則、教材版該長成「為什麼 + 案例 + 判讀」、協議版該長成「步驟 + 條件 + 產出格式」— 兩版講同一件事、句子自然長得不一樣；句子一樣、代表至少有一邊在用別人的形狀。

為什麼搬運是預設行為

寫第二份時、第一份就在手邊、而且它「已經寫對了」— 複製是零成本、重寫要重新思考這個 surface 的讀者需要什麼形狀。搬運在當下看起來甚至更安全（兩邊保證一致）；代價在第一次單邊修改時兌現：修了教材版的措辭、skill 版還是舊句、兩邊開始各說各話、而因為當初沒有宣告同源關係、沒有人知道要同步。

「禁止跨 surface 引用」防的是顯性耦合；搬運建立的是隱性耦合 — 更糟、因為看不見。語境化重寫讓兩份真正獨立：主旨對應靠概念、不靠字串。

反模式與修法

欄位與句式跟著用途走之後、兩份的字面自然分開；對照查漏時找的是概念缺口、不是字串差異。

跟其他抽象層原則的關係

• #44 Single Source of Truth：逐字搬運讓同一段論述以兩份完整複本存在、誰是權威沒有任何標記。比一般 SSoT 違反更難修 — 第一步的困難不在改、在發現同源關係存在。
• #122 Cadence 同質化是模板的隱形維度：偵測手段同構 — 都是 grep 句子層的字面重複；差別在範圍：#122 抓同 surface 多檔的句式骨架重複、本卡抓跨 surface 的完整句逐字重複。兩個掃描可以同一輪跑。
• #147 規範化跟自審是兩種認知任務：本卡的 case 正是規範已存在（「各寫一份、語境化在各 surface 內」白紙黑字）、執行時仍搬運 — 立規範的人在執行時用了「各寫一份」的字面（檔案確實是兩個）、漏了「語境化」的實質（句子是同一批）。規範的字面合規與實質合規是兩層檢查。
• #150 教材用中性陳述、不對讀者喊話：register 是語境化最敏感的維度 — 教材的中性陳述、協議的指令語氣、訪談的問句、三種 register 不可互換；搬運最先破壞的就是 register 對位。

觸發 case

一個交付形態判讀主題同時寫進 blog 教學章節與 agent 訪談 skill。Cadence 審查跨 surface 比對、抓到三句完整句逐字相同：「官方首頁文案」反向問、「判讀單位是每條業務流程」、「同一個錯誤的兩個方向」。兩個 surface 的規範明文要求各寫一份語境化 — 檔案確實是兩份、句子卻是搬的。修法把 skill 版三句全部改寫成訪談操作語氣（「請使用者用一句話描述核心流程、然後對照」「gate 逐條業務流程過、混合結論直接寫進決策記錄的交付形態欄」）、修辭句直接刪除 — 改寫後兩邊各自更貼自己的用途、概念對應不變。

判讀徵兆

• 寫第二個 surface 時發現自己在開兩個視窗對照逐段抄 — 關掉第一份、憑概念重寫、寫完再對照查漏。
• 跨 surface 掃描可操作：對兩份檔案跑完整句比對（句號切分後 grep 交集）、逐字相同的非術語句逐處判讀。
• 兩份同主題內容的 register 相同（教材版讀起來像協議、或協議版讀起來像散文）— 即使句子不同、也是語境化不完整的訊號。

讀 description 進來的人以為底線零彈性 — 這個誤解是摘要製造的、本體沒寫過這種規則。摘要、description、索引 hook 對規則做壓縮時、可以丟細節、不可以改模態：模態是約束的強度與結構：禁止（不可做）、條件允許（可做、但要滿足 X）、預設加例外（預設 A、條件 B 時走 C）。「防護底線可延後、但不可沉默跳過、要記錄延後理由與重評條件」是條件允許 — 壓成「不可跳過的防護底線」變成禁止、規則精心設計的出口（記錄式延後）在摘要層消失了。

檢驗的問題只有一個：讀者只依摘要行動、會不會做出本體不要求、或錯過本體允許的事？「不可跳過」的讀者會以為底線零彈性、可能因此放棄整個流程、或在現實壓力下偷偷跳過 — 兩種行為都是本體設計（給一條光明正大的延後路）想避免的。

為什麼模態最容易被壓掉

摘要追求短、模態詞通常比較長：「不可沉默跳過」比「不可跳過」多兩個字、「可延後但要記錄重評條件」比「必須做」多七個字。壓縮時每個字都在被審視「能不能省」、而模態詞看起來像修飾 — 砍掉之後句子更乾脆、語氣更有力、寫摘要的人甚至會覺得更好。失真就藏在「更有力」裡：力度是模態的一部分、加強力度就是改模態。

另一個機制：摘要常在本體完成後補寫、寫摘要時人記得的是規則的「主旨」（底線很重要、不能隨便跳）、不是規則的「結構」（重要、而且有一條設計好的延後路徑）。主旨記憶天然丟結構。

反模式與修法

前三列的失真都往絕對化壓（彈性 → 禁令）、這是主要的重力方向；第四列是反向 — 把有把關講成無把關 — 較少見、但判準同一條：摘要引發的行為偏離本體。

修法：壓縮時保留模態的最小標記 — 「不可沉默跳過」「預設 X、例外見本體」「通過 gate 後自動」。模態標記是摘要裡優先級最高的字、跟主詞動詞同級、比任何細節都後砍。

跟其他抽象層原則的關係

• #97 Metadata surface 要納入寫作 review 範圍：本卡是 #97 的「審什麼」具體化之一 — metadata surface 進了 review 範圍之後、模態一致性是該 surface 最該查的維度、因為 description 是讀者第一個（常常也是唯一一個）讀到的版本。
• #142 文章主體要對齊標題承諾：方向相反的同一條對齊軸 — #142 查 body 有沒有兌現 title 的承諾（由上往下）、本卡查摘要有沒有忠實代表 body 的約束（由下往上）。兩個方向都通過、surface 跟本體才真正一致。
• #152 教材把設計選擇講成選擇、不講成必然：跟 #152 同在「模態失真」這條軸上。#152 抓正文把條件性講成必然性、本卡抓摘要把條件允許壓成絕對禁止 — 主要失真方向相同（彈性 → 絕對；反向較少見、見上表第四列）、發生層不同（正文論述 vs 壓縮層）。絕對化的句子在兩層都更省字、更有力、更好寫 — 失真有一致的重力方向。
• #67 寫作便利度跟意圖對齊反相關：「不可跳過」比「不可沉默跳過」好寫好讀、正是便利驅動 — 摘要層的字數壓力讓這個重力更強、所以摘要的模態審查要比正文更嚴。

觸發 case

使用者開啟一個訪談 skill、description 告訴他「每個維度附不可跳過的防護底線」— 他合理推論底線零彈性、可能因此覺得流程太硬。本體寫的是另一回事：「可延後、不可沉默跳過（記錄『已告知 + 延後理由 + 重評條件』）」、整個 baseline reference 的核心設計就是那條延後記錄協議。跨 surface 審查的判定：「body 的設計更精緻、description 的壓縮把它講成絕對禁令」。修復把「不可跳過」改成「不可沉默跳過」— 模態跟著那兩個字一起回來。

判讀徵兆

• 寫完 description / hook / 目錄註解、回頭比對本體：摘要裡的每個禁止詞與必須詞、本體是同等強度嗎？本體帶「但 / 除非 / 可…需」的句子、摘要保留出口了嗎？
• 摘要讀起來比本體「更有力、更乾脆」— 力度差就是模態差的訊號、不是文筆進步。
• 規則被使用者抱怨「太死」或被整體無視時、先查他讀到的是哪一層 — 常常本體無罪、是摘要把彈性壓掉了。
• 反方向也要掃一眼：摘要讀起來比本體更寬鬆（「自動」「隨時可」）、把本體的把關與條件吃掉了 — 較少見、同樣是模態失真。

寫關係段的第一個動作是把被引卡重新打開 — 因為描述另一張卡、要用它自己的分類詞彙、而記憶給不出 taxonomy 級的細節。「引用句是 metadata surface 的一種」這句話裡、「metadata surface」是被引卡的術語 — 而被引卡自己的分類表把 link label、索引條目歸在與 metadata surface 並列的 navigation surface。引用方憑印象把對方的兩個分類併成一個、關係宣告的精神沒錯、詞彙錯位了。

錯位的代價由循線的讀者支付：他讀到引用句、點過去想看完整論述、發現被引卡的分類表跟引用句對不上 — 輕則困惑（是我讀錯還是卡寫錯）、重則回頭懷疑引用卡的其他關係宣告是不是也是憑印象寫的。關係段的價值在「可回溯」、詞彙錯位直接打在回溯體驗上。

為什麼憑印象轉述是預設

寫關係段時、被引卡是「自己以前寫的、很熟」— 熟悉感讓人跳過重讀、直接憑記憶描述。而記憶存的是概念（「那張卡講非正文的 surface 要進 review」）、不是分類結構（它把非正文拆成 metadata 跟 navigation 兩類）。概念記憶寫出來的引用、語意大方向對、taxonomy 細節隨機。翻譯憑語感不查原文、換掉的是術語的角色；引用憑記憶不開原卡、換掉的是分類的歸屬 — 兩個介面、同一種失誤。

被引卡越熟、風險越高：陌生的卡會被打開來查、自己的卡靠記憶。

反模式與修法

再陳述的查核對象永遠是原文、不是記憶 — 不論那張卡是不是自己寫的、寫關係段前把結論段跟分類表重新攤開。

跟其他抽象層原則的關係

• #109 術語翻譯要保留概念角色：同一條紀律在不同介面 — #109 管跨語言轉述（翻譯時概念在原文的角色不能換位）、本卡管跨卡片轉述（引用時概念在被引卡的分類位置不能換位）。兩者的失誤機制相同：轉述者用自己的理解重新組織了對方的結構。
• #107 術語翻譯要保留原文錨點：#107 的「保留原文讓概念可回溯」在引用場景的對應物 — 引用句裡被引卡的術語就是錨點、錨點寫錯、回溯就斷。
• #116 引用案例要分觀察層 / 判讀層：跟 #116 都在守引用的準確性。#116 管引用內容的層次標註（哪些是 case 的事實、哪些是本文推導）、本卡管引用所用詞彙的歸屬（描述對方時用對方的詞）— 兩者都在防「引用方的加工被讀者當成被引方的原文」。
• #97 Metadata surface 要納入寫作 review 範圍：本卡的觸發 case 恰好是引用 #97 時錯置了它的分類 — fact-check reviewer 打開 #97 的分類表逐欄比對才抓到。關係段的 review 方法就是這個動作：逐條開被引卡核對。

觸發 case

一張新卡的關係段寫「引用句是 metadata surface 的一種 — 它不是正文論述、是指向結構的導航層」、引用對象是「Metadata surface 要納入寫作 review 範圍」卡。Fact-check 審查打開被引卡、發現它的分類表把 link label / 索引條目列在 navigation surface、跟 metadata surface 是並列的兩列 — 引用句把對方明確分開的兩類併成了一類。判定原文：「關係精神成立（非正文 surface 要納入 review 掃描面）、但嚴格按被引卡的詞彙、引用句更接近 navigation surface」。修法：引用句改成「引用句屬於該卡分類中的 navigation surface（跟 link label、索引條目同層）」— 關係宣告不變、詞彙歸位。

判讀徵兆

• 寫關係段時沒有重新打開被引卡 — 不論多熟、開來把結論段跟分類表掃一遍再寫。
• 引用句使用了被引卡的專有分類詞（surface 類型、層級名、模式名）— 逐詞回原卡確認歸屬、這些詞是對方的 taxonomy、不是公共詞彙。
• review 關係段的方法：每條關係宣告配一次「開被引卡、找到支撐句」的核對、找不到支撐句的宣告就是憑印象寫的。

本規範適用於團隊內部各類型技術文章，包含：

• 概念說明：技術原理、系統架構、協定規格
• 實作教學：操作步驟、範例、API 用法
• 架構決策：方案比較、選型紀錄、設計文件
• 除錯復盤：事故紀錄、疑難排解
• 技術評估：工具調研、可行性評估

核心目標：讓讀者能複製思考過程，不只複製結論。結論一行就能給，思考過程才是文章的主體。

本規範四條規則各自後方附有正反例，來源標註：

• 正例多引自 /work-log/ 目錄下的已成文文章
• 反例多引自同系列文章修改前的版本（實際寫作過程中踩到過的問題）

一、階段分層

規則的商業邏輯

技術文章的內容從「事實或需求」推導到「動作或結論」，這個過程有四個功能不同的階段。每個階段處理的問題不同、失敗模式不同：

• 觀察：描述現況、需求、事實或訊息
• 判讀：說明本質、原理、問題所在
• 策略：列出可選方案並比較
• 執行：具體操作或實作

四階段若混著寫，讀者無法區分「這一段失敗是哪個階段」，也無法判斷自己的類似情境卡在哪一步。文章只能被原封不動複製，不能被理解後套用。

做法

每個主題段落應包含四階段。不同類型文章中四階段的對應：

實例對照

反例（跳過判讀，觀察直接進執行）：

1## 錯誤
2flutter_broadcasts_4m：Kotlin 1.8 vs Java 17 mismatch
3
4## 解法
5在 subprojects 加上：
6tasks.withType(KotlinCompile).configureEach { jvmTarget = '17' }

問題：讀者能複製貼上，但無法回答「為什麼是 configureEach 不是其他方式」「遇到下一個類似問題怎麼想」。思考過程沒有被保存。

正例：gradle_reasoning_traps 的節點 A 結構，每個節點顯式展開成「當下看到 → 判讀 → 可選策略 → 選擇與理由 → 結果 → 事後檢視」六個子段落。讀者看完後即使遇到不同錯誤訊息，也能套用同一個四階段推導。

禁止事項

• 從觀察直接跳執行，省略判讀與策略
• 判讀留下未解問題就進策略
• 文章中出現「選擇」卻只列一個選項

例外

純介紹性段落（例如 API 參數說明）可以省略「策略」階段，但不得省略判讀。

二、商業邏輯先於 CASE

規則的商業邏輯

技術文章的內容包含兩種資訊層次：

• 商業邏輯：系統層的概念（為什麼這件事存在、在體系中代表什麼）
• CASE：實例層的資料（具體的數值、路徑、屬性、設定）

CASE 單獨存在沒有意義。「jvmTarget = 17」這個值需要「為什麼 JVM target 要一致」這個概念當容器才能被理解。

順序顛倒（先 CASE 後商業邏輯）等於讓讀者先記一組沒有脈絡的資料，再倒推抽象概念。這條認知路徑是反向的，多數讀者在倒推失敗後會放棄，即使專業讀者能勉強跟上也會覺得閱讀成本偏高。

做法

每個主題段落包含兩層，順序不得顛倒：

商業邏輯層

• 主題涉及的系統層概念
• 該概念為什麼存在、解決什麼問題
• 該類內容的共通本質

此層不討論具體數值、路徑、屬性名。

CASE 層

• 訊息或規格中的關鍵字對應商業邏輯的哪個位置
• 具體數值或內容
• 從 CASE 推論的結論

實例對照

反例（直接給 CASE，預設讀者懂背景）：

1### 判讀
2
3- 這個子專案的 Java task 產出 bytecode target = 17
4- 同一個子專案的 Kotlin task 產出 bytecode target = 1.8
5- 兩者不一致觸發 Kotlin 2.2 的 strict validation

專業人士看了懂，但讀者若不知道「bytecode target」「strict validation」在系統中代表什麼，只能抓到字面字串，無法建立模型。

正例（加上商業邏輯層當容器）：

 1### 判讀
 2
 3**這類錯誤的本質（商業邏輯）**：
 4
 5Android 每個 module 會分別編譯 Java 跟 Kotlin 原始碼，各自產出
 6JVM bytecode。每個 bytecode 有 target version，決定能在哪些 JVM
 7runtime 上跑。同 module 內若兩種語言產出不同 target，runtime
 8可能踩到 API 相容性問題。Kotlin 2.2 把這個從 warning 提升為 error。
 9
10**這次訊息具體說了什麼（CASE）**：
11
12- compileDebugJavaWithJavac (17) → Java 產出 target 17
13- compileDebugKotlin (1.8) → Kotlin 產出 target 1.8
14- 符合上面「module 內不一致」的 pattern

（出自 gradle_reasoning_traps 節點 A 修改後的版本。修改前是反例那種寫法，修改後加入商業邏輯層。）

完成標準

段落結束前，讀者應能回答：

1. 這個主題在系統中為什麼重要？
2. 這個主題的具體案例對應商業邏輯的哪個位置？

若只能回答第二題，商業邏輯層不足。

三、評估用內在屬性

規則的商業邏輯

技術文章經常包含選擇或比較：選 A 不選 B、用 X 不用 Y、選這個架構不選另一個。選擇的優劣取決於方案的內在屬性，不取決於執行者的時間消耗：

• 內在屬性：覆蓋完整性、風險、可逆性、維護成本、可理解性、依賴前提
• 時間消耗：實作要多久、多少人工時

時間消耗是執行者的資源考量，跟方案本身的正確性無關。用時間當評估維度會造成結構性偏差：投資型方案（擴大影響、建立基礎）看起來總是比消費型方案（解當前問題）差，但兩者能力的性質不同，不應以同一量度比較。

讀者讀到時間評估會誤以為「這個方案比較好」，但真正該學到的是「兩個方案各自適合什麼情境」。

做法

每個方案比較必須包含下列維度中至少三項：

實例對照

反例（用時間成本換算划不划算）：

1節點 A 事後回顧：
2這一步多 2 分鐘掃一遍 pub-cache，但可以省下後來約 30 分鐘的
3build-炸-修循環。明顯划算。

讀者學到的是「划不划算」這個執行層結論，沒學到兩個方案的結構性差異。

正例（用內在屬性列出方案差異）：

 1節點 A 事後檢視：
 2
 3若當下選擇「A2 + 同步盤點 pub-cache」：
 4
 5- 優點：一次盤點所有同類地雷，修復範圍完整；避免之後
 6  遇到一個修一個的反應式除錯
 7- 缺點：盤點結果可能含假陽性；擴大修復範圍可能引入新變數
 8
 9當下漏掉這個選項的本質問題是：
10單點錯誤修復後沒有主動擴大搜尋同類問題。
11這是決策是否涵蓋完整問題面的問題，不是執行層的快慢考量。

（出自 gradle_reasoning_traps 節點 A 事後檢視。修改前是反例版本，修改後改用「覆蓋完整性」「範圍完整」這類內在屬性。）

禁止事項

不得以時間成本作為主要評估維度，包含：

• 「這方案比較快」
• 「多花 X 分鐘省下 Y 分鐘」
• 「立即可完成」

四、事後檢視看判讀品質

規則的商業邏輯

技術文章的品質檢視（review、事故檢討、復盤）常只看「結論對不對」，但多數失敗的根源在判讀階段：

• 判讀未確認的推論被當結論
• 判讀觀察範圍不足（只看單點）
• 判讀用類比代替機制驗證

這類問題會表現成「結論失敗」的樣子，但改善方向完全不同：

• 結論失敗 → 下次多列幾個選項
• 判讀失敗 → 下次判讀要更嚴謹、更廣、更實證

兩者混為一談會得到「要更仔細」這種無法行動的結論。

做法

文章或決策完成後，必須回答下列四題：

1. 判讀階段的「需要確認」項目是否全部解答？
2. 觀察範圍是否涵蓋同類情境，或僅處理當前一個？
3. 推論中的類比假設是否驗證？
4. 策略列舉是否完整？

任一題答「否」，對應失敗類型必須明確標示：

實例對照

反例（只檢視結論，歸因模糊）：

1這次修復走了彎路，下次應該更仔細。

無法行動。下次遇到類似情境仍會犯同樣錯誤。

正例（分類失敗類型，對應不同改善方向）：

 1七個節點中四個失敗，分類：
 2
 3| 節點 | 失敗類型 | 根本來源 |
 4|---|---|---|
 5| 節點 C | 需要新資訊（toolchain 時機） | 節點 B 判讀留下「需要確認」但沒補 |
 6| 節點 D1 | 對稱假設 | 節點 D 判讀用「結構對稱」取代「機制驗證」 |
 7| 節點 F | 方法呼叫時機 | 節點 E 判讀沒展開 API 的兩階段行為 |
 8
 9三個失敗都源自判讀未完成就進策略。不是策略選錯，是判讀階段
10進入策略時，還帶著未解決的問題。

（出自 gradle_reasoning_traps 的「整個過程的決策品質檢視」段落。）

這樣的檢視產出具體改善方向：「判讀完成標準要收緊」、「機制差異需實證」，而不是模糊的「要更仔細」。

五、判讀徵兆對照

技術文章撰寫中常見的徵兆與對應的判讀要求。看到徵兆時，作者必須回答對應問題。

徵兆：單一位置指向（檔案、行號、屬性名）

該位置是「現場」，不一定是「根因」。必須追問：

• 為什麼是這個位置出問題？
• 是目標的狀態錯了，還是呼叫的時機錯了？

徵兆：同類情境第二次出現

前次處理範圍不完整。必須追問：

• 還有哪些同類情境？
• 是否有共通原因？

徵兆：修改看似合理但未生效

時機或機制假設錯誤。必須追問：

• 修改的生效時機是否晚於覆蓋對象？
• 覆蓋機制是否真的能蓋過目標？

徵兆：「final」「already」「cannot」這類字眼

目標已進入不可修改狀態。必須追問：

• 目標何時進入該狀態？
• 修改能否提前到狀態轉換之前？

徵兆：「inconsistent」「mismatch」這類字眼

兩部分不一致。必須追問：

• 哪一邊是正確的目標值？
• 不一致的方向決定治理施加在哪一邊？

實例

這組徵兆對照表的完整應用案例見 gradle_evaluation_order_traps，該文將三種 Gradle 時序錯誤（already evaluated、is final、覆寫沒生效）各自對應到同一個底層問題（時機錯位），並給出對應的解法方向。這就是「看到徵兆 → 查表 → 推出判讀結論」的標準路徑。

六、術語

七、提交自檢

提交文章前自檢：

• 四階段（觀察／判讀／策略／執行）完整，或已說明可省略的階段
• 每個主題段落先商業邏輯後 CASE
• 判讀中所有「需要確認」項目已解答或註明可暫不確認
• 每個方案比較至少三個評估維度
• 未以時間成本為主要評估維度
• 事後檢視四題已回答
• 失敗類型已標示（若有）

參考範例

本規範四條規則的完整應用案例：

• Gradle JVM target 除錯復盤：七個節點的策略權衡 — 全四條規則的完整應用，每個節點皆含觀察／判讀／策略／結果／事後檢視五層
• Gradle 強制覆寫 plugin 的 JVM target：Kotlin 與 Java 的切入點不對稱 — 商業邏輯先於 CASE 的範例（先講 Kotlin plugin 與 AGP 的機制差異，再講具體寫法）
• Gradle Configuration 時序陷阱：afterEvaluate、evaluationDependsOn、finalized properties — 判讀徵兆對照的完整應用
• 為什麼 Bug 在合併後才爆：Gradle Cache 掩蓋潛伏問題的邏輯 — 事後檢視看判讀品質的範例（將「合併造成」重新歸因為「判讀時把觸發條件當根因」）