Саймон Уиллисон сворачивает ИИ-описания PR: суть изменений — в 1 абзаце

Открываете pull request, а там несколько экранов: постановка задачи, устройство решения, перечень файлов, проверки и ещё немного пояснений. Агент всё расписал старательно. Но прежде чем читать этот отчёт, хочется понять одну вещь: что изменилось и зачем тратить на это внимание.

Саймон Уиллисон описал приём, который использует для своих PR, подготовленных Claude Code и Codex. Сверху он оставляет короткое введение, за содержание которого отвечает сам. Полное описание агента помещает в раскрывающийся блок. GitHub позволяет сделать это прямо в Markdown с помощью HTML-тегов <details> и <summary>.

Для команды, которая регулярно получает изменения от кодинговых агентов, это готовый способ привести описания в порядок. Внедрить его можно через шаблон PR и инструкцию агенту. Правда, короткое введение всё равно придётся прочитать человеку.

Что должно остаться на виду

Уиллисон использует PR как единицу работы: собирает в нём коммиты, дорабатывает функцию, фиксирует решения и затем сливает готовый результат. Подробное описание здесь полезно. Проблема возникает, когда читатель вынужден разбирать весь материал, чтобы выяснить назначение изменения.

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

В одном из приведённых примеров страница отдельной записи показывала данные в таблице из одной строки. При большом количестве полей таблица уходила далеко вправо, а остальная страница оставалась пустой. Такое объяснение сразу даёт ревьюеру контекст для оценки нового представления. Скриншот помогает увидеть результат ещё до изучения кода.

Введение необязательно писать с нуля. Уиллисон иногда берёт подходящий фрагмент из текста агента. Существенно то, что человек выбрал его и считает достойным внимания читателя.

Как устроить раскрывающийся блок

Тег <details> оборачивает скрываемую часть описания. Внутри него <summary> задаёт видимый заголовок: по нажатию на него раскрывается остальное содержимое. GitHub поддерживает такую конструкцию в описаниях PR и комментариях к задачам.

Уиллисон указывает в заголовке блока название модели, иногда добавляя уровень усилий. Это обозначает происхождение подробного отчёта. Сам отчёт сохраняется целиком: читатель может открыть его, когда понадобятся объяснения реализации или сведения о проверках.

Представим PR с отложенной загрузкой скрипта редактирования. В начале достаточно объяснить: раньше скрипт загружался на каждой странице, теперь он подгружается при первом взаимодействии с функцией редактирования у пользователя с нужными правами. Это пересказ одного из примеров автора.

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

Где заканчивается польза оформления

Раскрывающийся блок не подтверждает корректность изменений и не делает перечисленные проверки достоверными. Если агент заявил, что тесты прошли, это по-прежнему нужно сопоставить с результатами запуска. Уиллисон описывает свой рабочий приём; измерений экономии времени или качества ревью в материале нет.

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

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