writing：讀者只有五分鐘；每個句子都必須值回票價
此方法旨在防止兩種失敗：一、用大量詞語傳達少量資訊的文字，且有著每個模型都會產生的節奏（開場宣告、三段式內文、結尾總結），並在此過程中改變了數字、遺漏了「可能」、或憑空捏造來源。二、改寫後文字變流暢，卻喪失了作者本身的語氣。
0. 由專案決定
在為一個專案寫作之前，請先閱讀 CLAUDE.md / AGENTS.md，並在 .claude/skills/ 中尋找該專案自身的技能。專案的規則和技能優先於此技能：PR 範本與閘門、提交慣例、宣告語言、語氣指南、設計系統樣式。此技能是當專案沒有定義時的預設值。語言、語域和語氣皆來自專案（第 10 節），絕不來自某個固定的專案或人員。
使用對象：每個為人類撰寫文字（登陸頁面、卡片、交接文件、PR、報告、提交訊息、README）的團隊 Agent。此技能負責寫作；發送、發布和張貼的動作始終歸屬於文字擁有者。$WRITING 是此技能的目錄（~/.claude/skills/writing）；其中的腳本使用 Python 標準庫，透過 python3 -I 執行。
1. 五種工作：開始前請選擇一種
| 工作 | 觸發條件 | 輸出 |
|---|---|---|
| 寫作（預設） | 你需要產生文字：文件、訊息、PR、回覆 | 僅輸出文字本身，不包含任何關於文字的說明 |
| 編輯 | 文字擁有者提供草稿請你修正 | 編輯後的草稿，加上簡短的「變動說明」 |
| 檢測 | 「這看起來像 AI 寫的嗎？」、「審計這個」、「指出問題但不要改寫」 | 列出已命名的模式，每個模式附帶一行引用原文，以及簡短的修正建議。不進行改寫、不給分數、也不斷言作者是誰 |
| 校準 | 提供兩個或以上的樣本：「照我的風格寫」、「產品的語氣」 | 一個符合 references/voice-profile.md 格式的語氣輪廓檔，供編輯和留存使用 |
| 壓縮 | 「壓縮 CLAUDE.md」、「修剪記憶」、「減少此交接文件的 Token 數」 | 保留所有事實的更小檔案，以及 fidelity_check.py 的執行結果 |
在「檢測」模式中，「已命名的模式」是可供擁有人驗證的證據，而 AI 檢測器則僅是猜測。一個語氣輪廓會影響後續工作階段中的所有任務，並可作為 --profile 傳遞給檢查工具，且只會改變機械性的模式，絕不會更改事實或禁止使用的建構。
2. 儀式層級
流程根據風險調整。每個層級都遵守規則；僅有閘門不同。
| 層級 | 文字類型 | 流程 |
|---|---|---|
| 0 | 聊天回覆、終端機狀態、提交訊息、程式碼註解、單行卡片 | 遵循記憶體規則。不執行腳本、不產出報告、不進行後設評論 |
| 1 | PR 內文、Agent 卡片、交接文件、Slack 或 WhatsApp 貼文、電子郵件、變更日誌、簡短 README | 遵循規則並執行機械性檢查（第 9 節） |
| 2 | 超過約 400 字且供第三方閱讀的文件：規格、ADR、提案、報告、事後分析、架構文件 | 執行完整流程；兩個腳本都需通過才算完成 |
精簡模式。當收到「精簡模式」、「原始人」、「簡潔」或「更少 Token」等指令時，層級 0 會變得更加嚴格，直到收到「正常模式」為止：先回答問題、零儀式、可省略冠詞、絕不使用否定句、每個句子最多 20 字且只說明一個想法、實際承載內容（程式碼、命令、路徑、錯誤訊息）保持原樣、工具狀態保持簡短、不要「扮演」該模式。遇到安全警告、不可逆操作、步驟順序、感到困惑的請求者、對使用者的提問，以及所有會記錄在聊天之外的情境時，恢復使用完整句子。提交訊息需遵循儲存庫的慣例（先閱讀 git log）；若無特別慣例，則使用祈使句的 Conventional Commits 格式，內文僅說明原因。完整規則及發送前的檢查事項：references/lean.md。
層級 0 並非豁免條款：規則適用於工作階段中的每一則回覆，因為經過幾輪對話後，預設的寫作節奏又會回來。層級 0 和 1 的記憶體自我檢查：參閱 eval.md 的最後一個區塊。
3. 嚴重性
發現的問題輕重不一，且其優先順序決定了哪些必須先修正、哪些絕不能發布。結構比詞彙更重要：一份用詞乾淨但遵循「開場白-內文-總結」結構的文件，依然是垃圾內容；反之，一個精確的術語即使出現在禁用詞列表中，也是正確的。
| 等級 | 情況 | 閘門 |
|---|---|---|
| 封鎖 | 捏造的事實、名稱、數字、日期、引述或來源。修飾語被遺漏、弱化或強化。決策、數字或需求被更改。觸及程式碼、表格、連結或 frontmatter。與來源產生矛盾 | 絕不能發布。沒有任何 allow 指令可以繞過它。fidelity_check.py 回傳非零值，或是覆蓋率清單中的項目遺漏 |
| 修正 | 檢查工具報錯 ERROR：使用禁用詞彙或建構、通用標題、表情符號、用列表取代散文、聊天機器人殘留。結構性問題：空洞的開場白、總結性的結尾、千篇一律的段落模式 | 修正它，或者用一行說明或 inline 的 allow 來保留它。絕不允許透過刪除問題所在的「事實」來規避 |
| 建議修正 | 檢查工具報錯 WARN：軟性建構、節奏、密度、轉折、確定性、名詞化、可移植性 | 在不損失事實的前提下修正它。否則就保留並繼續前進 |
| 建議參考 | eval.md 的判斷：15% 的刪減空間、標題、媒介、對稱性 | 自行決定。請說明你選擇保留哪些項目 |
4. 凌駕一切的三條規則
忠實度勝於可讀性。 為了讓句子流暢，絕不更改需求、決策、數字、名稱、風險、驗收標準或事實。如果事實本身讀起來不順，請調整句子來遷就事實，而不是反過來。絕不捏造事實、名稱、數字、日期、引述或來源。保持原樣保留：程式碼、命令、圖表、連結、表格、frontmatter、技術標識符。
語氣勝過修飾。 進行能解決問題的最小修改。首先注意草稿的詞彙、節奏、直接程度、幽默感、不確定性和離題之處，並將其保留下來。不要讓每個段落都同樣整齊；一個強烈的觀點、一句髒話或一個誠實的承認，如果它們屬於作者，就應該保留下來。拓展文字內容不等於將其弱智化。個性適用於貼文和評論文章；參考文獻、法律文件和事故報告則應保持中立。
不確定性即是事實。 「可能」、「估計」、「推斷」和「尚未測量」說明了作者對情況的了解程度。刪除重疊的修飾語只會留下一層修飾，並指明不確定的對象；它絕不能將推測提升為斷言。在安全、法律、財務、醫療和事故報告相關的文字中，修飾語本身就是內容，即使句子在沒有它的情況下讀起來更好，也必須保留。反之亦然：絕不能為來源明確陳述的事實添加不確定性。
5. 句子測試
每個句子都必須傳遞資訊、推理、必要的上下文或一個行動。如果一個句子的唯一作用是強調、儀式或填充內容：刪除它，不要改寫它。
在技術和操作文件中，這個標準更高，因為其中的推理通常簡短：每個句子都承載著一個事實、數字、命令、名稱、決策或風險。高階主管的散文和對話則允許有因果關係和框架說明的空間，遺失這些則是另一種失敗。
可移植性測試。如果一個句子在不修改的情況下可以移動到另一個人、公司、國家或產品上，那麼它就是填充內容。刪掉它，或者用特定於該主題的事實、機制、後果或判斷來取代它。
用展示代替說明。用事實、行動和後果來傳達重點。刪掉那些用於標記某個觀點很重要、很令人驚訝或很微妙的評論，取而代之的是直接展示它。
提供具體數值。一個沒有數字作為支撐的可量化形容詞，就是一個沒有證據的主張。技術分類則不屬於此類：public endpoint、private subnet、external dependency、manual approval、reversible migration 和 immutable tag 都是精準術語，應予以保留。
| 詞彙 | 取代為 |
|---|---|
| robust / robusto | 它能夠承受什麼：重試、容錯移轉、在 N 下測試通過 |
| scalable / escalável | 能擴展到多大：RPS、節點數、GB、租戶數 |
| significant / significativo | 具體的數字 |
| fast / rápido | 延遲時間或持續時間 |
| many / vários | 具體的數量 |
| recently / recentemente | 具體的日期 |
| best practice / boa prática | 誰的最佳實踐、來自哪份文件 |
6. 結構
- 先給答案。決策、修正、數字或命令應為第一行。
- 不要有介紹文件涵蓋範圍的開場段落，也不要有重複強調重點的結尾段落。每個結論只出現一次；讀者已經讀過了。
- 標題應命名內容（例如「回滾」），不應提問，也不應被其下的第一個句子重複。禁止使用的標題形式：總覽、關鍵要點、最終想法、結論、介紹、未來展望、全面概述、戰略亮點、實施流程。
- 段落用於陳述推理。列表只應用於真正屬於集合的項目。表格僅在讀者需要比較行與列的數據時使用。
- 句子和段落的長度應有變化。切勿因為三聽起來完整就構建一組三個。
- 如果內容適合用三行表達，那就只寫三行。
與文件一同發送的訊息應在一行內說明更改了什麼，不要說「這是文件」，也不要提供進一步的幫助。不同文件類型的結構範例：references/shapes.md。
7. 最清晰的媒介
不要預設以散文開始。在一個長段落之前，先說明讀者需要理解的關係，並選擇能承載該意義的最小媒介。完整規則請參考 references/visuals.md。
| 讀者需要 | 使用 |
|---|---|
| 比較 3 個以上的項目在 2 個以上的屬性，或閱讀精確的對應關係 | 表格 |
| 理解序列、拓撲、層級、所有權、狀態或依賴關係 | 圖表 |
| 辨識畫面、位置、佈局或前後對比 | 附有註解的插圖 |
| 執行一個程序 | 編號步驟和可直接貼上的程式碼 |
| 理解原因、細微差別或為何做出某個決策 | 散文 |
視覺元素只能來自來源中已確認的材料，需附上一行結論和替代文字，並且不應在散文中重複。生成的圖像不能用於展示精確的拓撲、數據、數值或架構。一個巨大且空蕩的圖表就是垃圾內容。
一個架構或雲端圖表是對真實系統的斷言：請遵循 cloud-diagram 技能（先盤點再繪製幾何圖形、標示當前或提議狀態、提供可編輯的原始檔、進行渲染探測）。此技能僅負責圖表周圍的散文。
渲染文件（HTML, Artifact, 其 PDF）：外觀屬於專案。從 templates/document.html 開始，將頂部的 --ds-* 區塊替換為 python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <root> --css 的輸出（如果專案中沒有設計系統，則保留團隊的中性色調）。預設使用一種語言；僅在面對雙語受眾或應要求時才使用雙語，並使用 templates/document-bilingual.html 範本，設定 <html data-languages="en pt">。提交前執行：python3 -I "$WRITING/scripts/artifact_check.py" <file>。PR、卡片、提交訊息和 docs/ 中的 Markdown 文件不需要這些設定。規則：references/rendered-document.md。
簡報：當安裝了簡報技能時，請在規劃投影片之前呼叫它；它擁有結構、佈局和渲染的主導權，此技能則負責散文和忠實度。除非被要求，否則不要將 README、ADR、Runbook、卡片或電子郵件轉換成投影片。
Pull Request：PR 內文旨在幫助審查者在 30 秒內決定是否要檢視 diff：包含哪些更改、原因、遺漏了什麼、如何驗證、風險和回滾方案。不要敘述 Agent 的工作歷程，也不要重複提交訊息。結構：遵循 pull-request 技能（或專案自身的規範）；references/pull-requests.md 中的 30 秒測試。只有 github 可以在 verifier 發出 SHIP 指令後開啟 PR。
8. 應刪除的模式和詞彙
包含修正方法、前後對比範例以及兩種語言的禁用詞列表的目錄在 references/patterns.md 中（快速摘要可直接打開該檔案）。每個工作階段閱讀一次。最常見的模式包括：二元對比（「不僅是 X，更是 Y」）、冒號揭示、開場清喉嚨（「值得注意」）、虛假洞見、宣告式用語（「讓我們深入探討」）、結尾的淺層 -ing 子句、誇大吹捧、模糊來源、後設話語、隱藏行動者、結尾的簡化否定（「沒問題」）、聊天機器人殘留、堆疊修飾語、一連串戲劇性的片段。
被標記的詞彙（leverage, seamless, delve, robust; alavancar, robusto, jornada, ecossistema）應被刪除，而不是用同義詞替換。在某些上下文中，有些詞是精確詞彙（例如在策略文件中使用「strategic decision」；或將 gate, harness, pipeline, realm 作為技術術語）：保留它們需要一行說明或 <!-- writing: allow <term> --> 註解，絕不能默認允許。空洞的副詞（just, actually, simply; só, literalmente, na verdade）在沒有增加任何價值時應刪除，但在承載強調、不確定性或作者節奏時則應保留。
9. 機械性檢查
在最終於文字中（層級 1 以上）：不使用長破折號或短破折號（除非作者的樣本中使用它們）、使用直角引號、標題使用句子大小寫、冒號後小寫字母開頭、不使用表情符號、粗體只用於定義的術語或警告、不使用粗體標籤列表、所有會貼上的內容都應放在程式碼區塊中。完整列表請參考 references/process.md。
10
…
[因翻譯需要，此處已截斷]