Plankton コード品質スキル は何をしますか？
@alxfazio による Claude Code 向け書き込み時コード品質強制システム、Plankton の統合リファレンスです。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 を再実行して修正を検証
└─ 正常なら Exit 0、違反が残っていれば Exit 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
インストールコマンドやプラグイン設定は不要です。.claude/settings.json のフックは Plankton ディレクトリで Claude Code を実行すると自動的に認識されます。
プロジェクトごとの統合
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 を使用
- PR 前の最終ゲートとして ECC の検証ループを使用
フック競合の回避
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 でも使用:
- フォーマッターチェックを実行
- リンター/型チェックを実行
- 厳格モードで早期失敗
- 修正サマリーを公開
健全性メトリクス
追跡:
- ゲートでフラグ付けされた編集
- 平均修正時間
- カテゴリ別の繰り返し違反
- ゲート失敗によるマージブロック