herdr 오케스트레이션

분할된 작업 공간에서 여러 에이전트가 역할을 나누어 실전 과제를 완수하는 오케스트레이션

herdr는 터미널을 여러 칸(pane)으로 나눠 관리하면서, 각 칸에서 돌고 있는 코딩 에이전트의 상태까지 알아보는 도구다. 이 저장소는 herdr 위에서 서로 다른 런타임과 모델을 Head, Worker, Reviewer로 나눠 일한다. 오케스트레이션을 실제로 어떻게 굴리는지 이 저장소의 방식으로 보여 준다.

기준일: 2026-09-30. 모델 조합과 effort 값은 비용·품질·남은 사용량을 보고 정한 현재 세팅이며, 누구에게나 맞는 최적값은 아니다.

런타임 간 호출

herdr는 workspace, tab, pane 순으로 터미널을 묶고, pane 안의 에이전트 상태(idle, working, blocked, done)를 읽는다. 모든 조작이 herdr 명령으로 되므로, 에이전트가 셸 명령을 실행할 수 있으면 다른 에이전트에게 일을 시킬 수 있다.

Head가 다른 에이전트를 부르는 명령은 네 개면 된다.

herdr agent list                                    # 떠 있는 에이전트와 상태
herdr agent prompt sonnet "docs/plan.md의 C5a를 맡아라"  # 이름으로 지시
herdr agent wait sonnet --timeout 1800000           # 끝날 때까지 기다림
herdr agent read sonnet --source recent-unwrapped --lines 80   # 화면 내용 읽기

에이전트는 pane 안에서 계속 살아 있으므로 대화 맥락이 이어진다. 같은 Worker에게 후속 지시를 하면 앞선 작업의 컨텍스트가 남은 채로 이어서 작업한다. 창을 닫아도 pane이 유지되는 세션 관리는 tmux와 같은 계열의 기능이다.

에이전트는 pane 번호가 아니라 이름(herdr agent rename)으로 부른다. 번호는 세션마다 바뀔 수 있어서 문서나 스킬에 적어 두지 않는다.

보충: 설치와 에이전트 띄우기

기준일: 2026-09-30. macOS·Linux에서는 curl -fsSL https://herdr.dev/install.sh | sh 또는 brew install herdr로 설치한다. 마우스 중심으로 쓸 수 있고, tmux를 쓰던 사람에게는 prefix가 ctrl+b로 익숙하다. 상세는 herdr 공식 문서와 설치 안내를 따른다.

빈 셸 pane에서 에이전트를 시작하는 명령은 다음과 같다. <pane>은 herdr pane list로 확인한 값을 넣는다.

herdr pane split <pane> --direction right --no-focus
herdr agent start reviewer --kind codex --pane <새 pane>

지원하는 런타임 종류(claude, codex, opencode, agy 등)는 herdr agent를 실행하면 나온다. 전체 명령은 CLI 레퍼런스에 있다.

스킬·룰을 통한 사용법

에이전트에게 herdr 명령을 매번 설명하지 않는다. 룰에는 한 줄만 두고, 절차는 스킬에 둔다.

- 여러 에이전트 작업은 Head/Worker로 나누고 사용량을 분산한다(0002, `orchestration` 스킬).
- 작업 단위가 끝나면 Worker가 해당 변경만 커밋한다(orchestration 스킬). push는 요청 시에만.

룰은 항상 읽히므로 짧아야 하고, 필요할 때만 읽히는 스킬에는 상세를 넣는다. 이 저장소에서는 세 스킬이 역할을 나눠 맡는다. 룰과 스킬을 나누는 기준은 룰과 스킬에서 다룬다.

스킬	담는 내용
herdr	명령 사용법과 안전 규칙: 남의 pane 닫지 않기, 백그라운드는 --no-focus, 서버 중지 금지
orchestration	역할 표, 지시문 쓰는 법, 작업 단위 크기, 커밋 규칙
agent-usage	풀별 남은 사용량과 등급을 한 번에 조회하는 스크립트

Head·Worker·Reviewer 분담

가장 비싼 모델 하나가 모든 일을 하지 않는다. 좋은 모델은 방향 결정과 통합에 쓰고, 구현·조사·검토는 가성비 모델에 넘긴다.

역할	모델 (effort)	런타임
Head	Opus 5.5 (medium) 또는 Sol 6.1 (medium) 중 하나	claude / codex
Worker·Reviewer	Sonnet 5.5 (high)	claude
Worker·Reviewer	Gemini Flash 3.8 (high)	agy(Antigravity)
Worker·Reviewer	DeepSeek 4.1 Flash (max)	OpenCode
보조	GLM 5.3 (max)	OpenCode

• Head는 요구사항 파악, 작업 분할, Worker 선택과 지시, 결과 검토와 통합만 한다. 긴 원고 작성이나 긴 로그 읽기는 직접 하지 않고 넘긴다. Head가 직접 쓰기 시작하면 가장 비싼 사용량이 가장 흔한 일에 쓰이기 때문이다.
• Worker는 조사, 초안, 반복 수정을 맡는다. 난도 높은 작성은 Sonnet, 빠른 조사와 병렬 작업은 Gemini Flash, 저비용 반복은 DeepSeek을 먼저 고려한다. 고정된 배정이 아니라 기본값이다.
• Reviewer는 작성한 Worker와 다른 모델이 맡는다. 같은 모델이 자기 결과를 다시 보면 같은 판단을 되풀이하기 쉽다. 다른 모델이라고 반드시 더 나은 검토가 되는 것은 아니다.
• Worker 한 칸을 무료 모델(OpenCode 무료 활용)로 채워도 된다. 대신 그 결과는 반드시 다른 모델이 검토한다.

사용량 분배

프론티어 모델의 사용량은 무한하지 않다. 일을 맡기기 전에 agent-usage 스킬의 스크립트로 풀별 남은 양을 본다.

.agents/skills/agent-usage/scripts/usage.sh

풀은 모델이 아니라 요금제 기준이다. Opus와 Sonnet은 같은 Claude 풀을 쓰므로 하나로 센다. Opus가 Head면 Sonnet 배정을 줄이고, DeepSeek과 GLM처럼 같은 풀(OpenCode Go)을 쓰는 모델을 한꺼번에 몰아 쓰지 않는다.

등급	조건	배정
정상	아래 조건에 해당하지 않음	제한 없음
주의	5시간 또는 주간 잔량 20% 이하	대체하기 어려운 작업 위주
최후	주간 2% 이하 또는 5시간 5% 이하	대체 불가일 때만 하나씩
없음	잔량 1% 이하	배정하지 않음

프론티어 풀이 주의 이하인데 OpenCode Go가 남아 있으면 GLM을 Worker나 Reviewer로 더한다. 모델 선택을 고정값으로 두지 않고 작업 난이도, 남은 사용량, 모델별 비용, 필요한 품질을 보고 매번 조정한다.

배정할 때마다 docs/plan.md에 날짜, 작업, Worker, Reviewer를 한 줄로 남긴다. 어느 Worker에 일이 몰렸는지 이 기록으로 보고 같은 Worker에 연속 배정하지 않는다.

지시 작성 방식

지시문에는 범위, 고칠 파일, 완료 조건을 적는다. 긴 설명은 문서에 두고 지시문은 그 항목을 가리킨다.

sonnet, docs/plan.md '작업 카드: 콘텐츠 작성'의 C5a를 맡아라.
- 범위: docs/practice/opencode-free.md, herdr.md 본문
- 고칠 파일: 위 두 파일만. 용어 색인은 항목 추가만 허용
- 완료 조건: pnpm docs:build 통과 후 그 파일만 커밋
- 보고: 커밋 해시와 페이지별 소제목만

• 한 번에 맡기는 단위는 사람 기준 25~50분 분량이다. 50분을 넘길 것 같으면 나눠서 순서대로 지시한다.
• 여러 Worker에게 나눌 때는 고칠 파일이 겹치지 않게 하고, --wait 없이 보낸 뒤 herdr agent wait로 회수한다.
• "끝났다"는 보고만 믿지 않는다. 결과 파일과 git diff를 열어 본 뒤 Reviewer에게 넘긴다.
• Worker가 질문이나 선택 화면에서 멈추면(blocked) Head가 화면을 읽고 답한다. 승인·권한 요청은 사용자에게 묻는다.
• 작업 단위가 끝나면 Worker가 자기 변경만 커밋한다. 다른 에이전트가 작업 중인 파일은 섞이지 않게 뺀다.

보충: herdr 스킬의 안전 규칙

기준일: 2026-09-30. 이 저장소의 herdr 스킬은 여러 에이전트가 같은 화면을 공유하는 상황에서 사고를 막는 규칙을 둔다.

• 백그라운드 작업은 --no-focus로 띄워 사용자의 화면을 뺏지 않는다.
• 대상은 항상 이름이나 명시적 ID로 지정하고, 다른 클라이언트에서 포커스된 pane에 기대지 않는다.
• 내가 만들지 않은 workspace·tab·pane은 사용자가 요청하기 전에는 닫지 않는다.
• herdr server stop과 전역 설정 변경은 사용자가 명시적으로 원할 때만 한다.
• timeout은 전달 실패를 뜻하지 않는다. 같은 프롬프트를 다시 보내기 전에 agent read로 화면부터 확인한다.

herdr 자체에는 에이전트 권한 모델이 없다. 파일 삭제 같은 권한은 각 런타임의 설정이 맡는다. 자세한 권한 설정은 세팅: 권한과 화면 요소를 참고한다.

상위 티어 없이도 가능

이 방식의 목적은 여러 모델을 쓰는 것 자체가 아니다. 비싼 모델이 할 일은 줄이고, 저렴한 모델이 할 수 있는 일은 넘기고, 서로 다른 모델이 결과를 검토한 뒤, Head가 통합한다. 최고 모델 하나의 성능을 끌어올리기보다 여러 모델의 가격과 성능 차이를 이용해 전체 효율을 높인다.

• 최상위 모델이 아니어도 역할을 나누고 검토 단계를 두면 충분히 효율적으로 코딩할 수 있다.
• Head의 사용량을 방향 결정에 남겨 두고, 반복 작업은 저비용·무료 모델이 소화한다. 절약 방법은 토큰 절약을 참고한다.
• 검토를 다른 모델에 맡기면 무료·저비용 모델의 실수를 잡아낼 수 있다.

이 조합은 현재 사용 가능한 요금제와 사용량을 기준으로 정한 세팅이다. 모델과 요금제가 바뀌면 orchestration 스킬의 표를 고치고, 방침이 바뀌면 결정 기록(ADR)을 새로 쓴다.