Перейти к содержанию

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, — никогда не простаивает:

  1. На idle или done: ревью коммитов этой lane, merge того, что зелёное, следующая задача или следующая lane, которую разрешает herd plan.
  2. Ревью пакетами: одно холодное ревью на поток, а не остановка после каждой задачи.
  3. На blocked: сначала herdr agent read <name>, потом ответ или эскалация владельцу. Поэтому herd status и показывает blocked первыми.
  4. Останавливайте агентов, когда их 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.