Координація

Один юніт, крок за кроком

Юніт — найменший шматок роботи, який запускає harness. Ось усе, що відбувається в одному юніті. Runner — звичайний код; модель задіяна лише в середніх кроках.

Пройди той самий юніт як повідомлення між runner, координатором і його спеціалістами. Третій сценарій показує, що стається, коли координатор перестає тримати хід.

Що отримує координатор

Runner збирає промпт кожного координатора з п'яти частин, у такому порядку:

1. промпт етапу — prompts/spec.md, prompts/plan.md, prompts/implement.md і так далі, по одному на етап;
2. постійні правила — правила, потрібні кожному агенту, наприклад ніколи не вбивати процеси за шаблоном;
3. спеціалісти цього етапу — ім'я кожного, коли його викликати, і його опис;
4. ## Memory — виміряні факти й нотатки попередніх юнітів, описані нижче;
5. ## This run — факти цього юніта: задача, файл, етап, гілка, база, scope, gate, тека артефактів, bounces, адреса застосунку, коли runner його запустив, рядок вердикту, якого вимагає етап, і секції файлу задачі, у які цей етап може писати. Усе інше йде всередину цих секцій як підсекції ###; будь-який інший заголовок ## зупиняє юніт.

Як запускається координатор

Runner запускає claude напряму, без shell. Smoke-запуск на Claude Code 2.1.308 цю команду прийняв:

claude -p --output-format stream-json --verbose --model <model> \
  --permission-mode dontAsk --setting-sources project,local \
  --agents .harness/trace/unit-NNNN.agents.json --allowedTools …

• --agents передає спеціалістів цього етапу, злитих із базового реєстру і реєстру проєкту.
• --permission-mode dontAsk відмовляє в недозволеному інструменті, а не чекає на людину, якої поруч немає. У smoke-запуску git commit відхилено одразу, без зависання, а відмову записано в permission_denials події result.
• В allowlist agent.allowedTools немає git commit і push. Це другий паркан за контрактом scope: коміти — робота runner.
• --setting-sources project,local не пускає в цикл твої особисті хуки користувача.
• Оточення задає CLAUDE_CODE_DISABLE_CLAUDE_MDS=1, тож агенти не вантажать файли CLAUDE.md проєкту і витрачають ці токени на задачу.

harness preview T-002 друкує точну команду і промпт наступного юніта задачі й не витрачає жодного токена.

Тримай хід

Це правило ламає більшість перших спроб написати координатора.

У Claude Code CLI кожен виклик саб-агента асинхронний: виклик повертається одразу, а спеціаліст працює у фоні. У claude -p повідомлення без виклику інструмента завершує хід, а з ним і процес.

Тож координатор, який роздав роботу трьом спеціалістам і написав «Чекаю на результати», щойно завершив юніт. Спеціалісти закінчують за хвилину, і їхні відповіді не потрапляють нікому.

Страховка — контракт трейсу: якщо обов'язкового вердикту немає, юніт падає, а не проходить на мовчанні.

Ланцюжок збірки: implement, qa, judge

Збірка, перевірка і суд — три окремі юніти. Кожен запускає свіжого координатора, тож суддя ніколи не бачив міркувань implementer, лише результат. Усередині implement-юніта tester спершу пише тести, а implementer — код, з яким вони проходять.

Коміт після кожного implement-юніта із зеленим гейтом робить harness, а не агент: у гілці задачі, з повідомленням T-NNN: <title> (round n). qa і judge рев'юять саме цей коміт.

Ліміт повернень

qa FAIL або judge REJECTED повертає задачу в implementing і додає одиницю до bounces у її frontmatter. Обидва вердикти ділять один лічильник.

Перш ніж implementer почне повернене коло, implement-юніт викликає debugger. Той читає звіт qa чи судді, знаходить причину і передає implementer діагноз, тож наступне коло лагодить причину, а не пробує наосліп.

Відмова, яка доводить bounces до limits.bounces — 2 за замовчуванням, — уже не повертає задачу. Вона паркує її з причиною для людини: максимум два implement-кола. Без ліміту implementer і суддя можуть сперечатися вічно, а кожне коло коштує цілий юніт.

Коло, яке нічого не змінило, не паркує задачу, якщо гілка вже містить її роботу; чому це важливо для хибної відмови, пояснює сторінка контрактів.

Пам'ять між юнітами

Свіжий контекст нічого не пам'ятає, тож runner вписує коротку пам'ять у кожен промпт, як секцію ## Memory:

1. виміряні факти — статус і bounces задачі, її останні handoff з вердиктами й причинами та diff stat її гілки;
2. хвіст ## Log задачі;
3. хвіст JOURNAL.md — нотатки, які попередні юніти лишили наступним;
4. інші задачі на дошці — id, статус і назва, лише для юнітів spec і plan, щоб специфікація ніколи не рекомендувала те, що вже робить інша задача. Задача з гілкою ще й каже, чи її змерджено в базову гілку, тож план ніколи не будує на роботі, якої там ще немає.

Факти йдуть першими, бо запис у журналі — думка одного агента, а статус у файлі — ні. Жодного хука і нічого в налаштуваннях проєкту: runner збирає секцію сам, тож harness preview показує і її.