Community程式設計與開發github.com

clean-code-guard

程式碼審查技能。在生產程式碼發布前,使用 Clean Code、SOLID、DRY、KISS、YAGNI 及 LLM 特定失效模式檢查,對任何程式語言產生的或修改過的程式碼進行審查。

clean-code-guard 是什麼?

clean-code-guard 是一個專為 AI 代理(如 Claude Code、Cursor、Codex)設計的可攜式指令技能,用於在程式碼發布前進行品質審查。它整合了 Clean Code、SOLID、DRY、KISS、YAGNI 等經典軟體工程原則,並特別加入了針對 LLM 生成程式碼的 14 種系統性失效模式檢查(如程式碼重複、套件幻覺、泛用錯誤處理、硬編碼成功返回值等)。支援三種模式:守衛傳遞(在產生程式碼後自動檢查)、即時模式(編寫時即套用規則)、以及審查模式(以唯讀方式產出結構化發現報告)。它不需要 MCP 伺服器、網路存取或外部 API 金鑰,僅依賴 SKILL.md 和本機的參考檔案(位於 references/ 目錄)。此技能特別適合在程式碼提交或合併前作為最終的品管關卡,也能用於 PR 審查請求或重構任務。

相容平台✓Claude Code✓Codex CLI~Cursor
Part ofReact
npx skills add https://github.com/EthanZ-ZJ/dsh-agent-team-roles/tree/HEAD/templates/software-dev/skills/cr/clean-code-guard

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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)。

參考檔案如下:

範例

  • 一個程式碼代理正在實作一個端點:在該工作被呈現或提交之前,對 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 特定層。

始終適用的命令

這些是每次程式碼變更都必須遵循的規則。它們是命令,而非建議。

函式和命名

  1. 名稱揭示意圖。 切勿在沒有限定詞的情況下使用 data、data2、result、result_final、item、temp、value、obj、info、helper、manager、utils 或 handle_*/process_*/do_*。一個名稱必須回答它為何存在以及它做什麼。(Clean Code 第 2 章)
  2. 函式保持短小。 目標 ≤20 行,一個抽象層級,只做一件事。如果你能提取一個函式,其名稱不重述主體,則表示父函式做了超過一件事。(Clean Code 第 3 章)
  3. 四個參數是硬上限。 達到五個時,停止並引入一個請求/配置物件(record、struct、DTO 或等效物)。切勿使用布林標誌參數——改為分割成兩個函式。
  4. 無輸出參數。 一個函式要么返回值(查詢),要么有副作用(命令)。兩者永遠不能同時存在。命令名稱使用動詞;查詢名稱使用名詞或 getter 風格的名稱。(CQS)

註解和結構

  1. 註解解釋為什麼,從不解釋什麼。 刪除任何重述其下方程式碼行的註解。刪除步驟編號支架型註解。刪除被註解掉的程式碼——版本控制系統已存在。(Clean Code 第 4 章)
  2. 與檔案現有風格保持一致。 在開始寫作之前,閱讀你將要編輯的檔案以及至少一個相鄰的檔案。比照大小寫、匯入順序、錯誤處理、日誌記錄和 HTTP/DB 用戶端的選擇。不要引入第二種模式。

SOLID

  1. 每個模組一個參與者。 一個類別應只對一個利益相關者群組(會計、認證、報告)負責。如果兩個不相關的子系統都使用同一個類別,則將其拆分。(SRP,Uncle Bob 2014)
  2. 透過新增程式碼而非編輯來進行擴展。 如果新增一個變體需要在現有函式中增加另一個型別標籤分支,請先重構為註冊表、策略或多型分發。(OCP)
  3. 沒有子類別拒絕其父類別的合約。 切勿覆寫方法來發出「未實作」或「不支援的操作」信號。切勿在覆寫中強化前置條件或弱化後置條件。如果你需要這樣做,表示繼承關係是錯誤的。(LSP)
  4. 抽象與客戶端共存,而非與實作共存。 當你引入一個介面、協定或抽象合約時,將其放入消費它的套件中,而不是放在具體類別旁邊。(DIP)

DRY、KISS、YAGNI

  1. 刪除重複的知識,而非重複的文字。 兩個看起來相似但編碼不同規則的函式不構成 DRY 違規。一個以程式碼 + 文件 + 綱要表達的規則才是。(實用程式設計師,「DRY」)
  2. 錯誤的抽象比重複更糟糕。 如果一個抽象已經累積了每個呼叫者特殊情況的分支,請將其重新內聯回呼叫者,然後在重新抽象之前刪除死分支。(Sandi Metz,「錯誤的抽象」)
  3. 複雜度上限:圈複雜度 ≤10,巢狀深度 ≤5。 在超過之前進行重構。(McCabe 1976)
  4. 沒有投機性的任何東西。 沒有當今呼叫者的可選參數、配置旗標、環境變數、功能切換、介面、工廠或基礎類別。如果你發現自己在添加 enable_*、use_*_v2 或 *_mode,請刪除它們並發布具體行為。(Fowler,「Yagni」)

AI 特定防護措施——影響最大的部分

  1. 永遠不要用廣泛的捕獲所有處理程序吞噬錯誤。 僅捕獲你能從中恢復的特定錯誤類型。如果你無法恢復,讓錯誤傳播。禁止從 catch 處理程序返回 null/none/empty 成功,除非函式合約明確記錄該行為。(Karpathy)
  2. 守護邊界;信任合約。 在信任邊界——外部輸入、請求/API 負載、反序列化或跨進程資料、任何來自不可信任來源的資料——進行驗證,即使快樂路徑看起來沒問題。在邊界內部,不要為其宣告型別或呼叫者合約已排除該情況的值添加 null 檢查或執行時期型別檢查。守護的測試不是「這在理論上是否可能錯誤」,而是「不可信任的資料是否能到達這裡」。(arXiv 2409.19182)
  3. 驗證每個匯入和外部呼叫。 在呼叫某個函式庫的方法之前,確認它存在於已安裝的版本中(讀取套件、檢查鎖定檔案、或匯入並檢查)。不要根據 API「應該」看起來的樣子來產生程式碼。(USENIX Security '25)
  4. 生產程式碼中沒有硬編碼的「成功」返回值或模擬固定值。 永遠不要從一個規格說明其執行實際工作的函式中返回 {"status": "ok", ...} 或罐頭資料。如果你無法實作,使用程式語言的未實作或不支援操作機制明確失敗,並說明原因。永遠不要禁用、跳過或弱化測試以使其通過。(Fowler,Claude Code 議題 #6984)
  5. 重新推導,而非從類似內容複製。 當想要複製一個函式並修改它時,停下來。從規格重新推導。Off-by-one 和錯誤空值語意的錯誤幾乎總是透過從類似內容複製而引入。(arXiv 2411.01414)
  6. 在編寫邊界案例之前先列舉它們。 對於任何範圍、off-by-one、null/empty/one/many、even/odd 或 unicode/byte 邊界,先以註解形式寫下案例列表。在繼續之前,在程式碼中涵蓋每個案例。
  7. 在交付前清理死程式碼。 執行 linter 或 grep 掃描未使用的匯入、未使用的符號、無法到達的分支和「以防萬一」的匯出。移除它們。今天沒有被任何東西呼叫的函式沒有資格為「某一天」而存在。
  8. 先讀後寫。 在不熟悉的儲存庫中編寫程式碼之前,請閱讀你將編輯的檔案、一個相鄰檔案以及任何專案規則檔案(CLAUDE.md、AGENTS.md、README 的「慣例」部分)。使用專案現有的輔助工具、錯誤類型和日誌記錄。
  9. 沒有僅為節省幾行程式碼而添加的新依賴項。 在添加套件之前,檢查標準函式庫、已安裝的依賴項,以及是否能用少許本機程式碼完成工作。新的依賴項是永久的維護和供應鏈攻擊面;只有在它處理你不應重新實作的真正複雜度(密碼學、解析、時區——僅為說明,並非詳盡清單)時才添加它,絕對不是為了節省十行程式碼。請參閱 references/dry-kiss-yagni.md。

底線——切勿為了簡潔而刪除這些

規則 16 信任邊界內部的合約;以下項目即使你剝離了投機性內容 (14)、防禦性守護 (16) 和死程式碼 (21),也應保留。刪除其中一項是行為變更,而非清理——保留它,或標記它並詢問。

  • 每個信任邊界的驗證和清理——外部輸入、請求/API 負載、反序列化或跨進程資料。
  • 防止資料遺失的錯誤處理。
  • 安全措施——授權、輸出轉義、參數化查詢、機密處理。
  • 使用者明確要求的行為。 隨口提及 ≠ 要求,但不要放棄被要求的內容。

重構紀律

  1. 在重構時保留可觀察的行為。 當使用者要求你清理、簡化或重構現有程式碼時,不要更改合約——相同的輸入產生相同的輸出,引發相同的例外,相同的副作用,相同的排序保證。如果你在重構時發現錯誤,請單獨標記它並在更改前詢問。重構的定義是*「為了使軟體更容易理解和更便宜地修改,而不改變其可觀察行為而對其內部結構進行的更改」*(Fowler,Refactoring)。錯誤修正和重構是兩種不同的操作——永遠不要將它們捆綁在一個變更中。

交付前自我檢查

在向使用者展示程式碼之前...

相關技能