플랑크톤 코드 품질 스킬

Plankton 코드 품질 스킬

Plankton(@alxfazio 제작)을 위한 통합 참조 문서입니다. Plankton은 Claude Code를 위한 작성 시점 코드 품질 강화 시스템으로, 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은 세 가지 계층으로 이를 차단합니다.

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

# 핵심 의존성 설치
brew install jaq ruff uv

# Python 린터 설치
uv sync --all-extras

# Claude Code 시작 — 후크가 자동으로 활성화됨
claude

설치 명령어나 플러그인 설정이 필요 없습니다. .claude/settings.json의 후크는 Plankton 디렉토리에서 Claude Code를 실행할 때 자동으로 인식됩니다.

프로젝트별 통합

자신의 프로젝트에서 Plankton 후크를 사용하려면:

1. .claude/hooks/ 디렉토리를 프로젝트에 복사
2. .claude/settings.json 후크 설정 복사
3. 린터 설정 파일(.ruff.toml, biome.json 등) 복사
4. 언어별 린터 설치

언어별 의존성

언어	필수	선택 사항
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)	자동(위반 복잡도 → 계층)

권장 조합

1. ECC를 플러그인(에이전트, 스킬, 명령어, 규칙)으로 설치
2. 작성 시점 품질 강제를 위해 Plankton 후크 추가
3. 보안 감사를 위해 AgentShield 사용
4. 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에서 사용:

1. 포매터 검사 실행
2. 린트/타입 검사 실행
3. 엄격 모드에서 빠르게 실패
4. 수정 요약 게시

상태 메트릭

추적 사항:

• 게이트에 의해 플래그된 편집
• 평균 수정 시간
• 카테고리별 반복 위반 사항
• 게이트 실패로 인한 병합 차단