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钩子在每次文件编辑时运行格式化工具和linter，然后启动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为了通过检查而修改linter配置而非修复代码
你需要分等级的模型路由来处理修复任务（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)
├─ 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)

What the Main Agent Sees

主Agent可见内容

Scenario	Agent sees	Hook exit
No violations	Nothing	0
All fixed by subprocess	Nothing	0
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

biome.json

to disable rules rather than fix code. Plankton blocks this with three layers:

PreToolUse hook —
```
protect_linter_configs.sh
```
blocks edits to all linter configs before they happen
Stop hook —
```
stop_config_guardian.sh
```
detects config changes via
```
git diff
```
at session end

Protected files list —

.ruff.toml

biome.json

.shellcheckrc

.yamllint

.hadolint.yaml

, and more

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

等

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

快速开始

bash

undefined

bash

undefined

Clone Plankton into your project (or a shared location)

Clone Plankton到你的项目（或共享目录）

Note: Plankton is by @alxfazio

注意：Plankton作者为@alxfazio

git clone https://github.com/alexfazio/plankton.git cd plankton

Install core dependencies

安装核心依赖

brew install jaq ruff uv

Install Python linters

安装Python linters

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:

Copy
```
.claude/hooks/
```
directory to your project
Copy
```
.claude/settings.json
```
hook configuration
Copy linter config files (
```
.ruff.toml
```
,
```
biome.json
```
, etc.)
Install the linters for your languages

要在你自己的项目中使用Plankton钩子：

复制
```
.claude/hooks/
```
目录到你的项目
复制
```
.claude/settings.json
```
中的钩子配置
复制linter配置文件（
```
.ruff.toml
```
、
```
biome.json
```
等）
安装对应语言的linters

Language-Specific Dependencies

语言相关依赖

Language	Required	Optional
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

互补而非重叠

Concern	ECC	Plankton
Code quality enforcement	PostToolUse hooks (Prettier, tsc)	PostToolUse hooks (20+ linters + subprocess fixes)
Security scanning	AgentShield, security-reviewer agent	Bandit (Python), Semgrep (TypeScript)
Config protection	—	PreToolUse blocks + Stop hook detection
Package manager	Detection + setup	Enforcement (blocks legacy PMs)
CI integration	—	Pre-commit hooks for git
Model routing	Manual ( `/model opus` )	Automatic (violation complexity → tier)

功能	ECC	Plankton
代码质量管控	PostToolUse钩子（Prettier、tsc）	PostToolUse钩子（20+ linters + 子进程修复）
安全扫描	AgentShield、安全审查Agent	Bandit（Python）、Semgrep（TypeScript）
配置保护	—	PreToolUse拦截 + Stop钩子检测
包管理器	检测 + 配置	强制管控（阻止旧版包管理器）
CI集成	—	Git预提交钩子
模型路由	手动（ `/model opus` ）	自动（根据违规复杂度分配等级）

Recommended Combination

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

控制所有行为：