plankton-code-quality

name	plankton-code-quality
description	Plankton을 이용한 쓰기 시점 코드 품질 강제입니다. 훅을 통해 모든 파일 수정 시 자동 포맷, 린트, Claude 기반 수정까지 수행합니다.
origin	community

Plankton 코드 품질 스킬

Claude Code용 쓰기 시점 코드 품질 강제 시스템인 Plankton(credit: @alxfazio)의 통합 참고 문서입니다. Plankton은 PostToolUse 훅으로 모든 파일 수정 시 포매터와 린터를 실행하고, 에이전트가 놓친 위반은 Claude 서브프로세스로 다시 수정합니다.

사용 시점

• 커밋 시점이 아니라 파일 수정 때마다 자동 포맷/린트를 원할 때
• 에이전트가 코드를 고치지 않고 린터 설정을 바꿔 통과시키는 것을 막고 싶을 때
• 수정 난이도별 모델 라우팅이 필요할 때
  • Haiku: 단순 스타일
  • Sonnet: 로직
  • Opus: 타입
• 여러 언어를 함께 다룰 때(Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)

동작 방식

3단계 아키텍처

Claude Code가 파일을 수정하거나 쓸 때마다 Plankton의 multi_linter.sh PostToolUse 훅이 실행됩니다.

Phase 1: Auto-Format (Silent)
├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint)
├─ Fixes 40-50% of issues silently
└─ No output to main agent

Phase 2: Collect Violations (JSON)
├─ Runs linters and collects unfixable violations
├─ Returns structured JSON: {line, column, code, message, linter}
└─ Still no output to main agent

Phase 3: Delegate + Verify
├─ Spawns claude -p subprocess with violations JSON
├─ Routes to model tier based on violation complexity:
│   ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout
│   ├─ Sonnet: complexity, refactoring (C901, PLR codes) — 300s timeout
│   └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout
├─ Re-runs Phase 1+2 to verify fixes
└─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent)

메인 에이전트가 보는 것

상황	에이전트가 보는 것