plankton-code-quality

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)

메인 에이전트가 보는 것

상황	에이전트가 보는 것	훅 종료 코드
위반 없음	아무것도 없음	0
서브프로세스가 모두 수정	아무것도 없음	0
서브프로세스 후에도 위반 남음	[hook] N violation(s) remain	2
권고 수준(중복, 구형 도구 등)	[hook:advisory] ...	0

메인 에이전트는 서브프로세스가 해결하지 못한 문제만 봅니다. 대부분의 품질 문제는 투명하게 해결됩니다.

설정 보호(규칙 회피 방어)

LLM은 코드를 고치기보다 .ruff.toml, biome.json을 수정해 규칙을 꺼버리려 할 수 있습니다. Plankton은 이를 3계층으로 막습니다.

1. PreToolUse hook — protect_linter_configs.sh가 린터 설정 편집을 사전에 차단
2. Stop hook — 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은 저장소에서 수동 설치해야 합니다. 설치 전 코드를 검토하세요.

# Install core dependencies
brew install jaq ruff uv

# Install Python linters
uv sync --all-extras

# Start Claude Code — hooks activate automatically
claude

설치 명령이나 플러그인 설정은 별도로 없습니다. Plankton 디렉터리에서 Claude Code를 실행하면 .claude/settings.json의 훅이 자동 활성화됩니다.

프로젝트별 연동

자기 프로젝트에서 Plankton 훅을 쓰려면:

1. .claude/hooks/ 디렉터리를 프로젝트로 복사
2. .claude/settings.json의 훅 설정 복사
3. .ruff.toml, biome.json 등 린터 설정 파일 복사
4. 사용하는 언어의 린터 설치

언어별 의존성

Language	Required	Optional
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 hooks (Prettier, tsc)	PostToolUse hooks (20+ linters + subprocess fixes)
보안 스캔	AgentShield, security-reviewer agent	Bandit, Semgrep
설정 보호	-	PreToolUse 차단 + Stop hook 감지
패키지 매니저	Detection + setup	Enforcement
CI 연동	-	git용 pre-commit hooks
모델 라우팅	수동 (/model opus)	자동 (위반 복잡도 -> tier)

권장 조합

1. ECC를 플러그인으로 설치(agents, skills, commands, rules)
2. 쓰기 시점 품질 강제를 위해 Plankton 훅 추가
3. 보안 감사에는 AgentShield 사용
4. PR 전 최종 게이트로 ECC의 verification-loop 사용

훅 충돌 방지

ECC와 Plankton 훅을 함께 쓸 때:

• ECC의 Prettier 훅과 Plankton의 biome 포매터가 JS/TS 파일에서 충돌할 수 있습니다.
• 해결책: Plankton을 쓸 때는 ECC의 Prettier PostToolUse 훅을 끄는 것이 낫습니다. 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 — 위반 수가 이 값을 넘으면 더 높은 모델 tier로 자동 승격
• subprocess_delegation: false — 3단계를 건너뛰고 위반만 보고

환경 변수 오버라이드

Variable	목적
HOOK_SKIP_SUBPROCESS=1	3단계를 건너뛰고 위반만 바로 보고
HOOK_SUBPROCESS_TIMEOUT=N	tier timeout 강제 재정의
HOOK_DEBUG_MODEL=1	모델 선택 결정 로깅
HOOK_SKIP_PM=1	패키지 매니저 강제 차단 우회

참고 자료

• Plankton (credit: @alxfazio)
• Plankton REFERENCE.md — 전체 아키텍처 문서
• Plankton SETUP.md — 상세 설치 가이드

ECC v1.8 추가 사항

복사 가능한 훅 프로필

엄격한 품질 동작을 설정합니다.

export ECC_HOOK_PROFILE=strict
export ECC_QUALITY_GATE_FIX=true
export ECC_QUALITY_GATE_STRICT=true

언어별 게이트 표

• TypeScript/JavaScript: Biome 우선, Prettier는 fallback
• Python: Ruff format/check
• Go: gofmt

설정 변조 가드

품질 강제 중 같은 iteration 안에서 설정 파일 변경을 감지합니다.

• biome.json, .eslintrc*, prettier.config*, tsconfig.json, pyproject.toml

위반을 숨기기 위해 설정이 바뀌면, 머지 전에 명시적 리뷰가 필요합니다.

CI 연동 패턴

로컬 훅과 동일한 명령을 CI에서도 사용합니다.

1. formatter check 실행
2. lint/type check 실행
3. strict mode면 빠르게 실패
4. remediation summary 발행

건강도 지표

추적할 것:

• 게이트에 걸린 수정 수
• 평균 remediation 시간
• 카테고리별 반복 위반
• 게이트 실패로 인한 머지 차단 수