Дебаты Astra × Fable04-runbooks-and-execution
4. Ранбуки и выполнение задач
Как получить ранбуки из существующей работы
Соберите типы изменений из backlog, истории PR и инцидентов. Группируйте
по результату, предусловиям и риску, а не только по файлам. Добавление
поля без изменения семантики и преобразование исторических данных требуют
разных проверок, даже если оба меняют models.py и миграции.
Для каждого кандидата модель разбирает несколько примеров: повторяемые шаги, точки решения, обязательные проверки, сбои и ручную механику. Ранбук рождается из проверенного исполнения и сохраняет причины шагов. Не превращайте случайные привычки автора старого PR в обязательную норму.
На старте достаточно исследовательской процедуры и двух процедур: создание изменения и независимая приёмка. По накоплении различий выделяются специализированные ранбуки.
| Класс задачи | Что должно быть особенным в ранбуке |
|---|---|
| Исследование неизвестного | Вопрос, источники, эксперимент, границы вывода, без изменения продукта |
| Исправление дефекта | Воспроизведение, бизнес-оракул, regression test, причины и соседние пути |
| Изменение бизнес-правила | Намерение, совместимость, примеры до/после, версия нормы |
| Изменение API | Контракт, права, потребители, обратная совместимость, версия/депрекация |
| Схема и данные | Поддерживаемые исходные состояния, ограничения, блокировки, rollout/restore |
| Фоновая задача | Повторы, дедупликация, тайм-аут, delivery semantics, observability |
| Интеграция | Контракты, sandbox, credentials, отказ зависимости, компенсация |
| Рефакторинг | Явно неизменное поведение, characterization, сравнение критических свойств |
| Производительность | Baseline, нагрузка, ограничения ресурса и проверка семантики |
| Обновление зависимости | Lockfile, changelog, лицензия, совместимость, косвенные эффекты |
| Изменение знаний/ранбука | Происхождение, ссылки, обновление проекций, тест самой процедуры |
| Инцидент/восстановление | Ограниченные полномочия, стабилизация, доказательство восстановления |
Контракт ранбука
Обязательные поля: ID, версия, назначение, область, входы, предусловия, разрешённые инструменты/действия, состояния и переходы, проверки, выходные артефакты, лимиты, обработка ошибок, восстановление, точки решений. Подробные команды определяются после выяснения стека и сохраняются как проверенный адаптер; универсальное «выполни тесты» не является исполняемым шагом.
Пример перехода (предложенный контракт, а не установленный инструмент):
transition: verified_to_pr_created
requires:
- candidate_is_current
- prepublish_checkpoint_checks_completed
- publish_authority_is_applicable
operation: adapter.ensure_pull_request
operation_key: project/change_id/target_branch
inputs: [candidate_id, expected_head, expected_base, pr_body_digest]
outputs: [pull_request_id, url, observed_head, observed_base]
on_timeout: outcome_unknown
reconcile: adapter.find_owned_pull_request
retry: only_after_reconciliation
Здесь проверки checkpoint — установленный набор перед публикацией на текущем head. Он не заменяет полный набор приёмки результата интеграции: тот исполняется на соответствующем candidate core после определения точных head/base/result. Наличие PR не является техническим условием вычисления кандидата, но его публикация и приёмка имеют разные предусловия.
Ранбук содержит и смысл операции, и её техническое исполнение. У каждого адаптера определены параметры, credentials с минимальными правами, выходная схема, проверка результата и совместимые версии инструмента.
Цепочка типового изменения
- Intake. Сохранить намерение, границы, уже принятые решения и неизвестное.
- Research/context. Построить impact map, собрать manifest и baseline.
- Contract. Зафиксировать критерии поведения, ограничения и план проверок.
- Implement. Подготовить изолированный checkout, правку, тесты и документы.
- Verify. Проверить фактический diff, выполнить релевантные проверки.
- Publish. Создать логические коммиты, push, PR и evidence manifest.
- Accept. Независимо проверить текущий кандидат и полномочие действия.
- Merge/release. Исполнить разрешённую механику и проверить результат.
- Close/learn. Обновить связность знаний, статус задачи и кандидаты улучшений.
Это логическая цепочка, а не обязательные девять ручных approval. Переход между ранбуками автоматический, если все условия выполнены и новое решение не нужно. Иначе модель готовит конкретный выбор и ставит только зависимую ветку работы на ожидание.
Состояния и журнал
Минимальные состояния выполнения: prepared, running, waiting_decision, blocked, outcome_unknown, verified, completed, failed, cancelled. У каждого события есть run ID, step ID, actor, время, входные отпечатки, ожидаемое действие, фактический результат и внешние идентификаторы. Перед внешним эффектом записывается намерение операции, после — наблюдаемый результат. Текст чата не заменяет журнал.
Примеры блокеров: обязательный источник неизвестен, проверка не запустилась, кандидат изменился, отсутствует разрешение, несовместимая версия инструмента. Ожидание человека отличается от ошибки сети и от неизвестного результата внешнего действия: эти ситуации нельзя обрабатывать одной кнопкой retry.
Возобновление после прерывания
- Найти run ID, закреплённую версию ранбука и последнее подтверждённое состояние.
- Проверить, какие операции уже имели внешний эффект, и сверить их по стабильным ключам/идентификаторам с реальной системой.
- Сравнить working tree и ветку с сохранённым состоянием. Не сбрасывать посторонние или смешанные изменения. Сохранить копию и продолжить в отдельном checkout, если принадлежность правок не установлена.
- Для
outcome_unknownсначала запросить статус операции. Повтор разрешён только если доказана безопасность повтора или подтверждено отсутствие эффекта. - Перепроверить полномочия и актуальность входов. Отзыв может разрешать только безопасное завершение/компенсацию, а не продолжение исходной задачи.
- Выполнить следующий допустимый переход и записать его результат.
Имя ветки или текст в PR помогают поиску, но недостаточны для доказательства принадлежности: сверяются repository, branch, actor/run marker и ожидаемое содержимое. Редактирование кода моделью не объявляется идемпотентным само по себе. Повтор генерации должен сравниваться с сохранённой правкой.
Отсутствие объекта в одном ответе поиска не всегда доказывает, что создание не произошло: адаптер учитывает задержку видимости платформы. При нескольких подходящих объектах состояние остаётся неоднозначным. Сохраняется вся рабочая копия, включая untracked-файлы; одного diff-патча для этого недостаточно.
Для каждого внешнего эффекта в паспорте фиксируются: есть ли устойчивый ключ,
записанный до отправки; поддерживается ли дедупликация; можно ли запросить
фактический результат; есть ли компенсация и кто вправе её выполнить.
Если это неизвестно, нельзя обещать автономный retry. При потерянном ответе
шаг остаётся outcome_unknown; зависимая работа останавливается. Добавление
outbox/ключа в старый продукт является отдельным изменением со своей приёмкой.
Компенсация — тоже внешнее действие, а не безусловно безопасный rollback.
Новая версия ранбука не подменяет текущую незаметно. Совместимое обновление имеет явное отображение checkpoint; иначе запуск завершается по прежней версии либо останавливается согласно политике. Отзыв опасной версии может быть автоматическим событием по уже принятому решению, без нового approval.
Решения и эскалации
Человеку передаётся: что именно нельзя решить по действующим правилам, проверенные факты, варианты, последствия, рекомендация и область выбранного ответа. Обычные технические ошибки сначала обрабатываются ранбуком.
Пример хорошего пакета: «Новая скидка меняет сумму в уже оплаченных заказах. Действующее правило запрещает их перерасчёт. Предлагается применять только к новым заказам; альтернатива — отдельная миграция с компенсацией». Нужен выбор поведения. Подготовка миграции, отчёта и фиксация решения не перекладываются на человека.
Контроль стоимости и сложности
Лимиты времени, числа попыток, инструментальных вызовов и стоимости задаются в ранбуке/политике. Исчерпание лимита сохраняет состояние и причины; не превращает незавершённую задачу в успех. Модель может предложить меньшую область или иной инструмент, сохраняя критерии качества.
Добавлять workflow engine, очередь, векторный поиск или отдельную БД нужно, когда измерены соответствующие проблемы: потеря состояния, параллельные исполнители, долгие ожидания, сложные зависимости. До этого достаточно малого исполнителя с долговечным журналом и проверяемыми адаптерами.