Herdr Multiagent: 병렬 코딩 에이전트 워크플로우

--- name: herdr-multiagent description: Run several coding agents in parallel under Herdr: stage decomposition, one git worktree, isolated env, pane and file brief per agent, state monitoring, review, merge. Child kind is read from `herdr pane current` (.result.pane.agent) and matches the orchestrator (omp, opencode, claude, codex, kimi, ...). Requires HERDR_ENV=1. --- # 멀티에이전트 작업 via Herdr 플레이북: 프로젝트 작업을 독립적인 단계로 분해하고, 각 단계에 별도의 에이전트를 자체 git worktree 및 herdr-pane에 배치하고, 파일 브리프를 발행하고, 모니터링하고 결과를 수락합니다. 스킬은 에이전트 독립적입니다: 자식 kind = 오케스트레이터 kind. opencode에서 스킬을 시작하면 자식은 opencode, omp에서 시작하면 omp, claude에서 시작하면 claude입니다. 오케스트레이터 kind를 기억에서 추측하거나 "인기 있는" kind를 선택하지 마십시오. ## 0. 사전 조건 ```bash test "${HERDR_ENV:-}" = 1 # 이 값이 없으면 중지 - 우리는 Herdr 내부에 있지 않음 ``` 검사가 실패하면 사용자에게 세션이 Herdr 아래에 있지 않다고 말하고 중지합니다. 외부에서 다른 Herdr을 관리하지 마십시오. 기본 pane/agent 명령은 표준 Herdr 스킬(`herdr --skill`)에 있습니다. 설치된 바이너리가 구문의 권위자입니다. 의심스러우면 추측하지 말고 `herdr agent`, `herdr pane`, `herdr integration`을 읽으십시오. ## 1. 자신의 kind 결정 - 어떤 작업보다 먼저 ```bash herdr pane current --current ``` `.result.pane.agent` 필드가 오케스트레이터 kind이며, 자식의 `--kind` 값이기도 합니다: ```bash KIND=$(herdr pane current --current | jq -r '.result.pane.agent') # jq 없이: KIND=$(herdr pane current --current | sed -E 's/.*"agent":"([^"]+)".*/\1/' | head -1) echo "$KIND" ``` 비어 있거나 `unknown`이면 사용자에게 어떤 kind로 자식을 시작할지 묻습니다. 이후 본문에서 `$KIND`는 리터럴이 아닌 얻은 값입니다. Herdr ↔ 이 kind 통합 확인(agent list/wait/prompt 제공): ```bash herdr integration status | grep -i "$KIND" ``` - `current` - 정상. - `not installed` - `herdr integration install "$KIND"`. 통합은 **새로운** 세션에서만 인식되므로 자식 시작 전에 설치해야 합니다. 오케스트레이터 자체는 `agent list`에 보이지 않습니다 - 정상이며 모니터링할 필요가 없습니다. - kind가 `herdr integration install` 목록에 없으면(예: `amp`, `cline`, `kiro`, `maki`) 구조적 모니터링이 불가능하며 §7(`pane read` + git)의 폴백으로 작업합니다. 이것은 차단 요인이 아닙니다. 기록하고 사용자에게 선언: "자식 kind = $KIND". ## 2. 분해 - 가장 중요한 단계, 서두르지 마십시오 - 프로젝트 계획/스펙 및 현재 상태(`git log`, 테스트, `git worktree list`)를 읽습니다. - 남은 작업을 **겹치지 않는 파일 영역**을 가진 단계로 나눕니다. 한 패키지에 두 에이전트 - 명시적 순서로만 의식적으로(병렬이 아닌 이후). - 공유 파일(config, lock)에 대한 추가적 변경은 허용됩니다 - 브리프에 "시그니처 변경 없이 추가적으로만" 기록하고 병합 충돌은 오케스트레이터가 해결합니다. - "단계 → 수정 가능/불가능 파일" 매트릭스를 기록합니다. 시작 전: main의 완성된 모든 것이 커밋되고 트리가 깨끗합니다. ## 3. Worktree + 에이전트별 격리된 환경 ```bash git worktree add ../<proj>-s<N> -b stage-<N>-<name> ``` Python 프로젝트의 함정: 공유 venv는 다른 코드를 가져옵니다(메인 저장소의 editable install). 각 worktree에 자체 venv: ```bash cd ../<proj>-s<N> && python -m venv .venv \ && ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]" ``` 여러 venv는 하나의 백그라운드 명령으로 순차적으로 설치합니다(공통 pip 캐시). JS 스택: 각 worktree에 자체 `node_modules`(`npm ci`). 오케스트레이터에 명령 래퍼 훅(rtk 등)이 있는 경우: 브리프의 상대 경로(`../.venv/Scripts/python.exe`)는 해당 훅을 통해 해석되지 않습니다("command not found"). 브리프 및 프롬프트에는 해당 worktree의 python/npm에 대한 **절대** 경로만 사용하십시오. ## 4. 브리프 - 명령줄이 아닌 파일로 `<repo>/.briefs/stage-<N>.md` (untracked). 브리프 구조: - **컨텍스트**: 먼저 읽을 것(스펙, 계약, 핵심 파일), 이미 완료된 것; - **작업**: 스펙 항목에 대한 링크가 있는 구체적인 요구사항; - **경계**: 수정 가능/불가능 파일, "worktree 밖으로 나가지 마십시오", "push 하지 마십시오"; - **수락**: 정확한 테스트/린터 명령(worktree 인터프리터의 절대 경로 포함), "기존 테스트는 계속 통과", 자체 브랜치에 커밋, 최종 보고서. 브리프는 특정 에이전트 kind를 가정하지 않아야 합니다: "omp/skill/... 실행"이라고 쓰지 말고 목표, 경계 및 수락 명령을 쓰십시오. 자식이 자신의 도구로 수행 방법을 결정합니다. 에이전트 프롬프트는 짧게: "파일 <브리프>를 읽고 끝까지 실행하십시오." ## 5. Pane: 생성 후 즉시 이름 지정 권장 레이아웃 - main-left: 오케스트레이터 pane은 왼쪽 전체 높이, 모든 자식은 오른쪽에 세로로 쌓입니다. 사용자가 main-left용 레이아웃 플러그인을 설치한 경우 다른 구성은 보기를 깨뜨립니다. 사용자가 명시적으로 다른 레이아웃을 요청하면 따릅니다. 첫 번째 자식 - `split --current --direction right`, 나머지 - 오른쪽 열 **내부에서** `split --pane <이전 자식> --direction down`. 오케스트레이터 pane을 분할하거나 에이전트 pane을 오른쪽으로 분할하지 마십시오 - 오른쪽 열에서 down 체인만. ```bash herdr pane split --current --direction right --cwd "<worktree1>" --no-focus herdr pane split --pane <agent1-pane> --direction down --cwd "<worktree2>" --no-focus ``` 새 pane의 ID는 JSON `.result.pane.pane_id`에서 가져옵니다. 사용자 포커스를 건드리지 마십시오(`--no-focus`). 자식 이름은 6단계에서 `agent start`를 통해 지정되며, 가시성을 위해 `herdr pane rename <pane_id> "s<N>-<name>"`도 사용합니다. ## 6. 자신의 kind 자식 시작 표준 경로는 `agent start`이며, pane에서 예상 에이전트가 올라왔는지도 검증합니다: ```bash herdr agent start s1-<name> --kind "$KIND" --pane <pane_id> -- <자율성-플래그> ``` 이름은 `[a-z][a-z0-9_-]{0,31}`와 일치해야 하며 활성 에이전트 중 고유해야 합니다. ### 자율성 플래그 자식은 사람 없이 작동해야 하며, 그렇지 않으면 승인에서 멈춥니다. 플래그는 Herdr이 아닌 CLI에 따라 다릅니다. 확인된 것: | kind | 시작 | |---|---| | `omp` | `-- --yolo` | | `claude` | `-- --dangerously-skip-permissions` (또는 `--permission-mode bypassPermissions`) | | `opencode` | `-- --auto` | 다른 kind(codex, gemini, kimi, cursor, copilot, droid, kilo, grok, hermes, qodercli, mastracode, pi 등)의 경우 - 플래그를 지어내지 마십시오. canonical 실행 파일을 확인하고 도움말을 읽으십시오: ```bash herdr agent start --help # --kind 설명에 canonical executable 명시 <executable> --help | grep -iE "permission|approve|yolo|auto|dangerous|allow" ``` 플래그를 찾지 못하면 CLI 구성에 자율성 모드가 있는지 확인하고(예: `~/.omp/agent/config.yml: tools.approvalMode: yolo`, `~/.claude/settings.json: permissions`, `opencode.json: permission`), 자식이 승인에서 멈출 수 있음을 사용자에게 경고합니다 - `blocked` 상태로 표시됩니다(§7). ### `agent start`가 타임아웃으로 실패한 경우 Windows PowerShell pane의 알려진 버그: `agent start`가 손상된 `Start-Process`를 보냅니다 → 타임아웃. 해결 방법 - pane에서 CLI를 직접 시작: ```bash herdr pane run <pane_id> "<executable> <자율성-플래그>" sleep 3 && herdr pane read <pane_id> --lines 15 # CLI 프롬프트 기대 herdr agent rename <pane_id> s1-<name> # herdr이 에이전트를 인식한 경우 ``` 이후 `herdr agent explain <pane_id>`가 인식된 에이전트를 제공하지 않으면 이 pane에 대한 구조적 모니터링이 불가능하며 §7 폴백으로 작업합니다. ### 브리프 전달 `pane run`을 통하지 마십시오: TUI가 삽입을 렌더링하는 동안 Enter가 삼켜집니다. 일시 중지와 함께 두 단계로: ```bash herdr pane send-text <pane_id> "파일 <브리프 절대 경로>를 읽으십시오 - 이것이 당신의 브리프입니다. 끝까지 완전히 실행(코드, 테스트, 린터, 자체 브랜치에 커밋)한 다음 최종 보고서를 제공하십시오." sleep 5 && herdr pane send-keys <pane_id> Enter ``` 통합이 설치되고 `agent start`가 작동한 경우의 표준 대안: ```bash herdr agent prompt s1-<name> "파일 <브리프>를 읽고 끝까지 실행하십시오" --wait --timeout 300000 ``` `pane read`로 브리프가 전송되었는지 확인: input이 비어 있고 에이전트가 작업 중입니다. ## 7. 모니터링 - cron이 아닌 통합을 통해 ```bash herdr agent list # 모든 자식 상태 herdr agent wait s1-<name> --until idle --timeout 1800000 herdr agent prompt s1-<name> "<텍스트>" # 작업 중인 에이전트에 지시 추가 herdr agent read s1-<name> --lines 40 ``` 상태 의미: `idle` - 입력 준비 및 해당 탭이 UI에서 보임; `done` - 보이지 않는 백그라운드 작업 후 동일한 idle(CLI를 통한 읽기는 탭을 본 것으로 표시하지 않음); `blocked` - herdr이 승인/질문 UI를 인식, 자식이 사람을 기다림; `unknown` - 에이전트는 있지만 분류가 없음, 완료 신호가 아님. 오케스트레이터 루프: `agent wait` 순차 또는 이벤트 기반 → 수락(§8). `blocked` → `agent read`, 질문 이해, `agent prompt`로 응답 또는 사용자에게 문의. 의심스러운 침묵 → `pane read <pane_id>`. `wait` 타임아웃은 적당히 유지(~30분)하고 트리거 시 재설정: 매우 큰 값은 "timed out"이 됩니다. `$KIND`에 대한 통합을 사용할 수 없거나 `agent explain`이 자식을 인식하지 못한 경우 폴백: 주기적 `herdr pane read <pane_id> --lines 60` + worktree의 `git log/status`. Cron은 최후의 수단이며 완료 시 반드시 제거합니다. 자식 세션 중단: worktree의 작업은 유지됩니다. 재시작 - 동일한 CLI와 해당 계속 플래그(`--help`에서 확인): `omp --resume`, `claude --continue`, `opencode --continue`. 그런 다음 프롬프트: "세션이 중단되었습니다. git status를 확인하고 브리프 <파일>을 끝까지 완료하십시오." ## 8. 수락 및 병합 - 각 브랜치: 해당 worktree에서 테스트 + 린터, `git diff main...<branch> --stat` 검토. - 자식의 최종 보고서를 맹신하지 마십시오 - 수락 명령을 직접 확인하십시오. - main 병합 - 사용자 확인 후에만; 추가적 충돌은 수동으로 해결. - 병합 후: `git worktree remove`; 브랜치는 사용자와 협의. - 사용자 pane을 건드리지 않고 자식 pane을 해제합니다.