Plankton 程式碼品質技能 是做什麼的？
Plankton（致謝：@alxfazio）的整合參考，這是一個專為 Claude Code 設計的寫入時程式碼品質強制系統。Plankton 會在每次檔案編輯後透過 PostToolUse 掛鉤執行格式化與 lint 工具，然後生成 Claude 子程序來修復代理未捕捉到的違規。
使用時機
- 你希望在每次檔案編輯時（而不僅是在提交時）自動進行格式化與 lint 檢查
- 你需要防止代理修改 linter 設定檔來繞過檢查，而不是真正修復程式碼
- 你需要分層模型路由來修復問題（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）
├─ 執行 lint 工具並收集無法修復的違規
├─ 返回結構化 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 以驗證修復
└─ 若無違規則退出 0，若有殘留違規則退出 2（報告給主代理）
主代理所見
| 情境 | 代理所見 | 掛鉤退出碼 |
|---|---|---|
| 無違規 | 無 | 0 |
| 子程序全部修復 | 無 | 0 |
| 子程序修復後仍有違規 | [hook] N 個違規殘留 | 2 |
| 建議（重複、過時工具） | [hook:advisory] ... | 0 |
主代理只會看到子程序無法修復的問題。大多數品質問題都會被透明地處理。
設定檔保護（防止繞過規則）
LLM 會修改 .ruff.toml 或 biome.json 來停用規則，而不是修復程式碼。Plankton 透過三層機制來阻止此行為：
- PreToolUse 掛鉤 —
protect_linter_configs.sh在編輯發生前就阻止對所有 linter 設定檔的修改 - Stop 掛鉤 —
stop_config_guardian.sh在工作階段結束時透過git diff偵測設定檔變更 - 受保護檔案清單 —
.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 linter
uv sync --all-extras
# 啟動 Claude Code — 掛鉤會自動啟用
claude
無需安裝指令，也無需外掛設定。當您在 Plankton 目錄中執行 Claude Code 時，.claude/settings.json 中的掛鉤會自動被載入。
專案整合
若要在您自己的專案中使用 Plankton 掛鉤：
- 將
.claude/hooks/目錄複製到您的專案中 - 複製
.claude/settings.json掛鉤設定 - 複製 linter 設定檔（
.ruff.toml、biome.json等） - 為您的語言安裝對應的 linter
語言特定相依套件
| 語言 | 必要 | 選用 |
|---|---|---|
| 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+ 個 linter + 子程序修復） |
| 安全掃描 | AgentShield、安全審查代理 | Bandit（Python）、Semgrep（TypeScript） |
| 設定檔保護 | — | PreToolUse 封鎖 + Stop 掛鉤偵測 |
| 套件管理器 | 偵測 + 設定 | 強制（封鎖舊版 PM） |
| CI 整合 | — | 用於 git 的 Pre-commit 掛鉤 |
| 模型路由 | 手動（/model opus） | 自動（違規複雜度 → 層級） |
建議組合
- 安裝 ECC 作為您的外掛（代理、技能、指令、規則）
- 新增 Plankton 掛鉤用於寫入時品質強制
- 使用 AgentShield 進行安全審計
- 使用 ECC 的驗證迴圈作為 PR 前的最終關卡
避免掛鉤衝突
如果同時執行 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 中使用與本地掛鉤相同的指令：
- 執行格式化檢查
- 執行 lint/型別檢查
- 在嚴格模式下快速失敗
- 發布修復摘要
健康指標
追蹤：
- 被關卡標記的編輯數
- 平均修復時間
- 按類別統計的重複違規
- 因關卡失敗而導致的合併阻斷