Сейчас за рассказ об ИИ дают выступить, но скоро будут давать в морду

Ну или вроде того. С 2023 года мы успели перерасти этап отправки непрошеных ответов LLM в чаты посреди человеческого общения и несколько сеансов массовой паники по поводу способности ИИ решать любые задачи за копейки — от управления базой знаний до задач SRE. Потихоньку перешагиваем даже детские болезни внедрения в компаниях, когда заказчики вместо реального ревью могут попросить агента протестировать результат, провалидировать документацию или просто дать обратную связь.

Сейчас ИИ где-то начал или начинает приносить реальную пользу после первой волны хайпа, когда большинство проектов внедрения проваливалось, но при этом у ИИ остаётся всё меньше места в публичном пространстве. Никто не хочет слушать о том, как кто-то другой научился решать свои задачи с помощью нейросетей и насколько он стал продуктивнее.

Я объясняю это и пресыщенностью, и тем, что сформировались две противоположные позиции. Например, в мире опенсорса Zig, Gentoo Linux, QEMU и Ghostty прямо запрещают использование ИИ для изменений от сторонних контрибьюторов. А такие проекты, как Linux Kernel, Django и Apache Software Foundation, сняли явные запреты либо полностью, либо частично, требуя обязательного раскрытия использования ИИ. Вместо этого они выдвинули требование наличия человека-контроллера (human-in-the-loop), несущего ответственность за результат.

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

То же самое можно сказать и про тексты — вы ведь тоже бросаете статью, если в ней слишком много нейрояза? В какой-то момент я понял, что это раздражает настолько, что удалил из CI своего блога все ИИ-проверки, чтобы текст мог быть не идеален, но читался легче.

Где-то тут, думаю, лежит и реальный предел возможностей агентов по работе с документацией: нельзя запромптить идею «пиши, не раздражая читателей и пытаясь понять, как он это воспримет». Особенно это заметно там, где важно не повторение действий или получение информации, как в инструкциях или справочниках, а получение знаний (подробнее в посте про DIKW). Но это тема для следующего большого поста.

Продолжим размышление о том, где может лежать предел возможностей агентов при подготовке документации. В качестве основного метода анализа я использую соотношение типов создаваемой документации с иерархией Данные - Информация - Знания. Вне рамок этого поста я также использую Diataxis и Seven-action documentation model.

TL;DR

1. Если документация предполагает нечто большее, чем справочник API для библиотеки или набор простых пошаговых инструкций для b2c-платформы, сильно возрастает значимость информационной архитектуры.

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

3. Если в треугольнике «Время - Качество - Стоимость» можно пожертвовать как качеством структуры, так и стилем текстов, или если шаблонные решения и есть целевое состояние документации, то можно положиться на агентов практически полностью.

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

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

Проблемы начинаются на уровне знаний и выше. Чтобы понять суть этих проблем, я бы предложил посмотреть на то, как агенты пишут код. Код можно покрыть любыми тестами, от простых юнит- до E2E-тестов, провести статический анализ, прогнать через линтеры, скомпилировать и так далее. Таким образом можно гарантировать, что код решит поставленную задачу. Тексты и дополнительные материалы также можно сделать грамотными, можно высчитать метрики типа индекса Флеша-Кинкейда (осуждаю), снабдить необходимыми ссылками и метаданными и т.д. Но все эти меры не гарантируют, что текст решит задачу передачи знаний. Не существует универсального способа работы со смыслом, который гарантировано обеспечил бы его передачу.

Я не хочу, чтобы мысль выше прозвучала слишком оптимистично. В конце концов, все больше людей хотят не читать тексты, а получать конкретные рекомендации на их основе в сжатом виде, используя умный поиск и чат-ботов. Но в работе с агентами я исхожу именно из того, что агенты могут создать качественные инструкции, справочники и релизноты (хоть они и не включены в фреймворк). Они способны на многое в практических руководствах и в части концептуальной документации. Тем не менее, в отличие от инструкций, концепции должны быть адаптированы в первую очередь для людей, которые хотят узнать, какие задачи они могут решить и каковы принципиальные ограничения, в отличие от инструкций, которые показывают, как можно что-то сделать.

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

Я уверен, что люди не должны чувствовать, что читают результат генерации, даже если он фактически достоверен. За неприятием нейрояза лежит более глубокая вещь — опасения людей, что они рискуют потратить ограниченные когнитивные ресурсы на текст, который может не привести к решению задачи, на текст, за которым не стоит идея авторов продукта, а просто желание иметь какую-нибудь документацию. Несколько лет заполнения интернета нейрослопом фундаментально подорвали доверие к результатам генерации и вызвали что-то наподобие старого феномена баннерной слепоты, только в отношении генерированных текстов.

Пример документации, которую стоит читать самостоятельно

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

Я захотел развернуть на своей виртуалке инстанс SilverBullet, простого клиент-серверного ПО для ведения базы знаний. Я составил план для агента, в котором ему нужно было прочитать документацию по ссылке, подготовить окружение и выбрать способ деплоя, при котором защита базы знаний будет обеспечиваться не только за счет аутентификации по паролю при условии доступа как минимум с трех устройств с разными ОС. Этого явно недостаточно, открытый порт, доступный из интернета — постоянная мишень для тысяч (или миллионов?) ботов, сканирующих и пытающих достучаться до любого открытого эндпойнта.

Агент (Kimi k2.6+Kimi CLI) предложил несколько вариантов, причем больше всего ему нравилась идея использовать Tailscale с бесплатным аккаунтом для создания VPN в смысле настоящей виртуальной частной сети. Идея в общем-то неплохая, но в основе Tailscale лежит блокируемый у нас WireGuard, а ещё я в принципе не хочу завязываться на внешнюю систему для контроля доступа.

Поэтому я отклонил все предложенные варианты и решил в стиле старой школы самостоятельно прочитать доку. Так как сам по себе SilverBullet — это ПО для управления базами знаний, его документация не содержит какой-то специфики для создания защищенного соединения, этим должен заниматься пользователь. Зато в документации нашлась секция со ссылками на посты от комьюнити, один из которых показывал, как настроить знакомый мне сервер Caddy и самостоятельно управлять сертификатами, чтобы только доверенные устройства могли установить TLS-соединение.

Я мог бы избежать траты 20 минут на оценку вариантов, предложенных агентом, если бы потратил 5 минут на изучение соответствующей секции в документации, но это знание, как обычно, пришло потом.

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

Как выбрать модель для задач, связанных с документацией и управлением знаниями

https://alexjameson.github.io/articles/choosing-llm-for-docs/

TL;DR

Главная развилка — можно ли в вашей ситуации отправлять данные наружу. Модели у внешних поставщиков и дешевле, и мощнее того, что вы сможете развернуть у себя.

Рассказы про полную автоматизацию всех процессов и замену людей — это рассказы про практически неограниченный доступ к фронтирным моделям последних поколений. Модели Anthropic и OpenAI опережают лучшие китайские модели минимум на поколение.

Требования к мощности модели определяются самой сложной частью пайплайна. В большинстве случаев стоит выбрать самую мощную мультимодальную модель из доступных.

Две основные категории задач: задачи по созданию контента и вспомогательные задачи, например ревью, поиск информации, расшифровка и суммаризация созвонов, мониторинг актуальности документации и так далее.

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

Это краткое изложение основных мыслей, подробнее читайте на сайте.

Делюсь своим навыком для агентов из пет-проекта

Исходники здесь: https://github.com/AlexJameson/agent-utils/tree/main/skills/print-image-prep

Где-то с 2018 года я развиваю и поддерживаю сайт с онлайн-галереей Евы — https://evailves.ninja. С момента запуска он работал на WordPress, хотя успел несколько раз сменить хостера и регистратора, пока не осел на ВМ в Yandex Cloud.

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

Я сформировал следующий универсальный набор характеристик: разрешение 300 DPI с сохранением исходного соотношения сторон (универсально, в отличие от PPI), цветовая схема в RGB, формат JPEG (в CMYK для печати можно перевести отдельно).

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

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

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

В последний момент отказался от идеи попросить сопроводить анонс моим фото в таком виде. Но в общем и целом знайте, что гость эфира видит себя как-то так, разговаривая на тему неизбежного будущего.

Постараюсь понабрасывать как следует и не забыть сказать что-то полезное.

Через две недели проведём эфир «ИИ в работе современного техписателя»

14 июля в 18:00 по МСК Семён Факторович встретится в прямом эфире с Александром Яковлевым, техническим писателем Yandex Cloud и автором tg-канала «Битословие». Семён и Александр поговорят о том, как влияют нейросети на жизнь технических писателей в 2026 году:

🔹 Насколько сильно давление ИИ на техписательский рынок труда?
🔹 Как делать хорошую документацию для людей и для машин одновременно?
🔹 Как использовать нейросети для решения практических задач и что за задачи это могут быть?
🔹 Что нужно сделать, чтобы не только сохранить работу, но и «оседлать волну»?

Приходите смотреть трансляцию на YouTube, Rutube и в VK Видео! Записи вы сможете найти по этим же ссылкам, но мы, как и всегда, будем рады вашему живому присутствию и вопросам в чате t.me/TechDocIT.

Выйти из гонки моделей

Чем дольше я работаю с агентами, тем больше меня раздражает политика ведущих вендоров в плане развития их моделей. Кажется, уже третье поколение, начиная с Opus 4.7, я думаю, что хочется зафиксировать качество и цену где-то на этом уровне и просто настроить конвейер для решения задач.

Но вендорам нужно зарабатывать деньги и выводить в плюс свои финансы, поэтому появляются новые модели, меняются токенизаторы, выводятся из эксплуатации части мощностей для старых моделей и все в таком духе. Я точно помню, что нормально генерировать релиз-ноты я научился с Claude Sonnet 4.6, но сейчас он путается даже на стадии анализа истории Git за месяц, не говоря уже о качественной суммаризации и следовании разветвленной системе правил.

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

И возникает вопрос: точно ли нам, техническим писателям, для всех задач нужны самые мощные модели? Нельзя ли подойти иначе к внедрению агентов и перестать воспринимать их в роли технического писателя с кремниевыми мозгами, решающего наши задачи в тех же условиях, что и мы, а вместо этого перестроить процессы, в которых они используются? В таком случае можно было бы отказаться от автоматизации роли и начать автоматизировать отдельные операции с соответствующим снижением требований к моделям, вплоть до возможности в будущем использовать self-hosting.

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

И в общем и целом действительно кое-какой результат есть. В прототипе системы, который я построил на связке из детерминированных скриптов и двух агентских стадий, я смог научиться стабильно получать решение простейших задач в неинтерактивном режиме, используя публично доступную в нашем облаке DeepSeek v4 Flash. Полный цикл обходится мне примерно в 30 рублей из-за невероятно низкой стоимости самой модели и эффективного кэширования.

О чем говорит этот опыт? О том, что задачи, лежащие за скоупом разработки, могут быть автоматизированы даже такой слабой моделью, не предназначенной для длинных и сложных размышлений. Это не решение для продакшена, все нужно будет переписывать нормально и использовать другие модели, а основной массив исследовательских и ad-hoc задач так и будет требовать фронтирных моделей или китайцев последних поколений, развернутых на чужих мощностях с работой в интерактивном режиме. Но главный вывод для себя я сделал — стабильный результат для наших задач достижим, а выход из зависимости от ведущих западных вендоров возможен, хоть и потребует совсем иного подхода как к процессам в организации, так и к подготовке контекста.