--- name: tw-writing description: > 撰寫、改寫、審查、潤稿或翻譯台灣繁體中文內容時使用，尤其適用於技術文件、 README、規格書、操作說明、錯誤訊息與 PR 描述。改善結構、語意、台灣用語、 中英文混排與標點，同時保留原文事實、技術識別名稱及規範強度。 --- # 台灣繁體中文寫作規範 ## 1. 目的與適用範圍 ### 1.1 目的 讓讀者正確理解內容，並知道需要採取的行動。寫作以清楚、精確、簡潔、一致、自然為目標；規則衝突時依 §27 判斷。 開始前先確認任務是撰寫、改寫、翻譯或審查，再確認讀者、用途與需要保留的內容。已有足夠資訊就直接處理；只有影響語意或交付範圍的缺漏才需要詢問。 ### 1.2 適用文件 適用於繁體中文說明、技術文件、README、設計文件、規格書、SOW、工程報告、操作手冊、UI 文字、錯誤訊息、commit message、PR 描述與程式碼註解。 只處理任務指定的文字與必要的上下文。套用寫作規範不代表取得修改程式、重命名檔案、變更設定或發佈內容的授權。 ### 1.3 適用限制與例外 - 使用者要求與既有專案風格指南優先；本 Skill 補充未涵蓋的部分。 - 法律契約、法規與標準文字保留規範強度及正式用字，不為文風改變效力。 - 引文、官方名稱、產品 UI 標籤、識別名稱與待分析的原文保留原貌；需要解釋時另寫說明。 - 行銷、文學與對話內容依用途調整語氣，不機械套用技術文件的修辭限制。 - 使用者只要求審查時，回報問題與建議，不直接改寫檔案。 ### 1.4 本 Skill 的檔案 | 檔案 | 用途 | 何時讀取 | |---|---|---| | `SKILL.md` | 核心規範、流程與檢查清單 | 套用本 Skill 時 | | [references/taiwan-terms.md](references/taiwan-terms.md) | 依領域分類的用語對照 | 查詢術語或審查疑似中國用語時 | 先依語意選詞，再查表。環境提供 `zhtw-mcp` 時，可用其機械檢查補充人工判斷，見 §25。工具不是本 Skill 的必要條件。 --- ## 2. 結構原則 ### 2.1 一段一主題 一段處理一個主要論點，讓理由、例子與限制支持該論點。主題改變就換段；不必把每句都拆成獨立段落。 ### 2.2 段首先說重點 一般說明先寫結論或行動，再補原因與細節。讀者需要背景才能理解結論時，先給最少的必要背景。 Before： > 由於不同部署環境的網路連線與服務啟動流程不同，因此設定時需要注意環境差異。 After： > 不同部署環境需要不同的服務啟動設定，因為各環境的網路連線與啟動流程不同。 ### 2.3 一句一主要意念 拆開含有多個轉折或條件的長句，保留因果與時間關係。簡單的連續動作可留在同一句。 Before： > 系統啟動後讀取設定檔並連線，如果連線失敗會重試，超過重試上限會記錄錯誤並停止服務。 After： > 系統啟動後會讀取設定檔並建立連線。如果連線失敗，系統會重試。超過重試上限後，系統會記錄錯誤並停止服務。 --- ## 3. 清楚 Clarity ### 3.1 明確主詞 讓讀者知道誰執行動作。操作步驟或上下文已明確時可省略主詞；不要為了句型完整而重複。 ### 3.2 具體動詞 使用「建立」「讀取」「驗證」「刪除」等動詞，取代「執行相關作業」。 Before：對設定檔進行修改。 After：修改設定檔。 ### 3.3 具體名詞 對象已知時直接寫明；未知時保留範圍，不自行補上檔名或設定值。 Before：請確認相關設定是否正確。 After（已知指的是連線設定）：請確認資料庫連線設定是否正確。 ### 3.4 明確指涉 代詞可能指向多個對象時，重複名詞。 Before：服務讀取設定檔後會建立連線。如果它失敗，系統會重試。 After：服務讀取設定檔後會建立連線。如果連線失敗，系統會重試。 ### 3.5 相關詞靠近 修飾語靠近對象，避免插入過多補充。調整語序時保留動作的實際範圍，不把「等待回應逾時」改成「建立連線逾時」。 ### 3.6 消除修飾範圍歧義 Before：刪除舊的日誌檔案與備份。 After（依已確認的語意擇一）： - 刪除舊的日誌檔案與舊的備份。 - 刪除舊的日誌檔案，以及所有備份。 原意無法確認時，指出這兩種解讀，或詢問作者；不要自行選擇會擴大刪除範圍的版本。同樣檢查「A 和 B 的 C」「三個系統的節點」「不完全支援」等結構。 --- ## 4. 簡潔 Concision ### 4.1 刪除贅字 刪除重複、空泛開場與沒有資訊價值的修飾，保留事實、條件、範圍與不確定性。 Before：在目前的情況之下，系統目前仍然存在問題。 After：目前系統仍有問題。 ### 4.2 名詞化改為動詞 「進行分析／確認／修改／驗證」通常可改為「分析／確認／修改／驗證」。但「測試正在進行」中的「進行」描述狀態，不需刪除。 ### 4.3 判斷「相關」的功能 能指明對象時改用具體名稱。「相關係數」是術語，「與此事件相關的日誌」限定範圍，都應保留。 Before：修改相關設定。 After（對象已知）：修改連線設定。 ### 4.4 保留範圍限定 「部分」不是贅字。只有已知實際範圍時才改得更具體，不用「某些」取代「部分」假裝改善精確度。 Before：部分使用者可能遇到此問題。 After（沒有更多證據）：部分使用者可能遇到此問題。 After（已確認只影響 Windows 11）：部分 Windows 11 使用者可能遇到此問題。 ### 4.5 判斷「可以」的語意 區分能力、許可、可能性與建議。只刪除不影響語意的「可以」。 Before（描述既有能力）：系統可以支援 TLS 1.3。 After：系統支援 TLS 1.3。 「管理員可以啟用 TLS 1.3」若表示許可就保留。規範中的 MAY 也不可刪除或改成「應」，見 §16.2。 ### 4.6 精確優先 不把「支援 TLS 1.2 與 TLS 1.3」縮成「支援 TLS」，也不刪除「僅」「至少」「預設」「可能」等會改變範圍或強度的詞。 --- ## 5. 主動語態 Active Voice ### 5.1 主動句優先 Before：設定檔會由系統在啟動時被讀取。 After：系統啟動時會讀取設定檔。 ### 5.2 被動句的用途 施事者未知、不重要，或受事者才是重點時可用被動句，例如「伺服器已遭入侵」「金鑰不得被匯出」。不要為改成主動句而捏造施事者。 Before：該欄位必須被設定為 UTF-8。 After：該欄位必須設為 UTF-8。 保留「設定值」的意思，不隨意改成描述編碼行為的「使用 UTF-8」。 --- ## 6. 肯定表達 Positive Form ### 6.1 直接表達 語意等價時，使用容易理解的肯定句。 Before：沒有不通過的測試。 After：所有測試都通過。 安全規範與禁止事項可保留否定句。「不得匯出私鑰」不等於「只能在系統內保留私鑰」。 ### 6.2 保留禁止與建議的強度 「不建議」表示建議，「不得」「禁止」表示禁止。「不要」的強度依上下文判斷，不一律當成建議；無法確認時保留原文。 Before：系統不得匯出私鑰。 After：系統不得匯出私鑰。 不可潤稿成「不建議匯出私鑰」。 ### 6.3 雙重否定 只有等價時才改寫。「並非不支援」可能是保留語氣；「並非所有節點都不可用」只表示至少有節點可用，不表示全部可用。 --- ## 7. 具體語言 Concrete Language ### 7.1 有依據才寫數字 已有量測、文件或原文依據時，用事實取代空泛形容。沒有依據時，不替作者新增吞吐量、加密演算法或認證。 Before：系統具有非常高的效能。 After（只做潤稿）：系統效能高。 審查意見：原文未附效能量測，這項主張需要佐證。 把審查意見與改寫分開；原文沒附數據不表示作者沒有量測，也不表示系統效能已驗證。 ### 7.2 量測附上範圍 有資料時寫明必要的測試條件、單位與統計方式，避免把單次結果當成普遍保證。 Before（原文已有量測）：測試中平均回應時間為 45 ms，所以系統非常快。 After：測試中平均回應時間為 45 ms。 ### 7.3 標示不確定性 區分已證實、推測、尚未驗證與尚未重現，不為了語氣肯定而刪除限定。 Before（原因未確認）：此問題由連線池耗盡造成。 After：目前推測此問題由連線池耗盡造成，尚未驗證。 --- ## 8. 平行結構 Parallel Structure 並列動作、選項、同層標題與表格欄位使用平行語法。 Before：系統支援資料建立、修改資料以及資料的刪除。 After：系統支援建立、修改與刪除資料。 不要為整齊而把「支援建立、預計支援刪除」改成「支援建立與刪除」；不同狀態必須保留。 --- ## 9. 資訊順序 Information Order ### 9.1 依用途安排 | 文件 | 常用順序 | |---|---| | 一般說明 | 結論、理由、細節、例外 | | 操作文件 | 前置條件、步驟、預期結果、疑難排解 | | 故障分析 | 現象、影響、已知原因、修正、待確認事項 | | 設計文件 | 問題、目標、限制、方案、取捨、決策 | | API 文件 | 用途、請求、參數、回應、錯誤、範例 | 這些順序是起點，依讀者問題調整；原因未確認時不填入推測的根本原因。 ### 9.2 強調重要資訊 重要條件可放句首、獨立句或標題，不必固定放句尾。 Before：請重新啟動服務，如果修改了設定檔。 After：如果修改了設定檔，請重新啟動服務。 --- ## 10. 中文語法特有規則 ### 10.1 的／地／得 「的」修飾名詞，「地」修飾動作，「得」引出補充狀態：穩定的系統、穩定地執行、執行得很穩定。可自然省略時不必補字，例如「穩定執行服務」。 ### 10.2 避免堆疊「的」 Before：系統所提供的可以用來管理金鑰的功能。 After：系統提供的金鑰管理功能。 若原文是名詞短語，保留其句法用途，不一律改成完整句。 ### 10.3 名詞化 Before：完成設定檔的修改後進行服務的重新啟動。 After：修改設定檔後重新啟動服務。 ### 10.4 條件與結論 條件或時間通常放在動作前。條件很長時，可先說結論，再用獨立句限定適用範圍，避免讀者誤以為無條件適用。 ### 10.5 連接詞與並列 並列詞用頓號，子句用逗號。最後一項可用「與」「及」「和」「以及」，依語氣與層次選擇，不強制技術文件只能用「與」。 Before：系統支援建立以及修改以及刪除金鑰。 After：系統支援建立、修改與刪除金鑰。 規格中的「或」若涉及互斥，寫明「兩者擇一」或「可同時使用」。 Before：請提供帳號和／或電子郵件。 After（已確認至少提供一項）：請提供帳號、電子郵件，或兩者皆提供。 ### 10.6 量詞 依對象選擇量詞，例如 3 台伺服器、1 份文件、5 項需求、10 則訊息、1,000 筆資料、3 次重試。量詞也會改變單位：「一組金鑰」不一定等於「一把金鑰」，不要機械替換。 ### 10.7 避免英文直譯 Before：它是被設計來處理大量請求的。 After：其設計目的是處理大量請求。 中文不需要比照英文標示複數；通常寫「使用者」「3 個 API」。但「們」是合法中文用法，不全面禁止。 ### 10.8 判斷「我們」是否必要 已知主體時可省略；表示團隊責任、承諾或立場時保留。 Before（操作說明）：我們接著重新啟動服務。 After：重新啟動服務。 「我們會在 3 天內回覆」保留責任主體與承諾，不改成無主詞的「3 天內回覆」。 --- ## 11. 台灣用語 ### 11.1 依語意選詞 新寫的說明使用台灣繁體中文。下表適用於對應的技術概念，不是逐字替換規則；引文、官方名稱、UI 標籤與識別名稱依 §1.3 保留。 | 中國用語或語境 | 台灣用語 | |---|---| | 軟件／硬件 | 軟體／硬體 | | 網絡 | 網路 | | 數據庫 | 資料庫 | | 默認／缺省 | 預設 | | 接口／界面 | 介面 | | 內存／硬盤 | 記憶體／硬碟 | | 服務器 | 伺服器 | | 用戶／賬號 | 使用者／帳號 | | 打印／存儲 | 列印／儲存 | | 緩存／隊列 | 快取／佇列 | | 線程／進程 | 執行緒／行程 | | 字符串／字符 | 字串／字元 | | 數組 | 陣列 | | 函數（程式） | 函式 | | 對象／類（程式） | 物件／類別 | | 變量／算法 | 變數／演算法 | | 循環／遞歸（程式） | 迴圈／遞迴 | | 異常（exception） | 例外 | | 源代碼／調試 | 原始碼／除錯 | | 兼容／集成 | 相容／整合 | | 優化（optimization） | 最佳化 | | 鏡像（image）／集群 | 映像檔／叢集 | | 端口／帶寬 | 連接埠／頻寬 | | 分辨率／屏幕／鼠標 | 解析度／螢幕／滑鼠 | | 菜單／刷新（UI） | 選單／重新整理 | | 卸載（軟體）／激活 | 解除安裝／啟用 | | 視頻／音頻 | 影片／音訊 | | 人工智能 | 人工智慧 | ### 11.2 同形異義詞 | 詞 | 判斷方式 | |---|---| | 文件／檔案 | document 用「文件」，file 用「檔案」；一份文件也可能儲存為檔案 | | 質量／品質 | mass 用「質量」，quality 用「品質」 | | 項目／專案 | item 用「項目」，project 用「專案」 | | 程序／程式 | procedure 用「程序」，program 用「程式」 | | 登錄／登入 | 登記、記錄可用「登錄」，login 用「登入」 | | 數據／資料 | 量測數值可用「數據」，一般 data 用「資料」 | | 資訊／訊息 | information 用「資訊」，message 用「訊息」 | Before（描述 file 與 project）：刪除項目中的臨時文件。 After：刪除專案中的暫存檔案。 「檢查項目」「物理質量」「狀態異常」「研究對象」都是合法用法，不因命中對照表而修改。 ### 11.3 用字慣例 本 Skill 預設使用「裡」「群」「部署」「占用」「什麼」。這是文件用字慣例，不把所有異體字或不同慣用詞都判為錯字。 Before：服務已佈署完成。 After：服務已部署完成。 「祗」與「祇」須先確認字義，不一律換成「只」。「傳送門」在遊戲中可保留；表示網頁連結時寫「連結」。正式地名與機構名稱保留官方用字，一般行文中的「台／臺」維持專案慣例。 ### 11.4 全形與半形 行文中的英數字使用半形，中文標點依 §14。避免用全形空格排版。引用與需要精確比對的字串保留原貌。 ### 11.5 查詢完整對照表 需要確認術語時讀取 [references/taiwan-terms.md](references/taiwan-terms.md)。表內相同詞或多個選項不表示必須替換；依領域、原意與專案慣例判斷。 --- ## 12. 中英文混排 ### 12.1 中譯與原文 已有穩定中譯且讀者熟悉時用中文；中譯不穩定或讀者慣用原文時保留原文。產品、標準與協定使用官方名稱，可採正式中文名稱，不自行造譯。 ### 12.2 行內程式碼 指令、路徑、API 識別名稱、環境變數、設定鍵、精確字串與需要逐字輸入的值使用行內程式碼。例如：將 `timeout` 設為 `30`。 API、CLI、HTTP 等一般術語不必只因是英文而加反引號。 ### 12.3 名稱與大小寫 保留官方拼寫，例如 `OAuth`、`OpenAPI`、`PostgreSQL`、`macOS`、`npm`。不因台灣用語規則而修改函式、變數或 API 名稱。 ### 12.4 空格 中文字與英文、阿拉伯數字、行內程式碼之間加一個半形空格。全形標點兩側不另加空格；字串、URL、檔名與版本號內部不插入空格。 Before：使用Python3.12，將timeout設為30秒。 After：使用 Python 3.12，將 `timeout` 設為 30 秒。 括號範例：多因素驗證（MFA）已啟用。數字與單位見 §13.2。 ### 12.5 縮寫 不熟悉的縮寫首次出現時說明全名或中文意義；API、URL 等讀者已熟悉的縮寫不必強制展開。短 UI 文字也可省略長全名。 中文句子通常用「例如」「即」「等」取代 e.g.、i.e.、etc.；引文保留。 --- ## 13. 數字、單位、日期與版本 ### 13.1 數字 技術數量使用阿拉伯數字，例如 3 個節點、30 秒。固定詞保留中文數字，例如「二進位」「第三方」。 ### 13.2 單位 一般行文中數字與單位間加空格，例如 `128 MB`、`10 ms`、`30 °C`。百分比與平面角採本 Skill 的慣例：`50%`、`45°`。標準、專案或官方格式另有要求時優先遵循；程式字串不改。 Before：記憶體上限為128MB。 After：記憶體上限為 128 MB。 不可混淆 MB／MiB、bit／byte，或為格式一致而換算未確認的單位。 ### 13.3 千分位與範圍 四位數以上的一般數量使用千分位，例如 10,000 筆資料。年份、連接埠、識別碼、版本與程式值不加逗號。 範圍可用「至」，例如 10 至 20 ms；端點是否包含若影響行為就寫明。「低於 100」不改成「100 以下」。 ### 13.4 日期與時間 預設使用 `YYYY-MM-DD`；日期時間需要區分時區時，寫明時區或 UTC offset。保留原文時間所指的瞬間，不自行換時區或更新日期。 ### 13.5 版本 保留官方格式，例如 `v1.2.3`、`Python 3.12`。不把「3.12 以上」改成「3.12 之後」，也不因潤稿更新版本。 --- ## 14. 標點符號 ### 14.1 中文標點 中文行文使用全形逗號、句號、冒號、分號、問號與括號。英文原文及精確字串維持原格式。 ### 14.2 頓號 並列詞用「、」，並列子句用「，」。不要把每個英文逗號都機械改成頓號，見 §10.5。 ### 14.3 引號與書名號 中文引號使用「」，內層使用『』；書籍與作品名稱可用《》。程式字串與引用內容的引號不改。 ### 14.4 括號 中文補充使用全形括號。補充過長或包含必要條件時，改成獨立句，避免讀者略過。 ### 14.5 破折號與刪節號 中文句內破折號使用「——」，刪節號使用「……」。技術說明優先考慮括號或獨立句；需要停頓或轉折時仍可使用。 Before：此設定—僅限測試環境—會略過驗證。 After：此設定僅限測試環境使用，會略過驗證。 標題分隔符、命令中的 `--`、程式中的 `...` 與引用原文不套用這項轉換。 ### 14.6 保護程式碼 保留程式碼與識別名稱原有的標點、空格及語意，不用全形標點替換語法符號。程式碼內的中文註解與字串可在任務授權範圍內修改文字，但保留引號、跳脫與插值語法。 Before：`timeout: 30` After：`timeout: 30` 不可寫成 `timeout：30`。同樣地，不把合法中文字串改成全 ASCII。 ### 14.7 列表結尾 同一清單維持一致：完整句加句號，短語通常不加結尾標點。引文、程式碼與固定格式可保留原貌。 ### 14.8 語氣標點 技術說明不用驚嘆號或連續標點營造情緒。UI、對話與行銷文字依用途調整；不修改程式運算子或原文引號內的符號。 --- ## 15. Markdown 與版面 ### 15.1 標題 標題直接描述內容，層級不跳級。完整文件通常只有一個 H1；片段、既有範本或外部格式依其要求。不為潤稿重排與任務無關的結構。 Before：一些需要注意的事情。 After：注意事項。 ### 15.2 列表 並列、步驟與比較適合列表；需要連續推理時使用段落。有順序時用編號，否則用項目符號。列表前留空行，避免過深巢狀。 ### 15.3 表格 多個項目與屬性需要比較時用表格，單一維度通常用列表。欄位保持平行，避免過寬或在儲存格中塞入長段落。 ### 15.4 連結 連結文字說明目標，例如「安裝指南」，避免只寫「這裡」。保留連結目標；修改標題或路徑時才檢查對應連結是否需同步。 ### 15.5 程式碼區塊 標註適當語言；純文字用 `text`。指令範例通常不含提示符號。展示含程式碼 fence 的 Markdown 時，外層使用四個反引號。敏感值使用明確佔位符，例如 ``。 ### 15.6 強調 粗體用於少量關鍵詞，不把整段或所有 After 範例加粗。中文通常避免斜體，底線不作一般強調；既有範本另有要求時保留。 --- ## 16. 技術寫作 ### 16.1 區分四種語意 | 類型 | 範例 | |---|---| | 要求 Requirement | 系統必須支援 TLS 1.3。 | | 能力 Capability | 系統支援 TLS 1.3。 | | 建議 Recommendation | 建議使用 TLS 1.3。 | | 許可 Permission | 管理員可以啟用 TLS 1.3。 | Before（原文為要求）：系統必須支援 TLS 1.3。 After：系統必須支援 TLS 1.3。 不可為簡潔改成「系統支援 TLS 1.3」，因為要求會變成既有能力的陳述。 ### 16.2 MUST／SHOULD／MAY 文件採用 RFC 2119 與 RFC 8174 時，保留原文規範語意，並使用一致對應詞。 | 英文 | 中文 | |---|---| | MUST／REQUIRED／SHALL | 必須 | | MUST NOT／SHALL NOT | 不得 | | SHOULD／RECOMMENDED | 應／建議 | | SHOULD NOT／NOT RECOMMENDED | 不應／不建議 | | MAY／OPTIONAL | 可以／可選 | 首次需要解讀規範詞時說明對應方式。一般文章中的「應」「可以」不因字面相同就自動視為 RFC 規範詞。 ### 16.3 前置條件與限制 已知且影響操作時，寫出版本、平台、相依套件、權限、副作用及不可逆結果。未知時標示缺漏，不自行補造。 Before（已知會刪除資料）：執行 `reset-db.sh` 重建資料庫。 After：執行 `reset-db.sh` 會刪除現有資料並重建資料庫。執行前先備份。 這個 After 只適用於已有刪除行為與備份需求依據的情況。 --- ## 17. 錯誤訊息 說明發生什麼事，以及使用者能採取的下一步。原因已知時才寫原因；不把可能原因當成已確認的診斷。 Before（只有連線失敗的證據）：發生錯誤，請重新操作。 After：無法連線至資料庫。請檢查連線設定與資料庫服務狀態。 不責怪使用者。面向使用者的訊息避免直接顯示堆疊或敏感內部資料；面向開發者的診斷保留必要資訊與可查詢的錯誤代碼。 --- ## 18. 操作步驟 步驟以動作開頭，不重複「首先」「接下來」。一個步驟通常處理一個可驗證的動作，密切相關的短動作可合併。條件、必要警告與權限寫在受影響的操作之前。 Before：首先需要將服務停止下來，接下來可以對設定檔進行修改。 After： 1. 停止服務。 2. 修改設定檔。 原文已有成功條件時保留；缺少預期結果時指出缺漏，不假設操作已成功。 --- ## 19. 術語一致性 同一概念使用同一名稱，包含中譯、縮寫、大小寫與版本格式。不同概念不為一致而合併，例如驗證與授權、逾時與連線失敗。 Before（兩處皆指相同角色）：使用者建立帳號。用戶設定密碼。 After：使用者建立帳號。使用者設定密碼。 引文與官方 UI 名稱可保留不同用字，必要時說明對應關係。 --- ## 20. 語氣與稱謂 ### 20.1 稱謂 同一份文件維持稱謂一致。開發者文件可省略主詞或用「你」；面向終端使用者的手冊可用「您」。翻譯引文不強制統一。 ### 20.2 禮貌 操作步驟不必逐句加「請」；錯誤訊息或對話可依語氣保留。 Before：請停止服務。請修改設定檔。請重新啟動服務。 After：停止服務、修改設定檔，再重新啟動服務。 正式步驟則依 §18 拆成編號清單。 ### 20.3 系統與團隊 描述系統行為時寫「系統會……」，不要把系統行為說成團隊承諾。團隊決策與責任可以使用「我們」，見 §10.8。 ### 20.4 不預設讀者立場 避免以「顯然」「很簡單」「只要」淡化讀者遇到的困難。需要同理時可自然表達，但不以情緒代替下一步。 --- ## 21. 避免的表達 ### 21.1 無依據的行銷語 技術說明避免「世界級」「革命性」「最佳」等沒有比較或證據的形容。已有依據時直接寫依據；行銷內容依 §1.3 調整。 Before：這是最佳的部署方案。 After（原文已有選擇理由）：此方案符合離線部署的需求。 ### 21.2 空泛修飾 「非常」「基本上」「相當」若沒有資訊價值就刪除；「通常」「可能」「約」若表示頻率或不確定性則保留。 Before：此方法通常可以降低延遲。 After：此方法通常可降低延遲。 不改成無條件的「此方法會降低延遲」。 ### 21.3 公文腔 「予以處理」「加以改善」「作為參考之用」通常可改為「處理」「改善」「供參考」。正式法規、引文與組織範本保留必要用字。 Before：針對此問題進行處理。 After：處理此問題。 ### 21.4 AI 生成腔調 刪除沒有資訊的開場、收尾、插入語與重述，例如「在當今快速發展的技術環境中」「值得注意的是」「希望本文能幫助你」。 Before：值得注意的是，快取不僅能降低負載，而且能改善效能。總而言之，快取非常重要。 After：快取可降低負載並改善效能。 不因刪除空話而補上原文沒有的量測。不要機械禁用「事實上」「總而言之」等詞；只有在它們沒有轉折或摘要功能時才刪除。 判斷方式：刪除後，讀者是否少知道事實、關係、限制或下一步？若沒有，就可刪除。 --- ## 22. 不要過度精簡 保留自然句法與必要上下文。簡潔的目標是減少理解成本，不是字數最少。 Before：系統啟動後會讀取設定檔。 After：系統啟動後會讀取設定檔。 不縮成「啟動讀設定」。原文已清楚時，不必為了交出修改而修改。 --- ## 23. 修改流程 完整文件依下列順序審查。短句或局部修改可合併檢查，不要求六次獨立操作；若後續修改影響事實或結構，回頭檢查受影響項目。 ### Pass 1 — Structure 確認讀者、用途與範圍，再調整主題、段落與資訊順序。保留任務要求的範本與章節。 ### Pass 2 — Clarity 檢查主詞、指涉、動作、修飾範圍、條件與因果。不能確認的歧義先標示，不自行選擇原意。 ### Pass 3 — Precision 對照原文或來源，確認事實、數字、單位、版本、否定、範圍、不確定性與規範強度。新寫內容也要有依據。 ### Pass 4 — Concision 刪除重複、名詞化與空話。保留有功能的「部分」「相關」「可以」「我們」，見 §4、§10.8。 ### Pass 5 — Consistency 確認術語、稱謂、中英文混排、數字、標點、連結與 Markdown 一致；檢查工具建議是否影響受保護內容。 ### Pass 6 — Naturalness 讀一次完成的文字，確認符合台灣語感，沒有英文直譯或為了縮短而生硬的句子。輸出前依 §26 檢查。 --- ## 24. Before / After 範例 下列範例只示範寫法，不提供真實系統的數據或設定。未註明額外依據時，After 不新增事實。 ### Example 1 — 贅字 Before：在目前的情況之下，系統基本上是可以正常進行運作的。 After：目前系統大致可正常運作。 「基本上」可能有限定功能；只有已確認完全正常時才改成「目前系統正常運作」。 ### Example 2 — 名詞化 Before：需要進行系統設定的修改。 After：需要修改系統設定。 ### Example 3 — 具體對象 Before：請確認相關設定是否正確。 After（已知指的是 `timeout`）：請確認 `timeout` 設定是否正確。 不知道正確值時不自行寫入 `30`。 ### Example 4 — 主動句 Before：設定檔會在服務啟動時被系統讀取。 After：系統會在服務啟動時讀取設定檔。 ### Example 5 — 量測事實 Before：測試結果顯示每秒可處理 5,000 個請求，因此效能非常高。 After：測試結果顯示每秒可處理 5,000 個請求。 數字來自 Before，不由改寫新增。 ### Example 6 — 平行結構 Before：系統支援建立金鑰、修改金鑰以及金鑰的刪除。 After：系統支援建立、修改與刪除金鑰。 ### Example 7 — 錯誤訊息 Before：TLS 連線失敗，原因尚未確認。 After：無法建立 TLS 連線，原因尚未確認。 不自行斷言憑證過期或要求啟用某個設定。 ### Example 8 — 台灣用語 Before：該項目使用內存緩存來優化數據庫查詢，默認配置下可以兼容多個客戶端。 After：本專案使用記憶體快取最佳化資料庫查詢，預設設定下可相容多個用戶端。 ### Example 9 — 修飾範圍 Before：清除過期的憑證與金鑰。 After（已確認只清除過期項目）：清除過期的憑證與過期的金鑰。 無法確認金鑰範圍時，保留原文並提出歧義。 ### Example 10 — AI 腔調 Before：在當今快速發展的技術環境中，快取扮演重要角色。值得注意的是，啟用快取後，測試中的平均回應時間從 240 ms 降至 45 ms。總而言之，快取非常重要。 After：啟用快取後，測試中的平均回應時間從 240 ms 降至 45 ms。 ### Example 11 — 條件語序 Before：請重新產生憑證，如果憑證已過期或將在 30 天內到期的話。 After：如果憑證已過期，或將在 30 天內到期，請重新產生憑證。 ### Example 12 — 混排與標點 Before：使用Python3.12開發,並支援Windows11與Linux(kernel 5.15以上). After：使用 Python 3.12 開發，並支援 Windows 11 與 Linux（kernel 5.15 以上）。 --- ## 25. AI Agent 行為規則 ### MUST 1. 保留原文事實、數字、版本、API、識別名稱與程式碼語意。 2. 保留否定、量詞、條件、範圍、不確定性與規範強度。 3. 使用符合語意的台灣繁體中文；引文與正式名稱依 §1.3 保留。 4. 依任務範圍交付，分清原文內容、改寫結果與審查意見。 ### SHOULD 1. 先說重點，使用具體動詞與清楚指涉。 2. 保持術語一致，採自然語序與適當版面。 3. 原文已清楚時保留；影響原意的缺漏先標示或詢問。 4. 依 §23 調整檢查深度，依 §26 確認結果。 ### SHOULD NOT 1. 保留空泛開場、收尾、重述與沒有功能的修飾。 2. 為正式感增加冗長語句，或為字數刪除必要語意。 3. 逐字替換用語、強制每句主動，或對短句執行過重流程。 ### MUST NOT 1. 捏造事實、數據、引用、診斷、權限或設定值。 2. 把要求改成能力、建議改成強制，或改變禁止與許可。 3. 擅自修正官方名稱、識別名稱、URL、程式語法或引文。 4. 把推測寫成事實，或擅自選擇有歧義的操作範圍。 5. 宣稱執行過未實際執行的查核或工具檢查。 ### 外部工具（若可用） 環境提供 [`zhtw-mcp`](https://github.com/sysprog21/zhtw-mcp) 的文字檢查工具時，在最終輸出前使用實際可呼叫的工具檢查行文。先確認其工具名稱與輸入格式；不要把伺服器名稱當成固定的函式名稱。 - 檢查標點、字形與用語，逐項判斷建議是否符合上下文及 §27，不直接接受所有修正。 - 行內程式碼、程式語法、識別名稱、URL、引文與官方名稱不自動套用修正；中文註解或字串僅依 §14.6 的授權範圍處理。 - 工具不存在時自行檢查。呼叫失敗時說明未完成工具檢查，改用 §26，不假稱通過。 - 僅有工具檢查不代表事實與語意已驗證；外部傳送文字仍遵守任務與環境的資料存取限制。 Before（工具建議把「物理質量」改成「物理品質」）：直接接受替換。 After：保留「物理質量」，因為此處描述 mass。 ### 輸出方式 依使用者指定格式交付。未指定時，改寫或翻譯以完成的文字為主，僅補充影響原意的決定或待確認事項；審查則指出位置、問題、影響與建議。沒有問題時可直接說明，不製造修改。 --- ## 26. 最終檢查清單 輸出前檢查與本次任務相關的項目，不必把清單附在每份交付內容後。 - [ ] 任務範圍、讀者與交付格式符合要求。 - [ ] 主要結論或行動清楚，段落與資訊順序合理。 - [ ] 主詞、指涉、修飾範圍、條件與因果沒有歧義。 - [ ] 事實、數字、單位、版本與引用有原文或來源依據。 - [ ] 否定、範圍、量詞、不確定性與規範強度未改變。 - [ ] 沒有為具體化而新增診斷、設定值、權限或量測。 - [ ] 使用自然的台灣繁體中文，術語依語意判斷；引文與正式名稱保留。 - [ ] 贅字與空話已刪除，有功能的限定詞與責任主體仍保留。 - [ ] 稱謂、大小寫、空格、標點、列表與 Markdown 一致。 - [ ] 程式語法、識別名稱、URL 與必要連結未受損。 - [ ] 若有使用外部工具，建議已覆核；沒有誤稱完成工具或事實查核。 --- ## 27. 規則衝突優先順序 使用者要求、任務範圍與適用的既有規範先依 §1.3 處理。寫作規則之間的衝突依下列順序判斷： ```text Technical correctness > Semantic accuracy > Clarity > Consistency > Concision > Elegance ``` Before：系統不得匯出私鑰。 After：系統不得匯出私鑰。 不能縮成「禁止匯出」，因為會失去主體與對象。格式、用語或工具建議也不能凌駕原文語意。 --- ## 28. 一分鐘版本 1. 確認任務、讀者與範圍，依要求交付。 2. 先說重點，一段處理一個主要論點。 3. 明確交代動作、對象、條件與因果。 4. 保留事實、數字、版本、否定、範圍、不確定性與規範強度。 5. 有依據才具體化，不為文風新增數據或診斷。 6. 刪除空話與重複，不機械刪除「部分」「可以」「我們」。 7. 依語意使用台灣用語，保留引文、正式名稱與識別名稱。 8. 中文用全形標點，英數字用半形；保護程式語法與精確字串。 9. 術語、稱謂、數字、空格與版面一致。 10. 工具建議需覆核；原文已清楚時保留。 11. 清楚優先於簡潔，正確優先於文風。 --- ## 29. 設計原則 本 Skill 參考 The Elements of Style 的清楚與簡潔原則，依中文語法、台灣用語及技術寫作需求調整，不逐條移植英文句法。 成效以讀者是否正確理解、是否能採取下一步衡量。能保留原意並減少理解成本的修改才有價值；不以刪字數、修改數或規則套用次數衡量品質。