Reference Authoring Standards — Skill reference 撰寫品質規範
Reference Authoring Standards
本文件為 compositional-writing Skill 的 reference 撰寫品質規範。適用對象：新增或修改本 Skill 任何 reference 的作者（人類或代理人）。
自包含聲明：閱讀本文件不需要先讀其他 reference。品質驗收 metric（M1-M2）見
meta-metrics.md；本文件聚焦「如何寫出符合品質的 reference」。
支撐本檔的原則卡
- parallel-parentheses-imply-a-uniform-relation：一組並列的括號各裝不同東西時，讀者會先找一條統一規則——給可掃描的形態（連續三個以上以括號收尾的條列項）與嚴重度依條文可執行性分級。
何時參閱本文件
| 觸發情境 | 動作 |
|---|---|
| 新增一份 reference | 遵循本文件的結構模板和品質標準 |
| 修改現有 reference | 確認改後仍符合五項必要要素 |
| 審查 Skill PR/Ticket | 逐項對照本文件的「驗收清單」 |
| 懷疑某 reference 違反原子化 | 執行「職責單一性測試」 |
一份合格 Reference 的五項必要要素
要素 1：情境聲明（何時讀這份文件）
每份 reference 的開頭必須有明確的「情境說明」段落，讓讀者在 30 秒內判斷適用性。
必須回答的問題：
- 這份 reference 服務哪種寫作情境？
- 讀者帶著什麼問題進來？
- 不適用的情境是什麼？
範本：
1本 reference 為「撰寫 prompt / instruction / Agent 派發」情境。
2
3適用：給 AI 模型的指令；Ticket Context Bundle；結構化派發 prompt。
4不適用：文件（見 writing-documents.md）；程式碼註解（見 writing-code-comments.md）。反例（情境不明確）：
1本文件說明寫作原則的應用。要素 2：職責單一性（原子化測試）
每份 reference 只服務一個讀者群體、回答一類問題。
判斷方法（原子化測試）：
| 問題 | 若需要「和」連接兩個答案 | 行動 |
|---|---|---|
| 「這份文件的讀者是誰？」 | 兩個不同讀者群體 | 必須拆分 |
| 「讀者帶著什麼問題來？」 | 兩類不相關問題 | 必須拆分 |
| 「讀完後讀者能做什麼？」 | 兩件不相關的事 | 必須拆分 |
反例（雙重職責）：
一份 reference 同時說明「如何撰寫 prompt」AND「如何撰寫其他 reference」——兩個讀者群體、兩種產出，必須拆分。
要素 3：自包含性（M2 通過）
讀者不看 SKILL.md 和其他 reference 的情況下，能獨立理解並套用。
自包含清單：
- 開頭有情境說明（不依賴 SKILL.md 判斷適用性）
- 文件內所有原則在本文件內展開（不引用其他 reference）
- 專有名詞在首次出現時給出就地定義
- 無「見 writing-xxx.md」的交叉引用（禁止鏈式）
可接受的外部引用：
- 引用外部公認資源（Anthropic 官方文件、業界標準）
- 引用 SKILL.md 觸發路由（只在「閱讀決策」表格中）
- 引用 meta-metrics.md 的量測方式（品質驗收場景）
要素 4：結構一致性
本 Skill 的所有 reference 遵循相同的段落骨架，便於讀者跨文件快速定位。
標準骨架：
1## [Reference 名稱]
2
3[1-3 行情境說明，含適用/不適用聲明]
4
5> **自包含聲明**：[說明閱讀本文件是否需要其他前置文件]
6
7---
8
9## 何時參閱本文件（或：情境定位）
10[觸發情境表格]
11
12## 為什麼 [情境] 需要獨立指引
13[說明此情境的特殊性，與一般文件的差異]
14
15## [核心原則 × 情境] 的應用
16（依情境選擇相關原則展開，每個原則含判斷標準 + 反例 + 正確做法）
17
18## [情境特有章節]
19（例如：Token 節省策略、結構化範例、自檢清單、反模式速查）
20
21## 延伸閱讀（可選）允許調整：
- 章節名稱可隨情境調整（「Token 節省策略」僅適用 prompt；「Log 結構化格式」僅適用 logs）
- 字數無硬性上限，但每個章節應只承載一個概念（M4 候選閾值 ≤ 3000 tokens）
要素 5：范例的具體性
範例必須足夠具體，讀者能「複製後略作修改直接套用」。
範例品質標準：
| 標準 | 說明 |
|---|---|
| 有反例對照 | 每個原則至少一組「錯 vs 對」範例 |
| 反例真實 | 反例應來自真實常見錯誤，不是刻意構造的極端案例 |
| 正例可直接套用 | 正例使用佔位符 {ticket_id} 等，讀者換掉佔位符即可使用 |
| 說明節省量（如適用） | Token 節省策略應標注估計節省比例 |
新增 Reference 的決策流程
在建立新 reference 前，先回答以下問題：
11. 此情境是否已有 reference 覆蓋？
2 是 → 擴充現有 reference（不新增）
3 否 → 繼續
4
52. 此情境的讀者群體是否唯一（原子化測試）？
6 否 → 拆分或重新定義情境邊界
7 是 → 繼續
8
93. 此情境是否需要對核心原則的「情境翻譯」？
10 否 → 考慮是否應放入 SKILL.md 核心原則速查表（不需要獨立 reference）
11 是 → 建立新 reference
12
134. 新 reference 加入後，SKILL.md 路由表的每個情境是否仍然唯一對應？
14 否 → 情境切分重疊，重新設計邊界
15 是 → 確認可新增單句消費位的資訊自足
Reference 的讀者是 runtime 的 LLM 與跳讀的維護者、句子經常被抽離消費：checklist 逐項執行、表格格被單獨引用、判斷標準句被 grep 命中、規則句被複製進 prompt。這些單句消費位的句子必須在句內資訊自足；段落敘事位的句子可以依賴鄰句、壓縮合法。
資訊自足是正向規格、四個條件——命題完整、指涉閉合、實詞可反推、一句一命題——驗收用抽離重讀：句子單獨交給沒讀過上下文的讀者、命題能不能無歧義復原。四條件的完整定義與機制見 sentence-self-sufficiency-by-consumption-unit。
錯 vs 對（checklist 項、實際案例）：
| 版本 | 句子 | 抽離後 |
|---|---|---|
| 錯 | 反比結構無法用文體先驗的無意滑動解釋、所以警惕等級最高 | 「反比結構」「無意滑動」指涉懸空 |
| 對 | 「話最滿的段落恰好最難查證」這種全篇分布比單點升格更難歸因於無意的文風滑動、所以警惕等級最高 | 每個指涉句內閉合、命題可獨立判真 |
驗收清單
新增或修改 reference 後，逐項確認：
職責單一性
- 原子化測試通過（一個讀者群體、一類問題）
- 無在標題或聲明中宣稱承擔多重職責
從原則卡壓出來的條目：壓縮後三問
把一張原則卡壓成本檔的條目時，壓出來的那一份要自己過這三問，三問都在該條目的範圍內回答、不准往卡裡找答案。
- 這一句有幾層帶極性的詞（
禁止、沒有、不、免除）——兩層以上就拆成兩句。實測一條疊了三層的條目被三份獨立讀者全數讀成相反的意思，而同一份清單裡只疊一層的條目三份全對，所以失效的是層數而不是否定句本身 - 這一句用到的承重術語，在同一節之內有定義嗎——判不出通過條件的條目等於不存在（實測有讀者明確回報「無法確定判斷通過或不通過的標準，因為定義沒寫」，另有讀者把沒定義的術語擴張到不該命中的詞上）
- 這一句的每個指涉詞（「那個數字」「它」「那三項」），先行詞在同一節之內出現過嗎——壓縮最常刪掉的就是指涉的來源，而本體那一句通常是完整的
連結不算定義。 節末指回原則卡是對的，而清單的消費單位是逐項勾選，所以每一項要自足到判得出通過。驗收問一句：照這一項工作的人，在不打開那個連結的前提下說得出通過條件嗎。
為什麼這三問要獨立跑：壓縮的人剛寫完那張卡，審查的人也讀過它，兩者讀條目時都會自動把卡上的內容補回去——本體正確正是衍生形不被檢查的原因，而補完發生在讀者這一側且無聲。機械掃描也放過它：疊加的極性沒有固定字串，掉落的定義是一段不存在的文字。判讀見 derived-operational-form-needs-its-own-check。
條文的可觸發性與效力方向
- 沒有要件寫成讀者的主觀狀態（「無法判定時」「有疑義時」「不確定時」）——換成去查文件就有答案的條件，並加一句把讀者的自我評估排除在外（例如「判定者自認顯然成立，仍須依前句的客觀條件判定」），否則他會用「我覺得這裡很明顯」把外部條件繞回主觀狀態
- 沒有極性詞當判定點的名字——極性詞指把判定結果本身當成名字的那些（「成立／不成立」「通過／不通過」「有效／無效」），描述條件的動詞不算（「滿足」「違反」不是極性詞）；讀者會替直述句自行加回極性，所以要廢除並禁用。同一次把雙重否定清完（雙重否定指一句裡有兩層否定疊在同一個命題上，「不使第一點不成立」是典型；單處還解得開，三處並存時讀者會在其中一處取到相反的極性並帶去別的款次）
- 條文沒有宣告某組結論的個數、互斥性或窮盡性（那三項是排除法的全部輸入，寫出來等於交給讀者一張走捷徑的地圖；想擋排除法的那句禁止語若附帶它們，擋的與給的在同一句，實測零效力）
- 每一個可能的結論各有自己的正面觸發條件——正面觸發條件指「當 X 成立時落入這一個」這種形式，「不屬於前面那些就落入這一個」不算；上一項拿掉了讀者原本用來做排除法的結構說明，所以每一個結論要有自己的入口，讓逐個查跟排除法一樣便宜（便宜指讀者要讀幾處才決定得了）
- 零引用的條款逐款寫下「它被引用會發生什麼」——零引用的作用域是這一批讀者的產出（沒有任何一份的依據句引用過它），不是指文件內部沒有互相引用；更差指的是判定結果（某一支會把原本判對的讀者推向判錯）。答案是「會讓結果更差」的那一類，處置是刪除而不是搬位置；答案是「有幫助」才進位置判斷，「沒作用」的直接刪
判讀見 subjective-precondition-never-fires-for-the-misreader 與 rule-text-can-have-negative-effect。
自包含性（對應 M2）
- 情境說明段落存在，30 秒內可判斷適用性
- 核心原則的必要內容在本文件內就地展開
- 無交叉引用其他 reference（只允許外部公認資源引用）
結構一致性
- 遵循標準骨架（情境說明 → 為什麼獨立 → 原則應用 → 情境章節 → 自檢清單）
- 所有原則有反例 + 正例對照
路由一致性（對應 M1）
- SKILL.md 觸發路由表已更新
- Directory Index 已更新
- 新情境與現有情境無重疊
范例品質
- 每個原則有至少一組「錯 vs 對」
- 正例使用 snake_case 佔位符，可直接套用
單句消費位自足
- checklist 項、表格格、判斷標準句逐句通過抽離重讀（單獨讀、指涉能回收、命題完整）
- 新增的規則句在入庫前先抽離重讀
與 meta-metrics.md 的分工
| 文件 | 職責 |
|---|---|
| 本文件（reference-authoring-standards.md） | 如何寫出合格 reference（撰寫指南） |
meta-metrics.md | 如何量測寫作品質（M1-M5 量化驗收） |
兩者互補：先用本文件的標準寫，再用 meta-metrics.md 的方法量測。
Last Updated: 2026-08-17 Version: 1.1.0 — 新增「單句消費位的資訊自足」段與驗收清單「單句消費位自足」兩條：reference 的句子經常被抽離消費（checklist 逐項執行、表格格單獨引用、判斷標準句被 grep 命中）、單句消費位必須句內資訊自足（四條件 + 抽離重讀測試）；含實際案例的錯對對照。對應 principle 卡 sentence-self-sufficiency-by-consumption-unit。
Version: 1.0.0 — 從 writing-prompts.md 雙職責拆分：Skill 品質規範獨立為本檔，writing-prompts.md 保留 prompt 寫作情境