# Compositional Writing > Composes atomic, intent-revealing, grep-friendly writing (Zettelkasten) for code comments, docs, logs, prompts, schema/ticket fields, external-analysis transformation, and long-form technical articles. Use when cognitive load and token cost matter. **Also triggers during multi-round review / batch review / 寫作 audit** — provides the keyword bank (正向陳述 / 口語修辭 / 地區用語 / 廢話前綴 / 裝飾符號 / 對讀者喊話 / 自評誇飾 / 必然性框架 / 澄清式框架 / 歸因語氣 / 宣導語氣 / 泛用詞 / 位置與集合指涉 / 脈絡懸置 / 敘事姿態 / 用詞搭配 / 物理化錯配 — 完整清單見本檔「字句層 keyword bank」節) and frame-specific check lists that multi-round-review reviewer agents need. Triggers: 寫註解, 寫文件, 寫日誌, 寫 prompt, 寫文章, 技術文章, 商業分析, 外部分析文章, 經驗談轉教學, 訪談整理, 機制重建, post-mortem, 架構決策, 除錯復盤, 檢討報告, 欄位設計, atomic, reusable, 多輪審查, multi-round review, batch review, 寫作 audit, 正向陳述, 口語修辭, 問句標題, 敘事視角, 字句層 grep, SOLID, 文章拆分, 結構決策, 擴充點, 依賴方向, 讀者分流. - Skill: `tarrragon/compositional-writing` (Agent Skill, multi-file: 93 files) - Install (CLI): `npx skillmds@latest add tarrragon/compositional-writing` - Raw SKILL.md: https://api.skillmd.com/api/skills/tarrragon/compositional-writing/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: tarrragon (https://skillmd.com/u/tarrragon) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/tarrragon/compositional-writing --- # Compositional Writing 以 Zettelkasten（卡片盒筆記法）為核心的寫作方法論。將每段文字視為可重複組合的原子卡片，讓人類讀者與 AI 代理人都能以最小認知負擔找到答案。 --- ## 這份檔案是綱領層 SKILL.md 給的是原則、判別線與邊界；**可執行的操作在兩個地方**——本檔的「字句層 keyword bank」那一節（有可直接跑的 rg 指令），以及 `references/` 底下各情境的 reference（有步驟與範例）。 所以讀本檔各原則時，「我的第一個動作是什麼」的答案幾乎都是同一個：**到觸發路由表找自己的情境，打開對應的 reference**。原則本身不指定動作，那是設計、不是缺漏——原則要跨情境成立，動作只在情境裡才有意義。要直接動手的人先跳到觸發路由表。 ## 動手之前先定這一份的定位 **定位決定體例，所以它在所有規則之前。** 寫下一句話：誰讀、讀完要做什麼。這一句是後面每一條規則的過濾器，也是選 reference 的依據。 判別的軸不是「內容裡有沒有可執行的東西」——教材也會給辨識訊號與可以改的東西——而是**那個動作落在哪裡：在世界上動手，還是在腦中重新歸類**。 | 定位 | 讀者 | 體例 | Reference | | ---------------- | ------------------ | -------------------------------------------------------------------------- | ----------------------------- | | Agent 指令、規範 | 照著執行的執行者 | 操作手冊：步驟編號是執行的位置，判錯代價要寫，因為執行者需要知道哪一步不能錯 | `reference-authoring-standards.md` | | 人類教材 | 來理解一件事的人 | 引導與脈絡：講清楚為什麼是這個順序，順序自己就出來；讀者要的是判讀的依據 | `writing-articles.md` | | 程式碼註解 | 正在讀那段程式的人 | 只解釋商業邏輯，不解釋原理也不冗長，因為原理讀程式碼就有 | `writing-code-comments.md` | 同一個內容集合底下可能兩種定位並存：一個分類裡的文章是教材，而它的目錄頁是那個分類的操作手冊；整個子集合也可能兩邊都不是，例如一份歸納問題與解法的記錄——讀者不是來理解一個主題的，而可執行的那一半住在別處。定位按稿件要讀者做什麼判，不按它放在哪裡判。 **會讓稿件被讀成手冊的裝置**（掃裝置比掃語氣可靠）：表徵對映清單（「症狀：成因」）、檢查順序的指示、配比與參數數字、順序關鍵加上顛倒的後果、可執行的操作判準、具體器具與工具作法、**序列連接詞（先、之後、最後）**。最後一項最容易漏——把步驟編號換成它只改掉一半。 處置不是刪掉資訊：材料與手法該留就留，改的是框架——把「照著做的步驟」改寫成「這件事為什麼是這樣」，把「顛倒的後果」改寫成「順序在這裡有什麼物理意義」。詳見 [positioning-decides-form-before-any-rule-applies](references/principles/positioning-decides-form-before-any-rule-applies.md)。 ## Core Pillars（核心支柱） | 支柱 | 意義 | | -------------------------------------- | ---------------------------------------------------------- | | **Atomization** 原子化 | 一段文字只承載一個概念，可獨立閱讀與重用 | | **Explicit Intent** 意圖顯性與層級貼合 | 讀者第一眼就看懂「為什麼在這裡、屬哪個抽象層級、該做什麼」 | | **Searchability** 可查詢性 | 人和 AI 都能用關鍵字 / grep / regex 快速定位 | --- ## Core Principles（核心原則速查） 讀者能在本區塊完成快速複習；需要具體應用時，依下方「觸發路由」讀對應情境 reference。 ### 1. 原子化（Atomization） 一張卡一個概念：能獨立理解、可跨情境重用。拆分依據是**認知負擔與情境匹配度** — 讀者要同時記住的概念數、以及這張卡是否符合讀者當下的情境需求。常見的誤判依據是「行數」（卡太長就拆）、行數只反映表面字數、不反映概念數：一張 200 行的卡可能只講一個概念、一張 30 行的卡可能塞了三個概念。判別問題是「讀者要同時 hold 幾個概念才讀得懂這張卡」、超過 7 個就要拆。 **內容壓力的出口是擴充結構、不是壓縮內容**：內容超出容器的自然大小時（判斷標準裝不進表格格、概念裝不進標題、範例讓段落過長）、合法出口都在結構層——就地展開（延伸段、本篇專屬內容）、外部化成卡（跨篇可用的支撐 / 背景概念、範例寫進卡片、文章引用卡片承接論證）、或換成連結（概念在內容集合裡已有卡或專章承載時、刪掉格內自撰的 gloss 改放連結）；裁內容遷就容器違規、終點形態是簡報式文章（表格當主體、格內殘語、條列連綴——簡報的正當性來自講者在場補完、文章沒有講者）。邊界：主線概念必須行內展開（外部化斷論證線）；擴充的對象是結構不是句長（句層另由消費單位分配管）；checklist、規格表與查表型段落（判讀徵兆表 / 對照表）的表格形態合法——消費單位是逐項執行或逐列查詢、同一機制豁免；拆卡淨收益待試點驗證、先小規模再全面。選出口前先搜內容集合有沒有既有落點（有落點就是換成連結、不寫 gloss；但**程序要逐項消耗的列舉**留在本篇、只有定義外部化——一次獨立冷讀顯示三篇裡「不點就接不下去」的連結全是這一類，而所有背景術語卡都判可選）。判「換成連結」之前要打開目的地把成員並排：它與「先收斂載體」在外觀上無法分辨、差別在切法對不對得上，而一次第二人分診（同一批 29 列、一致率 86%）的四處分歧有三處就出在這裡、方向全部偏向連結。，並跑一個前置檢查：**查這個概念在別篇有沒有不相容的版本**——用雙向對映測試（兩篇的成員並排、逐項問能不能互相對映完整、只存在於一側的成員就是不相容的證據）與動作測試（讀者會不會為這件事做同一個動作兩次：一篇的產出是另一篇的輸入是互補、兩篇是同一個動作的兩份指示是衝突）；有衝突就先收斂單一權威載體——判斷標準完整度決定哪一套內容留下（殘缺的那套當載體會擴散殘缺）、引用數只決定住址搬不搬（遷移成本、非品質、而且要數指向那組成員的引用不是指向那一頁的：整頁入連由該頁主題帶來、一次實測相差一個量級而據此選錯了理由）、同一對象已有卡時卡通常是住址（理由是成員定義本來就是卡的責任）、而兩套各有對方缺的成員時載體要先補齊才有資格當載體（收斂不是挑一套刪掉另一套、補齊時檢查新成員的名字在載體上有沒有被佔用的近義詞、否則會把同名異義搬進唯一的住址）——其餘各篇沿用它的語彙並重新界定 scope，「同步成一份」與「兩套並陳」都不是修法。搜尋別篇版本時掃的是「宣告一組固定成員、要求逐項填寫的段落」、不論它排成表格、清單或散文（寫成「掃表格」會漏掉全部——一次實測的六個住址全是編號清單），而計數只算同層的住址（不同層的分解對齊語彙、不收斂）。這種矛盾單篇視角下不落空（每篇單獨讀都自洽）、要在分診階段查。兩次實測的出口分布差異很大（一次以換成連結為主、另一次以收斂載體為主），分布隨卡層覆蓋與跨章關係變動、不可推廣——每次改寫重跑分診。文章要短、讓細節搬進卡片、別讓細節消失。詳見 [content-pressure-resolves-by-expansion-not-compression](references/principles/content-pressure-resolves-by-expansion-not-compression.md)。 **串連佔掉的是本篇的篇幅，順序是先自足再往外開門**：相互引用的集合會讓串連看起來像義務，而每一條引用都佔掉本來要用來講自己的位置——上一條的「換成連結」出口因此有個前提，**本篇的主線不能靠它**。驗收是把所有往外的連結當成不存在重讀一次，剩下定義加屬性清單就代表判斷做錯了；遮住連結之後第一個要查的是那個貫穿全篇的詞（承重術語在自己的主場最容易沒有定義，作者寫得越多陌生感消失得越早）。串連寫成條件分支（換掉哪一項會變成什麼）讓它成為本篇的內容，而**分支不會順便交代目的地，承諾要另外寫**——判斷標準是遮住目的地之後讀者預測不預測得出那一篇會給什麼，句型只影響命中率、不是判定條件（寫成謂語命中率高，但照句法規則判會產生假陰性）。症狀是讀得懂而說不出要交付什麼，只有問「這一篇讓你具備什麼能力」分得開。詳見 [cross-links-eat-the-article-they-live-in](references/principles/cross-links-eat-the-article-they-live-in.md)。 **拆分標準的核心問題**：「這張卡聚焦在什麼問題、議題切完整了嗎？」— 判斷標準是 **focus 完整度**。常見的次級訊號是「卡之間是否衝突」「邊界是否清晰」、兩者都不夠：兩張卡互不衝突、仍可能各切了一半同樣議題；一張卡邊界清晰、仍可能塞了兩個獨立議題。focus 完整度問的是「這張卡有沒有把它聲稱要解決的議題講完」、是 contrast 上面那兩個訊號抓不到的死角。 ### 2. 索引建立（Indexing） 用 MOC（Map of Content）、tag 層級與反向索引把卡片串成可導航的網。入口文件**只做路由**、把細節留給目標卡；引用深度**最多一層**、讓讀者一跳就到答案（避免 A→B→C 的多層跳躍）。 **引用錨點用語意標題、不用位置編號**：引用另一個章節 / 階段 / 條列項時寫「見核心問題」、不寫「見 Stage 3」— 編號是結構排列的 derivation、結構重排時引用句字面完好、語意 silent 指向錯的內容（比 broken link 難偵測：連結斷掉會報錯、編號錯位會成功解析到錯的東西）。對應要求是每個結構單位的標題要承載核心意義（「Stage 3：核心問題」、編號只作排序前綴）、引用取語意半邊；發布方凍結的編號（RFC 段號 / 法條）是 fact、可引用。**相對位置（末段 / 下段 / 上節 / 下方）是同構的另一種 derivation 而判準寬一階**——同檔緊鄰的合法且常比具名好讀，失效條件有兩個、各自獨立：跨檔即失效（讀者手上的「上節」是他正在讀的那一份的）、目標可能移動即失效（不報錯，成功解析到現在住在那個位置的東西）。由第二個推出**位置指涉的主要來源是修法自己**（寫下的當刻位置一定是對的），所以掃描的觸發是改動、不是完稿；定址型產物（地址表 / 索引 / 路由表）一律具名、不看距離。詳見 [reference-by-semantic-title-not-number](references/principles/reference-by-semantic-title-not-number.md)。 **語意錨用單一字串、引用他卡用對方的詞彙**：同一個結構單位的語意名稱只能有一個 canonical 字串（取標題語意半邊）。反向的形態同樣要查——**一個名字承擔多個所指**：一次實測裡「格」在同一個分類裡指四件事（責任位置、分類的一類、主題陣容裡的空位、某個框架的象限），而定義只掛在其中一個所指的另一個名字上（表頭與段標寫「位置」、散文寫「格」），三份理解探針對「格是什麼」全數回報「文字沒說」——定義存在、讀者卻拿不到，因為它掛在另一個名字底下。偵測靠探針而不是 grep：同名異義每一處單獨讀都通順— 同義雙名（標題「決策記錄 + scaffold 建議」、引用「決策收斂階段」）讓 grep 掃 A 漏 B、重排修復退回人腦對應。引用另一張卡並描述它的內容時、寫之前把被引卡重新打開、用它自己的分類詞彙轉述 — 記憶存概念不存 taxonomy、憑印象轉述會把對方明確分開的類別併掉、每條關係宣告要找得到被引卡的支撐句。 **集合命名用角色、不內嵌數量**：標題要當穩定錨、就得先是純 fact —「核心七問」「成長六階段」「四大支柱」把成員數烤進名字、數量是成員清單的 derivation、加一問名稱先失真、所有複製過名稱的地方跟著過期。命名只承載角色與層級（核心問題 / 撞牆階段 / 支柱）、數量讓清單自己呈現；外部凍結品牌（SOLID 五原則 / OWASP Top 10）跟概念閾值（兩次門檻）的數字是 fact、可留。**同一個機制在散文裡的載體掃不到而數量更多**：承擔指涉功能的計數（「後三列」「三則」「共用兩節」）沒有「刪掉」這個出口，且它的產生源是結構改動——寫下的當刻數字是對的，加一列、拆一檔、搬走一節就當場過期，每一輪修法都在生產新的。修法是改成不自帶計數（把數字改對只買到一輪），判別問句是**這個數字由什麼決定**——由會被改動的集合的成員數決定就不安全，由模式數 / 階段數這類不隨結構增刪的東西決定就安全；掃描的觸發同樣是改動、不是完稿。**合規邊界**：成員由機制固定且緊鄰具名展開者可帶數字（如「六欄位」「三查」）；`##` 標題帶數字（如〈五種情境〉）須與表列數一致並註明例外成員，否則仍屬違規。詳見 [name-collections-by-role-not-count](references/principles/name-collections-by-role-not-count.md)。 **錨點標籤的自足義務隨引用點數上升**：檢索鍵位（title / 表格鍵欄 / 段標 / 欄位標籤）的精簡優先只在這個鍵**只有一個消費點**時成立。鍵一旦被別處逐字引用它就是錨點，而引用的形式是逐字比對——加字即斷開，所以每個引用點只交付短名本身、補完的責任全部落回讀者；短名省下的字數付一次，還原限定語的成本乘以讀者數與引用點數，而既有標籤要改時它與全部引用點必須同一次改、修復成本同樣乘上去。判準是兩個問句：**這個標籤裡的每個名詞，讀者知道是哪一個嗎；每個動詞，讀者知道主詞是誰嗎**。省略的限定語補回標籤本身、不補在鄰欄（讀者先讀標籤才決定要不要讀那一列）。偵測的入口是引用點數（`rg -F -l -- "<標籤>" <根目錄>`、命中兩檔以上就是錨點），對象是定義處的標籤清單而非全文段標——用段標當代理會量到模板重複（一次實測前幾名全是 `YAML`、`Problem` 這類模板欄位）。**這一類讀起來是完整的詞，所以查殘片的檢查（名詞頭、指涉閉合）全數放行、一致性掃描也無效**——壓縮零星發生，周圍都是對的。例外：表頭語境下已自足的通用欄位標籤（「觸發」「反應」）、領域內一跳查得到的正式術語。詳見 [compressed-label-cost-multiplies-with-citations](references/principles/compressed-label-cost-multiplies-with-citations.md)。 ### 3. 意圖顯性與層級貼合（Explicit Intent & Layer Alignment） **寫作前先標記本文所在抽象層級（實作 / 工具 / 協作 / 認知 / 架構）、論述停在該層**。素材取自哪個層級、論述就收斂在哪個層級 — 因為跨層提升等於用 X 層的詞彙描述 Y 層的議題、讀者拿到規則但對不到自己當下的情境。要把實作層素材抽象到認知層、先補對應抽象層的支撐文件（讓論述有對應層的詞彙跟 case 可引用）、再做跨層提升。 寫「為什麼」和「要達成什麼」、把「程式碼在做什麼」留給程式碼自身（程式碼讀一次就知道做什麼、寫進註解只是冗餘）。主詞與動詞直接、段落開頭即表達意圖。TODO / placeholder 留給 inline 註解、文件本體只放當前契約 — 因為文件常被當成「契約 SSoT」引用、混入未完成事項會讓讀者誤判契約範圍。同一篇文字貼合它在系統裡的抽象層級、把下層實作藏在介面後面。 **機會成本語氣優先**：程式設計大多是多目標取捨、討論的是「在什麼情境下哪個選項較划算」。把絕對二元語氣（「正確概念是 X / 替代方案不足 / 應該這樣做」）翻成情境化敘述：「比較好的做法是 A、因為 [情境] / B 在 [其他情境] 合理 / D 的成本特別高、只在 [極端情境] 才划算」。機會成本教讀者「思考方式」（能套用到新情境）、絕對主義教讀者「規則」（壓力下會忘）— 所以前者是預設語氣。例外保留給物理 / 法律 / 數學事實（安全性、資料完整性、合規、雜湊必有碰撞）。絕對二元語氣有兩種形式：**命令式**（「應該做 X」）讀者聽得出是主張、會審；**必然式**（「X 天生就是 Y / 本質就是 / 必然」）偽裝成事實陳述、更隱形 — 把設計選擇講成自然法則時尤其要 catch、還原成「在選了某前提後 X 才以此形式成立」。判別線：這個必然有沒有上游設計選擇當前提（有=條件性、要講前提；無=真必然、可斷言）。詳見 [teaching-prose-neutral-register](references/principles/teaching-prose-neutral-register.md)。 **選項數由議題本身的合理選項數決定**：機會成本的精神是「教思考方式」 — 議題有幾個合理選項就寫幾個（2 個寫 A/B、3 個寫 A/B/C、4 個寫 A/B/C/D）。強湊到固定數量會把「教思考」退化成「填格式」、生出「實務上幾乎不存在」的低品質假反模式。真正的反模式直接標「D：反模式 — 違反 X 原則」、給讀者明確的「為什麼這條路該避開」、保持誠實。 **讀者定位聲明（生成端前置步驟）**：每個教學模組在第一篇文章生成前，顯式聲明讀者定位——一段話描述目標讀者的背景、已有能力、缺的經驗。這份聲明是後續所有生成和 review 的可檢查基準。缺少顯式聲明時，LLM 預設用「教外行人」的姿態寫教學內容，這個預設不被 review 挑戰（reviewer 共享同一個預設），導致宣導語氣通過多輪審查。per [outside-in reader frames](references/principles/review-lacks-outside-in-reader-frames.md) **讀者定位：缺經驗的專業人士、不是外行人**：技術教材的讀者是在特定領域缺乏經驗的專業人士，不是完全不懂的外行人。寫法是補足經驗缺口（直接描述情境與操作需求），不是從零科普（故事線導入、比喻堆疊、宣導語氣）。宣導式語氣（「你可能沒注意到」「把 X 想成 Y」「跑得好好的」）預設讀者無能、降低教材可信度。**這條定位是能力宣稱、不是知識宣稱**——它說讀者有能力理解（研究方法、開發原則、邏輯推導），不說他已經知道這個領域的名詞、原理與縮寫；兩種讀法對同一句話都通順，而只有後一種會授權省略。方向由需求決定：專業讀者要的是每個流程的原因、成本、代價與用詞精準，全部是更多的文字，所以這條原則推向展開。判別問句是**這一處省略，省下的是讀者不需要的字，還是讀者要自己補回來的脈絡**；省略在產物上沒有痕跡（沒補的卡不存在、沒展開的原理不佔行數），所以偵測靠術語分級表與理解取樣、不靠讀稿。詳見 [audience-is-professional-not-layperson](references/principles/audience-is-professional-not-layperson.md)。 **跨專業溝通用情境遞進、不用比喻堆疊**：向非本領域的專業人士（管理層、決策者）解釋技術議題時，減少術語並從簡單情境遞進到複雜情境。比喻傳遞形狀但不傳遞嚴重性、在細節處崩解、且隱含「對方聽不懂」的預設。用決策者熟悉的維度（影響範圍、恢復時間、成本量級）表達。詳見 [cross-expertise-scenario-not-analogy](references/principles/cross-expertise-scenario-not-analogy.md)。 **技術教材內嵌管理層可彙報的資訊**：技術段落旁嵌入成本量級、時程估算、進度指標與決策簽核點（各 1-2 句），讓讀者學完技術做法的同時拿到向上彙報的素材。成本用量級不用精確數、時程用範圍不用單點、進度用可查詢指標。詳見 [management-reportable-info-in-technical-content](references/principles/management-reportable-info-in-technical-content.md)。 **斷言清單要過重建測試、重建不了展開成讀者走查**：條列式斷言（「拆開來看有三個毛病：1、2、3」）是作者走完推導後只輸出結論；判定用重建測試——讀者只憑文中已給的材料能不能自己得出每一條，不能就展開成讀者位置的走查：把讀者放到使用產物的位置、每條斷言換成動作加材料（缺的材料補進文中、那正是清單藏住的缺口）、可重用的檢查方式放在走完之後浮現。摘要位置的條列（前文已推導、條列是回收）與每條自帶證據的清單合規。詳見 [assertion-list-needs-reader-walkthrough](references/principles/assertion-list-needs-reader-walkthrough.md)。 **教學與檢討內容的敘事姿態：寫給帶問題來的讀者**：教學與檢討內容的讀者由搜尋或路由帶來、自帶問題與動機；演講技巧（問句標題、懸念段標、三幕劇遞進、第一人稱事件敘事）服務的是注意力會流失的聽眾，搬進教學內容時代價全部落在資訊結構上——問句標題把檢索錨用來提問、懸念弧把判斷標準壓到文末、個人時間線把可重用的判斷包在一次性經歷裡。標題與段標是承載結論的直述句；檢討內容以客觀條件視角組織（「reviewer 問了 X」改成「若對這個做法問 X 而答不出來、就該重新檢討」）、「來自實際事件」的宣告開頭一句話帶過。**修懸念不是把結論搬到開頭**：灌輸與懸念是同一個缺陷的兩個方向、都讓結論與推導脫節——未經推導的開頭結論摘要（含「觸發場景 / 整理目的 / 本文邊界」欄位組）讀者只能硬記、同樣要抽掉；分工是標題承載結論、開頭承載情境定位、判斷標準在推導走完的位置浮現。判別線是位置：操作型自問句（判斷標準的執行步驟）合規、標題 / 段標 / 結論位的問句是懸念型。這類問題是生成端高頻預設、審查是逆風、防線主力在生產側。詳見 [write-for-readers-not-audiences](references/principles/write-for-readers-not-audiences.md)。 **敘事的解碼材料要在讀者已讀的文本裡**：教學敘事的每一句、解碼所需的材料必須已經在讀者手上——已讀過的正文加基線知識；動用讀者還沒讀到的後文、或只存在於作者腦中的全篇地圖，是把作者側的成本轉嫁給讀者。作者寫敘事時持有全篇地圖、文學化壓縮（位置與數量指涉「前兩本 / 另外幾個 / 後者 / 這一側」、轉喻代替命名、單邊對比、把操作結論留給讀者推、抽象名詞當解釋句主詞、破折號懸念）全部預設讀者共享這張地圖——書評體的密度審美混入教學語域、代價落在資訊結構。判定問句逐句可執行：「讀者線性首讀讀到這一句、能不能當場復原完整命題（指涉對象、對比兩面、操作含義）」。修法：指涉具名（首次全名；位置與數量是排列的 derivation、實例中連作者自己都數錯——同一篇三次計數三次全錯）、對比補全另一面、結論寫到讀者能決定下一步動作的層級、具體實體當主詞（框架欄位名起句當主詞是高頻形態——「X 的前提是…」改成被描述的實體當主詞、欄位對應由內容自己承載）、並列定義各自成段、旁註移到主線走完後。位置指涉的極端形態是跨頁指涉（「該篇的起點條目」——綁定在另一份文件裡、讀完本篇也解不開）。展開的價格依反模式類型分層：具名替換是代換不加字、補全對比與隱式結論才花字數——實測導言多兩成、全篇只多百分之五，最高頻的違規恰好是最便宜的修法。命中是候選不是判決：向後近距回指、下半句立即揭曉的破折號、「」內引用合規、判定只看解碼材料（綁定）在不在已讀文本裡——同一個角色詞可以在定義它的篇內合法、在跨頁處違規。詳見 [decodable-from-text-already-read](references/principles/decodable-from-text-already-read.md)。 **文章的連貫靠鞏固形狀、不靠讀者的記憶**：讀者的工作記憶要當成隨時會清空的（設計條件取自 ADHD 讀者——注意力隨時中斷、無法被要求記住任何東西；而任何讀者被打斷、隔天續讀或從搜尋落在中段時，持有的脈絡與之相同），脈絡必須能從任一節點就地重建。做法是每個結構單位攜帶它與其他單位的**內容關係**（誰給定義、誰在同一個問題上走不同邏輯、誰承接誰留下的問題），讀者從任一切面推得出其他切面。四種把脈絡寄存在讀者記憶裡的形態：前向懸置（「等下再討論」是沒有內容的欠條）、位置回指（「前面兩個小節」要讀者持有位置地圖）、壓縮總結（「用一句話總結」把形狀推遲到文末補交）、列舉鳥瞰（「分成兩組、第一組四本講……」要讀者 hold 整張清單才能繼續、注意力在列舉途中斷掉的讀者帶走的是零）。修法是關係鏈（成員逐個以它與前一個成員的內容關係進場、工作記憶負擔恆為一）加錨點路由（關係詞旁掛連結、找回情境的成本是一次點擊）；帶內容名的前向路由合法——判定看指涉攜帶什麼：只有位置或時間違規、攜帶內容名是路由。這不是前情提要：重複讓文章變長而形狀不變清楚，鞏固動的是指涉的載體、多數是代換不加字。連不進關係網的段落是拆分訊號：對立與獨立都是關係，說不出任何內容關係的段落考慮獨立成篇、不硬寫轉場句黏合。割裂對作者與同源 reviewer 不可見（能力強的讀者自動補完形狀），驗收可以用不會補完的讀者——探針從中段讀起、問「這一節跟前後是什麼關係」。詳見 [coherence-by-shape-not-reader-memory](references/principles/coherence-by-shape-not-reader-memory.md)。 **連貫靠句句推進、回收語只暴露斷點**：形狀層的配套句層原則——前句的成果是後句的條件、句句朝同一個方向，逐句判斷標準是「這一句要求讀者往前走還是回頭」。五類要刪的字：回收式過場（「立場站定、量尺在手」——把剛讀完的內容摘一次當跳板，需要跳板的位置就是上一句沒接好的位置，修法是把承接改寫成推進「釐清 X 之後還需要 Y」、不是把跳板寫漂亮）、懸念否定（「仍然沒有答案——」）、文章自指（「承接的就是這一段」——讀者在讀主題、不在讀文章怎麼編排自己）、迂迴指代、姿態描述（「質疑的是問題本身」交付的是關係的元資料，把問題寫出來之後對立詞整個省下）。譬喻分兩層判、第一層答完通常就結束：**這個概念在領域裡有沒有現成術語**（標準 / 判斷標準 / 門檻 / 成本 / 邊界）——有就用術語、譬喻不進場（中英文技術文件用的是同一組詞，standard 而不是 the yardstick；譬喻要讀者建一筆對映、術語不用，那筆成本換到的只有畫面感）；沒有術語才問**服役長度**（貫穿全篇的是導航地標、兩三句就拆場的是純成本）。成因是散文審美混入技術語域，實測形態是同一篇裡總覽用術語、專節用譬喻而分裂成兩個名字——掃描要跨全篇對同一個所指、不是逐段看。與用詞搭配的錯配軸正交。總覽段每環只背「關係＋名字」、細節下放專節；連結掛在句中已有的名字上、不為連結另造括號標籤；順序由讀者的問題序驅動、不由素材的來源鏈驅動，推遲項集中句尾、不在論證中途插入推遲宣告。附完整 before / after 對照範例，詳見 [coherence-by-advancing-not-recapping](references/principles/coherence-by-advancing-not-recapping.md)。 **教學內容不預設考核情境**：「說得出 / 答得出 / 講得出」當檢核動詞時、句子預設一個考核情境（有問的人、答案要被說出來給人聽），而教學讀者為吸收知識而來、實際活動是自我評估理解與應用——文章的定位是建立識別能力與應用能力、檢核動詞用那些能力自己的動詞（識讀 / 辨別 / 指認 / 列得出 / 查得出 / 判斷得出 / 對應得出 / 追得出 / 算得出——按被檢核的能力選、一律替換做出新模具）。判定問句：這一句描述的情境裡有沒有真實的問方與言說行為。三類合法保留：場景內真實對話（稽核 / 客服核身 / 會議追問）、協定與查詢語意（DNS 回答查詢——主詞是系統時「答不出」多半該寫「查不出」）、表達載體（名稱 / 註解 / 型別「說」什麼是它的功能）；自查問句合規、要看收尾的「答不出來就 X」。**檢核的出口是時機與路由、不是宣判**：前置檢核三步——需求句陳述前置、主動提醒內容與回顧點（列出會用到什麼、告訴讀者可以去哪裡回顧——檢查的工作由文章做完、不派給讀者；自我評估問句是可選變體不是預設）、對還不熟的讀者給時機定性加路由（先建立概念、再回來讀）；後果句可以存在但不能是段落最後一句、路由才是。這是借來的讀者框架家族第三個成員（聽眾 / 地圖共享者 / 受試者）。詳見 [verify-by-recognition-not-recitation](references/principles/verify-by-recognition-not-recitation.md)。 **寫作除了表達意義，還要設計閱讀的節奏、壓力與引導**：意義正確而閱讀過程沒被設計的文章、每一行都讀得懂、整篇讀下來卻累——負擔在句與句的累積裡。三個設計面：**節奏**（中文單音節、閱讀節奏比多音節拼音文字快；要讀者思考的位置刻意加字延長閱讀時間——「不僅是」寫成「不僅僅是」、「有無」寫成「有或無」；字數是節奏資源不是壓縮目標、精簡義務只在檢索鍵位）、**壓力**（高密度要求理解力、不指稱人事物要求記憶力、兩者相乘成壓迫力；診斷問句：讀到這行時讀者手上有幾個未解決的指涉、上一次喘口氣的句子在幾行前）、**引導**（用到前置概念的位置主動提醒「會用到什麼、可以去哪裡回顧、再回來讀」——檢查的工作由文章做完、不派給讀者；識讀落差用一層層的切入點承接——術語分級 / 概念卡 / 讀者路線；高專業內容也不寫成只有同領域小圈頂尖讀者能讀、語句與段落容易理解跟銜接是底線、深度不因此降）。冷讀審查在「看得懂」之外加兩問：讀起來累不累、卡住的讀者有沒有被接住。詳見 [writing-designs-the-reading-process](references/principles/writing-designs-the-reading-process.md)。 **評價由讀者自己形成、寫作交付材料**：傳達觀點的寫作交付材料（事實、屬性、行為、取捨、後果、推導），評價由讀者用材料自己形成——主觀評價語（優雅 / 出色 / 經典 / 值得 / 紮實）是預先消化的結論、給讀者速成印象、取代讀者形成想法的過程。判定不看準不準：**準確而溫和的評價同樣違規**（形態問題、跟誇飾強度軸正交）；操作測試是「讀者能不能用文中材料檢驗這句話」。修法：問「我看到什麼讓我這樣覺得」、把那個東西寫出來、評價刪掉；角色標籤用功能不用地位。邊界：評鑑文體例外（評價附材料與判斷標準）、推導收尾的結論合法、凍結外部名照抄、機制描述不觸發、註解不鑑賞程式碼。明確立場：讀者的速成期待存在、但不以滿足它為目標。詳見 [readers-form-their-own-judgments](references/principles/readers-form-their-own-judgments.md)。 **檢視註解的最高原則是商業邏輯**：檢視一則註解時第一個評估是它有沒有解釋到這個行為、這個事件、或這個 flag 的商業邏輯——有、才進入文字層的修法；沒有、不修文字、先重新檢討寫它的動機。這一條決定註解該不該存在、其餘原則決定它該怎麼寫、順序顛倒會把力氣花在修一則不該存在的註解的文字上。詳見 `references/writing-code-comments.md` 的最高原則節。 **註解的動機先於註解的文字**：準備寫一則程式碼註解時，先問寫它的動機是「說明這裡在做什麼」還是「怕有人改壞它」。後者不是註解問題——散文型註解不參與執行、改壞的當下不產生任何訊號，而做批次整理與自動化重構的人不會經過那一行。處置是先問那個約束能不能被消除（它通常是某個結構選擇的產物），不能消除才交給會發聲的機制；判斷標準是問這段資訊有沒有對應的斷言（存不存在一條會紅的斷言，不是造不造得出句子），驗證是當場把約束破壞掉、跑測試、把輸出貼出來。詳見 [protective-comment-signals-missing-enforcement](references/principles/protective-comment-signals-missing-enforcement.md)。 **規則要指到一個打得開的東西**：寫會被別人照著執行的文件（規範、手冊、skill、spec、agent 指令）時，每個步驟的可執行性由「照它工作的人第一個動作指得出來嗎」決定、不由它寫得清不清楚決定。三種失效成因不同而後果相同——名字指向不存在的東西（改名後沒跟著改的路徑）、名字從來不是實體（像專有名詞但查無對應檔案的詞）、根本沒指名（步驟寫成形容詞並列，「核心先行、正向陳述、案例補足」）。第三種最難發現，因為前兩種至少有一個錯的名字可以查。這類缺陷通得過任意多輪人工審查，理由是**規則文件的讀者全部自帶答案**：讀的人知道自己打開的是哪個檔，補完發生在讀者那一側而且無聲。判斷標準是一句話——照這一條工作，第一個動作是打開什麼檔、執行什麼指令、叫用哪一個具名的東西；答得出名字就驗它現在還在不在。修法對應形態：名字錯了就換掉並搜全庫的舊名、名字不是實體就換成實體（查無對應實體代表規則要求的東西還不存在，處置是建立它或刪掉規則）、沒指名就把形容詞換成動作加對象。概念層的定位宣告不適用。詳見 [rule-must-point-at-something-openable](references/principles/rule-must-point-at-something-openable.md)。 **教材的脈絡由三件事決定，而三件都靠自審檢查不到**：這一篇在序列裡的位置（說得出讀者手上已經有什麼、交付什麼、刻意不碰什麼；深度看第一項不看題材的表面複雜度）、論證用得到的材料有沒有就地寫進去（承重術語當場定義、承重機制寫進正文、每一句的指涉能從已讀文字解出來）、以及往外的連結綁在什麼上面（綁在本篇模型的一個可動項上——「把其中一項換掉會變成什麼」，而不是「遇到 X 去讀 Y」，也不只是列舉相鄰主題；做不到代表本篇還沒建立帶可動項的模型，而這條推論只適用於模型有兩個以上可動項的教材）。`description` 與第一段決定整篇形狀，所以從要交付的觀念發想、不從假想的讀者問題發想，查閱型內容不受這一條約束。偏移的成因固定是規則錯配——為執行者或查閱型內容設計的規則被套到教材上，而觸發條件只看形狀；一份原則的射程限制放在它自己身上沒有效力，適用邊界要由引用它的規範寫出來。詳見 [teaching-article-context](references/principles/teaching-article-context.md)。 **知識卡建卡標準用「最不熟悉的讀者」**：知識卡的建卡標準是「目標讀者群裡最不熟悉的那端能不能理解這個術語」，不是「作者覺得夠不夠常見」。常識是相對於背景的——.htaccess 對 PHP 工程師是常識、對 Node.js 工程師完全陌生。跨背景讀者群的教材裡，幾乎所有領域特定術語都需要建卡。建卡的邊際成本低（40-50 行）、讀者缺卡的代價高（離開教材去 Google、可能找到不一致的解釋）。per [常識是相對於讀者背景的](references/principles/common-knowledge-is-relative-to-reader-background.md)。 **操作步驟帶環境專屬工具路徑**：操作型文章的每一步至少帶一條工具路徑（用什麼軟體、輸入什麼指令）。同一個動作在不同環境（container / VM / 共享主機）的工具路徑可能完全不同——「拍下現況」在 container 是 `docker commit`、在 VM 是 AMI 快照、在共享主機是 FTP mirror + phpinfo。文章涵蓋多種環境時、每一步要按環境分列工具、或標明適用環境。自測問題：「讀者坐在電腦前，下一個動作是打開什麼軟體？」答不出來就是缺口。per [操作指引要帶環境專屬工具路徑](references/principles/operational-how-needs-environment-specific-tooling.md)。 **Case 引用段落的三段式結構**：三段式是案例引用段落的順序紀律 — 把「概念 → 案例 → 操作」三層分開承擔（段首給概念定義、case 引用居中、通用工程知識展開）、讓段落結構跟讀者學習新概念的認知順序對齊。LLM 從 case 反推內容容易把 case 揭露當概念出發點、實證觀察 11/12 段都犯這個錯。詳見 [case-citation-three-part-structure](references/principles/case-citation-three-part-structure.md)。 **知識目標決定文章結構**：文章寫完後讀者帶走的是判斷能力（面對新情境能自己評估）還是操作步驟（照做能解決特定問題）——兩者需要不同的結構。判斷力導向把機制理解當主線、操作當自然推導的結果；流程導向把步驟當主線。多數教學文章應走判斷力導向——文章的價值在於提供判斷力、這是官方文件不做的事。詳見 [teach-judgment-not-procedure](references/principles/teach-judgment-not-procedure.md)。 **判斷標準寫到條件層**：判斷標準有三個成熟度——口訣（無推導的結論）、維度清單（「判斷看 A / B / C」）、條件映射（「A 成立 → 做 X；A 破 → 切 Y」加失效情境）——教學要交付到第三層。維度清單是判斷標準的空殼：有判斷的動詞、每個維度都有機制支撐、通過字句與機制審查，卻在讀者要做決定的那一刻斷線；且機制重建完成後它仍會殘留（機制正確與判斷標準到位是兩個獨立檢查）。驗收用重算測試：讀者帶自己的參數進來能不能走出行動。條件不可窮舉的決策，用自查問句組（把變數轉成讀者可自答的問題）＋排序規則，同樣算第三層。詳見 [criteria-need-condition-action-mapping](references/principles/criteria-need-condition-action-mapping.md)。 **判斷標準的輸入集合要跟正文的組織維度對齊**：映射的成熟度與輸入的完整性是兩個獨立的檢查——一段判斷標準可以把每個條件都對到明確的行動，而只要讀者帶進來的個案在某個維度上取了作者沒設想的值，整條路就走不到底。最高頻的形態是**只收「表徵」一個輸入，把產生表徵的那個條件從輸入端折疊掉**，即使它在正文裡佔了整整一節（處置句寫著只有某一種執行環境才有的操作名詞，而內容涵蓋的環境不只那一種）。便宜的自查指標是分支數與種類數的落差：分支數少於正文自己列出的種類數時，就有種類落在所有分支之外。作者看不見它，因為讀的人自帶那個被折疊的條件；驗收要拿具體個案走一遍、而個案要刻意挑落在那些種類上的。詳見 [criteria-fold-away-the-condition-that-produces-the-symptom](references/principles/criteria-fold-away-the-condition-that-produces-the-symptom.md)。 **教學模組要有推導源頭**：分析導向的教學模組（判斷標準密集、讀者要帶走判斷力），模組級結構要是推導體系、不是主題集合——一個源頭機制（成本結構 / 約束 / 生命週期，各篇判斷標準能折算回去的基準）、每篇承擔一條展開、模組入口能一句話說出推導起點。源頭買到：判斷標準同尺、跨篇矛盾現形、擴篇有掛載點、推導式閱讀路線成立。目錄型模組與異質 case 記錄不適用；源頭是折算基準、不是開場模板。詳見 [teaching-module-needs-derivation-anchor](references/principles/teaching-module-needs-derivation-anchor.md) 與 `references/managing-article-collections.md` 的對應段。 **深度的分配不看主題的表面複雜度**：判斷一段要寫多詳細時用「讀者讀到這裡手上有什麼」，而不是這個主題看起來簡不簡單。基本處讀者手上的既有結構最少、作者的熟悉度最高，兩邊的需求剛好反向，所以用熟悉度當訊號必然分配錯——而陷阱聚集在基本處有結構上的原因：基本語法用得最頻繁，同一個誤解在每次使用裡重複，且失效多半是靜默的（實作為相容性接受寬鬆寫法，寬鬆的那一版還能算出看起來合理的值）。**「難」與「危險」是兩個不同的軸。** 同一條也管進階議題的起點——推導從底下的基本機制開始、複雜需求留成案例，驗收用一句話測試（這個起點能不能在不預設本模組任何內容的前提下說完）。詳見 [basics-anchor-the-advanced](references/principles/basics-anchor-the-advanced.md)。 **複合問題先拆機制再談交互**：問題由多個概念交互導致時、先各自教 A / B / C 的機制、再談 A×B×C 交互。讀者理解各元件後交互作用是自然推導的。各概念獨立成篇、文章之間用連結而非重複來串接。判讀訊號是文章裡出現「另外還有一個原因是...」的堆疊式展開。詳見 [compound-problem-decompose-then-interact](references/principles/compound-problem-decompose-then-interact.md)。 **原子筆記要有向上的議題入口**：承載知識的原子筆記（Zettelkasten 卡 / glossary / 術語條目）不是字典條目 — 字典答「這個詞是什麼」、承載知識答「你在討論什麼、撞到什麼問題、才需要這知識」。撰寫者有預設情境讀者沒有、所以每張卡（或其上層）要從情境進入而非劈頭給定義：建議題 hub（以讀者遇到的問題為題）討論再分流到原子卡、卡頂回指議題、讓搜尋直接落地者也有回路。沒這層卡淪字典、讀者沒有觸發點、不知何時用。詳見 [atomic-note-needs-situational-entry](references/principles/atomic-note-needs-situational-entry.md)。 **軸名要取機制、不要取它的代理**：替一組判斷標準或一條分界軸命名時，選中的常常是與機制同向但較弱的代理（用途之於性質、識別碼之於預設行為），而真正在做功的那句話留在括號或下一句的理由裡。代理與機制分岔的情況正是判斷標準要處理的難題，於是判斷標準在最需要它的地方失效；作者看不見是因為讀到軸名時腦中自動補上機制，而讀者只拿得到名字。修法是把括號裡那句升格成軸名、代理降級成入口。判讀訊號：同一份內容的兩處把同一個東西歸到軸的兩側、套到具體個案時分不開、或一個名詞底下的東西成本差一個量級（複合名詞蓋住不同性質的形態）。字句與結構層審查都抓不到它，只有對抗性審查與個案實跑抓得到。詳見 [axis-named-by-proxy-not-mechanism](references/principles/axis-named-by-proxy-not-mechanism.md) ### 4. 可查詢性（Searchability） 關鍵字前置、使用可 grep 的分隔符（`:` `|` `→` `==`）、欄位名稱使用 regex 友善格式。命名讓 AI 能以單次 grep 命中，不需要語意推理。 **行自足是可查詢性的配套義務**：grep-friendly 設計預期句子被單獨命中、被命中的句子就要單獨讀得懂。單句消費位（checklist 項、表格格、判斷標準句、grep 目標行、章節首句）必須在句內資訊自足——四條件：命題完整（主詞 / 謂語 / 對象 / 條件在場）、指涉閉合（殘片名詞有完整形先行）、實詞可反推（承載內容的詞能反推到機制 / 條件 / 契約）、一句一命題（對仗的每個半句能獨立判真）；驗收用抽離重讀測試（句子單獨給沒讀過上下文的消費者、命題能不能無歧義復原）。第三類位置是檢索鍵位（title / description / 表格鍵欄 / 卡名）——義務是識別充足、命題完整不適用、跟精簡規範衝突時精簡優先。段落敘事位可依賴鄰句、壓縮合法——三角取捨（精準、總長、句自足）的解法是按消費單位分配：自足要補成分、精準要加限定語與名詞頭、兩者都與精簡的減字反向、全域加長跟全域壓縮都是錯的答案。中文單字多義與 LLM 的三種消費模式（單行檢索 / attention 稀釋 / 風格繼承）是放大條件；四字節奏與對仗是「該跑抽離重讀」的候選訊號、不是判決（判定看消費單位）。詳見 [sentence-self-sufficiency-by-consumption-unit](references/principles/sentence-self-sufficiency-by-consumption-unit.md) 與 `references/reference-authoring-standards.md` 的單句消費位段。 ### 5. 欄位設計（Field Design） 同一份文件的不同欄位，從不同角度觀察同一件事，不重複撰寫。`what` 描述動作、`why` 陳述動機、`acceptance` 定義可驗證條件；混淆欄位會讓讀者在多處讀到相同內容。 ### 6. 多輪 Re-read Pass（Multi-pass Review） 完稿即進入 review 階段。一次寫對全部維度違反 working memory、實際結果是「每維度都做一半」。設計 N 輪 re-read、每輪用不同 frame： | 輪 | Frame | 抓什麼 | | --- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | 1 | 生成 | idea → 字、預期會有錯 | | 2 | 對意圖（[ease-of-writing-vs-intent-alignment](references/principles/ease-of-writing-vs-intent-alignment.md)） | 正文、title、description、MOC hook 都跟原意對齊 | | 3 | 機會成本語氣 | 全 surface 的絕對詞翻成 trade-off | | 4 | Grep-ability / 命名 / 術語 | title、slug、link label、段首關鍵字可單次 grep 命中；術語保留原文錨點與完整名詞頭 | | 5 | 反例 / 邊界 | 「何時不適用」段、反模式列表 | Surface enumeration 是 multi-pass 的固定前置步驟。寫作產物包含 body surface 與 metadata / navigation surface：`title`、`description`、`tags`、heading、link label、MOC / index entry、slug / filename。每輪 frame 都掃這份 surface 清單，讓正文與讀者入口共用同一個概念錨點。description / hook 對規則做壓縮時、**可以丟細節、不可以改模態** — 把本體的「條件允許（可延後但要記錄）」壓成「絕對禁止（不可跳過）」、讀者依摘要行動就會偏離本體；摘要讀起來比本體「更有力、更乾脆」就是失真訊號、模態詞跟主詞動詞同級、最後砍。實測一批七份文件有四份的 description 出現模態漂移 — 這個檢查每批都要跑。 **核心**：「再仔細一次」≠ multi-pass — 同 frame 重看 catch 不到新問題。每輪換 frame、才能 catch 不同層。各 reference（writing-articles / writing-code-comments / writing-documents / writing-prompts）依 output 類型有特化的輪次組合。 Naming 是這條原則最容易跳的子場景 — 第一版命名幾乎不對、四輪 review（第一版 / grep / cross-call-site / impl 洩漏）才收斂、見 [naming-as-iterated-artifact](references/principles/naming-as-iterated-artifact.md) 跟 writing-code-comments 的 naming review 段。術語是 naming 的高歧義子場景：翻譯術語第一次出現保留原文錨點，中文壓縮術語保留完整名詞頭，中文名詞頭要保留來源中的概念角色，轉換他人材料時強度詞停在原文量級（保真轉換鎖定量級、原創文案與宣告過的再創作以訴求效果為準），見 [terminology-keeps-original-anchor](references/principles/terminology-keeps-original-anchor.md)、[compressed-chinese-terms-need-head-noun](references/principles/compressed-chinese-terms-need-head-noun.md)、[translation-must-preserve-concept-role](references/principles/translation-must-preserve-concept-role.md) 與 [rewrite-preserves-claim-intensity](references/principles/rewrite-preserves-claim-intensity.md)。 **高 stakes 內容追加輪 E（epistemic rigor、conditional opt-in）**：reader 照做後錯誤不可逆的內容（資安 / concurrency 正確性 / distributed consistency / financial / medical）在 5 輪基本 frame 之外、追加 stakes 軸的 epistemic rigor pass——比照學術 peer review 跑 claim / evidence / method / threats / citation 五個 sub-check、加上 audit recommendation tier（accept / minor / major / withdraw）。一般內容 5 輪夠、不跑輪 E；高 stakes 內容兩軸都跑。詳見 `references/auditing-articles.md` 跟 `references/principles/writing-multi-pass-review.md` 的「stakes-conditional 追加輪」段。 **Production 教學文章追加輪 8-10（字句層 catch、跑 N 輪仍漏時觸發）**：跑了 5 輪基本 frame 仍系統性漏 catch 字句層問題（口語修辭 / 廢話前綴 / 地區漂移 / 依賴 code / **裝飾符號 emoji** / 對讀者喊話 / 自評誇飾 / 必然性框架 / 恐嚇式語氣 / 歸因語氣）時、追加三個換軸機制——輪 8 keyword bank（換工具、含 emoji / 裝飾 unicode 掃描）、輪 9 reader simulation（換視角、四 lens：自包含性 + register/stance + meta 殘留 + AI 歸因過度）、輪 10 self-criticism（換層次、審視 framework 本身覆蓋度）。短文 / 即時 note 不需要、production 教學文章在跑 5 輪後仍漏同類問題時 opt-in。**keyword bank 命中是候選、不是判決**——grep 命中後仍要一個語意判定步驟（這個命中是建立概念的違規、還是合規的反例對照 / hook），reviewer 容易把違規合理化放行；偵測（bank）跟判定（語意）是兩個認知步驟。**register/stance 類（喊話 / 誇飾 / 必然）無穩定關鍵詞、keyword bank 抓不到、輪 9 reader-sim 是主 keyword bank 是輔、且最依賴 external cold-read**。漏抓後補機制前先分 **design gap**（框架缺 frame、改框架）vs **execution gap**（框架有 frame 但只跑了臨時子集、改執行不是改框架）——「加 keyword」對 execution gap 跟無關鍵詞的類都無效。詳見 [multi-pass-review-frame-granularity](references/principles/multi-pass-review-frame-granularity.md)、[decorative-symbols-keyword-bank](references/principles/decorative-symbols-keyword-bank.md)、[teaching-prose-neutral-register](references/principles/teaching-prose-neutral-register.md) 跟 `references/writing-articles.md` 輪 8-10 段。 **批量 sibling 寫作的生成端輪替**：一次寫多份同類文件時、cadence 同質化會在六個層發生（title 形式 / 開場句式 / 章節標題 / 敘事骨架 / 條目形態 / 跨檔引用句）、單份 review 全部抓不到、且 review 端抓過的同骨會在下一批復發 — 同類 finding 第二次出現、就把規則升到生成端：寫之前排好開場 frame 輪替（規則先行 / 後果先行 / 動作先行 / 反差先行）、條目形態輪替、敘事視角輪替、引用句去重。詳見 [cadence-homogenization](references/principles/cadence-homogenization.md)。 **Instance 軸：跨 reviewer instance 隔離**：Instance 軸是 multi-pass review 的另一條擴展軸 — N 個獨立 reviewer instance 各自獨立 context、各自跑 background、解「單一 reviewer 同時看多維度容易維度盲點 + context 污染」的問題。Instance 指獨立 reviewer 程式實體（如 agent tool spawn 出的 subagent）、跟同一 reviewer 換輪次 frame（frame 軸）正交可疊加。適用 production 教學文章 / 高 stakes 內容 / 跨章節教學模組這類維度複雜度高的審查場景。詳見 [agent-team-context-isolation](references/principles/agent-team-context-isolation.md)。 詳見 [Writing 的 multi-pass review](references/principles/writing-multi-pass-review.md)、[Methodology 的 multi-pass 該 embed 在 pillar](references/principles/methodology-multi-pass-embedding.md)、[Metadata surface 要納入寫作 review 範圍](references/principles/metadata-surface-in-writing-review.md)、[False sense of security 是高 stakes 寫作的主要失敗模式](references/principles/false-sense-of-security-as-primary-failure.md)、[Risk-asymmetric audit standard](references/principles/risk-asymmetric-audit-standard.md)、[colloquial-rhetoric-erodes-technical-precision](references/principles/colloquial-rhetoric-erodes-technical-precision.md)、[prose-self-contained-without-code-reference](references/principles/prose-self-contained-without-code-reference.md)、[regional-terminology-alignment](references/principles/regional-terminology-alignment.md)、[multi-pass-review-frame-granularity](references/principles/multi-pass-review-frame-granularity.md)、[design-flaw-by-current-axes-not-hindsight](references/principles/design-flaw-by-current-axes-not-hindsight.md)、[agent-team-context-isolation](references/principles/agent-team-context-isolation.md)、[decorative-symbols-keyword-bank](references/principles/decorative-symbols-keyword-bank.md)、[teaching-prose-neutral-register](references/principles/teaching-prose-neutral-register.md)。 --- ## When to Consult This Skill（觸發路由） | 觸發情境 | 讀哪份 reference | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | 要寫或改一段程式碼註解 / doc comment | `references/writing-code-comments.md` | | 要起草 / 改寫一份文件（worklog、spec、README） | `references/writing-documents.md` | | 要設計 log / 錯誤訊息 / 結構化輸出 | `references/writing-logs.md` | | 要撰寫給 AI 的 prompt / instruction / Agent 派發 / Ticket Context Bundle | `references/writing-prompts.md`（為 `.claude/rules/core/ai-communication-rules.md` 的詳細版庫，portability-allow） | | 要撰寫完整長篇技術文章（blog post / post-mortem / 架構決策 / 除錯復盤 / 技術評估） | `references/writing-articles.md` | | 要把外部分析文章 / 產業評論 / 投資人備忘錄 / 高密度研究材料轉成教學型分析文章，把從業者經驗談（訪談 / 社群貼文 / 口述）轉成分析教學（機制重建），或把 AI 改寫稿從摘要升級成可遷移框架 | `references/source-to-teaching-analysis.md` | | 要翻譯 / 轉譯文章、把英文材料改寫成中文、檢查術語誤譯、中文譯名放回句子後是否成立、或譯文有沒有超譯（強度被拉高成口號） | `references/translation-review.md` | | 要管理多篇相關文章的結構（系列、文集、知識庫、素材庫比例、MOC、跨篇引用、何時抽抽象層 / Pattern 卡片） | `references/managing-article-collections.md` | | 要做文章 / 模組 / 系列的結構決策（該不該拆篇、擴充點設計、方法論與案例的依賴方向、多讀者分流）、或用結構原則 review 既有文集 | `references/structuring-with-solid.md` | | 要對既有高 stakes 內容（資安 / concurrency / distributed / financial / medical）做 reviewer-style audit、找 false sense of security / 對位失效 / context 缺 / citation 過時 / 強度失準（誇飾或降格） | `references/auditing-articles.md` | | 要寫或檢查判讀 / 選型 / 決策類內容（回答「該怎麼判斷」那一層），或讀者提問「什麼情況會需要這個」「什麼樣的系統會這樣做」「沒有範例看不懂」 | `references/judgment-content-needs-scenarios.md` | | 要設計 ticket 欄位 / schema frontmatter / 表單欄位 | `references/designing-fields.md` | | 想驗證寫作品質（認知負擔、獨立理解率） | `references/meta-metrics.md` | | 要新增或修改一份 Skill reference（撰寫品質規範、結構標準） | `references/reference-authoring-standards.md` | | 要驗收 Skill 發布品質（語意層驗收、Phase 2 dry-run） | `references/dry-run-guide.md` | 每份 reference 自包含：以該情境為核心，把核心原則翻譯成可直接套用的檢查項與範例。閱讀任一 reference 不需要回來看其他 reference。 --- ## Success Criteria（M1-M2 認知負擔類） | Metric | 定義 | 目標 | | ----------------------------- | ----------------------------------------------------- | ---- | | **M1 — 找到答案路徑** | 讀者從 SKILL.md 出發，需要開啟幾個檔案才能解決問題 | ≤ 2 | | **M2 — reference 獨立理解率** | 隨機挑一份 reference，不讀其他 reference 能否獨立套用 | 100% | 詳細量測方式與自評表見 `references/meta-metrics.md`。M3-M5（token 類）保留未定，待實際範例累積後補足。 --- ## 跟特化寫作流程的分工 本 skill 是 *單篇* 寫作的基礎方法、覆蓋 articles / comments / logs / prompts / fields 等 surface。當寫作對象是 *跨多章節的教學模組*（5+ 章、有案例庫支撐、跨章引用密集）、屬特化情境、有專屬的 *跨章節生產流程*：案例庫 audit 抽 findings、SSoT 對應規劃、agent team 平行 review、跨檔修正循環、跨章 polish pass。 兩類流程的分工： | 流程 | 適用 | 核心紀律 | | ------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **本 skill（compositional-writing）** | 單篇文字（articles / comments / logs / prompts / fields） | 6 原則（原子化 / 索引 / 意圖顯性 / 可查詢 / 欄位 / 多輪 review）+ 各 surface 特化 reference | | 跨章節教學模組生產流程 | 跨 5+ 章、有 case 庫的教學模組 | case-first 流程：案例 audit → 基於 findings 寫稿 → agent team 平行 review → 修正循環 → polish pass、加 case 引用四 axis 紀律（深度 / 分層 / 合成 / 結構） | 兩類流程互補疊加 — 教學模組的每章內部寫作仍套本 skill 6 原則、case 引用段落用 [case-citation-three-part-structure](references/principles/case-citation-three-part-structure.md)、agent team review 用 [agent-team-context-isolation](references/principles/agent-team-context-isolation.md)。當下游專案沒有跨章節教學模組需求、本 skill 即可獨立運作；當有需求、教學模組生產流程是本 skill 的擴展層、不取代本 skill。 ## 字句層 keyword bank（完整清單） **這一節是本站字句層檢查的唯一權威清單。** 其他地方（本檔的 frontmatter description、multi-round-review 的 Round 1-A、專案規範）出現的枚舉都是摘要，數量與成員以這一節為準。做字句層審查時打開這一節逐類跑，不要憑記憶重編 pattern——重編版通常把不同類別的詞混進同一條 regex，命中之後無法判定是哪一類違規。 寫多篇章節 / report 卡 / knowledge card 後做**多輪 agent reviewer audit** 時、本 skill 應該跟 multi-round-review skill 同時啟動。觸發詞「多輪審查 / Round 1/2/3 / batch review / 寫作 audit」會同時啟動兩個 skill： - **multi-round-review** 規劃 frame 切換結構（Round 1 compliance / Round 2 cadence / Round 3 self-application）跟跨輪 finding 整合工作流 - **本 skill（compositional-writing）** 提供每輪 frame 的字句層 keyword bank — Round 1-A 寫作規範 reviewer 必須跑： - **正向陳述優先 grep**：`rg "不[行可是要能該支對符夠必]|無法|沒[做有]|而非|而不是"`、加上**否定起手定義句**（原 pattern 漏「而是」、抓不到「不是 X、而是 Y」的後半）：`rg "不是.{0,30}而是|不是.{0,20}、是|不是.{0,25}，\s*是|與其.{0,20}不如|不只.{0,15}更"` — 主要敘述要正向、反例對照的少量負向可保留；判別在「核心概念第一次正面出現在句首、還是被擠到『而是』之後」。**合規邊界**：糾正已文件化誤讀的「不是 A、而是 B」仍列可改——修法保留糾正語意（例如改寫成「條件是 B；A 不是判斷條件」），概念前置不因糾正目的豁免 - **口語修辭 grep**：`rg "其實|實務上|真的|碰巧|立刻撞牆|沒事"` - **地區用語 grep**：單詞層 `rg "集群|默認|質量|視頻|函數|文件夾|接口"`（封閉集合、掃得到）；慣用語層 `rg "拍腦袋|拍板|靠譜|給力|接地氣|一波|死磕|躺平|內卷"`（已知個案、**非窮舉**——慣用語是開放集合、grep 追不完、新個案要靠目標地區讀者冷讀，同源 reviewer 回報「地區用語 clean」對慣用語層不可當真，見 [`regional-idioms-evade-keyword-bank`](references/principles/regional-idioms-evade-keyword-bank.md)） - **廢話前綴 grep**：`rg "值得注意的是|需要說明的是|實際上|基本上|事實上"` - **裝飾符號 grep**：`rg "✅|❌|⚠️|🚨|🟡|🟢|⭐|📌|✓|✗"` - **對讀者喊話 grep**：`rg "很多人|大家|不少人|你的|你在|你把|你正在|你補|你天天|你會|你可能|先讀懂|先釐清|別搞混|別被"`（**裸「你」非窮舉**：實測過 `你正在`、`你補完` 這類「你 + 一般動詞」逃過原 pattern，回報 clean 前另跑一次裸 `rg "你"` 逐處判定） — 教材中性陳述、不安撫情緒 / 不第二人稱代入 / 不祈使控制閱讀（hook / narrative 段落輕度第二人稱可留）。**裸所有格 / 主詞（你的 X / 你在 X）也算、不限「你 + 動詞」的祈使 / 預測句型**；grep 對裸『你』非窮舉、真防線是 reader-simulation 冷讀（同源 grep 抓不到 register、見 [multi-pass-review-frame-granularity](references/principles/multi-pass-review-frame-granularity.md)） - **自評誇飾 grep**：`rg "教科書級|堪稱|可謂|完美|經典|範本級|大師級|漂亮地|優雅地|最佳實踐|best practice"` — 品質 verdict 頂替技術理由、換成機制 / 條件；命中後的合法性判定用位置功能兩軸（文體契約 × 行動耦合）——hook 段的強度合法、判斷標準段零容忍、判定前先定位、見 [hyperbole-legitimacy-by-position-function](references/principles/hyperbole-legitimacy-by-position-function.md) - **必然性框架 grep**：`rg "天生|與生俱來|本質就是|本來就是|必然|唯一|註定|理所當然"` — 把設計選擇講成自然法則、還原成條件性（物理 / 法律 / 數學事實除外）。**合規邊界**：SSOT／權威住址／裁決陳述中的「唯一」（如「唯一權威定義」「唯一標準指令」）與由機制定義直接蘊涵的「必然」（如「A 與 B 必然分屬兩個 commit」）合規；違規限把可變的設計選擇講成自然法則，改寫成條件句反而會失去 SSOT 語意 - **澄清式框架 grep**：`rg "最容易誤|容易誤判|常見的?誤判|要點破|直覺會?帶偏|抵抗.*的直覺|你以為|會困惑|值得記"` — 把「讀者會誤解」當敘事中心是知識缺口訊號、不是澄清時機；補正向模型與機制讓誤解無從發生、不提醒讀者一個他本不需要有的困惑。界線是具體第一人稱實測敘事跟真實診斷區分（逾時 vs 被拒、症狀層 vs 根因層）保留、只有把假想誤會當主題句起手的才改；同義變體多、grep 抓不全、靠 reader-simulation 語意判定（「這段在補正向知識、還是在提醒讀者會犯錯？」）。見 [fill-knowledge-gap-not-center-misconception](references/principles/fill-knowledge-gap-not-center-misconception.md) - **歸因語氣 grep**：`rg "承認|暴露了|證明了失敗|被迫"` — 描述系統行為用「信號」「反映」「顯示」等中性觀測詞、避免「承認」「暴露」等責任歸因詞；「被迫」在描述外部強制約束時可保留。**合規邊界**：「承認」的主詞是規範／文件對實作的認可（非人對過失的認錯）時合規 - **宣導語氣 grep**：`rg "你可能沒注意|你可能不知道|想像一下|把.{1,5}想成|跑得好好的|聽起來很|其實很簡單|說穿了就是|等於拆未爆彈|乾瞪眼|延遲引爆"` — 預設讀者無知或用情緒管理取代事實陳述；讀者是專業人士、直接描述情境與後果 - **泛用詞濫用 grep**：`rg "坑|東西|搞|弄|處理一下|情況"` — 同一個泛用詞蓋過不同具體情境時、依情境換精確詞（意外 / 陷阱 / 出問題 / 發生狀況）；命中密集且各指不同事才算違規、真泛指 / 引號引用 / 輕度 hook 合規；「坑」另有地區偏移面（某些地區高頻、某些少用）。**合規邊界**：「視情況」「預設情況下」為固定搭配，不計入「情況」命中。見 [avoid-overused-generic-words](references/principles/avoid-overused-generic-words.md) - **位置與集合指涉 grep**：`rg "前者|後者|前兩[本篇章個]|另外[一二三四五兩][本篇個章條張]|其他[一二三四五兩][本篇個章條張]|其餘[一二三四五兩][本篇個章條張]|下一[本篇章節]|上一[本篇章節]|這一側|那一側"` — 解碼材料要在讀者已讀的文本裡：位置與數量是作者腦中地圖的 derivation、連作者自己都常數錯（實測同一篇三次計數三次全錯）；**集合指涉即使計數正確也要給成員或方向**——數字只證明數過、不承載意義，成員各自的方向才是讀者要用的資訊。命中是候選——緊鄰具名清單的行內計數、全稱比較（宣稱對全體成立、方向不參與意義）、已具名集合的向後回指、時間距離的遠指（「那個年代」）都合規；判定看綁定在不在已讀文本、命中時順手驗計數。集合成員多到列不動是分類規劃要拆的訊號、不是省略的授權。見 [decodable-from-text-already-read](references/principles/decodable-from-text-already-read.md)。**這條 pattern 的成員是從論述型內容歸納的，換體裁要重做形態盤點**——清單型內容（書單、工具比較、選型表）的結構單位是「一篇裡的一組並列成員」，指涉因此走序數，主流形態是 `前一本|下一本|上一本|本篇第[一二三四五六]本|上述[兩三四]本|前面幾本|第[一二三四五六]本`，跟論述文的「前者 / 後者」沒有交集。一次實測：論述文那組 pattern 在一批書單上回傳 86 個命中而逐處判定全部合規，該體裁的三十處違規一個都不在裡面，修完之後命中數只動一。判斷標準見 [keyword-pattern-does-not-transfer-across-genres](references/principles/keyword-pattern-does-not-transfer-across-genres.md) - **脈絡懸置 grep**：`rg "等下再|稍後再|之後會(講|談|提到)|後面會(提到|講|說明)|下面會(提到|講)|如前所述|前面(提過|說過|講過|幾個小節|兩個小節)|上[一面](提到|說過)|用一句話(總結|概括)|一言以蔽之"` — 把脈絡寄存在讀者工作記憶裡的三種句式：前向懸置（「等下再討論」是沒有內容的欠條、到期時讀者已不記得）、位置回指（「前面兩個小節」要讀者持有位置地圖、中斷後的讀者不持有）、壓縮總結（「用一句話總結」把形狀推遲到文末補交）。判定看指涉攜帶什麼——只有位置或時間違規、攜帶內容名（最好再帶連結）是合法路由（「那正是 C 那本要處理的問題」）；緊鄰的近距指涉（「見下表」而表在下一行）、「」內引用、已具名對象的向後回指合規。同類的結構層形態**列舉鳥瞰**（「分成兩組、第一組四本講……」）grep 候選 `rg "分成[兩三四五]組|第[一二三四]組"`、要讀者 hold 整張清單才能繼續讀，修法是關係鏈——成員逐個以它與前一個成員的內容關係進場；緊鄰表格或清單且各成員隨即具名展開的合規。見 [coherence-by-shape-not-reader-memory](references/principles/coherence-by-shape-not-reader-memory.md) - **敘事姿態 grep**：問句標題 `rg "^title:.*[？?]"`、問句段標 `rg "^#{2,} .*[？?]"`、敘事轉折詞 `rg "才想清楚|還是被退|我到底|我於是"`、輔助訊號是檢討類文章的「我」密度顯著高於同類其他篇 — 教學與檢討內容寫給帶問題來的讀者、標題承載結論、判斷標準由推導交付（不設懸念、也不把結論抽到開頭灌輸）、檢討用客觀條件視角；操作型自問句（判斷標準的執行步驟）與「」內引用合規、標題 / 段標 / 結論位扣住答案的問句違規、未經推導的開頭結論摘要與欄位組同屬違規；這類是生成端高頻預設、審查是補位、防線主力在生產側規範與模板。**虛構經驗軸（AI 生成內容）**：第一人稱複數經驗宣稱 `rg "我們團隊|我們的團隊|我們公司|我們曾|我當時"` 與精確出處宣稱（「第 N 頁寫道」+ 引號引文）預設待驗——經驗宣稱是證據宣稱、虛構是造假不是修辭；先判定事件存不存在、再改姿態（順序反了會把虛構藏進條件視角）；引文逐字核對、出處只寫到驗證過的層級；真實事件的工作紀錄與「」內他人自述合規。**grep 只覆蓋三個掃描面裡的一面**：虛構的人更常以第三人稱出現（PM / reviewer / 同事 / 新人 / 團隊士氣），沒有穩定關鍵詞、靠逐篇讀開場，而動機句常掛在這些角色身上；**判定單位是生成批次不是關鍵字命中**——一篇被判定虛構之後用版本歷史查同批（同 commit / 同日期 / 同模板）整批逐篇驗，清單清空不等於批次清空（一次實測：關鍵字命中 6 篇、實際同批 31 篇）。見 [no-fabricated-experience-or-attribution](references/principles/no-fabricated-experience-or-attribution.md) 與 [write-for-readers-not-audiences](references/principles/write-for-readers-not-audiences.md) - **用詞搭配錯位 grep**：`rg "說完的話|背後.{0,8}的話|想告訴|潛台詞|訊號很直接|訊號.{0,4}很直接"` — 把抽象概念（角度 / 框架 / 訊號 / 數字）配上不貼合屬性的謂語：擬人化錯配（角度不會「說」、數字不會「想告訴」）與形容詞錯配（訊號的可辨識度是「清晰 / 明確」不是「直接」）。無穩定關鍵詞、grep 只抓已知形態、真防線是異源冷讀（跟 register 類同屬同源盲區）。見 [word-choice-fits-concept-attributes](references/principles/word-choice-fits-concept-attributes.md) - **物理化錯配 grep（同一張卡四種錯配裡唯一有一組高密度關鍵詞可掃的）**：`rg "撐得住|撐不住|撐得起|撐不起|能撐|撐住|撐起|撐不久|站得住|站不住|站得起|站不起|掛在|扛|垮|頂得住|咬得|咬合|啃"` — 抽象概念（證據、論證、結論、判斷標準、方法、責任）配上承重、支撐、懸掛類的動詞。證據跟結論之間沒有重量、沒有支點、沒有材料強度，那些動詞不帶進資訊，只是把讀者對物理世界的直覺借過來蓋住實際的關係。**判斷標準可機械執行**：問這個動詞照字面成立需要什麼物理條件——需要重量、支點、材料強度、上下方位的就是借來的。替換：證據**支持**結論、論證**依賴**前提、資料**佐證**、方法**維持不久**、責任由某人**負責**。這一種還有一層特殊危害——「撐得住」聽起來已經像答案，於是「支持什麼、到什麼範圍」不必被回答，是繞過而不只是說錯。**例外**：明示並就地展開成可逐項對應的類比（物理意象在同一段被對回真實機制）合規；沒展開的就是借詞。主詞是真實物體或系統負載時不觸發（一次全站實測：716 個命中行只有 68 個是違規，「拖垮 OLTP」「route table 掛在 subnet」都合規）。**這串清單是抽樣、不是這一類的全部**——能進清單的只有違規義項佔該詞用法多數的詞，而本義合法的直譯（「滑坡」的本義是山崩，違規的只有 slippery slope 借來的義項；「下滑 / 滑落 / 滑向某個狀態」合規）與詞頻過高的泛用動詞（「拿到的是理解」——讀書得到的是理解、該說學到 / 讀出來 / 得到的教訓；而「拿到的需求 / 拿去用」合規）都漏在清單外，加進去只會用噪音蓋掉訊號。兩者改用探針：**補語型態探針**（「⋯⋯的是」 …(truncated)