GitHub: как разбить огромный AI-сгенерированный pull request на стек управляемых PR

GitHub Blog опубликовал практическое руководство, в котором инженеры компании предлагают решить проблему огромных и нечитаемых pull request, создаваемых AI-агентами, с помощью механизма stacked pull requests. Вместо одного диффа на тысячу строк авторы советуют разбивать задачу на несколько небольших PR, выстроенных в стек, где каждый следующий зависит от предыдущего. Это упрощает ревью, ускоряет мерж и снижает риск конфликтов.

Проблема: один гигантский PR от AI-агента

По данным GitHub, AI-агенты становятся всё более продуктивными: аналитики Gartner прогнозируют, что к 2028 году они обеспечат 50% прирост производительности на всех этапах разработки ПО. Однако, как отмечают авторы, агенты по умолчанию генерируют код так, как это делалось годами, — одним большим PR. В статье приводится пример: добавление поиска по товарам в shopping assistant приводит к появлению PR на 1721 строку, включающего новую модель данных, API-роут, клиентскую часть и UI. Такой PR сложно ревьюить, ревьюеры теряют контекст, а мерж затягивается.

Решение: stacked pull requests

GitHub предлагает использовать stacked pull requests — подход, при котором фича разбивается на логические слои, каждый из которых оформляется отдельным PR. Эти PR выстраиваются в стек, где каждый следующий базируется на предыдущем. Это позволяет ревьюить изменения небольшими порциями, привлекать разных специалистов для разных слоёв и упрощает поддержку.

Практический пример: четыре слоя

В статье разобран пример добавления поиска по товарам. Авторы выделяют четыре слоя:

• L1 (feat/catalog-data) — типизированный каталог с данными, валидацией и модулем доступа к данным;
• L2 (feat/search-api) — валидированный эндпоинт /api/products/search;
• L3 (feat/chat-grounding) — интеграция чата с API и ответы на основе реальных данных;
• L4 (feat/grounded-ui) — UI с карточками товаров и состояниями.

Каждый слой зависит от предыдущего, что позволяет ревьюить их по отдельности. Например, данные ревьюит data owner, а UX — UI owner.

Инструменты: gh-stack CLI и GitHub UI

GitHub предоставляет нативную поддержку stacked pull requests в интерфейсе, а также CLI-расширение gh-stack. Для установки расширения и обучения агентов работе со стеком используются команды:

gh extension install github/gh-stack
gh skill install github/gh-stack
# или
npx skills add github/gh-stack

В примере используются кастомные агенты: data modeler, backend и frontend. Каждый агент работает над своим слоем, следуя строгой дисциплине скоупа.

Работа со стеком: от создания до ревью

Процесс начинается с инициализации стека: агент создаёт ветку feat/catalog-data с базой main с помощью gh init stack. Затем добавляются следующие слои через gh stack add. После завершения работы ветки пушатся командой gh stack push, а PR создаются через gh stack submit.

В GitHub UI на каждом PR отображается stack map — навигация между PR в стеке. Ревьюер читает PR сверху вниз для контекста, а ревьюит снизу вверх, начиная с базового слоя.

Обновление стека: rebase и sync

Если в нижний PR вносятся изменения, стек расходится. GitHub помечает ветки как diverged и блокирует мерж. Для решения проблемы есть кнопка Rebase stack в UI, но она запускает rebase на серверах GitHub, что сбрасывает коммиттера и ломает подпись коммитов. Безопаснее использовать локальную команду gh stack rebase, которая выполняет каскадный rebase с вашим Git-конфигом, а затем gh stack push. Для синхронизации всего стека используется gh stack sync.

Что это значит

Подход GitHub к stacked pull requests даёт практический способ управлять растущим объёмом AI-генерируемого кода. Вместо того чтобы бороться с гигантскими PR, команды могут структурировать работу так, чтобы каждый слой был небольшим и ревьюируемым. Это не отменяет необходимости вдумчивого ревью, но делает процесс более управляемым.