Community程式設計與開發github.com

CodeQuality

任何儲存庫的程式碼品質循環,透過兩種視角檢視:工具視角(linter、型別檢查器、安全掃描、死碼與重複程式碼掃描器;修復順序:P0 安全 → P1 正確性 → P2 可維護性)與原則視角(SOLID + Clean Code 壞味道;一次一個原則,在特性測試保護下提議 → 確認 → 套用)。包含一份免費本地工具清單、一次掃描、一個修復循環、一份強制性的品質改善報告。

CodeQuality 是什麼?

CodeQuality 技能為 AI 代理(例如 Claude Code、Cursor、Codex)提供了一個結構化的程式碼品質改善框架,適用於任何儲存庫。它透過兩種互補的視角解決程式碼品質問題:工具視角,可自動化執行 linter、型別檢查器、安全掃描器(如 npm audit、pip-audit、checkov)及重複/死碼掃描器,並依優先級(P0 安全 → P1 正確性 → P2 可維護性)修復發現的問題;原則視角,則以 SOLID 與 Clean Code 原則為基礎,針對設計壞味道(如萬用類別、過長方法)進行重構,每次專注於一個原則與一個邊界清楚的熱點,並要求先提出建議、獲得確認後才套用變更。此技能支援 JavaScript、Python、YAML 語言,所有工具皆為免費且可於本地執行。其工作流程包含安裝工具、掃描並建立基線、執行迭代修復循環,並以一份強制性的品質改善報告作為結尾,該報告摘要了新增/刪除的程式行數、問題數量變化、複雜度差異等指標。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/juanmherrerav/agent-workday-skills/tree/main/skills/CodeQuality

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

在你喜歡的 AI 中提問

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

說明文件

自訂

選擇性個人偏好: ${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.mdsummary.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 僅為了其漏洞資料庫而連線網路。

槓桿階梯(原則視角預設順序)

  1. 命名 — 你無法安全地修改你無法閱讀的程式碼。成本低,能解鎖一切。
  2. DRY / 重複 — 以最低風險移除最多程式碼;暴露隱藏的抽象。
  3. 小型函式 — 長方法 → 抽取;每個函式維持單一抽象層級。
  4. SRP — 拆分因為超過一個原因而變更的類別與模組。
  5. OCP / DIP — 反轉相依性、新增接縫;高影響力、高風險,需先建立安全網。
  6. 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 橫條圖
延期項目看到但超出範圍的項目,以及原因

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

BattlePlan

Daily execution plan from a task tracker (local CSV, Excel workbook, or Google Sheet). Groups open tasks by context and sub-context, estimates time, finds parallel threads, and writes ready-to-paste starting prompts per thread. Starts from yesterday instead of from zero — recaps the previous day's agent sessions and git commits, pre-fills the audit, and offers resume commands. Includes an end-of-day handoff (--close), an unattended morning draft (--draft), and task management (add, done, cancel, restore, sweep, batch import). USE WHEN plan my day, daily plan, battle plan, what should I work on, close the day, end of day handoff, morning draft, task overview, standup prep, prioritize tasks, add a task, mark task done, set up battleplan, configure task tracker.

MeetingAnalysis

Turn meetings into structured summaries and tracked action items. Transcribes recordings locally (faster-whisper on CUDA, Apple Silicon or CPU), imports Google Meet / Gemini notes through connectors, or takes pasted notetaker transcripts; writes a summary with decisions and an action table; pushes only your own items to the BattlePlan tracker. Includes an unattended inbox ingest (drop a recording, get a summary) and a hard rule that recordings never land in a git repo. USE WHEN analyze meeting, meeting summary, transcribe meeting, transcribe recording, summarize this call, what happened in the meeting, import meeting notes, Gemini notes, Google Meet notes, import meetings to tracker, auto ingest meetings, meeting inbox, process recordings folder, set up meeting analysis.

相關技能