TL;DR
Исследователи посмотрели на почти тридцать тысяч pull request'ов (PR — пакет правок, который агент отправляет на проверку и вливание в проект) от Claude Code, Cursor, Devin, Copilot и Codex. Они проверили, обновляет ли агент документацию вместе с кодом. В почти двух третях PR документацию не трогают. Чаще всего она отстаёт при исправлении багов и рефакторинге. При добавлении новых функций агенты документируют заметно охотнее.
Главная находка: пропущенная документация тянет за собой проблемы. Файлы, изменённые без документации, чаще правят повторно: на 9–12% (в относительных цифрах) чаще, чем файлы с документацией. Хуже того, долг накапливается: такой файл потом документируют вдвое реже. Агент работает быстро и много, поэтому разрыв между «что делает код» и «что про него написано» растёт быстрее, чем кто-то успевает его закрывать. Есть и ловушка в данных. Если считать по PR целиком, всё выглядит наоборот: PR с документацией кажутся «более багованными». Причина в том, что они в ~4 раза крупнее, и к ним больше цепляется поздних правок. Когда считали по отдельному файлу, картина перевернулась.
Практический вывод авторов: прописать агенту обязанность обновлять документацию в том же PR и дописывать её в старых файлах, куда он заходит. Людям — подключать ревью по размеру изменения, а не по наличию документации. Важная оговорка: сами эти правила авторы не проверяли. Они вывели их из наблюдений, а наблюдения не доказывают причинность.
Схема метода
Это исследование-находка, не техника. Ниже схема того, как применить выводы авторов (сами рекомендации экспериментом не проверены):
ШАГ 1: Правило в файле инструкций агента → «изменил поведение — обнови доку в том же PR»
ШАГ 2: Правило «долг» → «зашёл в файл без доки — допиши описание»
ШАГ 3: Самопроверка перед PR → агент выводит список: что изменено / какие доки затронуты / почему не нужны
ШАГ 4: Человек → ревью включается по размеру PR (много файлов), а не по наличию доки
ШАГ 5: Пропуск доки в PR → считается сигналом риска, смотрим внимательнее
Шаги 1–3 живут в системном промпте или в файле вроде CLAUDE.md / AGENTS.md. Шаги 4–5 — правила для вашей команды.
Пример применения
Задача: Небольшая команда ведёт бэкенд интернет-магазина: приём платежей через ЮKassa, доставка через СДЭК, заказы в amoCRM. Весь рутинный код пишет Claude Code, PR уходят в GitHub. Через три месяца никто не помнит, почему возврат платежа теперь работает иначе. README и docs/ описывают старое поведение. Разработчик вставляет правило в AGENTS.md.
Промпт (блок для AGENTS.md):
## Правила по документации
Документация в этом репозитории: README.md, папка docs/, CHANGELOG.md.
1. Любой PR, который меняет поведение системы (платежи, возвраты,
доставка, статусы заказов, интеграции с ЮKassa, СДЭК, amoCRM),
обязан обновить соответствующий файл в docs/ в том же PR.
2. Это касается и исправления багов, и рефакторинга.
Если после фикса поведение изменилось для пользователя или
другого модуля — обнови описание. Не думай, что документация
нужна только для новых функций.
3. Если ты открываешь файл с кодом, который нигде не описан
в docs/, и вносишь в него изменения — добавь краткое описание:
что делает модуль, какие входы и выходы, какие есть оговорки.
4. Перед созданием PR выведи чеклист в описании:
- Какие файлы кода изменены
- Какие файлы документации обновлены
- Если документация не обновлялась — одной фразой почему
(например: «внутренний рефакторинг, поведение не изменилось»)
5. Не добавляй в CHANGELOG пустые записи ради галочки.
Запись должна описывать реальное изменение.
Результат: Агент в описании каждого PR будет выводить чеклист: что изменено в коде, что в документации. Если документацию не трогал, он объяснит причину, и ревьюеру видно, что пропуск был осознанным. При фиксах и рефакторингах, где раньше документацию пропускали, агент будет чаще дописывать описание. Заходя в «немой» модуль, он оставит краткую справку. Гарантии нет: модель может выполнять правило формально, поэтому чеклист стоит выборочно проверять глазами.
Почему это работает
Почему агент пропускает документацию. Задача в тикете сформулирована про код: «почини возврат», «вынеси функцию». Документация в задачу не входит, и агент делает то, о чём просили. Для новых функций документация чаще выглядит естественной частью работы. Для фиксов и рефакторинга она кажется лишней. Это объяснение авторов-наблюдателей, они его не проверяли.
Что модель делает хорошо. Она следует явным правилам из контекста. Если в инструкции написано «документацию обновляй в том же PR», это становится частью задачи. Требование вывести чеклист заставляет модель явно ответить на вопрос «что с документацией?», а не пропустить его молча.
Рычаги управления: - Список файлов документации → чем точнее перечислены пути, тем меньше агент гадает, что считать документацией. - Правило «не только для новых функций» → снимает перекос, из-за которого фиксы и рефакторинг остаются без доки. - Чеклист с «почему не обновлял» → превращает молчаливый пропуск в видимое решение, которое можно проверить. - Порог ревью по размеру → меняй число файлов под свой проект. Авторы приводят пример «больше 5 файлов».
Шаблон промпта
## Правила по документации
Документация в этом проекте: {файлы_и_папки_с_документацией}.
1. Если PR меняет поведение {области_проекта} — обнови соответствующий
файл документации в том же PR. Это относится не только к новым
функциям, но и к исправлениям багов и рефакторингу.
2. Если ты меняешь файл, который нигде не описан в документации —
добавь краткое описание: назначение, входы, выходы, оговорки.
3. Перед созданием PR добавь в описание чеклист:
- Изменённые файлы кода: {список}
- Обновлённые файлы документации: {список или «нет»}
- Если «нет» — одна фраза, почему документация не нужна
4. Не пиши пустые или формальные записи ради галочки.
5. Если PR затрагивает больше {число_файлов} файлов —
отметь это в описании: «Требуется внимательное ревью».
Что подставлять:
- {файлы_и_папки_с_документацией} — реальные пути: README.md, docs/, CHANGELOG.md.
- {области_проекта} — модули, где документация критична (платежи, API, интеграции).
- {число_файлов} — порог размера, после которого нужен человек. Начните с 5 и подстройте.
Ограничения
⚠️ Корреляция, не причинность: Авторы показали, что пропуск документации сопровождается большим числом поздних правок. Они не показали, что заставить агента писать документацию эти правки уменьшит. Вместе с документацией может уходить и другое: тип задачи, аккуратность агента, культура проекта.
⚠️ Рекомендации не проверены: Идея «пропишите агенту обновлять доку» — вывод авторов. Эксперимента «с таким правилом и без него» в статье нет. Применяйте как гипотезу и сравните результаты на своих PR.
⚠️ Метрика грубая: «Документацией» считался любой изменённый файл вроде README,
docs/или CHANGELOG. Качество и связь с изменённым кодом не проверяли. Правка CHANGELOG ради галочки считалась как обновление доки. Docstring'и и комментарии в коде не учитывались, внешние вики тоже. Реальная доля «недокументированных» PR может быть другой.
⚠️ Данные могли устареть: Это PR за конец 2024 — середину 2025 года, и две трети из них от Codex. Агенты быстро меняются, а часть современных уже сама читает файлы инструкций и обновляет документацию лучше.
⚠️ Нет сравнения с людьми: Неизвестно, много это или мало относительно разработчиков-людей. Возможно, люди пропускают документацию так же часто.
⚠️ Скорость слияния — слабый сигнал: Вывод, что документированные PR вливаются быстрее, нужно читать осторожно. Большинство слияний там автоматические.
Как исследовали
Исследователи взяли открытый набор AIDev. Это сотни тысяч PR, которые написали пять ИИ-агентов в открытых репозиториях. Отобрали PR, где менялся хотя бы один файл с кодом. Получилось 29 669 PR из 2 585 репозиториев. Дальше всё формально, по путям файлов. Есть код и есть документация (.md, .rst, папка docs/, README, CHANGELOG): тогда PR «с документацией». Кода без документации — «дрейф».
Главная аккуратность работы — борьба с ловушкой размера. Если считать поздние исправления на уровне PR, документированные PR выглядят хуже: +79% исправлений. Но они в ~4 раза крупнее, и к ним просто есть что «прицепить». Тогда исследователи перешли на уровень отдельного изменённого файла (177 743 изменения). Картина перевернулась: файл без документации чаще правили позже, 16,6% против 14,9% за 90 дней. Урок для практики: сравнения «по PR целиком» легко обманывают, пока не учтён размер.
Для проверки «долга» они смотрели, дописали ли документацию к файлу в следующие 90 дней. Файлы, изменённые без документации, получали её лишь в 24% случаев, против 48% у файлов, изменённых вместе с ней. Эффект сохранился (слабее), даже когда сравнивали только внутри одного репозитория. Значит, дело не только в том, что «в одних проектах доки любят, в других нет».
Что удивило: Claude Code пропускал документацию реже других (около половины PR), Devin чаще всего (почти три четверти). Но проблема есть у всех агентов. Внутри каждого агента фичи документировались в 1,6–2,1 раза чаще, чем фиксы, так что дело не в составе агентов.
Адаптации и экстраполяции
🔧 Техника: добавить «аудит долга» → закрывать накопленный разрыв
Авторы советуют «погашать» старый долг: просить агента документировать файлы, в которые он заходит. Можно сделать это отдельной задачей, а не побочным правилом:
Просмотри папку {путь}. Найди модули, которых нет в docs/ или описание которых расходится с кодом. Для каждого выведи: файл / что делает / чего не хватает в доке. Ничего не меняй — только список. Приоритет — модули, которые чаще всего правились за последние 3 месяца.Сначала список, потом отдельным запросом правки. Так проще проверить результат. Это моя адаптация, в статье такого нет.
🔧 Техника: ревью по размеру → фильтр для человека
Если агент помечает PR больше N файлов фразой «Требуется внимательное ревью», человек смотрит только их. Отсутствие доки при этом — повод заглянуть глубже, но не единственный триггер. Это прямо следует из рекомендации авторов, правило 5 в шаблоне выше.
Ресурсы
- Работа: Documentation Drift in AI-Generated Pull Requests
- Авторы: Will De Michele, Kla Tantithamthavorn — Monash University, Мельбурн, Австралия
- Набор данных: AIDev (Li, Zhang, Hassan, «The rise of AI teammates in software engineering (SE) 3.0», arXiv:2507.15003), челлендж MSR 2026
- Пакет для воспроизведения: https://doi.org/10.5281/zenodo.21873884
- Близкая работа: Haque et al., «An empirical study of tests in agentic pull requests» (MSR 2026) — то же самое про тесты