Plankton Code Quality スキル

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

使用時機

• ファイル編集時に自動フォーマットとリントを実行したい（コミット時だけでなく）
• エージェントがリンター設定を変更してコードを修正する代わりに合格させることに対する防御が必要
• 修正のための段階的なモデルルーティングが必要（Haiku for シンプルスタイル、Sonnet for ロジック、Opus for 型）
• 複数言語で作業している（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）
├─ リンターを実行して修正不可能な違反を収集
├─ 構造化 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 を再実行して修正を検証
└─ クリーンなら Exit 0、違反が残れば Exit 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 はすべてのリンター設定への編集が発生する前にブロック
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

セットアップ

クイックスタート

# Plankton をプロジェクト（または共有場所）にクローン
# 注: Plankton は @alxfazio によるもの
git clone https://github.com/alexfazio/plankton.git
cd plankton

# コア依存関係をインストール
brew install jaq ruff uv

# Python リンターをインストール
uv sync --all-extras

# Claude Code を起動 — フックは自動的にアクティベート
claude

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

プロジェクトごとの統合

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

1. .claude/hooks/ ディレクトリをプロジェクトにコピー
2. .claude/settings.json フック設定をコピー
3. リンター設定ファイル（.ruff.toml、biome.json など）をコピー
4. 言語用のリンターをインストール

言語別の依存関係

言語	必須	オプション
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	—

clarc との組み合わせ

補完的で、重複しない

関心事	clarc	Plankton
コード品質強制	PostToolUse フック（Prettier、tsc）	PostToolUse フック（20 以上のリンター + サブプロセス修正）
セキュリティスキャン	AgentShield、security-reviewer エージェント	Bandit（Python）、Semgrep（TypeScript）
設定保護	—	PreToolUse ブロック + Stop フック検出
パッケージマネージャー	検出 + セットアップ	強制（レガシー PM をブロック）
CI 統合	—	Git 用の pre-commit フック
モデルルーティング	手動（/model opus）	自動（違反複雑さ → 階層）

推奨される組み合わせ

1. clarc をプラグインとしてインストール（エージェント、スキル、コマンド、ルール）
2. 書き込み時品質強制用に Plankton フックを追加
3. セキュリティ監査に AgentShield を使用
4. PR 前の最終ゲートとして clarc の検証ループを使用

フック競合の回避

clarc と Plankton の両方のフックを実行する場合：

• clarc の Prettier フックと Plankton の biome フォーマッターは JS/TS ファイルで競合する可能性があります
• 解決策: Plankton を使用する場合は clarc の Prettier PostToolUse フックを無効化（Plankton の biome がより包括的）
• 両方は異なるファイルタイプで共存可能（clarc が 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）