AI Skills
plankton-code-quality

plankton-code-quality

熱門

使用 Plankton 在寫入時強制執行程式碼品質 — 每次檔案編輯時透過鉤子自動格式化、靜態分析，並由 Claude 自動修復。

23萬星標
3.5萬分支
更新於 2026/7/17
獲取技能源代碼

相關技能

incremental-implementation7.7萬cut-the-curve3.6萬weather38萬
SKILL.md
readonlyread-only
name
plankton-code-quality
description

使用 Plankton 在寫入時強制執行程式碼品質 — 每次檔案編輯時透過鉤子自動格式化、靜態分析，並由 Claude 自動修復。

Plankton 程式碼品質技能

Plankton（致謝：@alxfazio）的整合參考，這是一套專為 Claude Code 設計的寫入時程式碼品質強制系統。Plankton 透過 PostToolUse 鉤子在每次檔案編輯時執行格式化與靜態分析，然後啟動 Claude 子程序來修復代理未捕捉到的違規問題。

使用時機

  • 你希望在每次檔案編輯時自動進行格式化與靜態分析（不僅限於提交時）
  • 你需要防範代理修改靜態分析設定檔以繞過檢查，而非修復程式碼
  • 你想要分層模型路由來處理修復（Haiku 處理簡單樣式，Sonnet 處理邏輯，Opus 處理型別）
  • 你使用多種語言（Python、TypeScript、Shell、YAML、JSON、TOML、Markdown、Dockerfile）

運作方式

三階段架構

每次 Claude Code 編輯或寫入檔案時，Plankton 的 multi_linter.sh PostToolUse 鉤子會執行：

階段 1：自動格式化（靜默）
├─ 執行格式化工具（ruff format、biome、shfmt、taplo、markdownlint）
├─ 靜默修復 40-50% 的問題
└─ 不輸出給主代理

階段 2：收集違規（JSON）
├─ 執行靜態分析工具並收集無法自動修復的違規
├─ 回傳結構化 JSON：{line, column, code, message, linter}
└─ 仍不輸出給主代理

階段 3：委派 + 驗證
├─ 啟動 claude -p 子程序，傳入違規 JSON
├─ 根據違規複雜度路由到對應模型層級：
│   ├─ Haiku：格式化、匯入、樣式（E/W/F 代碼）— 120 秒超時
│   ├─ Sonnet：複雜度、重構（C901、PLR 代碼）— 300 秒超時
│   └─ Opus：型別系統、深度推理（unresolved-attribute）— 600 秒超時
├─ 重新執行階段 1+2 以驗證修復
└─ 若無違規則 Exit 0，若有違規則 Exit 2（回報給主代理）

主代理看到的內容

情境 代理看到 鉤子退出碼
無違規 無 0
子程序全部修復 無 0
子程序後仍有違規 [hook] N violation(s) remain 2
建議（重複、舊工具） [hook:advisory] ... 0

主代理只會看到子程序無法修復的問題。大多數品質問題會透明地解決。

設定檔保護（防範規則繞過）

LLM 會修改 .ruff.toml 或 biome.json 來停用規則，而非修復程式碼。Plankton 透過三層機制阻止此行為：

  1. PreToolUse 鉤子 — protect_linter_configs.sh 在編輯發生前就封鎖所有靜態分析設定檔的修改
  2. 停止鉤子 — stop_config_guardian.sh 在會話結束時透過 git diff 偵測設定檔變更
  3. 受保護檔案清單 — .ruff.toml、biome.json、.shellcheckrc、.yamllint、.hadolint.yaml 等

套件管理器強制執行

Bash 的 PreToolUse 鉤子會封鎖舊版套件管理器：

  • pip、pip3、poetry、pipenv → 封鎖（請使用 uv）
  • npm、yarn、pnpm → 封鎖（請使用 bun）
  • 允許例外：npm audit、npm view、npm publish

設定

快速開始

注意： Plankton 需要從其儲存庫手動安裝。安裝前請先檢視程式碼。

# 安裝核心依賴
brew install jaq ruff uv

# 安裝 Python 靜態分析工具
uv sync --all-extras

# 啟動 Claude Code — 鉤子會自動啟用
claude

無需安裝指令或外掛設定。當您在 Plankton 目錄中執行 Claude Code 時，.claude/settings.json 中的鉤子會自動被載入。

專案整合

若要將 Plankton 鉤子用於您自己的專案：

  1. 將 .claude/hooks/ 目錄複製到您的專案中
  2. 複製 .claude/settings.json 鉤子設定
  3. 複製靜態分析設定檔（.ruff.toml、biome.json 等）
  4. 安裝您所用語言的靜態分析工具

語言特定依賴

語言 必要 選用
Python ruff、uv ty（型別）、vulture（死碼）、bandit（安全性）
TypeScript/JS biome oxlint、semgrep、knip（死匯出）
Shell shellcheck、shfmt —
YAML yamllint —
Markdown markdownlint-cli2 —
Dockerfile hadolint（>= 2.12.0） —
TOML taplo —
JSON jaq —

與 ECC 搭配使用

互補而非重疊

關注點 ECC Plankton
程式碼品質強制 PostToolUse 鉤子（Prettier、tsc） PostToolUse 鉤子（20+ 靜態分析工具 + 子程序修復）
安全性掃描 AgentShield、security-reviewer 代理 Bandit（Python）、Semgrep（TypeScript）
設定檔保護 — PreToolUse 封鎖 + Stop 鉤子偵測
套件管理器 偵測 + 設定 強制執行（封鎖舊版 PM）
CI 整合 — Git 的 pre-commit 鉤子
模型路由 手動（/model opus） 自動（違規複雜度 → 層級）

建議組合

  1. 安裝 ECC 作為您的外掛（代理、技能、指令、規則）
  2. 加入 Plankton 鉤子以進行寫入時品質強制
  3. 使用 AgentShield 進行安全稽核
  4. 在 PR 前使用 ECC 的驗證迴圈作為最終關卡

避免鉤子衝突

若同時執行 ECC 和 Plankton 鉤子：

  • ECC 的 Prettier 鉤子與 Plankton 的 biome 格式化工具可能在 JS/TS 檔案上衝突
  • 解決方案：使用 Plankton 時停用 ECC 的 Prettier PostToolUse 鉤子（Plankton 的 biome 更全面）
  • 兩者可以在不同檔案類型上共存（ECC 處理 Plankton 未涵蓋的部分）

設定參考

Plankton 的 .claude/hooks/config.json 控制所有行為：

{
  "languages": {
    "python": true,
    "shell": true,
    "yaml": true,
    "json": true,
    "toml": true,
    "dockerfile": true,
    "markdown": true,
    "typescript": {
      "enabled": true,
      "js_runtime": "auto",
      "biome_nursery": "warn",
      "semgrep": true
    }
  },
  "phases": {
    "auto_format": true,
    "subprocess_delegation": true
  },
  "subprocess": {
    "tiers": {
      "haiku":  { "timeout": 120, "max_turns": 10 },
      "sonnet": { "timeout": 300, "max_turns": 10 },
      "opus":   { "timeout": 600, "max_turns": 15 }
    },
    "volume_threshold": 5
  }
}

關鍵設定：

  • 停用您不使用的語言以加快鉤子速度
  • volume_threshold — 違規數超過此值時自動升級到更高模型層級
  • subprocess_delegation: false — 完全跳過階段 3（僅回報違規）

環境變數覆寫

變數 用途
HOOK_SKIP_SUBPROCESS=1 跳過階段 3，直接回報違規
HOOK_SUBPROCESS_TIMEOUT=N 覆寫層級超時
HOOK_DEBUG_MODEL=1 記錄模型選擇決策
HOOK_SKIP_PM=1 繞過套件管理器強制執行

參考資料

  • Plankton（致謝：@alxfazio）
  • Plankton REFERENCE.md — 完整架構文件（致謝：@alxfazio）
  • Plankton SETUP.md — 詳細安裝指南（致謝：@alxfazio）

ECC v1.8 新增功能

可複製的鉤子設定檔

設定嚴格的品質行為：

export ECC_HOOK_PROFILE=strict
export ECC_QUALITY_GATE_FIX=true
export ECC_QUALITY_GATE_STRICT=true

語言關卡表

  • TypeScript/JavaScript：優先使用 Biome，Prettier 作為備用
  • Python：Ruff format/check
  • Go：gofmt

設定檔竄改防護

在品質強制期間，標記同一輪中對設定檔的變更：

  • biome.json、.eslintrc*、prettier.config*、tsconfig.json、pyproject.toml

若設定檔被修改以壓制違規，則需明確審查後才能合併。

CI 整合模式

在 CI 中使用與本地鉤子相同的指令：

  1. 執行格式化檢查
  2. 執行靜態分析/型別檢查
  3. 嚴格模式下快速失敗
  4. 發布修復摘要

健康指標

追蹤：

  • 被關卡標記的編輯次數
  • 平均修復時間
  • 按類別分類的重複違規
  • 因關卡失敗而導致的合併封鎖