plankton-code-quality

Plankton コード品質スキル（Plankton Code Quality Skill）

Plankton（@alxfazio に感謝）の統合リファレンスです。Claude Code 向けの、コード作成時（Write-time）にコード品質を強制するシステムです。Plankton はツール呼び出し後フック（PostToolUse hooks）を通じてファイル編集のたびにフォーマッターと Linter を実行し、その後 Claude の子プロセス（Subprocess）を起動して、エージェント（Agent）が見逃した違反を修正します。

適用される場面

• コミット時だけでなく、ファイル編集のたびに自動でフォーマットとコードチェックを実行したい場合。
• コードを本当に修正するのではなく、Linter の設定を変更してチェックを回避するエージェントを防ぎたい場合。
• 修正タスクに対して、モデルを段階的に振り分けたい場合（単純なスタイルには Haiku、ロジックには Sonnet、型には Opus）。
• 複数の言語（Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile）で開発している場合。

仕組み

3 段階のアーキテクチャ

Claude Code がファイルを編集または書き込むたびに、Plankton の multi_linter.sh ツール呼び出し後フック（PostToolUse hook）が実行されます。

阶段 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 代码) — 120s 超时
│   ├─ Sonnet: 复杂性、重构 (C901, PLR 代码) — 300s 超时
│   └─ Opus: 类型系统、深度推理 (unresolved-attribute) — 600s 超时
├─ 重新运行阶段 1+2 以验证修复结果
└─ 如果清理完成则 Exit 0，如果仍存在违规项则 Exit 2（报告给主智能体）

メインエージェントに表示される内容

場面	エージェントに表示される内容	フックの終了コード
違反なし	なし	0
子プロセスがすべての問題を修正	なし	0
子プロセスの処理後も違反が残る	[hook] N violation(s) remain	2
提案情報 (重複、古いツール)	[hook:advisory] ...	0

メインエージェントに表示されるのは、子プロセスが修正できなかった問題だけです。品質に関する問題のほとんどは、透過的に解決されます。

設定の保護 (ルールの悪用への対策)

LLM は、コードを修正する代わりに .ruff.toml や biome.json を変更してルールを無効化しようとすることがあります。Plankton は 3 層の保護によってこれを防ぎます。

1. ツール呼び出し前フック（PreToolUse hook） — protect_linter_configs.sh が、変更前にすべての Linter 設定ファイルの編集を阻止します。
2. 停止フック（Stop hook） — stop_config_guardian.sh がセッション終了時に git diff で設定の変更を検出します。
3. 保護対象ファイルのリスト — .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml などが含まれます。

パッケージマネージャーの使用強制

Bash のツール呼び出し前フック（PreToolUse hook）は、古いパッケージマネージャーの使用を阻止します。

• pip, pip3, poetry, pipenv → 使用不可 (uv を使用してください)
• npm, yarn, pnpm → 使用不可 (bun を使用してください)
• 使用可能な例外: npm audit, npm view, npm publish

セットアップ

クイックスタート

# 将 Plankton 克隆到你的项目（或共享位置）
# 注: Plankton 由 @alxfazio 开发
git clone https://github.com/alexfazio/plankton.git
cd plankton

# 安装核心依赖
brew install jaq ruff uv

# 安装 Python linter
uv sync --all-extras

# 启动 Claude Code — 钩子将自动激活
claude

コマンドのインストールも、プラグインの設定も不要です。Plankton ディレクトリ内で Claude Code を実行すると、.claude/settings.json のフックが自動的に読み込まれます。

単一プロジェクトへの統合

独自のプロジェクトで Plankton のフックを使用するには：

1. .claude/hooks/ ディレクトリをプロジェクトにコピーします。
2. .claude/settings.json からフック設定をコピーします。
3. Linter 設定ファイル (.ruff.toml, biome.json など) をコピーします。
4. 使用する言語に対応する 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
コード品質の強制	ツール呼び出し後フック (Prettier, tsc)	ツール呼び出し後フック (20 以上の Linter + 子プロセスによる修正)
セキュリティスキャン	AgentShield, security-reviewer エージェント	Bandit (Python), Semgrep (TypeScript)
設定の保護	—	ツール呼び出し前フックで阻止 + 停止フックで検出
パッケージマネージャー	検出 + セットアップ	使用強制 (古いパッケージマネージャーを阻止)
CI 統合	—	git 用 Pre-commit フック
モデルの振り分け	手動 (/model opus)	自動 (違反の複雑さ → 対応する階層)

おすすめの組み合わせ

1. ECC をプラグイン（エージェント、スキル、コマンド、ルール）としてインストールします。
2. 作成時の品質強制用に Plankton のフックを追加します。
3. セキュリティ監査には AgentShield を使用します。
4. PR 前の最終ゲートには ECC の検証ループ（verification-loop）を使用します。

フックの競合を避ける

ECC と Plankton のフックを同時に実行する場合：

• ECC の Prettier フックと Plankton の biome フォーマッターが、JS/TS ファイルで競合する可能性があります。
• 解決方法：Plankton の使用中は、ECC の Prettier ツール呼び出し後フックを無効にします（Plankton の biome のほうが包括的です）。
• 異なるファイル形式であれば、両方を併用できます（Plankton が対象としていない内容を ECC が処理できます）。

設定リファレンス

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 に感謝）