Nanako0129/pilotfish

pilotfish – Claude Code 에이전트 오케스트레이션

개요

• Claude Code (Anthropic의 코딩 어시스턴트)가 프로그래밍 세션을 여러 개의 경량 "role agent"로 분할할 수 있게 해주는 정책 패키지입니다.
• 각 역할은 비용과 성능을 위해 선택된 서로 다른 Claude 모델 (Opus, Sonnet, Haiku)에서 실행됩니다. 이를 통해 메인 세션은 고수준의 계획 및 판단에 집중할 수 있고, 더 저렴한 모델이 반복적이거나 위험도가 낮은 작업을 처리할 수 있습니다.

중요성

• 긴 코딩 세션에서는 핵심 설계 결정보다는 검색, 리팩토링, 테스트 및 문서화에 대부분의 토큰이 소비됩니다.
• pilotfish는 이러한 제한된 작업들을 자동으로 저렴한 모델로 라우팅하여 토큰 비용을 줄이고, 메인 모델이 최첨단 추론 및 최종 승인에 집중할 수 있도록 유지합니다.

작동 방식

1. 설치 – Claude Code의 네이티브 플러그인 라이프사이클에 연결되는 Plugin (macOS/Linux) 또는 ~/.claude/ (또는 사용자 정의 CLAUDE_CONFIG_DIR) 아래에 파일을 작성하는 legacy global 설치 방식이 있습니다.
2. 정책 파일 –
   • settings.json은 메인 모델 별칭 (Opus 계열) 및 폴백 체인을 정의합니다.
   • agents/*.md는 각 역할 (예: scout, mech-executor, security-reviewer)을 설명합니다.
   • CLAUDE.md에는 작업을 메인 세션에 유지할지 아니면 역할에 위임할지 결정하는 디스패치 로직이 포함되어 있습니다.
3. 디스패치 흐름 – Claude와 상호작용할 때, pilotfish는 상호작용 형태 (예: co_discover, explore_then_plan, execute)를 검토합니다. 형태에 따라 다음과 같이 수행할 수 있습니다:
   • 저장소 정찰을 위해 저비용의 scout (Haiku)를 호출합니다.
   • 제안된 계획에 이의를 제기하기 위해 plan-verifier (Opus)를 사용합니다.
   • 기계적인 반복 작업은 mech-executor (Sonnet)에게 넘기고, 승인 후 위험도가 높은 코드는 executor (Sonnet)에게 넘깁니다.
   • 구현 후 결과의 오류를 증명하기 위해 verifier (새로운 Opus 컨텍스트)를 실행합니다.
   • 보안 민감 작업은 security-reviewer 및 security-executor (둘 다 Opus, 읽기 전용 후 고수준 작업)를 통해 라우팅합니다.
4. 정책은 CLAUDE.md 내부의 마크다운 블록 (pilotfish:begin/end)으로 표현됩니다. Claude는 매 세션마다 이를 읽으므로 동작이 자동으로 적용됩니다.

설치 단계 (요약)

• Plugin beta – install/PLUGIN-INSTALL.md를 따릅니다. macOS (Claude Code 2.1.239) 및 Linux (Ubuntu 20.04+, Debian 10+, Alpine 3.19+)에서 작동합니다. Claude Code 2.1.219+가 필요합니다. 플러그인은 유일한 설치 방식이어야 합니다 (legacy global 설치와 공존할 수 없습니다).
• Legacy global – 태그된 릴리스의 저장소를 클론하고, claude를 실행하여 install/AGENT-INSTALL.md의 런북을 따르도록 요청합니다. 설치 프로그램은 병합 계획을 보여주고, 기존 파일을 백업하고, 멱등성을 보장합니다.

시스템 운영

• 동일한 설치 가이드를 통해 플러그인을 활성화/비활성화하거나 업데이트할 수 있습니다.
• docs/usage.md에서 모델 선택, 노력 수준, 또는 위임 규칙을 조정할 수 있습니다.
• 세션을 위해 pilotfish를 활성화하려면 제공된 /pilotfish 명령어나 CLI 래퍼를 install/ACTIVATION-INSTALL.md에서 설명된 대로 실행합니다.
• Claude에게 설치 제거 런북을 실행하도록 요청하여 8개의 에이전트 파일과 정책 블록을을 제거함으로써 안전하게 삭제할 수 있습니다.

증거 및 연구

• 저장소에는 설계 노트, 경제적 분석, 및 현장 보고서 문서 (docs/design.md, docs/research.md)가 포함되어 있습니다.
• spontaneous-dispatch 및 dispatch-brake와 같은 벤치마크는 위임이 얼마나 자주 발생하는지에 대한 행동 관찰 결과를 제공합니다.

사용 대상

• Claude Code에서 많은 시간을 보내며 토큰 비용을을 낮추고 싶은 개발자.
• 저위험 자동화와 고위험 판단을 것을지를 위해 재현 가능한 정책 기반 방식이 필요한 팀.
• 멀티 모델 오케스트레이션 및 위험 인지 AI 어시스턴스에 관심이 있는 연구자.

라이선스 및 지원

• MIT 라이선스.
• 저자는 유료 모델 검증 실행을 위한 자금을 마련하기 위해 Patreon을 통한 후원을 요청합니다.

---

모든 상세 내용은 저장소의 README에서 직접 가져왔습니다. 추가적인 기능은 추론되지 않았습니다.