自訂
選擇性個人偏好: ${AGENT_SKILLS_CONFIG:-~/.config/agent-skills}/CodeQuality/PREFERENCES.md。
若該檔案存在,則讀取並套用;否則使用技能預設值。僅限個人偏好:任何關於儲存庫或產品的事實,都應歸屬於該儲存庫(其 .claude/workflow-profile.sh 或工具設定檔),絕不放在此處。
CodeQuality 是做什麼的?
一個循環,兩種視角。循環永遠是:偵測 → 挑選一個項目 → 在測試保護下修復 → 驗證 → 重複。工具視角以現有測試作為防護網,依優先順序修復掃描器標記的項目。原則視角則修復導致程式碼難以變更的問題(萬用類別、重複、不可測試的核心),一次遵循一個 SOLID / Clean Code 原則,且絕不在未先展示的情況下套用任何設計變更。兩種視角都讀取相同的工具清單,寫入相同的報告目錄,並以相同的品質改善報告作結。
兩種視角
| 工具視角 | 原則視角 | |
|---|---|---|
| 驅動力 | 掃描器輸出 (summary.md) | 對應至 Principles.md 的設計壞味道 (smell-inventory.md, roadmap.md) |
| 工作單位 | 一個發現:一個規則在一個檔案:行號 | 一個原則應用在一個有邊界的熱點:一次抽取、一次類別拆分、一次相依反轉 |
| 順序 | P0 安全 → P1 正確性 → P2 可維護性 | 槓桿階梯(如下),可依儲存庫調整 |
| 自主性 | 修復,然後顯示差異 | 提議 → 確認 → 套用;在獲得批准前不編輯任何內容 |
| 安全網 | 現有測試保持綠燈 | 當目標未被測試時,先撰寫特性測試 |
| 指標 | 較少的發現,工具重新執行後乾淨 | 重複百分比、循環複雜度、函式長度、扇入/扇出、「現已可單元測試」 |
| 使用時機 | lint/型別/安全債、CI 紅燈、「讓掃描器滿意」 | 難以變更的程式碼;修復衝刺的結構性層級 |
循環
掃描 → 選擇 → 安全網 → [提議 → 確認] → 修復 → 驗證 → 報告 → 重複
└─ 原則模式下強制執行,工具模式下跳過 ─┘
工作流程路由
| 觸發詞 | 工作流程 | 產出物 |
|---|---|---|
| "install quality tools", "set up code quality" | Workflows/Install.md | 安裝並驗證清單中的工具 |
| "scan", "baseline", "analyze code quality", "smell report", "what should we fix first", "refactoring roadmap" | Workflows/Scan.md | summary.md (A), smell-inventory.md (B), roadmap.md (C) |
| "improve code quality", "fix lint", "quality loop", "fix [finding]" | Workflows/Loop.md 在工具模式下 | 修復、session-log.md、報告 |
| "refactor", "apply SOLID", "clean this up", "start the loop" | Workflows/Loop.md 在原則模式下 | 修復、session-log.md、報告 |
| "clean up this repo" 無其他限定詞 | 掃描 A + B + C,然後以原則模式執行循環 | 以上全部 |
| "remediation sprint", "remediation cycle" | IssueFlow Remediation 擁有分支、PR 與合併權;掃描界定循環範圍,循環執行修復 | 每個 PR 一個循環 |
若未指定模式,循環會自行判斷:當儲存庫不存在 roadmap.md 時使用工具模式,存在時則使用原則模式。使用者可以強制指定任一模式。
工具清單
Tools/tools.tsv 是此技能中唯一的工具列表。以 Tab 分隔,每行一個工具和語言:language category priority tool install run notes,其中 language 為 js | python | yaml,category 為 lint | format | types | security | deadcode | duplication | complexity | deps | coverage,priority 為 P0 | P1 | P2。兩個腳本皆讀取此清單;工作流程中不會內嵌工具列表。要新增或移除工具,編輯一行即可。
| 腳本 | 從清單中讀取 | 功能 |
|---|---|---|
Tools/install-quality-tools.sh [--dry-run] [lang ...] | 所選語言的 install 欄位 | 偵測語言(package.json → js; pyproject.toml, requirements.txt 或 *.py → python; *.yaml/*.yml → yaml);以儲存庫的套件管理器安裝 js 工具作為 devDependencies(lockfile → npm/pnpm/bun),以 uv pip install 或 pip 安裝 python 和 yaml 工具;npm:/pip: 前綴可覆蓋安裝通道,- 則不安裝 |
Tools/run-quality-baseline.sh [--dry-run] [lang ...] | run 欄位 | 將每個工具執行至 reports/codequality/<YYYY-MM-DD>-<HHMMSS>/,取代 $OUT(報告目錄)、$SRC(QUALITY_SRC_DIRS,預設若 src 存在則為 src,否則為 .)、$PM 和 $NPX;未安裝的工具標記為 MISSING,崩潰的工具標記為 FAILED,兩者皆不中斷執行;寫入 summary.md,包含每個工具的狀態、解析出的問題計數以及 P0/P1/P2 總數;印出報告路徑 |
run 欄位為 - 的工具(覆蓋率工具)會被安裝但不會由基線腳本執行:覆蓋率將在循環中、僅針對目標範圍進行測量。每個工具皆為免費且於本地執行;npm audit、pip-audit 與 checkov 僅為了其漏洞資料庫而連線網路。
槓桿階梯(原則視角預設順序)
- 命名 — 你無法安全地修改你無法閱讀的程式碼。成本低,能解鎖一切。
- DRY / 重複 — 以最低風險移除最多程式碼;暴露隱藏的抽象。
- 小型函式 — 長方法 → 抽取;每個函式維持單一抽象層級。
- SRP — 拆分因為超過一個原因而變更的類別與模組。
- OCP / DIP — 反轉相依性、新增接縫;高影響力、高風險,需先建立安全網。
- ISP / LSP — 肥大介面與破壞的可替代性;需要步驟 5 的接縫。
掃描部分 C 會根據實際的清單調整此順序(槓桿 = 影響力 ÷ 風險;請見 Principles.md 第 3 部分)。
不可協商事項
- 每次迭代一個項目。 一個發現,或一個原則應用在一個有邊界的目標上。小型、可審查的差異。
- 行為保持不變。 結構改變,行為不變。若行為必須改變,請停止並標記:那是功能,不是修復。
- 綠燈到綠燈。 測試在變更前後都必須通過。變更後若變紅,則還原,絕不嘗試向前修復。
- 先撰寫特性測試,若將要觸及的程式行未被測試。沒有安全網,就沒有重構。
- 套用任何設計變更前先提議(原則模式)。工具模式可以直接修復,然後顯示差異。
- P0 → P1 → P2 用於工具發現的項目,跨語言,且不依語言區分。
- 絕不為通過而弱化測試或 lint 規則。 過時的測試應移至新的正確行為;規則應由程式碼滿足。
- 童子軍原則,但有邊界。 讓觸及的檔案更乾淨,但不要超出當前項目的範圍。
- 證據,而非意見。 指出規則或原則名稱,以及指標(若存在)。
輸出產出物
全部位於 reports/codequality/ 目錄下(已加入 gitignore):
| 檔案 | 由誰寫入 |
|---|---|
<YYYY-MM-DD>-<HHMMSS>/summary.md + 各工具原始輸出 | run-quality-baseline.sh (掃描 A) |
<YYYY-MM-DD>/smell-inventory.md | 掃描 B |
<YYYY-MM-DD>/roadmap.md | 掃描 C |
<YYYY-MM-DD>/session-log.md | 循環,每次迭代一筆記錄 |
<YYYY-MM-DD>/quality-report.md | 循環,在 session 結束時(如下) |
品質改善報告(強制)
每個循環 session 以此報告作結,無論哪種模式。它與程式碼變更一同作為交付成果,並在透過 IssueFlow 發佈時成為 PR 或追蹤器評論的內文。
| 章節 | 內容 |
|---|---|
| 摘要表格 | 新增/刪除/淨變更行數;問題數量(修復前後,按優先級分類);移除的死碼熱點;測試數量(修復前後,全部綠燈) |
| 已移除的程式碼 | 檔案、內容、行數、風險 |
| 新增或修改的程式碼 | 檔案、內容、行數、目的 |
| 已修復的錯誤 | 嚴重性、描述、根本原因(僅當有錯誤浮現時) |
| 複雜度差異 | 最大與平均循環複雜度(修復前後),每個熱點附有 ASCII 橫條圖 |
| 延期項目 | 看到但超出範圍的項目,以及原因 |