Дебаты 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 с минимальными правами, выходная схема, проверка результата и совместимые версии инструмента.

Цепочка типового изменения

  1. Intake. Сохранить намерение, границы, уже принятые решения и неизвестное.
  2. Research/context. Построить impact map, собрать manifest и baseline.
  3. Contract. Зафиксировать критерии поведения, ограничения и план проверок.
  4. Implement. Подготовить изолированный checkout, правку, тесты и документы.
  5. Verify. Проверить фактический diff, выполнить релевантные проверки.
  6. Publish. Создать логические коммиты, push, PR и evidence manifest.
  7. Accept. Независимо проверить текущий кандидат и полномочие действия.
  8. Merge/release. Исполнить разрешённую механику и проверить результат.
  9. Close/learn. Обновить связность знаний, статус задачи и кандидаты улучшений.

Это логическая цепочка, а не обязательные девять ручных approval. Переход между ранбуками автоматический, если все условия выполнены и новое решение не нужно. Иначе модель готовит конкретный выбор и ставит только зависимую ветку работы на ожидание.

Состояния и журнал

Минимальные состояния выполнения: prepared, running, waiting_decision, blocked, outcome_unknown, verified, completed, failed, cancelled. У каждого события есть run ID, step ID, actor, время, входные отпечатки, ожидаемое действие, фактический результат и внешние идентификаторы. Перед внешним эффектом записывается намерение операции, после — наблюдаемый результат. Текст чата не заменяет журнал.

Примеры блокеров: обязательный источник неизвестен, проверка не запустилась, кандидат изменился, отсутствует разрешение, несовместимая версия инструмента. Ожидание человека отличается от ошибки сети и от неизвестного результата внешнего действия: эти ситуации нельзя обрабатывать одной кнопкой retry.

Возобновление после прерывания

  1. Найти run ID, закреплённую версию ранбука и последнее подтверждённое состояние.
  2. Проверить, какие операции уже имели внешний эффект, и сверить их по стабильным ключам/идентификаторам с реальной системой.
  3. Сравнить working tree и ветку с сохранённым состоянием. Не сбрасывать посторонние или смешанные изменения. Сохранить копию и продолжить в отдельном checkout, если принадлежность правок не установлена.
  4. Для outcome_unknown сначала запросить статус операции. Повтор разрешён только если доказана безопасность повтора или подтверждено отсутствие эффекта.
  5. Перепроверить полномочия и актуальность входов. Отзыв может разрешать только безопасное завершение/компенсацию, а не продолжение исходной задачи.
  6. Выполнить следующий допустимый переход и записать его результат.

Имя ветки или текст в PR помогают поиску, но недостаточны для доказательства принадлежности: сверяются repository, branch, actor/run marker и ожидаемое содержимое. Редактирование кода моделью не объявляется идемпотентным само по себе. Повтор генерации должен сравниваться с сохранённой правкой.

Отсутствие объекта в одном ответе поиска не всегда доказывает, что создание не произошло: адаптер учитывает задержку видимости платформы. При нескольких подходящих объектах состояние остаётся неоднозначным. Сохраняется вся рабочая копия, включая untracked-файлы; одного diff-патча для этого недостаточно.

Для каждого внешнего эффекта в паспорте фиксируются: есть ли устойчивый ключ, записанный до отправки; поддерживается ли дедупликация; можно ли запросить фактический результат; есть ли компенсация и кто вправе её выполнить. Если это неизвестно, нельзя обещать автономный retry. При потерянном ответе шаг остаётся outcome_unknown; зависимая работа останавливается. Добавление outbox/ключа в старый продукт является отдельным изменением со своей приёмкой. Компенсация — тоже внешнее действие, а не безусловно безопасный rollback.

Новая версия ранбука не подменяет текущую незаметно. Совместимое обновление имеет явное отображение checkpoint; иначе запуск завершается по прежней версии либо останавливается согласно политике. Отзыв опасной версии может быть автоматическим событием по уже принятому решению, без нового approval.

Решения и эскалации

Человеку передаётся: что именно нельзя решить по действующим правилам, проверенные факты, варианты, последствия, рекомендация и область выбранного ответа. Обычные технические ошибки сначала обрабатываются ранбуком.

Пример хорошего пакета: «Новая скидка меняет сумму в уже оплаченных заказах. Действующее правило запрещает их перерасчёт. Предлагается применять только к новым заказам; альтернатива — отдельная миграция с компенсацией». Нужен выбор поведения. Подготовка миграции, отчёта и фиксация решения не перекладываются на человека.

Контроль стоимости и сложности

Лимиты времени, числа попыток, инструментальных вызовов и стоимости задаются в ранбуке/политике. Исчерпание лимита сохраняет состояние и причины; не превращает незавершённую задачу в успех. Модель может предложить меньшую область или иной инструмент, сохраняя критерии качества.

Добавлять workflow engine, очередь, векторный поиск или отдельную БД нужно, когда измерены соответствующие проблемы: потеря состояния, параллельные исполнители, долгие ожидания, сложные зависимости. До этого достаточно малого исполнителя с долговечным журналом и проверяемыми адаптерами.