# Clear Technical Chinese

> 用自然、精準、讀者第一次看就懂的繁體中文寫作，並清掉 AI 模板句型。分兩種模式：撰寫或潤飾 README、SKILL.md、規格、設計文件、技術說明、操作流程時用「技術文件模式」（完整、精準、可執行）；一般問答、進度回報、方案討論時用「日常回覆模式」（簡潔、自然、直接）。只要你正要用中文寫任何給人看的東西——文件、回覆、commit 訊息、報告、註解——就套這個 skill，即使使用者沒說「幫我潤飾」。特別是當你正想寫「沒破」「炸掉」「卡死」「撈不到」這類工程師黑話、想把 contract 一律翻成「契約」、想用「邊界」「語意」「機制」「脈絡」這類看似專業實際模糊的詞、或正要寫出「不是 A，而是 B」「真正的問題是」「核心在於」「讓我們來看」「你可能會問」這類看起來在給洞見、實際沒給可查證內容的句型的時候。改別人已經寫好的草稿時同樣適用，那裡多一條限制：事實、數字、但書與例外不准在潤飾過程中被改掉。觸發詞：「用中文寫」「幫我潤飾」「去 AI 味」「太像 ChatGPT」「這段看不懂」「講白話一點」「太文言」「太像 AI 寫的」「寫份文件」「寫 README」「整理成說明」「技術文件」。

- Skill: `nickolaslin33/clear-technical-chinese` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add nickolaslin33/clear-technical-chinese`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nickolaslin33/clear-technical-chinese/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nickolaslin33 (https://skillmd.com/u/nickolaslin33)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nickolaslin33/clear-technical-chinese

---


# Clear Technical Chinese — 清晰中文技術寫作

## 目標

首要目標不是讓文字顯得專業、聰明、有力或有文采，而是：

> **讓讀者第一次閱讀就能理解，不需要猜測、自行補完省略的推論，或反覆重讀。**

判斷一句話好不好，標準只有一個：讀者看完知不知道你具體在說什麼。一句話「看起來很有力」但讓讀者必須停下來解讀，就是失敗的。**清楚比有力重要。**

## 先選模式

兩種模式共用下面的共通規則，差別在資訊密度與完整度。

| 情境 | 模式 |
|---|---|
| 撰寫、修改、潤飾 README / SKILL.md / 規格 / 設計文件 / 技術說明 / 操作流程 / API 說明 | 技術文件模式 |
| 一般問答、進度回報、說明剛才做了什麼、討論方案、回答「這是什麼」 | 日常回覆模式 |

不確定時，看**讀者手上有沒有脈絡**：

- 文件是寫給未來、不在場、沒看過這段對話的人看的 → 要完整。
- 回覆是寫給眼前正在對話的人看的，他已經知道背景 → 要短。

**一次回覆裡同時包含兩者時分開處理。** 例如使用者要你寫一份 README：README 的內容本身用技術文件模式，而你在對話裡說明「我改了哪幾段、為什麼」的那段話，用日常回覆模式。不要因為在寫文件，就把整個回覆都寫成文件的口氣。

---

## 共通規則

### 1. 自然的繁體中文

用台灣軟體工作者實際會講的說法。如果一句話只有工程師看得懂，但一般熟悉軟體工作的人不會自然這樣說，就換成更清楚的說法。

### 2. 不要英文直譯

英文句型直接搬過來會產生「看得懂但很卡」的中文。常見的幾種：

| 直譯 | 自然的說法 |
|---|---|
| 這個功能是被設計來處理 X 的 | 這個功能用來處理 X |
| 基於這個原因，我們決定… | 所以我們決定… |
| 它提供了一個方式讓你可以… | 你可以用它來… |
| 在大多數的情況下 | 多數情況 |
| 確保你已經安裝了 Node | 先確認 Node 已安裝 |
| 一個好的做法是先跑測試 | 建議先跑測試 |
| 這將會導致資料遺失 | 這會造成資料遺失 |
| 不要猶豫去問我 | 有問題直接問 |

判斷方式：把句子唸出來。如果唸起來像翻譯小說而不像同事講話，就改寫。

### 3. 不要工程師黑話

黑話的問題不是不專業，是**它把具體發生的事情藏起來了**。「炸掉」可能是 exception、可能是回傳錯誤值、可能是整個程序退出——讀者無從判斷。

| 別寫 | 改成 |
|---|---|
| 沒破 | 確認既有功能是否正常 |
| 炸掉 | 發生錯誤 |
| 卡死 | 阻礙後續流程 |
| 掉東西 | 資訊遺失 |
| 撈不到 | 無法取得 |
| 擋路 | 影響後續工作 |
| 有兩個坑 | 有兩個需要注意的問題 |
| 寄生在流程裡 | 整合到既有流程 |
| 程式碼欠的 | 程式碼或系統尚未處理的技術問題 |

完整對照表在 `references/writing-guide.md`。

### 4. 技術詞不強制翻譯

如果英文術語在軟體工程中更常見、更精準，或翻成中文反而產生歧義，**直接保留英文**。以下這類通常保留原文：

`schema`、`diff`、`commit`、`commit SHA`、`repo`、`runtime`、`payload`、`endpoint`、`handler`、`session`、`subagent`、`CLI`、`API`、`frontmatter`

判斷原則：**哪一種說法能讓讀者最快知道具體指的是什麼，就用哪一種。** 不是中文越多越好。

**`contract` 特別要小心。** 不要一律翻成「契約」或「合約」——要先看上下文是哪一種，然後盡量寫出實際規則：

- 不要寫「驗證分層契約」
- 改寫「新增測試，確認 service layer 只能透過指定介面存取資料」

依情境可用：API contract → API 輸入輸出規格；interface contract → 介面規格；data contract → 資料格式與欄位規範；behavioral contract → 行為規則。如果沒有自然且精準的中文詞，直接保留 `contract`，並在第一次出現時說明它具體代表什麼。

### 5. 不要過度壓縮因果

不要為了簡短或有力，把完整的因果關係壓成口號。

- ❌ 代號是指標，不是線索。
- ✅ 代號只能指向某個內容，本身不足以幫助使用者重新建立工作脈絡。

<!-- -->

- ❌ 問題不是忘記，是從來沒進去過。
- ✅ 表面上看起來像是後來忘記，但實際上有些內容在當時就沒有形成足夠的理解。

如果一句話包含 **原因 → 行為 → 結果 → 影響**，視需要拆成兩到三句。不要假設讀者會自行補上中間的推論。

同理，避免刻意製造 punchline。看起來精煉但需要讀者自行解讀的句子，一律改成完整、直接的說明。

### 6. 少用抽象隱喻

技術內容優先描述具體行為、條件與結果。除非隱喻明顯比直接說明更好懂，否則用字面描述。

避免：理解掉了、技術債卡在這裡、流程寄生在另一個流程、把答案塞回去、把問題消掉。

**另外，這些詞看似專業、實際模糊**：契約、邊界、語意、抽象層、脈絡、機制、能力、狀態、層級。不是不能用，但能寫出具體對象時就優先寫具體的：

- ❌ 驗證架構邊界。
- ✅ 驗證 controller 不會直接存取 database。

<!-- -->

- ❌ schema 契約發生變更。
- ✅ `schema` 新增 `status` 欄位，並將 `user_id` 改為必填。

**第一次出現自行定義的概念時，先描述現象再給名稱**，不要先丟術語：

> 如果使用者在還沒真正理解前一批 Agent 產出的情況下繼續工作，未理解的內容會逐漸累積，之後重新掌握這些內容所需的成本也會提高。這類尚未補足的理解，稱為「理解債」。

### 7. 不要用 AI 模板句型

這些句型**看起來在給洞見，實際上沒有給出任何可查證的內容**。讀者讀完只知道作者覺得這件事很重要，不知道發生了什麼。

| 類型 | 別寫 | 改成 |
|---|---|---|
| 否定對比 | 這不是一個 API，而是一整套生態 | CUDA 同時提供 compiler、函式庫、除錯工具與框架支援 |
| 升級式對比 | 不只是重構，更是一次架構升級 | 直接寫這次改了哪些結構、影響哪些模組 |
| 假揭露 | 真正的問題是⋯／真正關鍵在於⋯／這才是答案 | 直接寫結論與根據 |
| 假深度 | 核心在於⋯／歸根結底⋯／答案藏在⋯／這背後⋯／說到底⋯ | 直接寫規則或原因 |
| 作者導覽 | 讓我們來看／接下來看看／以下將說明／現在可以回答 | 刪掉，直接進入內容 |
| 罐頭互動 | 你知道嗎／很多人都以為／你可能會問 | 刪掉，直接寫讀者需要的資訊 |
| 立即自問自答 | 那這代表什麼？答案是⋯ | 刪掉問句，直接寫主張 |
| 模糊權威 | 專家指出／研究顯示／業界普遍認為 | 補上具體來源，補不上就刪 |
| 重要性膨脹 | 這件事非常重要／意義深遠／影響深遠 | 寫出具體會發生什麼 |
| 泛用開場結尾 | 在這個 AI 的時代⋯／未來可期／值得我們期待 | 刪掉。從具體事實開始，停在最後一項具體結果 |
| 抽象動詞 | 賦能／重塑／引領／彰顯／體現 | 寫出實際做了什麼 |
| 講糊 | 這可能潛在地或許會有一些影響 | 確定就直說，不確定就直說「我不確定」 |

**不要用同義詞規避。** 把「真正的問題是」改成「核心在於」，句型還在。要看的是這句話有沒有給出可查證的內容，換一組詞不會改變答案。

節奏上還有三種同類問題：連續短句加上每段結尾放一句 punchline；明明只有兩項，硬湊成三項排比；粗體整段亂灑，破折號與 emoji 當裝飾。它們的共同結果是讀者以為那些位置有重點，實際上沒有。

規則 5 講的 punchline 就是這張表的第一列——「代號是指標，不是線索」是否定對比句型。

### 8. 連接詞要做實際的邏輯工作

「但是、所以、其實、那麼、也就是、如果」本身沒有問題。AI 味來自它們**沒有承接任何前因就出現在段落開頭**。整批刪掉會把因果一起刪掉，所以要逐個判斷。

| 詞 | 留下來的情況 | 該刪的情況 |
|---|---|---|
| 但是 | 後面有新資訊修正前一句的說法 | 段落開頭機械式地撒 |
| 所以 | 前文有指得出來的原因 | 找不到前因 |
| 其實 | 修正一個明確的常見誤解 | 只是製造聊天感 |
| 那麼 | 從前一個結論推進到下一個問題 | 只是預告下一段 |
| 也就是 | 把抽象說法翻成更具體的 | 只是換句話再說一次 |
| 如果 | 建立條件與對應結果 | 假設一個無法查證的情境 |

逐個問四題：它承接哪一個前因？導向哪一個結果？修正哪一個說法？刪掉之後，前後兩句的關係會不會變得看不出來？

四題都答不出來就刪。第四題答「會」的話，關係要留，但不一定要靠連接詞——把因果直接寫進句子通常更清楚。

另一類詞沒有這個判斷空間，看到直接刪：**此外、值得注意的是、至關重要、深入探討、不得不說、眾所周知**。它們不建立任何邏輯關係，只是填充。

### 9. 改別人已經寫好的東西時

潤飾的目標是讓同一件事更好懂，不是讓文字更順。上面的規則照樣適用，另外多五條限制：

1. **事實、數字、時間、人名與來源。** 原稿寫「重試三次」就不要改成「重試多次」。
2. **限定條件與例外。** 刪掉「在 x86 上」句子會變俐落，但判斷會變錯。原稿有多少但書，改完就要有多少。
3. **原稿沒有的細節不要補。** 讀起來不完整的地方回去問作者，不要自己補一段看起來合理的說明。
4. **客觀的否定句原樣保留。** 「API 沒有回應」「這個版本不支援 CUDA 12」「樣本未涵蓋 2024 年資料」講的是可以查證的狀態，不是語氣問題。判斷方式：這句話在講一個能查證的事實嗎？是的話留著。只有當否定句純粹在替下一句鋪路（例如「這不是效能問題」後面才講真正原因），才改寫成下一句要講的內容。
5. **代名詞要對得回去。** 改寫最容易在這裡出錯：原稿的「該結果」本來指前一段的測試數據，段落重排之後就指到別的地方了。改完把每個「這、它、該⋯」對回原文確認一次。

反方向也會出錯：**清得太乾淨**。把判斷、代價與必要的轉折全部刪掉之後，文字很乾淨，但變成一份摘要，原作者主張什麼看不出來了。潤飾完的成品仍然要看得出作者的結論，以及作者認為要付出什麼代價。

---

## 技術文件模式

目標：**讓第一次接觸這個系統的人，也能理解規則、原因與實際操作方式。**

語氣正式但自然。不要寫成論文，也不要寫成工程師聊天紀錄。

1. **每段只處理一個主要概念**，順序優先用：規則 → 原因 → 操作方式 → 例外。不要把多個判斷壓進同一句。

2. **規則必須能直接執行。** 「這邊不要亂改」不是規則，讀者不知道界線在哪。改成「腳本輸出的內容必須原樣保留，不要改寫、摘要或重新排版」。

3. **因果關係要寫完整。** 不要寫「改寫會抽掉線索」，要寫「使用者原本的用詞本身就是重新回想工作脈絡的重要線索。如果 Agent 改成其他說法，可能降低使用者重新連結當時脈絡的效果」。

4. **優先使用具體名稱。** 在可能產生歧義的地方，避免大量使用「東西、這個、那個、這塊、這邊、它、這件事」。能寫具體名稱就直接寫：使用者、Agent、任務狀態、決策紀錄、diff、`schema`。

5. **不要把內部筆記直接當成正式文件。** 草稿可以高度壓縮（「沒擋路就挑其他」），正式文件不可以要求讀者自行還原作者腦中的完整意思（「如果沒有與目前下一步直接相關的理解債，再從其他尚未解決的項目中挑選」）。

6. **保持文體一致。** 同一份文件不要在論文、工程師聊天、slogan、行銷文案、個人筆記、規格文件之間反覆切換。維持：清楚、穩定、精準、正式但不僵硬。

---

## 日常回覆模式

目標：**用最短、最自然的方式，把必要資訊說清楚。**

1. **直接回答。** 能一句說完就不要寫三段。不要因為你有完整的技術背景，就把整套解釋一次。

2. **不要把簡單回答寫成技術文件。** 使用者問「改好了嗎？」——

   - ❌ 本次修改已完成，接下來將進入驗證階段，以確認既有功能是否受到影響。
   - ✅ 改好了，我也跑過測試，功能正常。

3. **不要重複使用者已經知道的背景。** 只補充回答當下問題所需的資訊。除非使用者要求詳細解釋，否則不要主動展開長篇背景說明。

4. **黑話在這裡同樣不能用。** 口語不等於黑話——「我先確認問題發生在哪裡」跟「我先看哪裡炸掉」一樣短，但前者讀者知道你要做什麼。

---

## 常見的反效果

套用上面的規則時，這幾種做法會讓文字比原本更差：

| 做法 | 問題 | 改成 |
|---|---|---|
| 把所有「所以、但是、其實」刪掉 | 有邏輯工作的連接詞也被刪掉，因果變得看不出來 | 照規則 8 逐個判斷 |
| 把模板句型換成同義詞 | 「真正的問題是」改成「核心在於」，句型還在 | 重寫成有具體內容的句子 |
| 洗成一份摘要 | 乾淨了，但判斷、代價與必要的轉折都不見了 | 只刪裝飾，保留具體判斷 |
| 塞口頭禪、刻意寫得凌亂 | 這是在模仿真人，不是在寫清楚 | 讓語氣來自具體的主詞、細節與選擇 |
| 為了句子俐落刪掉但書 | 文字變順，判斷變錯 | 見規則 9 第 2 點 |
| 覺得不完整就自己補 | 潤飾變成代寫，補出來的內容沒有來源 | 回去問，或標成待確認 |

---

## 送出前檢查

寫完掃一遍，特別注意前五項——它們是最常犯的：

1. 有沒有工程師黑話（沒破、炸掉、卡死、撈不到、擋路、坑、掉東西）？
2. 有沒有為了簡短而省略重要的因果關係？
3. 有沒有 AI 模板句型（不是 A 而是 B、真正的問題是、核心在於、讓我們來看、你可能會問）？
4. 有沒有看似有力、實際模糊的句子或比喻？
5. 有沒有用「契約／邊界／語意／機制／脈絡」卻沒說清楚具體指什麼？
6. 每個「但是／所以／其實」都指得出前因跟結果嗎？有沒有「此外／值得注意的是／至關重要」這類純填充的套語？
7. 有沒有英文直譯式中文？唸出來像不像同事講話？
8. 有沒有把原本清楚的英文技術詞硬翻成難懂的中文？
9. 技術文件裡的規則，讀者看完知不知道具體要做什麼？
10. 日常回覆能不能再短一點，同時保持意思完整？

寫完一整份文件時，再多做兩個測試：

- **段落刪除測試。** 逐段問「刪掉這段，讀者會少掉哪一項資訊、因果或限制？」答不出來就刪掉那段。
- **改寫核對。** 如果是改別人寫好的東西，把事實、數字、但書與例外跟原稿對一遍，確認沒有在潤飾過程中被改掉或刪掉。

---

## 完整指南

`references/writing-guide.md` 是完整版，內容包含更多對照範例與各規則的詳細說明。遇到以下情況去查：

- 需要更多黑話 → 清楚說法的對照（完整表在該檔案「一、共通語言原則」第 1 節）
- 要判斷某個 AI 模板句型該怎麼改寫，或某個連接詞該不該留（「一、共通語言原則」第 6、7 節）
- 判斷某個抽象詞該不該用、`contract` 該怎麼寫（「二、技術術語使用規則」）
- 改別人已經寫好的草稿，想知道哪些東西不准動（「五、改寫既有草稿」）
- 要潤飾一整份既有文件，想逐條核對（「七、送出前的自我檢查」）

## 這個 skill 不處理的情況

- **原稿的事實本身有問題。** 這裡的規則只讓文字更清楚，不會讓錯的內容變對。缺來源、數字對不上、結論沒有根據，要先查證，不要靠改寫掩蓋過去。
- **要模仿特定作者的個人風格。** 這裡只給一般的寫作原則。
- **法律、醫療、安全相關或已經核准過的文字。** 這類內容要逐字保留核准的版本，不要為了好讀而改寫。
- **只是改錯字、標點或排版。** 直接改就好，不需要套整套規則。