Автономное управление проектами: STATE.yaml и параллельные агенты

Координация нескольких AI-агентов через файл STATE.yaml: параллельная работа без оверхеда оркестратора.

Когда проект разрастается — рефакторинг нескольких репозиториев, исследовательский спринт, контент-пайплайн — вы неизбежно упираетесь в проблему координации. Один агент не успевает, переключение контекста съедает время, а централизованный оркестратор становится бутылочным горлышком. Существует другой паттерн: децентрализованная координация через общий файл STATE.yaml, где каждый агент работает автономно и сам сообщает о прогрессе.

Проблема: оркестратор как бутылочное горлышко

Классический подход к управлению несколькими AI-агентами — централизованный оркестратор. Главный агент получает задачу, разбивает её на подзадачи, раздаёт их субагентам, ждёт результатов, собирает обратно. На бумаге звучит логично, на практике возникают три проблемы:

• Последовательность вместо параллели. Оркестратор тратит токены на каждый цикл «раздать → собрать → решить следующее». Субагенты простаивают, пока главный «думает».
• Хрупкость. Упал контекст оркестратора — потеряна вся картина проекта. Ни один агент не знает, что делают остальные.
• Масштабирование. Два-три субагента — ещё терпимо. Пять-семь — оркестратор уже тонет в управлении, а не в стратегии.

Решение: STATE.yaml как единый источник правды

Паттерн децентрализованной координации убирает оркестратора из цепочки. Вместо него — файл STATE.yaml в корне проекта. Каждый агент читает его, находит свои задачи, работает, обновляет статус. Никакого центрального диспетчера.

# STATE.yaml — файл координации проекта
project: website-redesign
updated: 2026-02-10T14:30:00Z

tasks:
  - id: homepage-hero
    status: in_progress
    owner: pm-frontend
    started: 2026-02-10T12:00:00Z
    notes: "Working on responsive layout"

  - id: api-auth
    status: done
    owner: pm-backend
    completed: 2026-02-10T14:00:00Z
    output: "src/api/auth.ts"

  - id: content-migration
    status: blocked
    owner: pm-content
    blocked_by: api-auth
    notes: "Waiting for new endpoint schema"

next_actions:
  - "pm-content: Resume migration now that api-auth is done"
  - "pm-frontend: Review hero with design team"

Файл — простой YAML. Статусы: in_progress, done, blocked. Каждая задача привязана к владельцу (owner). Блокировки указаны явно через blocked_by. Следующие шаги — в секции next_actions.

Как работает жизненный цикл

Процесс выглядит так:

1. Главная сессия получает задачу от пользователя. Она не выполняет работу — только делегирует.
2. Спавнится субагент с конкретной областью ответственности (например, pm-backend).
3. Субагент читает STATE.yaml, находит назначенные ему задачи.
4. Работает автономно — коммитит код, обновляет документацию, меняет статусы в файле.
5. Другие агенты опрашивают STATE.yaml и подхватывают разблокированные задачи.
6. Главная сессия периодически проверяет состояние проекта, корректирует приоритеты.

Главная сессия остаётся «тонкой» — минимум вызовов инструментов, только спавн и отправка сообщений. Это паттерн CEO: стратегия, а не тактика.

Практический пример: спавн менеджера проекта

Пользователь говорит: «Рефакторь модуль авторизации и обнови документацию». Что происходит:

1. Главная сессия проверяет реестр активных проектов — pm-auth не найден.
2. Создаёт субагента: sessions_spawn(label="pm-auth-refactor", task="Refactor auth module, update docs. Track in STATE.yaml").
3. Отвечает пользователю: «Запустил pm-auth-refactor. Сообщу, когда будет готово.»
4. Субагент создаёт STATE.yaml с разбивкой задач, работает через них, коммитит изменения.
5. По завершении сообщает в главную сессию.

Главная сессия сделала два вызова инструментов — и свободна. Весь execution — на стороне субагента.

Почему файл, а не сообщения

Кооординация через файлы принципиально отличается от message-passing между агентами:

• Персистентность. Упал субагент — STATE.yaml остался. Новый субагент подхватит задачи с того места, где остановился предыдущий. Сообщения в очереди так не умеют.
• Прозрачность. Открыл файл — видишь весь проект. Не нужно копать логи и восстанавливать контекст.
• Версионирование. STATE.yaml в git. Каждое изменение — коммит с сообщением. Полный аудит-трейл бесплатно.
• Простота отладки. Что-то пошло не так? Смотрите последний коммит STATE.yaml — видно, кто что менял и когда.

Настройка: AGENTS.md

Паттерн фиксируется в конфигурации агента:

## PM Delegation Pattern

Main session = coordinator ONLY. All execution goes to subagents.

Workflow:
1. New task arrives
2. Check PROJECT_REGISTRY.md for existing PM
3. If PM exists → sessions_send(label="pm-xxx", message="[task]")
4. If new project → sessions_spawn(label="pm-xxx", task="[task]")
5. PM executes, updates STATE.yaml, reports back
6. Main agent summarizes to user

Rules:
- Main session: 0-2 tool calls max (spawn/send only)
- PMs own their STATE.yaml files
- PMs can spawn sub-subagents for parallel subtasks
- All state changes committed to git

Ключевые правила: главная сессия — не более двух вызовов инструментов. Каждый PM-агент владеет своим файлом STATE.yaml. Субагенты могут порождать собственных субагентов для параллельных подзадач. Все изменения состояния — через git.

Конвенции именования

Для отслеживания агентов используйте схему pm-{project}-{scope}:

• pm-auth-refactor — рефакторинг модуля авторизации
• pm-frontend-redesign — редизайн фронтенда
• pm-content-migration — миграция контента

Такая схема позволяет быстро находить нужного агента в реестре и понимать его зону ответственности.

Когда это работает лучше всего

• Мульти-репозиторные рефакторинги. Один агент на репозиторий, координация через STATE.yaml.
• Исследовательские спринты. Параллельный сбор информации из разных источников.
• Контент-пайплайны. Один агент пишет, другой редактирует, третий публикует — каждый со своим статусом.
• Долгие проекты. STATE.yaml переживает падение сессии. Новый запуск — агент читает файл и продолжает.

Подводные камни

• Гонки записи. Два агента одновременно обновляют STATE.yaml — один перезаписывает изменения другого. Решение: блокировка на уровне файловой системы или атомарные обновления отдельных секций.
• Раздувание файла. В больших проектах STATE.yaml может вырасти. Секционируйте по модулям: STATE-frontend.yaml, STATE-backend.yaml.
• Забытые агенты. Субагент может зависнуть. Добавляйте таймауты и проверку heartbeat в updated поле.

Итого

STATE.yaml — это не замена оркестратору, а альтернативная модель координации. Она лучше всего работает, когда задачи достаточно независимы, а параллелизм важнее последовательности. Файл как единственный источник правды, git как аудит-трейл, субагенты как автономные исполнители. Просто, прозрачно, масштабируемо.