Plankton 程式碼品質技能 是做什麼的？
Plankton（致謝：@alxfazio）的整合參考文件，這是一個針對 Claude Code 的寫入時間程式碼品質強制系統。Plankton 在每次檔案編輯時透過 PostToolUse 鉤子執行格式化工具和 linter，然後生成 Claude 子程序來修復代理程式未捕捉到的違規。
使用時機
- 你想要在每次檔案編輯時自動進行格式化和 linting（不僅限於提交時）
- 你需要防禦代理程式修改 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）
├─ 執行 linter 並收集無法修復的違規
├─ 回傳結構化 JSON：{line, column, code, message, linter}
└─ 仍然不對主代理輸出
階段 3：委派 + 驗證
├─ 使用違規 JSON 生成 claude -p 子程序
├─ 根據違規複雜度路由到對應模型層級：
│ ├─ Haiku：格式化、匯入、樣式（E/W/F 碼）— 120 秒超時
│ ├─ Sonnet：複雜度、重構（C901、PLR 碼）— 300 秒超時
│ └─ Opus：型別系統、深度推理（unresolved-attribute）— 600 秒超時
├─ 重新執行階段 1+2 來驗證修復
└─ 如果乾淨則退出 0，如果仍有違規則退出 2（回報給主代理）
主代理看到的內容
| 情境 | 代理看到 | 鉤子退出碼 |
|---|---|---|
| 無違規 | 無 | 0 |
| 子程序全部修復 | 無 | 0 |
| 子程序後仍有違規 | [hook] N violation(s) remain | 2 |
| 通知（重複、舊工具） | [hook:advisory] ... | 0 |
主代理只會看到子程序無法修復的問題。大多數品質問題會透明地被解決。
設定檔保護（防範規則規避）
LLM 可能會修改 .ruff.toml 或 biome.json 來停用規則，而非修復程式碼。Plankton 透過三層機制阻止此行為：
- PreToolUse 鉤子 —
protect_linter_configs.sh在編輯發生前就阻擋所有對 linter 設定檔的修改 - 停止鉤子 —
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、security-reviewer agent | Bandit（Python）、Semgrep（TypeScript） |
| 設定檔保護 | — | PreToolUse 阻擋 + 停止鉤子偵測 |
| 套件管理器 | 偵測 + 設定 | 強制執行（阻擋舊版套件管理器） |
| 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/型別檢查
- 嚴格模式下快速失敗
- 發布修復摘要
健康指標
追蹤：
- 被關卡標記的編輯次數
- 平均修復時間
- 按類別的重複違規
- 因關卡失敗而導致的合併阻塞