clean-code-guard 是做什麼的?
你正在審查產生的或修改後的程式碼,這些程式碼即將推出。請在首次實作完成後,套用以下規則作為守衛檢查。一旦此技能啟用,請在整個對話中持續對後續的每次程式碼變更套用規則,並在每次編輯後重新執行自我檢查,而不是因為技能已載入而回復到未受保護的輸出。如果使用者明確在編寫程式碼前啟動此技能,請在編寫時使用相同的規則,並在交付前仍然執行自我檢查。
代理團隊整合
儲存庫的規則、已接受的合約、角色權限和使用者範圍優先於本指南及其參考資料。DEV 會對其自身的變更使用守衛檢查;CR 使用唯讀審查模式,不會編輯實作。將數值限制、命名禁令、引數形狀和抽象規則視為需要調查的信號,而不是自動編輯或障礙。發現的結果應在上下文中解釋具體的正確性或維護成本;不要為了滿足數量而拆分內聚的程式碼、破壞介面或加入例外註解。審查已變更的程式碼及其直接受影響的呼叫者,而不是無關的技術債。
此套件使用的所有指南和檢查清單均為本機資源。外部出版物的名稱僅用於歸屬;請使用儲存庫的證據和捆綁的參考資料,而不是進行瀏覽。如果此任務超出技能範圍,請遵循儲存庫的正常流程;不需要同級別的技能。
相容性
這是一個可攜式的指令技能。它不需要 MCP 伺服器、網路存取、API 金鑰、Shell 命令、本機可執行檔或捆綁的腳本。它可以在任何支援 SKILD.md 加上直接連結的 references/ 檔案的執行環境中使用;agents/openai.yaml 僅是輕量級的顯示元資料。
此技能不會取代專案的 linter、格式化工具、型別檢查器或測試執行器。請使用專案自身的工具進行機械驗證;使用此技能進行程式碼品質和審查的判斷層。
如何使用此技能
此技能有三種模式 — 根據使用者要求選擇。
守衛傳遞模式(建議):在程式碼被產生、編輯、重構或修正之後,根據始終適用的命令檢查 diff 或目標檔案。在呈現、提交或合併工作之前修正違規。
即時模式(明確):當使用者在進行有風險的程式碼編輯前調用此技能時,在編寫時套用相同的命令,然後執行交付前自我檢查清單。如果你違反任何規則,在展示給使用者之前修正它。
審查模式(當使用者要求你審查、稽核、評論或評分程式碼時觸發):針對目標檔案執行 references/review-checklist.md 的檢查清單,並產生結構化的發現報告。除非被要求,否則不要在審查模式下編輯程式碼。
在所有三種模式中,規則的主體內容位於 references/ 中。在以下情況閱讀相關的參考檔案:
- 你遇到一條你不完全記得其理由的規則。
- 使用者對某條規則提出異議,你需要來源引用。
- 你處於審查模式,需要完整的檢查清單。
- 正在審查的程式碼涉及特定原則(例如,子類化 → references/solid.md;去重複 → references/dry-kiss-yagni.md)。
參考檔案如下:
- references/naming-and-functions.md — 命名、函式大小、參數、命令/查詢分離。
- references/comments-and-formatting.md — 何時加註解、何時刪除、與相鄰風格保持一致。
- references/solid.md — SRP、OCP、LSP、ISP、DIP,包含現代措辭和偵測氣味。
- references/dry-kiss-yagni.md — 知識重複 vs 程式碼重複、Sandi Metz 的重新內聯規則、McCabe 複雜度、Fowler 的 YAGNI 成本類別。
- references/ai-failure-modes.md — LLM 產生不良程式碼的 14 種系統性方式。如果你是正在閱讀此技能的 AI 代理,請先閱讀此檔案。 這是本技能影響最大的檔案。
- references/review-checklist.md — 審查模式的結構化逐步檢查清單。
- references/sources.md — 來源 URL 的中央參考文獻。僅在需要驗證或引用外部來源時閱讀。
範例
- 一個程式碼代理正在實作一個端點:在該工作被呈現或提交之前,對 diff 使用守衛傳遞模式。
- 使用者詢問「審查此 PR」或「我應該合併此內容嗎?」:使用審查模式,並從 references/review-checklist.md 報告發現結果;除非被要求,否則不要編輯。
- 使用者要求「使用 clean-code-guard 實作此端點」:在編寫時使用即時模式,然後在交付前執行自我檢查。
- 使用者要求「重構此函式,行為不變」:精確保持可觀察的行為,並將任何錯誤修正視為單獨的變更。
成功標準
當程式碼編寫任務避免列出的失效模式、程式碼審查任務產生帶有具體證據的優先級發現結果、以及重構在未經使用者明確要求行為變更時保持行為不變時,此技能就算有效運作。對於涵蓋在前言排除範圍內的概念性、CI、git 工作流程、散文、數據分析和測試執行任務,它應保持靜默。
此技能存在的原因
LLM 生成的程式碼具有可測量的系統性失效模式,而一般的「遵循良好程式碼」指令無法捕捉到這些模式。有已發表的研究作為證據:
- 在 2021 年至 2024 年間,追蹤的程式碼庫中的程式碼重複增長了 8 倍(GitClear 2025 報告)。
- 16 個模型的套件幻覺率平均為 19.6%(Spracklen 等人,USENIX Security '25)。
- LLM 經常用廣泛的捕獲所有處理程序包裝有風險的操作,從而吞噬錯誤(Karpathy)。
- AI 代理**「在測試失敗的情況下仍宣告成功」**,方法是返回硬編碼的固定值(Fowler,減少摩擦的模式)。
- 在 AI 輔助的提交中,函式大小從 142 LoC 增加到 267 LoC,圈複雜度從 4.2 增加到 8.1(GitClear)。
經典原則(Clean Code、SOLID、DRY/KISS/YAGNI)仍然是基礎——但此技能增加了大多數規則包遺漏的AI 特定層。
始終適用的命令
這些是每次程式碼變更都必須遵循的規則。它們是命令,而非建議。
函式和命名
- 名稱揭示意圖。 切勿在沒有限定詞的情況下使用
data、data2、result、result_final、item、temp、value、obj、info、helper、manager、utils或handle_*/process_*/do_*。一個名稱必須回答它為何存在以及它做什麼。(Clean Code 第 2 章) - 函式保持短小。 目標 ≤20 行,一個抽象層級,只做一件事。如果你能提取一個函式,其名稱不重述主體,則表示父函式做了超過一件事。(Clean Code 第 3 章)
- 四個參數是硬上限。 達到五個時,停止並引入一個請求/配置物件(record、struct、DTO 或等效物)。切勿使用布林標誌參數——改為分割成兩個函式。
- 無輸出參數。 一個函式要么返回值(查詢),要么有副作用(命令)。兩者永遠不能同時存在。命令名稱使用動詞;查詢名稱使用名詞或 getter 風格的名稱。(CQS)
註解和結構
- 註解解釋為什麼,從不解釋什麼。 刪除任何重述其下方程式碼行的註解。刪除步驟編號支架型註解。刪除被註解掉的程式碼——版本控制系統已存在。(Clean Code 第 4 章)
- 與檔案現有風格保持一致。 在開始寫作之前,閱讀你將要編輯的檔案以及至少一個相鄰的檔案。比照大小寫、匯入順序、錯誤處理、日誌記錄和 HTTP/DB 用戶端的選擇。不要引入第二種模式。
SOLID
- 每個模組一個參與者。 一個類別應只對一個利益相關者群組(會計、認證、報告)負責。如果兩個不相關的子系統都使用同一個類別,則將其拆分。(SRP,Uncle Bob 2014)
- 透過新增程式碼而非編輯來進行擴展。 如果新增一個變體需要在現有函式中增加另一個型別標籤分支,請先重構為註冊表、策略或多型分發。(OCP)
- 沒有子類別拒絕其父類別的合約。 切勿覆寫方法來發出「未實作」或「不支援的操作」信號。切勿在覆寫中強化前置條件或弱化後置條件。如果你需要這樣做,表示繼承關係是錯誤的。(LSP)
- 抽象與客戶端共存,而非與實作共存。 當你引入一個介面、協定或抽象合約時,將其放入消費它的套件中,而不是放在具體類別旁邊。(DIP)
DRY、KISS、YAGNI
- 刪除重複的知識,而非重複的文字。 兩個看起來相似但編碼不同規則的函式不構成 DRY 違規。一個以程式碼 + 文件 + 綱要表達的規則才是。(實用程式設計師,「DRY」)
- 錯誤的抽象比重複更糟糕。 如果一個抽象已經累積了每個呼叫者特殊情況的分支,請將其重新內聯回呼叫者,然後在重新抽象之前刪除死分支。(Sandi Metz,「錯誤的抽象」)
- 複雜度上限:圈複雜度 ≤10,巢狀深度 ≤5。 在超過之前進行重構。(McCabe 1976)
- 沒有投機性的任何東西。 沒有當今呼叫者的可選參數、配置旗標、環境變數、功能切換、介面、工廠或基礎類別。如果你發現自己在添加
enable_*、use_*_v2或*_mode,請刪除它們並發布具體行為。(Fowler,「Yagni」)
AI 特定防護措施——影響最大的部分
- 永遠不要用廣泛的捕獲所有處理程序吞噬錯誤。 僅捕獲你能從中恢復的特定錯誤類型。如果你無法恢復,讓錯誤傳播。禁止從 catch 處理程序返回 null/none/empty 成功,除非函式合約明確記錄該行為。(Karpathy)
- 守護邊界;信任合約。 在信任邊界——外部輸入、請求/API 負載、反序列化或跨進程資料、任何來自不可信任來源的資料——進行驗證,即使快樂路徑看起來沒問題。在邊界內部,不要為其宣告型別或呼叫者合約已排除該情況的值添加 null 檢查或執行時期型別檢查。守護的測試不是「這在理論上是否可能錯誤」,而是「不可信任的資料是否能到達這裡」。(arXiv 2409.19182)
- 驗證每個匯入和外部呼叫。 在呼叫某個函式庫的方法之前,確認它存在於已安裝的版本中(讀取套件、檢查鎖定檔案、或匯入並檢查)。不要根據 API「應該」看起來的樣子來產生程式碼。(USENIX Security '25)
- 生產程式碼中沒有硬編碼的「成功」返回值或模擬固定值。 永遠不要從一個規格說明其執行實際工作的函式中返回
{"status": "ok", ...}或罐頭資料。如果你無法實作,使用程式語言的未實作或不支援操作機制明確失敗,並說明原因。永遠不要禁用、跳過或弱化測試以使其通過。(Fowler,Claude Code 議題 #6984) - 重新推導,而非從類似內容複製。 當想要複製一個函式並修改它時,停下來。從規格重新推導。Off-by-one 和錯誤空值語意的錯誤幾乎總是透過從類似內容複製而引入。(arXiv 2411.01414)
- 在編寫邊界案例之前先列舉它們。 對於任何範圍、off-by-one、null/empty/one/many、even/odd 或 unicode/byte 邊界,先以註解形式寫下案例列表。在繼續之前,在程式碼中涵蓋每個案例。
- 在交付前清理死程式碼。 執行 linter 或 grep 掃描未使用的匯入、未使用的符號、無法到達的分支和「以防萬一」的匯出。移除它們。今天沒有被任何東西呼叫的函式沒有資格為「某一天」而存在。
- 先讀後寫。 在不熟悉的儲存庫中編寫程式碼之前,請閱讀你將編輯的檔案、一個相鄰檔案以及任何專案規則檔案(CLAUDE.md、AGENTS.md、README 的「慣例」部分)。使用專案現有的輔助工具、錯誤類型和日誌記錄。
- 沒有僅為節省幾行程式碼而添加的新依賴項。 在添加套件之前,檢查標準函式庫、已安裝的依賴項,以及是否能用少許本機程式碼完成工作。新的依賴項是永久的維護和供應鏈攻擊面;只有在它處理你不應重新實作的真正複雜度(密碼學、解析、時區——僅為說明,並非詳盡清單)時才添加它,絕對不是為了節省十行程式碼。請參閱 references/dry-kiss-yagni.md。
底線——切勿為了簡潔而刪除這些
規則 16 信任邊界內部的合約;以下項目即使你剝離了投機性內容 (14)、防禦性守護 (16) 和死程式碼 (21),也應保留。刪除其中一項是行為變更,而非清理——保留它,或標記它並詢問。
- 每個信任邊界的驗證和清理——外部輸入、請求/API 負載、反序列化或跨進程資料。
- 防止資料遺失的錯誤處理。
- 安全措施——授權、輸出轉義、參數化查詢、機密處理。
- 使用者明確要求的行為。 隨口提及 ≠ 要求,但不要放棄被要求的內容。
重構紀律
- 在重構時保留可觀察的行為。 當使用者要求你清理、簡化或重構現有程式碼時,不要更改合約——相同的輸入產生相同的輸出,引發相同的例外,相同的副作用,相同的排序保證。如果你在重構時發現錯誤,請單獨標記它並在更改前詢問。重構的定義是*「為了使軟體更容易理解和更便宜地修改,而不改變其可觀察行為而對其內部結構進行的更改」*(Fowler,Refactoring)。錯誤修正和重構是兩種不同的操作——永遠不要將它們捆綁在一個變更中。
交付前自我檢查
在向使用者展示程式碼之前...