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