Plankton Code Quality Skill
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 훅이 실행됩니다:
Phase 1: 자동 포맷 (무음)
├─ 포맷터 실행 (ruff format, biome, shfmt, taplo, markdownlint)
├─ 문제의 40-50%를 자동으로 수정
└─ 메인 에이전트에 출력 없음
Phase 2: 위반 사항 수집 (JSON)
├─ 린터를 실행하고 수정 불가능한 위반 사항을 수집
├─ 구조화된 JSON 반환: {line, column, code, message, linter}
└─ 여전히 메인 에이전트에 출력 없음
Phase 3: 위임 + 검증
├─ 위반 사항 JSON으로 claude -p 하위 프로세스 생성
├─ 위반 복잡도에 따라 모델 계층으로 라우팅:
│ ├─ Haiku: 포맷팅, 임포트, 스타일 (E/W/F 코드) — 120초 타임아웃
│ ├─ Sonnet: 복잡도, 리팩토링 (C901, PLR 코드) — 300초 타임아웃
│ └─ Opus: 타입 시스템, 심층 추론 (unresolved-attribute) — 600초 타임아웃
├─ Phase 1+2를 재실행하여 수정 사항 검증
└─ 깨끗하면 Exit 0, 위반 사항이 남으면 Exit 2 (메인 에이전트에 보고)
메인 에이전트가 보는 것
| 시나리오 | 에이전트가 보는 것 | 훅 종료 코드 |
|---|---|---|
| 위반 사항 없음 | 없음 | 0 |
| 하위 프로세스가 모두 수정 | 없음 | 0 |
| 하위 프로세스 후에도 위반 사항 남음 | [hook] N violation(s) remain | 2 |
| 권고사항 (중복, 오래된 도구) | [hook:advisory] ... | 0 |
메인 에이전트는 하위 프로세스가 수정하지 못한 문제만 확인합니다. 대부분의 품질 문제는 투명하게 해결됩니다.
설정 보호 (규칙 우회 방어)
LLM은 코드를 수정하는 대신 .ruff.toml 또는 biome.json을 수정하여 규칙을 비활성화할 수 있습니다. Plankton은 세 가지 계층으로 이를 차단합니다:
- 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 사전 커밋 훅 |
| 모델 라우팅 | 수동 (/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— Phase 3 완전히 건너뛰기 (위반 사항만 보고)
환경 변수 오버라이드
| 변수 | 목적 |
|---|---|
HOOK_SKIP_SUBPROCESS=1 | Phase 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에서 로컬 훅과 동일한 명령어 사용:
- 포맷터 검사 실행
- 린트/타입 검사 실행
- 엄격 모드에서 빠르게 실패
- 수정 요약 게시
건강 지표
다음 추적:
- 게이트가 플래그한 편집 횟수
- 평균 수정 시간
- 카테고리별 반복 위반 사항
- 게이트 실패로 인한 병합 차단 횟수