Planktonコード品質スキル は何をしますか？
Plankton（クレジット: @alxfazio）の統合リファレンス。Claude Code向けの書き込み時コード品質強制システム。PlanktonはPostToolUseフックを介してファイル編集ごとにフォーマッターとリンターを実行し、エージェントが見逃した違反を修正するためにClaudeサブプロセスを起動します。
使用タイミング
- ファイル編集ごとに自動フォーマットとリンターを実行したい場合（コミット時だけでなく）
- エージェントがリンター設定を改変してルールを回避するのを防ぐ必要がある場合
- 修正に階層型モデルルーティングを使用したい場合（スタイルは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）
├─ リンターを実行し、修正不能な違反を収集
├─ 構造化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つのレイヤーでこれをブロックします:
- PreToolUseフック —
protect_linter_configs.shがリンター設定への編集をブロック - 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はリポジトリから手動でインストールする必要があります。インストール前にコードを確認してください。
# コア依存関係のインストール
brew install jaq ruff uv
# Pythonリンターのインストール
uv sync --all-extras
# Claude Codeの起動 — フックが自動的に有効化されます
claude
インストールコマンドやプラグイン設定は不要です。PlanktonディレクトリでClaude Codeを実行すると、.claude/settings.jsonのフックが自動的に認識されます。
プロジェクトごとの統合
自分のプロジェクトでPlanktonフックを使用するには:
.claude/hooks/ディレクトリをプロジェクトにコピー.claude/settings.jsonのフック設定をコピー- リンター設定ファイル（
.ruff.toml、biome.jsonなど）をコピー - 使用する言語のリンターをインストール
言語別依存関係
| 言語 | 必須 | オプション |
|---|---|---|
| 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+リンター＋サブプロセス修正） |
| セキュリティスキャン | AgentShield、security-reviewerエージェント | Bandit（Python）、Semgrep（TypeScript） |
| 設定保護 | — | PreToolUseブロック＋Stopフック検出 |
| パッケージマネージャー | 検出＋セットアップ | 強制（レガシーPMをブロック） |
| CI統合 | — | git用Pre-commitフック |
| モデルルーティング | 手動（/model opus） | 自動（違反の複雑さ→階層） |
推奨される組み合わせ
- ECCをプラグインとしてインストール（エージェント、スキル、コマンド、ルール）
- Planktonフックを書き込み時品質強制として追加
- AgentShieldをセキュリティ監査に使用
- ECCの検証ループをPR前の最終ゲートとして使用
フックの競合回避
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で使用:
- フォーマッターチェックを実行
- リンター/型チェックを実行
- 厳格モードで早期失敗
- 是正サマリーを公開
健全性メトリクス
追跡:
- ゲートでフラグされた編集
- 平均是正時間
- カテゴリ別の繰り返し違反
- ゲート失敗によるマージブロック