Back to Details

plankton-code-quality

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Plankton Code Quality Skill

Plankton 代码质量 Skill

Integration reference for Plankton (credit: @alxfazio), a write-time code quality enforcement system for Claude Code. Plankton runs formatters and linters on every file edit via PostToolUse hooks, then spawns Claude subprocesses to fix violations the agent didn't catch.
Plankton（致谢：@alxfazio）的集成参考文档，这是一款面向Claude Code的编写时代码质量管控系统。Plankton通过PostToolUse钩子在每次文件编辑时运行格式化工具与代码检查工具，随后启动Claude子进程修复Agent未发现的问题。

When to Use

适用场景

  • You want automatic formatting and linting on every file edit (not just at commit time)
  • You need defense against agents modifying linter configs to pass instead of fixing code
  • You want tiered model routing for fixes (Haiku for simple style, Sonnet for logic, Opus for types)
  • You work with multiple languages (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)
  • 希望在每次文件编辑时自动格式化与代码检查（而非仅在提交时）
  • 需要防止Agent修改代码检查工具配置以绕过规则，而非修复代码
  • 希望根据问题复杂度分层路由模型进行修复（Haiku处理简单样式问题，Sonnet处理逻辑问题，Opus处理类型问题）
  • 涉及多语言开发（Python、TypeScript、Shell、YAML、JSON、TOML、Markdown、Dockerfile）

How It Works

工作原理

Three-Phase Architecture

三阶段架构

Every time Claude Code edits or writes a file, Plankton's 
multi_linter.sh
PostToolUse hook runs:
Phase 1: Auto-Format (Silent)
├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint)
├─ Fixes 40-50% of issues silently
└─ No output to main agent

Phase 2: Collect Violations (JSON)
├─ Runs linters and collects unfixable violations
├─ Returns structured JSON: {line, column, code, message, linter}
└─ Still no output to main agent

Phase 3: Delegate + Verify
├─ Spawns claude -p subprocess with violations JSON
├─ Routes to model tier based on violation complexity:
│   ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout
│   ├─ Sonnet: complexity, refactoring (C901, PLR codes) — 300s timeout
│   └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout
├─ Re-runs Phase 1+2 to verify fixes
└─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent)
每当Claude Code编辑或写入文件时，Plankton的
multi_linter.sh
PostToolUse钩子会启动运行：
Phase 1: Auto-Format (Silent)
├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint)
├─ 静默修复40-50%的问题
└─ 不向主Agent输出任何内容

Phase 2: Collect Violations (JSON)
├─ 运行代码检查工具并收集无法自动修复的问题
├─ 返回结构化JSON数据：{line, column, code, message, linter}
└─ 仍不向主Agent输出任何内容

Phase 3: Delegate + Verify
├─ 启动claude -p子进程并传入问题JSON数据
├─ 根据问题复杂度路由至对应模型层级：
│   ├─ Haiku：格式化、导入、样式问题（E/W/F类代码）——超时时间120秒
│   ├─ Sonnet：复杂度、重构问题（C901、PLR类代码）——超时时间300秒
│   └─ Opus：类型系统、深度推理问题（unresolved-attribute）——超时时间600秒
├─ 重新运行Phase 1+2以验证修复效果
└─ 若问题全部修复则返回Exit 0，若仍有问题则返回Exit 2（并向主Agent报告）

What the Main Agent Sees

主Agent可见内容

ScenarioAgent seesHook exit
No violationsNothing0
All fixed by subprocessNothing0
Violations remain after subprocess
[hook] N violation(s) remain
2
Advisory (duplicates, old tooling)
[hook:advisory] ...
0
The main agent only sees issues the subprocess couldn't fix. Most quality problems are resolved transparently.
场景Agent可见内容钩子退出码
无问题无0
所有问题被子进程修复无0
子进程修复后仍有问题
[hook] N violation(s) remain
2
建议信息（重复项、旧工具）
[hook:advisory] ...
0
主Agent仅能看到子进程无法修复的问题。大多数质量问题会被透明地解决。

Config Protection (Defense Against Rule-Gaming)

配置保护（防止规则规避）

LLMs will modify 
.ruff.toml
or 
biome.json
to disable rules rather than fix code. Plankton blocks this with three layers:
  1. PreToolUse hook — 
    protect_linter_configs.sh
    blocks edits to all linter configs before they happen
  2. Stop hook — 
    stop_config_guardian.sh
    detects config changes via 
    git diff
    at session end
  3. Protected files list — 
    .ruff.toml
    , 
    biome.json
    , 
    .shellcheckrc
    , 
    .yamllint
    , 
    .hadolint.yaml
    , and more
大语言模型会修改
.ruff.toml
或
biome.json
等文件来禁用规则，而非修复代码。Plankton通过三层机制阻止此类行为：
  1. PreToolUse钩子 — 
    protect_linter_configs.sh
    在编辑发生前阻止对所有代码检查工具配置文件的修改
  2. Stop钩子 — 
    stop_config_guardian.sh
    在会话结束时通过
    git diff
    检测配置文件变更
  3. 受保护文件列表 — 
    .ruff.toml
    、
    biome.json
    、
    .shellcheckrc
    、
    .yamllint
    、
    .hadolint.yaml
    等

Package Manager Enforcement

包管理器强制管控

A PreToolUse hook on Bash blocks legacy package managers:
  • pip
    , 
    pip3
    , 
    poetry
    , 
    pipenv
    → Blocked (use 
    uv
    )
  • npm
    , 
    yarn
    , 
    pnpm
    → Blocked (use 
    bun
    )
  • Allowed exceptions: 
    npm audit
    , 
    npm view
    , 
    npm publish
针对Bash的PreToolUse钩子会阻止使用旧版包管理器：
  • pip
    、
    pip3
    、
    poetry
    、
    pipenv
    → 被阻止（请使用
    uv
    ）
  • npm
    、
    yarn
    、
    pnpm
    → 被阻止（请使用
    bun
    ）
  • 允许的例外情况：
    npm audit
    、
    npm view
    、
    npm publish

Setup

安装配置

Quick Start

快速开始

Note: Plankton requires manual installation from its repository. Review the code before installing.
bash
undefined
注意： Plankton需要从其代码仓库手动安装。安装前请先查看代码内容。
bash
undefined

Install core dependencies

安装核心依赖

brew install jaq ruff uv
brew install jaq ruff uv

Install Python linters

安装Python代码检查工具

uv sync --all-extras
uv sync --all-extras

Start Claude Code — hooks activate automatically

启动Claude Code——钩子会自动激活

claude

No install command, no plugin config. The hooks in `.claude/settings.json` are picked up automatically when you run Claude Code in the Plankton directory.
claude

无需安装命令或插件配置。当你在Plankton目录中运行Claude Code时，`.claude/settings.json`中的钩子会被自动加载。

Per-Project Integration

多项目集成

To use Plankton hooks in your own project:
  1. Copy 
    .claude/hooks/
    directory to your project
  2. Copy 
    .claude/settings.json
    hook configuration
  3. Copy linter config files (
    .ruff.toml
    , 
    biome.json
    , etc.)
  4. Install the linters for your languages
要在你自己的项目中使用Plankton钩子：
  1. 将
    .claude/hooks/
    目录复制到你的项目中
  2. 复制
    .claude/settings.json
    中的钩子配置
  3. 复制代码检查工具配置文件（
    .ruff.toml
    、
    biome.json
    等）
  4. 为你的开发语言安装对应的代码检查工具

Language-Specific Dependencies

各语言依赖

LanguageRequiredOptional
Python
ruff
, 
uv
ty
(types), 
vulture
(dead code), 
bandit
(security)
TypeScript/JS
biome
oxlint
, 
semgrep
, 
knip
(dead exports)
Shell
shellcheck
, 
shfmt
—
YAML
yamllint
—
Markdown
markdownlint-cli2
—
Dockerfile
hadolint
(>= 2.12.0)		—
TOML
taplo
—
JSON
jaq
—
语言必填依赖可选依赖
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
—

Pairing with ECC

与ECC搭配使用

Complementary, Not Overlapping

互补而非重叠

ConcernECCPlankton
Code quality enforcementPostToolUse hooks (Prettier, tsc)PostToolUse hooks (20+ linters + subprocess fixes)
Security scanningAgentShield, security-reviewer agentBandit (Python), Semgrep (TypeScript)
Config protection—PreToolUse blocks + Stop hook detection
Package managerDetection + setupEnforcement (blocks legacy PMs)
CI integration—Pre-commit hooks for git
Model routingManual (
/model opus
)		Automatic (violation complexity → tier)
关注点ECCPlankton
代码质量管控PostToolUse钩子（Prettier、tsc）PostToolUse钩子（20+代码检查工具 + 子进程修复）
安全扫描AgentShield、security-reviewer agentBandit（Python）、Semgrep（TypeScript）
配置保护—PreToolUse阻止 + Stop钩子检测
包管理器检测 + 配置强制管控（阻止旧版包管理器）
CI集成—Git的pre-commit钩子
模型路由手动（
/model opus
）		自动（根据问题复杂度分配层级）

Recommended Combination

推荐组合

  1. Install ECC as your plugin (agents, skills, commands, rules)
  2. Add Plankton hooks for write-time quality enforcement
  3. Use AgentShield for security audits
  4. Use ECC's verification-loop as a final gate before PRs
  1. 安装ECC作为你的插件（包含Agent、Skill、命令、规则）
  2. 添加Plankton钩子实现编写时代码质量管控
  3. 使用AgentShield进行安全审计
  4. 在提交PR前使用ECC的验证循环作为最终检查

Avoiding Hook Conflicts

避免钩子冲突

If running both ECC and Plankton hooks:
  • ECC's Prettier hook and Plankton's biome formatter may conflict on JS/TS files
  • Resolution: disable ECC's Prettier PostToolUse hook when using Plankton (Plankton's biome is more comprehensive)
  • Both can coexist on different file types (ECC handles what Plankton doesn't cover)
如果同时运行ECC和Plankton钩子：
  • ECC的Prettier钩子与Plankton的biome格式化工具可能在JS/TS文件上产生冲突
  • 解决方案：使用Plankton时禁用ECC的Prettier PostToolUse钩子（Plankton的biome功能更全面）
  • 两者可在不同文件类型上共存（ECC处理Plankton未覆盖的场景）

Configuration Reference

配置参考

Plankton's 
.claude/hooks/config.json
controls all behavior:
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
  }
}
Key settings:
  • Disable languages you don't use to speed up hooks
  • volume_threshold
    — violations > this count auto-escalate to a higher model tier
  • subprocess_delegation: false
    — skip Phase 3 entirely (just report violations)
Plankton的
.claude/hooks/config.json
控制所有行为：
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
    — 完全跳过Phase 3（仅报告问题）

Environment Overrides

环境变量覆盖

VariablePurpose
HOOK_SKIP_SUBPROCESS=1
Skip Phase 3, report violations directly
HOOK_SUBPROCESS_TIMEOUT=N
Override tier timeout
HOOK_DEBUG_MODEL=1
Log model selection decisions
HOOK_SKIP_PM=1
Bypass package manager enforcement
变量用途
HOOK_SKIP_SUBPROCESS=1
跳过Phase 3，直接报告问题
HOOK_SUBPROCESS_TIMEOUT=N
覆盖层级超时时间
HOOK_DEBUG_MODEL=1
记录模型选择决策
HOOK_SKIP_PM=1
绕过包管理器强制管控

References

参考资料

  • Plankton (credit: @alxfazio)
  • Plankton REFERENCE.md — Full architecture documentation (credit: @alxfazio)
  • Plankton SETUP.md — Detailed installation guide (credit: @alxfazio)
  • Plankton（致谢：@alxfazio）
  • Plankton REFERENCE.md — 完整架构文档（致谢：@alxfazio）
  • Plankton SETUP.md — 详细安装指南（致谢：@alxfazio）

ECC v1.8 Additions

ECC v1.8 新增功能

Copyable Hook Profile

可复制的钩子配置文件

Set strict quality behavior:
bash
export ECC_HOOK_PROFILE=strict
export ECC_QUALITY_GATE_FIX=true
export ECC_QUALITY_GATE_STRICT=true
设置严格的质量管控行为：
bash
export ECC_HOOK_PROFILE=strict
export ECC_QUALITY_GATE_FIX=true
export ECC_QUALITY_GATE_STRICT=true

Language Gate Table

语言管控表

  • TypeScript/JavaScript: Biome preferred, Prettier fallback
  • Python: Ruff format/check
  • Go: gofmt
  • TypeScript/JavaScript：优先使用Biome，Prettier作为备选
  • Python：使用Ruff格式化/检查
  • Go：使用gofmt

Config Tamper Guard

配置篡改防护

During quality enforcement, flag changes to config files in same iteration:
  • biome.json
    , 
    .eslintrc*
    , 
    prettier.config*
    , 
    tsconfig.json
    , 
    pyproject.toml
If config is changed to suppress violations, require explicit review before merge.
在质量管控过程中，标记同一迭代中对配置文件的修改：
  • biome.json
    、
    .eslintrc*
    、
    prettier.config*
    、
    tsconfig.json
    、
    pyproject.toml
如果配置文件被修改以抑制问题，合并前需要明确的审核。

CI Integration Pattern

CI集成模式

Use the same commands in CI as local hooks:
  1. run formatter checks
  2. run lint/type checks
  3. fail fast on strict mode
  4. publish remediation summary
在CI中使用与本地钩子相同的命令：
  1. 运行格式化检查
  2. 运行代码检查/类型检查
  3. 严格模式下快速失败
  4. 发布修复总结

Health Metrics

健康指标

Track:
  • edits flagged by gates
  • average remediation time
  • repeat violations by category
  • merge blocks due to gate failures
跟踪：
  • 被管控标记的编辑次数
  • 平均修复时间
  • 按类别统计的重复问题
  • 因管控失败导致的合并阻塞次数