pilotfish – Claude Code용 오케스트레이션 정책

그것이 무엇인가

pilotfish는 Anthropic의 AI 기반 코딩 어시스턴트인 Claude Code에 다중 모델 오케스트레이션 계층을 추가하는 정책 패키지입니다. 가벼운 "역할 에이전트"(예: 정찰병, 메크 실행기, 보안 검토자) 세트와 코딩 세션의 일부를 가장 비용 효율적인 모델로 자동 라우팅하는 디스패치 정책을 정의하며, 중앙 "메인 세션"(Opus 제품군)이 높은 수준의 계획과 최종 판단을 담당합니다.

왜 존재하는가

일반적인 Claude Code 세션은 반복적이고 위험이 낮은 작업(검색, 형식 지정, 테스트 스캐폴딩)에 많은 토큰을 소비합니다. pilotfish는 이러한 경계가 있는 작업을 더 저렴한 모델(Haiku, Sonnet)로 분할하고 계획, 보안 검토 및 검증에는 더 비싼 Opus 모델만 사용하므로 감독을 희생하지 않고 토큰 비용을 줄입니다.

작동 방식

• 역할 – 사전 정의된 에이전트 파일(~/.claude/agents/*.md). 각각 특정 모델과 노력 수준(낮음/중간/높음)에 바인딩됩니다.
• 정책 – 상호 작용 형태(co_discover, explore_then_plan, execute)와 작업의 난이도에 따라 호출할 역할을 결정하는 CLAUDE.md 블록.
• 디스패치 흐름 – 메인 세션(Opus)이 오케스트레이션하고, 저장소 정찰을 위해 정찰병, 기계적 코드 생성을 위해 메크 실행기, 판단이 많이 필요한 구현을 위해 실행기, 결과를 반증하기 위한 검증자(새 Opus 컨텍스트)를 호출할 수 있습니다. 보안 관련 작업은 읽기 전용 검토자와 중간 노력 실행기를 통과합니다.
• 노력 수준 – 정책은 Claude Code의 CLAUDE_CODE_EFFORT_LEVEL 재정의를 존중합니다. 그렇지 않으면 역할별로 노력 수준을 선택합니다(예: scout = 낮음, plan-verifier = 중간, security-reviewer = 높음).

설치 옵션

1. 플러그인(macOS / Linux) – install/PLUGIN-INSTALL.md를 통한 네이티브 마켓플레이스 설치. 정책을 후크 기반 플러그인으로 추가합니다. Claude Code 2.1.219+ 및 Linux의 경우 Ubuntu 20.04+/Debian 10+/Alpine 3.19+가 필요합니다.
2. 레거시 전역 설치 – 태그가 지정된 릴리스(예: v1.5.0)를 클론하고 정책 파일을 ~/.claude/에 쓰는 런북으로 Claude Code를 실행합니다. 설치 프로그램은 멱등적이며 변경 전에 병합 계획을 표시합니다.

시스템 운영

• 제공된 CLI 래퍼(/pilotfish) 또는 플러그인 UI를 사용하여 세션에 정책을 활성화합니다.
• docs/usage.md를 통해 모델 별칭, 노력 임계값을 조정하거나 위임을 활성화/비활성화합니다.
• 모든 변경 사항은 되돌릴 수 있습니다. 설치 프로그램은 8개의 역할 파일과 정책 블록을 제거할 수 있습니다.

문서 및 증거

• 상세 설계(docs/design.md), 모델 경제성 연구(docs/research.md) 및 현장 보고 로그가 포함되어 있습니다.
• 벤치마크(디스패치 브레이크, 자발적 디스패치, 배턴 활성화, 프롬프트 압축, 검증자 경계)는 위임이 발생하는 빈도와 토큰 영향에 대한 경험적 한계를 제공합니다.

누가 사용해야 하는가

• 대규모 코딩 세션에서 Claude Code에 의존하고 토큰 비용을 낮추면서 안전 검사를 유지하려는 개발자.
• AI 워크플로에 구조화된 보안 검토 및 검증 단계를 통합해야 하는 팀.
• macOS 또는 Linux에서 Claude Code 구성 파일 편집 및 플러그인 설치 관리에 익숙한 고급 사용자.

성숙도

• MIT 라이선스이며 버전 관리된 릴리스 기록과 변경 로그가 있습니다.
• 동작 호환성에 대한 주장은 유료 모델 실행으로 뒷받침됩니다. 지속적인 후원은 추가 검증 자금을 지원합니다.
• Windows는 지원되지 않습니다. Linux 지원은 "계약 자격"입니다(테스트되었지만 공식적으로 검증되지는 않음).

---

위의 모든 정보는 저장소의 README에서 직접 가져온 것입니다. 추가 기능은 추론되지 않습니다.