关于
使用 Plankton 在编写时强制代码质量——通过钩子在每次文件编辑时自动格式化、代码检查和 Claude 驱动的修复。
name: plankton-code-quality description: "使用 Plankton 的写入时代码质量强制执行——通过钩子在每次文件编辑时自动格式化、lint 和 Claude 驱动的修复。" origin: community
Plankton 代码质量技能
Plankton（作者：@alxfazio）的集成参考，一个用于 Claude Code 的写入时代码质量强制执行系统。Plankton 通过 PostToolUse 钩子在每次文件编辑时运行格式化器和 linter，然后生成 Claude 子进程来修复代理未捕获的违规。
何时使用
- 你希望在每次文件编辑时自动格式化和 lint（而不仅仅是提交时）
- 你需要防御代理修改 linter 配置来通过检查而非修复代码
- 你希望分层模型路由进行修复（Haiku 处理简单样式，Sonnet 处理逻辑，Opus 处理类型）
- 你使用多种语言（Python、TypeScript、Shell、YAML、JSON、TOML、Markdown、Dockerfile）
工作原理
三阶段架构
每次 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)
主代理看到什么
| 场景 | 代理看到 | 钩子退出码 | |----------|-----------|-----------| | 无违规 | 无 | 0 | | 子进程全部修复 | 无 | 0 | | 子进程后仍有违规 | [hook] N violation(s) remain | 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 需要从其仓库手动安装。安装前请审查代码。
# Install core dependencies
brew install jaq ruff uv
# Install Python linters
uv sync --all-extras
# Start Claude Code - hooks activate automatically
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 阻止 + Stop 钩子检测 | | 包管理器 | 检测 + 设置 | 强制执行（阻止旧版 PM） | | CI 集成 | — | git 的 Pre-commit 钩子 | | 模型路由 | 手动（/model opus） | 自动（违规复杂度 -> 层级） |
推荐组合
- 安装 ECC 作为你的插件（代理、技能、命令、规则）
- 添加 Plankton 钩子用于写入时质量强制执行
