Plankton コード品質スキル

Plankton（作者：@alxfazio）の統合リファレンスです。Plankton は Claude Code 用の執筆時コード品質強制執行システムです。PostToolUse フックを通じて、各ファイル編集時にフォーマッタと linter を実行し、その後 Claude サブプロセスを生成して、エージェントが検出できなかった違反を修正します。

使用時期

• ファイル編集のたびに自動フォーマットと検査を行いたい（コミット時だけでなく）
• エージェントが linter 設定を修正する代わりに変更して検査をパスするのを防ぎたい
• 修正用の階層化モデルルーティングが必要（簡単なスタイルは Haiku、ロジックは Sonnet、型システムは Opus）
• 複数の言語を使用している（Python、TypeScript、Shell、YAML、JSON、TOML、Markdown、Dockerfile）

仕組み

3段階アーキテクチャ

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 は 3 層の防御でこの動作を防止します：

1. PreToolUse フック — protect_linter_configs.sh が編集発生前に全 linter 設定への変更をブロック
2. Stop フック — stop_config_guardian.sh が git diff で設定変更を検出（セッション終了時）
3. 保護ファイルリスト — .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

セットアップ

クイックスタート

# Clone Plankton into your project (or a shared location)
# Note: Plankton is by @alxfazio
git clone https://github.com/alexfazio/plankton.git
cd plankton

# Install core dependencies
brew install jaq ruff uv

# Install Python linters
uv sync --all-extras

# Start Claude Code — hooks activate automatically
claude

インストールコマンドは不要で、プラグイン設定も不要です。Claude Code を実行すると、Plankton ディレクトリの .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
コード品質強制執行	PostToolUse フック (Prettier, tsc)	PostToolUse フック (20+ linter + サブプロセス修正)
セキュリティスキャン	AgentShield, security-reviewer エージェント	Bandit (Python), Semgrep (TypeScript)
設定保護	—	PreToolUse ブロック + Stop フック検出
パッケージマネージャ	検出 + セットアップ	強制執行（レガシーパッケージマネージャをブロック）
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 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 では本地フックと同じコマンドを使用：

1. フォーマッタチェックを実行
2. lint/型チェックを実行
3. 厳格モードで速く失敗
4. 修正サマリーを発行

ヘルスメトリクス

以下を追跡：

• ゲートによってフラグされた編集
• 平均修正時間
• カテゴリ別の反復違反
• ゲート失敗による マージブロック