yonathan-boop/Claude

antislop-code

反泛AI：AI 編碼代理規則。程式碼註解技能

屬於 antislop 系統的一部分。請與 antislop.md（核心規則）一起閱讀。此技能負責過濾那些聽起來像是由 AI 通用產生的註解（裝飾性的、重複顯而易見的、生硬的、大聲的），同時保留承載真實資訊的註解。它透過編號引用核心規則，絕不重複或重新編號。當任務需要撰寫或編輯程式碼註解時載入此技能。

如何使用此技能

• 每當任務涉及程式碼註解時，請與 antislop.md 一起載入。核心規則包含機制（目的測試、三個層級、交付關卡）；此技能則包含註解特定的細節。
• 每個條目都具有相同的結構：說明（模式）、原因（為何這被視為泛AI生成）、修正（應該怎麼做），並引用相關核心規則編號（R-XX）。
• 範圍護欄： 此技能僅修改註解。絕不修改可執行的程式碼、識別符號、匯入語句、格式、縮排、空白字元、控制流程或邏輯。若有疑慮，請保持程式碼不變。
• 核心規則中的交付關卡仍然是最終關卡。本文檔末尾的「程式碼註解檢查清單」是與其並行使用的註解特定補充。

無貢獻的註解

裝飾性分隔線

• 說明： 由重複字元、全大寫標籤或圍繞區段名稱的方框繪製而成的橫幅註解：例如 // ======================= 包圍著 Authentication，// -------- WORKFLOW --------，或 /* ---- ROUTES ---- */ 標題。
• 原因： 裝飾本身就是訊息。用 = 或 - 包裹的標籤顯示出「這是 AI 做的」，卻沒有增加任何資訊，而且全大寫讀起來像是吼叫。
• 修正： 替換為單一純文字行，或者如果標籤沒有增加任何價值，則完全移除（R-31）。

重複顯而易見的內容

• 說明： 重複下一行或宣告所顯示內容的註解，例如在 let count = 0 上方加上 // Initialize the variable，在 class User {} 上方加上 // User class，在 function validateUser() 上方加上 // Validate user，或是 const userAge = 25; // User age is 25。
• 原因： 這增加了閱讀負擔卻沒有增加任何價值。程式碼已經說明了；註解只是重複它。
• 修正： 移除註解，保持程式碼行原樣。

工作流程敘述

• 說明： 逐步敘述流程的註解，例如 // Step 1: Validate input，// Step 2: Process request，// Step 3: Return response，或 // First...，// Next...，// Finally...。
• 原因： 控制流程在程式碼本身就可見。為其編號讀起來像是一份檢查清單，而非解釋。
• 修正： 移除。如果流程真的難以理解，那是結構問題，不是缺少註解的問題。

空洞的標籤

• 說明： 背後沒有資訊的通用標籤：例如 // Main logic，// Core logic，// Business logic，// Helper function，// Entry point，// Error handling，或是 // Note: This is important. / // Important: Please read.
• 原因： 標籤命名了一個類別，而非一個事實。「主要邏輯」沒有告訴讀者任何他們無法從程式碼推斷出來的東西。
• 修正： 移除，除非標籤承載了特定資訊。「注意：僅在 5xx 狀態碼時重試」有其存在的價值；「注意：這很重要」則沒有。

模糊的佔位符

• 說明： 承諾未來會做但未說明具體內容的註解：例如 // TODO: Improve this，// Future improvements，// Additional optimization can be added here，// Add more validation。
• 原因： 模糊的 TODO 是噪音。它命名了一種感覺（這可以更好），而不是一個任務（要做什麼，以及為什麼）。
• 修正： 移除。僅在 TODO 命名了一個具體任務並附有足夠可執行上下文時才保留。

簽名迴響

• 說明： 僅重複函式簽名的文件，例如一個 JSDoc 區塊重複了 @param price The price. 和 @returns Total price.，但函式的名稱和參數已經足以說明一切。
• 原因： 迴響簽名的文件增加了長度，卻沒有增加理解。讀者學不到任何新東西。
• 修正： 簡化或移除迴響部分。保留那些解釋業務規則、邊界情況、假設、演算法、限制、副作用、API 行為或安全影響的文件。絕不剝奪真正的文件。

裝飾性表情符號

• 說明： 在註解中用作裝飾的表情符號，例如 // ✅ Validation 或 // 🚀 Performance。
• 原因： 表情符號在程式碼中是視覺噪音，而且特定組合（✅, 🚀, 🔒）是 AI 的預設詞彙。
• 修正： 替換為純文字，或者如果標籤沒有增加價值則移除。

區塊結尾標記

• 說明： 僅標記區塊結尾的註解，例如 } // end if，# End of function，或 // End processOrder。
• 原因： 閉合括號已經標示了區塊的結束。標記的存在是出於習慣，而非需要。
• 修正： 移除。在極少數情況下，如果一個結尾標記確實有助於理解一個很長的檔案，僅在它能防止混淆的地方保留它，而非出於習慣。

應該如何撰寫

過度解釋的註解

• 說明： 一個註解寫了好幾行，圍繞一個一行就能說完的事實堆疊原因、上下文和歷史：一個四行的區塊解釋某個存根位於 PATH 上、哪個版本引入了這個解決方法、以及之前什麼東西壞掉了。每一句都是真的。長度就是問題所在。
• 原因： 人類留下一則筆記，生成器寫出一個案例。將一個一行的事實擴充成段落、建立「因為 X，所以 Y，因此 Z」的因果鏈、或者引用問題編號和修復它的版本，這些都和其他 AI 模式一樣是修飾手法，它們把重要的一行埋沒在無關緊要的內容之下。
• 修正： 只保留限制條件本身：一行，最多兩行，絕不超過三行。保留平台陷阱、靜默失敗、協議規則、效能成本。刪除問題編號、版本歷史和推理鏈。

逐行敘述

• 說明： 每一行簡單陳述上都有註解，敘述著每一行程式碼的書寫過程：// Initialize count，然後 // Loop items，然後 // Get item，然後 // Increment，然後 // Return result。
• 原因： 當每一行都有註解時，就沒有哪個註解是重要的了。讀者必須逐一檢查才能找到有意義的那個。
• 修正： 每個邏輯區塊撰寫一個簡潔的註解，而不是每行一個。如果該區塊不需要註解，就不要寫。

生硬或大聲的措辭

• 說明： 聽起來正式、冗長或大聲的註解：「此函數負責在繼續驗證流程之前驗證所提供憑證的有效性」，或全大寫的 // MAIN LOGIC。
• 原因： 正式和大聲的措辭讀起來像是生成的，而不是工程師為下一個人留下的筆記。
• 修正： 用自然的開發者語氣撰寫簡短、句子大小寫的行：// Validate credentials before issuing a token. 好的註解解釋「為什麼」，而非「是什麼」，並且保持簡短。

非禁止項目（保留這些）

絕不移除解釋以下內容的註解：

• 商業邏輯與意圖
• 架構決策
• 安全考量
• 效能權衡
• 並發行為
• 協定細節
• API 合約
• 解決方法
• 邊界情況與假設
• 授權與法律聲明

必須保留的範例：

// Stripe may retry webhook deliveries for up to three days.
// Ignore duplicate events using the event ID.

當一個註解解釋了程式碼未能直接顯示的內容時，它才有資格存在：原因、限制、非顯而易見的行為。

「有資格存在」說明了什麼可以留下，從未規定它可以寫多長。一個解決方法的筆記，應該是一行關於該解決方法的說明，而不是一段關於它的段落。上面的例子是兩行，因為有兩個真實的事實，而不是因為兩行是目標。這個列表是註解通過不該通過的審查最常見的原因：內容本身確實有價值，因此長度被忽視了。價值不等於長度。

程式碼註解檢查清單

當任務涉及註解時，請與核心交付關卡一起執行這些檢查。所有答案必須為是：

• 每個註解是否都增加了程式碼本身未顯示的資訊？(R-31)
• 註解是否避免了裝飾性分隔線、全大寫橫幅和方框繪製的標題？
• 註解是否避免了重複顯而易見的程式碼行、宣告或簽名？
• 註解是否避免了逐步的工作流程敘述？
• 註解是否避免了空洞的標籤和未命名任務的模糊 TODO？
• 註解是否避免了裝飾性表情符號和區塊結尾標記？
• 註解密度是否為每個邏輯區塊一個，而不是每行一個？
• 每個註解是否為一行，或者只有在第二行攜帶新的事實時才為兩行？
• 保留的註解是否讀起來簡短、自然且使用句子大小寫？
• 是否堅守了範圍護欄：僅更改註解，程式碼保持不變？