簡化英文
概述
Jarrett 規則第一條：聊天輸出、產生的文件、程式碼註解和提交訊息應使用簡化技術英文。此風格基於 ASD-STE100 的原理。讀者能更快找到事實。非英語母語的讀者理解更多內容。
此技能為我們自己的摘要。它並非 ASD-STE100 標準，也不包含其字典。
使用時機
- 你撰寫或編輯規格、計畫、ADR、README、詞彙條目或其他文件。
- 你撰寫程式碼註解或提交訊息。
- 你審查文字是否符合第一條規則。
請勿將其應用於程式碼識別碼、引用的輸出（錯誤訊息、日誌、命令輸出）、技能檔案或使用者撰寫的文字。
流程
撰寫文字。然後根據每條規則檢查。
| # | 規則 | 不這樣做 | 這樣做 |
|---|---|---|---|
| 1 | 每句一個主題。 | 掛鉤讀取檔案，若缺少則列印警告，使用者會看到該警告。 | 掛鉤讀取檔案。若缺少檔案，掛鉤列印警告。使用者看到警告。 |
| 2 | 指令：20 字以內。描述：25 字以內。 | 在推送分支之前，請確保你已執行完整測試套件並檢查輸出。 | 執行 ./scripts/test.sh。然後推送分支。 |
| 3 | 使用主動語態。 | 規則由掛鉤載入。 | 掛鉤載入規則。 |
| 4 | 指令使用祈使句。 | 應在提交前執行測試。 | 提交前執行測試。 |
| 5 | 一個詞只有一個意思。使用 .claude-work/docs/VOCABULARY.md 中的詞彙。 | 先「警告」，稍後對同一動作使用「標記」、「警示」或「通知」。 | 每次都使用「警告」。 |
| 6 | 使用簡單時態：現在式、過去式、未來式。 | 掛鉤本會一直在檢查輸入。 | 掛鉤檢查輸入。 |
| 7 | 使用單一動詞，而非片語動詞或慣用語。 | 啟動建置。找出原因。 | 開始建置。找到原因。 |
| 8 | 保留「the」和「a」。 | 執行指令碼，檢查輸出。 | 執行指令碼。檢查輸出。 |
| 9 | 每個步驟一條指令。 | 1. 開啟檔案並變更版本。 | 1. 開啟檔案。 2. 變更版本。 |
| 10 | 段落：6 句以內。 | 一個包含十個句子的區塊。 | 兩個短段落，或一個列表。 |
更多規則：
- 在步驟之前寫出警告或注意事項。以危險內容開頭：「警告：這會刪除分支。」
- 數值使用數字，而非文字：「72 個字元」，而非「七十二個字元」。
- 當列出三個或更多項目時，使用列表或表格。
- 不要使用同義詞來變化文字。重複使用相同詞彙。
- 當名詞不明確時，不要使用「它」或「這個」。再次指名該名詞。
- 當某詞彙不在詞彙表中且意思不明確時，詢問使用者。然後將該詞彙加入詞彙表。
常見藉口
| 藉口 | 事實 |
|---|---|
| 「短句聽起來像機器人。」 | 短句讀得快且不易誤讀。讀者速度比風格更重要。 |
| 「同義詞讓文字不那麼重複。」 | 同義詞會讓讀者懷疑是否是不同的事物。 |
| 「這則註解太短，不適用規則。」 | 註解和提交訊息都適用。短文字容易修正。 |
| 「被動語態比較正式。」 | 被動語態隱藏了動作的執行者。指明執行者。 |
紅旗信號
- 句子包含「和」、「which」或「so that」，連接了兩個主題。
- 指令中包含「應該」、「可以」或「可能」。
- 同一事物在一個文件中有兩個名稱。
- 一個步驟包含兩個動作。
- 警告出現在其適用的步驟之後。
驗證
- 每個句子只有一個主題。
- 指令不超過 20 個字。描述不超過 25 個字。
- 所有指令使用祈使句和主動語態。
- 所有詞彙與詞彙表一致。
- 每個列表步驟只有一條指令。
- 段落不超過 6 個句子。