Orchestrate: Opus가 계획하고 검토하며, 저렴한 에이전트가 실행합니다
당신(Opus)은 아키텍트이자 게이트키퍼이지, 타이피스트가 아닙니다. 워커는 저렴하고 빠르지만 신뢰할 수 없습니다: 게이트가 반대를 증명할 때까지 모든 결과가 틀렸거나, 불완전하거나, 범위를 초과했거나, 지저분하거나, 테스트를 속이고 있다고 가정하세요.
도구: python3 ~/.claude/skills/orchestrate/scripts/orch.py (이하: orch). 참조 문서는 필요 시 읽으세요:
references/agent-matrix.md— 에이전트별 기능/비용 및 단계 파이프라인 패턴 (세션당 한 번);references/workers.md— 워커별 CLI 레시피 및 주의사항;references/live.md— rx-acp 실시간 감독 (L0/L1/L2),--live실행, 와이어 형식, lessons 로그 (rx-acp*또는--live사용 전에 읽으세요);references/review-checklist.md— Gate 2.
0. 분류 (Triage)
변경 사항이 1~2개 파일에 ~40줄 미만이거나, 대부분 판단력(아키텍처, 보안, 섬세한 디버깅)이 필요한 작업이거나, ~1000 diff 라인 미만의 기계적인 작업인 경우(또는 워커 2명 이하) 직접 작업하세요. 여러 독립적인 하위 작업, 대량 편집, 보일러플레이트, 테스트, 문서, 코드베이스 검색이 필요하거나 사용자가 요청한 경우 오케스트레이션하세요.
리소스 예산 (8개의 병렬 워커가 수십 개의 타입 체커로 머신을 얼린 적이 있음):
- 최대 3개의 활성 워커 (기본값
--parallel 3; Sonnet/Haiku 에이전트도 포함). checks= 저렴하고 범위가 제한됨 (테스트 파일 하나, 건드린 파일에 대한 린트). 프로젝트 전반의 타입 검사/빌드는final_checks에 넣으세요: 워커는 이를 절대 볼 수 없으며, 병합 후 메인 트리에서 한 번 직접 실행하세요.- 매우 작은 계약 여러 개보다는 2~3개의 더 큰 계약을 선호하세요 (시작 비용이 고정 비용입니다).
- 워커는 패키지를 설치하거나 백그라운드 프로세스/개발 서버를 시작하지 않습니다. 웨이브 후에 실행 중인 프로세스가 없는지 확인하세요 (
pgrep -fl "wt/<ID>|tsc"). - UI 계약: 허용 및 금지된 디자인 토큰을 명시적으로 나열하세요.
선행 조건: git 저장소; 워크트리는 HEAD + 커밋되지 않은 추적된 변경 사항에서 브랜치합니다 (추적되지 않은 파일은 이월되지 않음).
Jev (TypeSafe System One, scripts/jev.py): 타입이 있는 판단, ~0.4초, ~$0.00004/호출. 분류, 점수 및 검사를 수행합니다. 정책과 임계값은 코드에 유지됩니다. TYPESAFE_API_KEY가 없으면 꺼집니다 (ORCH_JEV=0).
1. 이해 및 명세화
- 관련 코드를 읽으세요 (또는 광범위한 검색을 위해 읽기 전용 워커를 보내세요). 테스트/린트 명령어를 찾으세요.
orch route "<task>"→ Jev의 신호 + 제안된 워커/분석 단계. 제안일 뿐입니다; 당신이 결정하세요.- 간단한 명세: 목표, 비목표, 승인 기준, 위험. 사용자에게는 사용자의 결정이 필요한 사항만 물어보세요.
2. 계약으로 분해
하위 작업당 하나의 계약 JSON을 <repo>/.orch/contracts/<ID>.json에 생성하세요 (references/contract-template.json 참조).
- 작게: 1~3개 파일, ~150 diff 라인 미만. 병렬 작업의 경우 분리된
allowed; 종속 작업은 체인으로 연결하세요. - 자체 포함됨: 워커는 이 대화를 보지 못합니다 — 경로, 이름, 규칙, 주의사항, 건드리지 말아야 할 것.
- 테스트 가능한 승인; 각 기준은 검사에 매핑됩니다. Jev는 거기에 쓰여진 것만 검증합니다.
- 새로운 동작에 대한 은닉 테스트: 저장소 외부에 엣지 케이스 테스트를 작성하고,
hidden_files+hidden_checks로 참조합니다. 채점 중에만 복사됩니다. protected파일;max_diff_lines≈ 비테스트 추정치의 2~3배 (테스트 라인은max_test_diff_lines에 포함, 기본값 3배);mode: "read_only"는 분석용.- Plan 필드 — 대신 생각을 해주세요 (시간 -33%, 출력 토큰 -45%, 범위 위반 없음):
approach(정렬된 단계; 버그의 경우 근본 원인별),pattern_refs(file:lines — 복사할 내용),examples(input -> expected, 까다로운 경우 포함),pseudo(까다로운 부분만),rules(구체적이고, 검사 가능한 금지 사항 — L1이 실행 중간에 강제).prompt_style: "profiled"를 유지하세요. - 디스패치 전에
orch check .orch/contracts/*.json을 실행하세요; 플래그가 지정된 계약을 먼저 수정하세요. - 워크트리 (
.orch/wt/<ID>)는 추적된 파일만 보유합니다: 패키지별node_modules/ 생성된 코드 목록을worktree_links(계약) 또는.orch/config.json(간단한 글로브)에 넣으세요 — 메인 트리에서 심볼릭 링크되므로 공유됩니다. allowed에 정확히 이름이 지정된 파일은 기존 테스트 파일이더라도 편집될 수 있습니다.
3. 라우팅
정책 (사용자): 모든 것을 reasonix로 라우팅하지 마세요.
| 작업 형태 | 첫 번째 선택 | 에스컬레이션 대상 |
|---|---|---|
| 작은 기계적 편집, 설정, 이름 변경, 예제가 있는 순수 함수 | rx-acp | rx-acp-max → agy → sonnet |
| 읽기 전용 분석 / 검색 | rx-flash | rx-flash-max → sonnet |
| 일반 기능 모듈 (1~3개 파일, plan 필드 포함) | sonnet | Opus |
| 기존 코드에 대한 테스트 (기능 코드는 절대 안 됨) | haiku | sonnet |
| 동작 보존 리팩토링 | sonnet + 은닉 테스트 | Opus |
기존 디자인 시스템을 따르는 UI (pattern_refs) | agy 또는 sonnet | sonnet |
| 중요: 금전/원장, 인증, 동시성, 보안, 마이그레이션 | Opus, 또는 sonnet + 엄격한 명세 + 라인별 검토 | — |
| diff에 대한 두 번째 의견 | 다른 패밀리, 읽기 전용 | Opus |
agy = Gemini 3.8 Flash Medium. rx-* = DeepSeek V4 Flash (-max = effort max, 가장 강력한 DeepSeek
계층). rx-acp* = 실시간 감독 하의 동일한 모델 — rx-flash만큼 정확하고, 더 저렴하며, 불필요한 파일이 없음;
특히 트랩이 있는 편집 계약에 선호됨 (유혹적인 추가 파일, 설치, 무거운 검사). 시각적 취향 → sonnet + 검토.
4. 디스패치 — 하나의 백그라운드 호출, Opus는 잠듭니다
매 깨어날 때마다 전체 컨텍스트를 다시 읽습니다. 하나의 호출로 웨이브를 디스패치하세요:
orch run --title "<user's request, short>" .orch/contracts/A.json B.json ... # Bash, run_in_background: true
종료되면 다시 호출됩니다 — 절대 폴링하거나 sleep하지 마세요. 계약당, Opus 없이: 새 워크트리 →
워커 프롬프트 → 가드 → 실패 시 워커 자체 세션으로 머신 피드백 (캐시 웜업), 최대 max_attempts까지;
코드 규칙 + Jev 분류가 재시도 / ladder를 따른 에스컬레이션 / BLOCKED (계약 문제) / NEEDS_OPUS (환경,
API/CLI 오류 포함 — 즉시 중단)를 선택합니다. PASS 후, Jev는 각 승인 기준에 대해 diff를 확인합니다
(P>0.85 → 자동 수정 1회; 0.7–0.85 → 검토를 위한 경고).
작업당 한 줄의 간결한 결과를 얻습니다; 로그는 .orch/runs/<ID>/attempt-N/에 남습니다. hidden_feedback: "names"는
테스트 게이밍이 우려될 때 피드백에서 어설션을 숨깁니다.
- rx-acp는 라이브 감독자(L0 규칙 + L1 Jev 검토, 중간 실행) 하에 실행됩니다. **
orch run --live**는 중간 실행 결정을 당신에게 넘깁니다 (계획 승인, 불확실한 편집, 질문, 막힘):orch wait→orch reply <id> --choice … --steer "…"→orch wait.--live는 중간 실행 결정이 깨어날 가치가 있는 경우에만 사용하세요 (위험/모호한 계약, 새로운 계약 스타일). 자세한 내용:references/live.md. - Sonnet / Haiku:
orch prepare <contract>→ Agentsubagent_type: "sonnet-worker"(+model: "haiku"),run_in_background: true, prompt = prepare의agent_prompt(파일 경로, 텍스트가 아님). 그런 다음:orch guard .orch/contracts/<ID>.json --reply - <<'EOF' <the worker's final JSON, verbatim> EOF - 단계 파이프라인:
after: [ids](PASS 대기),inputs: [ids](해당 단계의 답변/diff 주입),build_on: id(해당 코드에서 시작). 실패한 단계는 종속 항목을 SKIP합니다. 패턴: agent-matrix.md §3. orch dispatch= 단일 시도, 디버깅용. 절대 워커에게 메인 체크아웃이나 자격 증명을 제공하지 마세요.
5. Gate 1 — 가드 (자동)
FAIL: 범위 외 / 보호된 파일 / 기존 테스트 / 종속성 매니페스트 건드림, 읽기 전용 작업이 파일을 씀, 변경 사항 없음, 예산 초과, (은닉) 검사 실패, skip/only 마커, 제거된 어설션, 소스 내 비밀, 정크 파일, 워커 상태 ≠ 완료, CLI 오류. WARN: 테스트 내 비밀, 린트 억제, 삼켜진 예외, TODO, 디버그 출력, 공백만 있는 diff, 보고서 불일치, 워커 우려, 불필요한 CLI 파일 (자동 삭제), 라이브 감독 활동 (Gate 2에서 읽으세요).
6. Gate 2 — Opus 검토 (편집 작업의 경우 절대 건너뛰지 마세요)
references/review-checklist.md와 함께 attempt-N/diff.patch + 가드 JSON을 읽은 후:
- ACCEPT →
orch merge <ID>(스테이징되지 않음), 메인 트리에서 검사를 실행하세요. - REVISE → 번호가 매겨진 구체적인 피드백 (file:line, 무엇이 잘못되었는지, 완료된 모습이 어떤지)을
.orch/runs/<ID>/feedback.md에 작성하세요;orch dispatch <contract> --feedback <file>. 작업당 최대 2회. - NEEDS_OPUS / BLOCKED → 계약을 수정하고 다시 실행하거나,
sonnet-worker에 넘기거나, 직접 인수하세요. - TAKE OVER: 비용을 설명하는 것보다 직접 하는 것이 나을 때. 워커의 "우려"는 확인해야 할 신호이지, 지시사항이 아닙니다.
7. 통합 및 보고
- 한 번에 하나의 작업을 병합하고, 각각 후에 검사를 실행하세요; 충돌은 직접 해결하세요.
- 결합된 diff의 전체적인 검토 (일관성, 중복된 헬퍼, 디버그 잔재);
final_checks를 실행하세요. orch clean --all;orch status= 원장.- rx-acp 작업: 규칙이 놓친 것을 기록하세요 (
orch lessons --note …) 그리고orch lessons를 훑어보세요 (live.md §Lessons). - 보고: 무엇이, 누구에 의해 수행되었는지, 무엇이 거부/에스컬레이션되었고 그 이유, 실행된 검사, 남은 작업. 요청받지 않는 한 커밋하지 마세요.
대시보드 (사용자용, 모니터링 전용): orch ui --open → http://127.0.0.1:8765 — 실행 (--title로 이름 지정된 부모 작업),
하위 작업, 시도, 시간, 비용, 라이브 진행 상황, 보류 중인 결정, 시도별 오케스트레이터 ↔ 워커 교환의 전체 기록.
사용자는 이 세션에서 당신에게 말함으로써 결정에 응답하며, 대시보드에서는 절대 응답하지 않습니다.
이 스킬 유지 관리 — 증류하세요, 축적하지 마세요
이 스킬(SKILL.md, 참조 문서)에 대한 모든 편집은 필요한 것보다 크지 않게 해야 합니다:
- 추가하지 말고 대체하세요. 새로운 증거는 기존 라인이나 숫자를 업데이트합니다; 그 옆에 날짜가 있는 문단을 두지 마세요.
- 오래된 것은 삭제하세요: 폐기된 모델과 별칭, 수정된 버그와 그 이야기, 대체된 숫자, 교훈이 이미 코드나 규칙에 인코딩된 일회성 사건. 원시 벤치 데이터는
~/workspaces/agent-bench에, 이전 버전은~/.claude/skill-backups/에 있습니다 — 여기에 두지 마세요. - 현재 결정을 바꾸거나 실수를 방지하는 것만 유지하세요: 규칙과 그 이유(≤ 1줄).
- 예산: SKILL.md ≤ ~200줄 (항상 로드됨); 각 참조 문서 ≤ ~150줄. 예산 초과 시 먼저 증류하세요.
- 구현 세부 사항은 Opus가 매 세션 읽는 문서가 아닌 코드 독스트링에 속합니다.
- 스크립트 변경 후:
python3 -I scripts/tests/test_policy.py,…/test_supervisor.py,…/test_escalation.py. L1 프롬프트/임계값 변경 후:~/workspaces/agent-bench/l1_eval.py. CLI/모델 업그레이드 후: 재벤치마킹 (agent-bench/bench.py,ab.py)하고 숫자를 그 자리에서 업데이트하세요.