Документация — самая «машинная» из задач разработчика: она требует аккуратности, следования правилам и внимания к деталям, но почти не требует творчества. Именно поэтому она отлично ложится на AI-агентов: агент читает исходники, собирает факты и правит файлы, а человек проверяет результат. В августе 2026 года это уже не теория — техрайтер Márcio Florindo за три дня переименовал четыре продукта в 695 файлах документации, собрав весь инструментарий разговорами с агентом. Ниже — его кейс, перенесённые из него приёмы для README и changelog и честные ограничения.
Кейс: 4 продукта, 695 файлов, 3 дня
Márcio Florindo — технический писатель в enterprise-компании, без опыта программирования. Когда компания решила переименовать четыре продукта одновременно, ему досталась вся документация: тысячи файлов на Astro-сайте в одном GitHub-репозитории. Итоги первого этапа (статья на dev.to, 03.08.2026, оригинал — в его блоге):
| Метрика | Значение |
|---|---|
| Переименовано продуктов | 4 |
| Затронуто файлов | ~695 |
| Вставок / удалений | ~2 848 / ~2 816 |
| Проверено URL-маппингов | 349 |
| Добавлено/обновлено redirect-правил | 71 |
| Проверено скриншотов | 486 (67 на обновление) |
| Сгенерировано отчётов | 29 |
| Коммитов | 17 |
| Срок | 3 дня |
Ключевая фраза автора — про то, кто это сделал:
I am not a programmer. But I built every tool that made this possible by chatting with AI.
«Я не программист. Но я собрал каждый инструмент, который сделал это возможным, просто разговаривая с ИИ.»
Инструментарий: OpenCode (open-source агент в терминале) с моделью Claude Opus 4.6 — по словам автора, модели послабее «теряют edge case’ы и ошибаются», а документационный сайт сложен. Всё началось с одного переиспользуемого промпта и выросло в шесть инструментов.
Почему документация — это не find-and-replace
Первое, что выяснил Флориндо: имя продукта не «просто текст». Оно живёт в десятках разных структур, и сломать можно всё разом (источник):
- YAML-файлы с метаданными продукта (ID, отображаемое имя, URL-путь);
- frontmatter каждой страницы документации (поля
products:); - папки, от которых зависят URL — переименовал папку, и все ссылки на раздел умерли;
- redirect-правила: пропустил одно — закладка пользователя уходит в 404;
- пропсы компонентов в MDX-файлах, ссылающиеся на ID продукта;
- записи changelog, привязанные к идентификаторам продукта;
- SVG-иконки, названные по имени продукта;
- перекрёстные ссылки в доках других продуктов;
- скриншоты, где старое имя видно в интерфейсе, сайдбаре и хлебных крошках.
Отдельная категория — то, что менять нельзя вообще: API-поля, имена CLI-инструментов, код в блоках, Terraform-ресурсы и исторические записи changelog, где старое имя — исторически точное. Простой «заменить всё» превращает рабочую документацию в сломанную.
Один промпт → шесть инструментов
Начал Флориндо с описания задачи агенту: структура сайта, что нужно изменить, что нельзя трогать. Первая версия промпта «переименуй продукт» была грубой — переименовывала лишнее, не умела переименовывать папки. Дальше каждую ошибку он превращал в правило:
Each mistake became a rule. Each conversation refined the tool.
«Каждая ошибка становилась правилом. Каждый разговор оттачивал инструмент.»
К финалу команда rename умела: safe-листы (термины, похожие на старое имя, но неприкосновенные), связанные переименования (родительский продукт тянет за собой подпродукты), мост-фразу «(ранее Old Name)» после первого упоминания нового имени, два прохода (сначала файлы самого продукта, потом перекрёстные ссылки в чужих доках) и батч-режим (сначала контент на старых именах файлов, затем структурные изменения отдельным коммитом).
Из проблем при исполнении выросли ещё пять инструментов:
- Validator — 16 автоматических проверок без полной сборки сайта: сломанные ссылки, пропущенные redirects, устаревшие ID в frontmatter, пропавшие SVG-иконки. Проверки разделены по severity: BUILD (сборка упадёт), RUNTIME (UI сломается), CORRECTNESS (пользователи увидят не то), COSMETIC (мелочь). За все переименования валидатор подтвердил: ~80 имён API/CLI в коде сохранены верно, 110+ исторических записей changelog не тронуты.
- Image scanner — vision-модель проверяет скриншоты на устаревшие имена: 486 изображений, 310 просканировано визуально, 67 отправлено на обновление. Самый неожиданный вывод: все 113 SVG-диаграмм были полностью векторизованы, и grep их не находил — старое имя было «впаяно» в пути векторных данных. Единственный способ — рендерить SVG в PNG и читать визуально.
- Redirect validator — детерминированная Python-утилита без ИИ: «нужно ли ИИ, чтобы проверить, что URL отвечает 200? Нет». 349 маппингов проверяются скриптом до и после мержа.
- Cleanup — запустится через 6 месяцев и уберёт ~300 мост-фраз «(ранее Old Name)», когда пользователи привыкнут к новым именам.
- Generic-версии rename и image audit — переиспользуемые: вместо зашитых правил проекта задают интерактивные вопросы (старое имя, новое имя, что нельзя менять).
Что из этого переносится на README и changelog
Кейс масштабный, но три приёма работают и для обычного проекта.
README: агент пишет, человек проверяет
Самый простой сценарий: агент генерирует README по исходникам. Флориндо не трогал README, но принцип тот же — дать агенту контекст и правила, а не просить «напиши красиво». Рабочий промпт:
Изучи исходники и документацию проекта (модули, скрипты, примеры).
Напиши README.md: назначение, установка, быстрый старт, примеры,
структура проекта, лицензия. Команды из README проверь по коду —
не выдумывай. Не упоминай то, чего нет в репозитории.
Пример с живыми промптами по-русски — старый, но показательный кейс на Habr (март 2023, ChatGPT): автор сгенерировал README для проекта speakerpy, предварительно сжав документацию через Sphinx autodoc в текст, потому что «весь код в контекст не влезает». Главные грабли того кейса актуальны и сейчас: лимит контекста — на вход агента надо подавать сжатую суть (докстринги, аннотации, оглавление), а не сотню тысяч строк.
Готовые сервисы, которые делают README/вики автоматически: DeepWiki от Cognition генерирует полноценную вики по публичному репозиторию (разделы, архитектура, ссылки на исходники), ReadmeAI и отечественный Open-Source-Advisor (обзор инструментов — на Habr).
Changelog: новые записи — агенту, историю — не трогать
В кейсе Флориндо записи changelog были привязаны к ID продуктов, и валидатор отдельно проверял, что 110+ исторических записей остались нетронутыми. Это главное правило работы с changelog через агента:
- Новые записи агент может писать по диффам коммитов — задача, для которой он создан: «посмотри дифф за эту неделю и добавь записи в CHANGELOG.md по формату Keep a Changelog».
- Исторические записи — не редактировать. Старое имя в старой записи — историческая точность, а не ошибка, которую «надо исправить». Это тот же safe-лист, что и API-имена.
- Записи, привязанные к идентификаторам (версии пакета, ID продукта), менять только согласованно — как в кейсе, «родитель + подпродукты вместе».
Проверка — детерминированными скриптами
Самая ценная часть кейса: агент делает основную работу, а проверка результата там, где это возможно, — обычный скрипт. «Нужно ли ИИ для “URL отвечает 200?”» — нет. Redirect-валидатор, grep по safe-листам, сверка диффов — всё это без LLM. ИИ оставляют там, где без него никак: скриншоты, SVG-диаграммы, смысл перекрёстных ссылок.
Промпты для типовых задач
Готовые формулировки, с которых можно начать (адаптированы под любой терминальный агент — OpenCode, Claude Code, Gemini CLI):
# README по репозиторию
Изучи исходники и существующую документацию. Напиши README.md:
назначение, установка, быстрый старт, примеры, структура, лицензия.
Каждую команду проверь по коду. Не упоминай того, чего нет в проекте.
# Запись в changelog по диффу
Посмотри git diff с момента прошлого релиза (git log --oneline v1.2..HEAD).
Добавь записи в CHANGELOG.md по формату Keep a Changelog: Added / Changed /
Fixed / Deprecated. Существующие записи не редактируй.
# Перекрёстные ссылки после переименования
Продукт Old Name переименован в New Name. Найди все упоминания Old Name
в чужих разделах документации и обнови ссылки и текст. НЕ трогай:
API-имена, CLI-команды, код в блоках, исторические записи changelog.
# Скриншот-аудит
Проверь скриншоты в docs/ на устаревшие названия интерфейса.
Отметь файлы, где старое имя видно в UI (заголовки, сайдбар, кнопки).
SVG-диаграммы отрендерь в PNG и проверь визуально.
# Проверка перед мержем
Сверь, что все ссылки внутри документации ведут на существующие страницы,
все redirect-правила указаны, в changelog нет дублей записей.
Отчёт — списком файлов с проблемами.
Два промпта из списка — «не редактируй существующие записи» и «не трогай API/CLI/код» — это те самые safe-листы из кейса Флориндо. Без них агент «наведёт порядок» там, где порядок уже исторически верный.
Инструменты и российские реалии
Для генерации и обновления документации подходят те же агенты, что и для кода:
- OpenCode — open-source агент в терминале, работает в России без VPN и прокси, бесплатные модели из коробки (установка — отдельная статья). Именно им пользовался Флориндо.
- Claude Code — терминальный агент Anthropic с сильными моделями (в кейсе — Claude Opus 4.6); из РФ требует подписку или API с зарубежной картой (гайд).
- Gemini CLI — бесплатный вход через API-ключ AI Studio, подходит для пересказа кода и черновиков README (гайд).
- DeepWiki — веб-сервис, вики по репозиторию без установки; региональных ограничений при проверке не обнаружено.
Пример по-русски: бизнес-аналитик из статьи на Habr собрал на Claude Code открытую платформу «AIналитик» (AGPL-3.0), где агент ведёт документацию и оформляет артефакты по методологии BABOK: 21 скилл, 22 MCP-сервера, 111 инструментов. README и папка docs/ в его репозитории — наглядный пример того, как выглядит документация, ведущаяся вместе с агентом.
Русскоязычный контекст по теме:
- «Как писать README-файлы для ИИ-агентов» (Habr, декабрь 2025) — исследование 2303 контекстных файлов из 1925 репозиториев: авторы вводят термин «контекстный долг», советуют относиться к документации для агентов как к коду и регулярно её ревьюить.
- «ИИ для технической и пользовательской документации» (Habr, октябрь 2025) — обзор задач, включая ченджлоги: актуализация документации по ченджлогам названа одной из типовых задач ИИ; честно перечислены галлюцинации и неправильная терминология.
- «Полезный проект — ещё полдела: инструменты для README» (Habr, сентябрь 2025) — OSA (отечественный генератор README, использован для FEDOT), ReadmeAI, DeepWiki.
- «Почему README стали шаблонными» (Habr, июль 2026) — data-driven разбор: ИИ-сгенерированные README похожи друг на друга, и это заметно читателям.
Честно о пробеле: генерация README в рунете освещена (в основном на Habr), а вот связка «ИИ + changelog» почти не описана — она встречается только пунктом внутри общих обзоров ИИ для документации. Кейс Флориндо в этом смысле закрывает реальный пробел.
Ограничения (честно)
- Галлюцинации в документации опаснее, чем в коде: неправильная команда установки или несуществующий параметр уйдёт к тысячам читателей. Проверять каждое утверждение по коду — обязательный шаг.
- Историческая точность. Чанжлог — не место для «исправлений задним числом»: агент может «навести порядок», переписав старые записи, и это будет ошибка.
- Шаблонность. Исследование июля 2026 (Habr) показывает: README, сгенерированные ИИ, всё чаще выглядят одинаково. Если отличить ваш README от соседнего нельзя — редактировать вручную.
- Vision-лимиты. Проверка скриншотов упирается в разрешение модели: большие изображения приходится уменьшать, результаты идут батчами по 10 с возможностью остановиться и продолжить (детали — в кейсе Флориндо).
- Стоимость. Сложные модели (в кейсе — Claude Opus 4.6) «стоят» проекта; для простых задач хватает дешёвых моделей, но качество распознавания структур падает.
- Агент не заменяет техрайтера. Он ускоряет рутину и ловит то, что человек пропустил бы, но решение о терминологии, структуре и точности остаётся за человеком.
Итог
Документация — одна из самых выгодных областей для AI-агентов: задачи рутинные, критерии проверяемые, а ошибки видны сразу. Кейс Флориндо показывает потолок — техрайтер без опыта программирования собрал инструментарий, который выполнил за три дня работу, на которую ушли бы недели. Три приёма переносятся на любой проект: передайте агенту контекст и правила (включая список «что нельзя трогать»), новые записи пусть пишет он, а проверку там, где это возможно, делайте детерминированными скриптами.
Начать можно с малого: пусть агент сгенерирует README по вашему репозиторию, а вы проверите каждую команду. Дальше — changelog по диффам недели, потом — перекрёстные ссылки. Инструменты вырастут из работы, как это было в кейсе.
Дальше по серии «Агентный кодинг для программистов»: фундамент — «Что такое агентный кодинг», агенты для текста и кода — «Как установить OpenCode», «Как установить Claude Code», «Gemini CLI от Google», контекст для агентов — «AGENTS.md», подключение внешних инструментов — «Что такое MCP».