Agent teams и herdr
Кому это? Тому, кто запускает Claude Code на репозитории с harnessimo и хочет, чтобы несколько агентов работали одновременно — lane'ы параллельно, несколько тиммейтов внутри одной lane — не сталкиваясь и не выжигая лимит API. Когда читать? Когда одного агента уже мало. Правила столкновений под этим — в «Больше одного агента»; какая модель берёт какую работу — в «Маршрутизации работы».
Два инструмента, два уровня, одно правило: никогда два агента на одном файле.
| Уровень | Инструмент | Что даёт | Что делает это безопасным |
|---|---|---|---|
| Между lane'ами | herdr + harnessimo herd |
worktree, панель и claude на каждую lane |
отдельные checkout'ы — столкновение файлов между lane'ами невозможно |
| Внутри одной lane | agent teams в Claude Code | лид и несколько тиммейтов на общем списке задач | непересекающиеся файлы у тиммейтов; гейт TaskCompleted |
Почему топологией владеет herdr
Тиммейты agent teams работают в checkout'е лида. Отдельного worktree на тиммейта нет, а
isolation в вызове агента означает, что этот агент — не тиммейт. Поэтому команда не может
быть единицей параллельных lane'ов: два тиммейта, ведущие две lane в одном checkout'е, в
одной неудачной правке от того, чтобы затереть друг друга, и ничто их не остановит.
herdr может: он управляет рабочими пространствами терминала, открывает worktree на каждое
пространство и распознаёт состояние агента в панели — idle, working, blocked, done,
unknown. Одна lane — это один worktree с одним процессом claude, так что файлы между
lane'ами столкнуться не могут. Заборы ## Owns по-прежнему решают, какие lane'ы можно
запускать одновременно: две lane, правящие один путь, столкнутся при merge. Решение записано в
.harness/4-state/DECISIONS.md.
Установка
# herdr — менеджер рабочих пространств терминала: установка с https://herdr.dev
herdr --version
npx harnessimo init # пишет .claude/settings.json, если в проекте его нет
npx harnessimo doctor # сообщает, есть ли herdr в PATH и панель ли это herdr
Затем запустите herdr, откройте панель в репозитории и запустите там claude. Больше ничего
не нужно: с настройками ниже тиммейты работают in-process в терминале лида, а herd запускает
агентов lane через herdr agent start --kind claude.
Как показываются тиммейты решает собственный teammateMode Claude Code: in-process
(по умолчанию в Claude Code — все тиммейты в терминале лида, переключение на месте), tmux
или iterm2 (отдельная панель на тиммейта) или auto, который выбирает панели, когда сессия
запущена внутри tmux или iTerm2, и in-process в остальных случаях. Шаблон ставит auto. В
любом случае тиммейты работают в checkout'е лида — меняется отображение, а не топология.
init пишет .claude/settings.json, только если в проекте его нет; в существующий файл
хуки вливаются, файл не заменяется:
{
"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
"teammateMode": "auto",
"subagentPromptCacheTtl": "1h",
"hooks": { "TaskCompleted": [{ "hooks": [{ "type": "command",
"command": "npx --no-install harnessimo hook task-completed" }] }] }
}
плюс брифинг на SessionStart и гейт на Stop/SubagentStop. subagentPromptCacheTtl
держит кэш промптов тиммейтов тёплым час вместо пяти минут — иначе тиммейт, ждущий ревью,
заново платит за весь свой контекст.
Между lane'ами: harnessimo herd
harnessimo herd plan # какие lane'ы можно запустить сейчас бок о бок и почему ждут остальные
harnessimo herd up [lane…] # внутри панели herdr: worktree, панель и агент на lane
harnessimo herd status # каждая lane рядом с состоянием её агента, blocked — первыми
plan берёт живые lane'ы в порядке индекса и запускает lane, когда её строка в индексе
говорит active, всё из её ## Depends on закрыто, её ## Owns не пересекается с уже
выбранными lane'ами и работает меньше herd.maxWorking агентов. Lane без ## Owns
запускается только одна: ничто не показывает, что она ни с кем не столкнётся.
up должна работать внутри панели herdr (HERDR_ENV=1); в другом месте она падает и
говорит об этом. Для каждой lane она делает worktree так же, как harnessimo worktree add, —
вместе с шагом установки, — открывает в нём панель, запускает агента с именем по slug'у lane,
ждёт herd.staggerSeconds между стартами и отправляет однострочный стартовый промпт:
прочитать AGENTS.md, загрузить handoff, делать задачи внутри ## Owns, гонять проверки,
коммитить, отступать на 429.
Каждый агент lane — это claude, запущенный через herdr agent start --kind claude
(herd.agentKind), поэтому herdr знает его как агента и сообщает его
состояние. up без имён lane запускает все lane'ы, которые разрешает plan, и оставляет
отложенные.
Модель задаёт роль — флагом запуска
Агент lane играет роль (herd.defaultRole, по умолчанию implementer; herd.laneRoles — для
lane, которая не implementer), и up запускает его на модели этой роли. Модель и effort:
читаются из .claude/agents/<role>.md и передаются как
herdr agent start … -- --model sonnet --effort high:
$ harnessimo herd plan
each starts as (lane, role, flags after `herdr agent start … --`, tab):
search implementer --model sonnet --effort high (model: .claude/agents/implementer.md; effort: default for sonnet) → this tab
Причина: маршрутизацию из файла роли Claude Code читает для сабагента. Агент в панели — это сессия верхнего уровня, она файл не читает, поэтому раньше работала на модели по умолчанию, что бы ни говорила роль.
- Откуда берётся значение, первое совпавшее: явный
--model/--effortвherd.agentArgs(для этого флага он главный, план называет его источником), frontmatter роли,herd.roles.<role>(запас на случай отсутствующего или молчащего файла) и, только для effort,highдля Sonnet. Роль, нигде не назвавшая модель, стартует без--model, аplanиupоб этом предупреждают. - Никогда
/modelи/effortв запущенной сессии. Оба сохраняют выбор как глобальное значение пользователя в~/.claude/settings.jsonи меняют все его остальные сессии. Чтобы сменить модель агента, остановите его и запустите заново с флагами. - Рутинную работу с herdr делает сам координатор: открывает панели, запускает агентов, отправляет промпты. Промпт агенту в панели самодостаточен и использует абсолютные пути — в боковом worktree файлов координации может не быть. Владельцу ручные шаги не передают.
Не больше четырёх панелей во вкладке
Вкладка больше чем с четырьмя панелями нечитаема, поэтому herd.panesPerTab (по умолчанию 4)
ограничивает её, считая панель координатора. up добивает вкладку координатора до
лимита — первый агент делит её вправо, следующие идут ниже самой новой панели, — затем
открывает новую вкладку с именем её первой lane, тоже до лимита, для остальных. plan
показывает вкладку каждого агента (→ this tab, → new tab "billing"). Вне herdr он считает,
что координатор во вкладке один, и говорит об этом.
Когда lane готова: ревью, harnessimo worktree merge <slug>, затем
harnessimo worktree remove <slug>. Общее состояние держит основной checkout.
Внутри одной lane: agent teams
- Мало сфокусированных тиммейтов. Три–пять, по пять–шесть задач на каждого. Каждый стоит целого контекста; больше тиммейтов — больше затрат и координации, редко больше скорости.
- Непересекающиеся файлы. Делите задачи lane так, чтобы два тиммейта не трогали один файл, — или дайте одному роль ревьюера, который ничего не правит. Никогда два пишущих на одном файле.
- Тиммейты на Sonnet, ревью на Opus. Модель задают определения в
.claude/agents/(промпт запуска >modelв определении >CLAUDE_CODE_SUBAGENT_MODEL> модель лида). Механическая работа — Sonnet или Haiku; Opus — для архитектуры и холодного ревью рискованного диффа. - Самодостаточные определения. Тиммейт в отдельной панели (режим
tmuxилиiterm2) получает тело своего определения вместо системного промпта по умолчанию, поэтому каждый шаблон несёт свои ключевые правила и раздел «As a teammate»: брать задачу из общего списка, трогать только свои файлы, писать лиду, остановиться, когда закончил. -
Задача не закрывается на красной проверке.
harnessimo hook task-completedзапускает гейты и выходит с кодом 2 и упавшими строками; Claude Code показывает их тиммейту и не даёт закрыть задачу. -
Гейта на
TeammateIdleнет. У этого хука нет флага «я уже задержал этого тиммейта», поэтому проверка, которую тиммейт не может починить, удержала бы его в цикле, тратящем лимит впустую. Утверждение «готово» делается вTaskCompleted— там его и держим.
Ограничения, о которых стоит знать: одна команда на сессию, лид фиксирован, тиммейты не запускают тиммейтов, in-process тиммейтов нельзя возобновить, а статус задачи может отставать — прочитайте агента, прежде чем действовать по его статусу.
Протокол лида
Лид — человек или сессия, запустившая herd up, — никогда не простаивает:
- На
idleилиdone: ревью коммитов этой lane, merge того, что зелёное, следующая задача или следующая lane, которую разрешаетherd plan. - Ревью пакетами: одно холодное ревью на поток, а не остановка после каждой задачи.
- На
blocked: сначалаherdr agent read <name>, потом ответ или эскалация владельцу. Поэтомуherd statusи показывает blocked первыми. - Останавливайте агентов, когда их lane закончена: простаивающий агент всё равно занимает слот.
Протокол лимитов
Параллельные агенты делят один лимит API, а 429 завершает ход тиммейта и уведомляет лида. Значения по умолчанию держат план под большинством лимитов:
- Ограничьте число работающих агентов —
herd.maxWorking, по умолчанию 3.planиupзасчитывают в него уже работающих. - Разносите старты —
herd.staggerSeconds, по умолчанию 20, чтобы первые запросы не пришли разом. - Дешёвые модели для дешёвой работы — Sonnet или Haiku для механики, Opus только для архитектуры и ревью.
- Тёплый кэш —
subagentPromptCacheTtl: "1h". - Отступите, потом сократитесь — на 429 ждите 60, 120, затем 240 секунд
(
herd.backoffSeconds, вписаны в каждый стартовый промпт), повторите промпт и уменьшите число работающих агентов на один. - Таймаут не доказывает, что промпт не дошёл. Промпт, упавший по таймауту, мог прийти:
herdr agent read <name>, прежде чем отправлять его снова. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS(по умолчанию 20) ограничивает субагентов, а не тиммейтов, — уменьшите и его, если субагенты работают рядом с командой.
Все ключи: Конфигурация → herd.