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

Ну или вроде того. С 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 задач так и будет требовать фронтирных моделей или китайцев последних поколений, развернутых на чужих мощностях с работой в интерактивном режиме. Но главный вывод для себя я сделал — стабильный результат для наших задач достижим, а выход из зависимости от ведущих западных вендоров возможен, хоть и потребует совсем иного подхода как к процессам в организации, так и к подготовке контекста.

Прочитал «Если ты — технический писатель» Кати Ушаковой

Наконец дошли руки до книги @ringova, которую я заказал ещё из первого тиража. Книга мне понравилась по соотношению объема и пользы — чтение, запись заметок и написание этого поста заняли у меня 4 часа, требующихся на дорогу до Москвы в Сапсане.

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

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

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

Это вещи, из-за которых прочитанное понравилось именно мне (ещё, конечно, обзор метрик, неприятие FAQ как формата современной документации и лишь одно использование аббревиатуры «ИИ» за всю книгу!). А вот джуниорам и мидлам я рекомендовал бы её из-за количества практических рекомендаций, которых там много практически на любой случай и в любых формах. Есть, правда, и неожиданные моменты. Совсем начинающие могут быть удивлены тем, что чек-лист для ревью с базовыми пунктами встречается на 98-й странице, а рекомендации по анализу логов поведения пользователей и А/Б-тестированиям — на 51-й. Я предполагаю, что это может быть хорошим заделом для повторного прочтения в будущем, тем более что книга сама по себе совсем небольшая — 122 страницы прочитает любой писатель.

Короче, рекомендую. Не так много про нас пишут в целом, а про то, как действительно обстоят дела в нашей сфере во второй четверти XXI века и как со всем этим быть, пока не писали вообще.

Выложил в опенсорс свой агентский пресет для создания документации

https://github.com/AlexJameson/agent-user-doc-preset

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

С тех пор я многому научился, много сделал сам и помог со множеством запросов, в которых была одна и та же тема — как объяснить агентам, что нужно для создания хорошей доки. Интересно, что этот вопрос беспокоит не только техписов, но и других специалистов — я окончательно решил допилить свой пресет до готового состояния в ходе дискуссии в чате канале Ивана Бегтина.

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

Мой пресет работает иначе, создавая фундамент, который можно потом достроить:

1. Самая важная часть пресета — навык scan-user-docs, который анализирует содержимое репозитория и фиксирует контракты в виде Markdown KV. Это обычный маркдаун, в котором есть понятная структура данных, адаптированная для чтения как агентами, так и людьми. При сканировании он определяет размер репозитория и примерный тип, то есть разделяет продуктовую документацию с условными репозиториями с кодом, где дока — один README. Результат записывается в виде трёх контрактов — STRUCTURE.md, TOOLING.md и STYLE.md, которые потом можно расширять и изменять по своему усмотрению.

2. Навык maintain-user-docs призван дать агентам минимальное руководство по тому, как в принципе создавать документацию. Агент с этим навыком пытается сразу определить тип документа, с которым сейчас работает, по топологии Diataxis. В качестве базовых стилистических рекомендаций для русского и английского языков используются отдельные рекомендации в стиле STE100 с примиерами хороших и плохих текстов (можно и нужно добавлять свои примеры). Также переиспользуются контракты, создаваемые scan-user-docs.

3. Последняя часть — primary agent для OpenCode. Он содержит некоторые дополнительные правила и рекомендации, но в целом опционален. Его главная цель — по умолчанию загружать в контекст все контракты. Его рекомендуется адаптировать для своих правил и особенно для других харнесов.

Я уверен, что примерно так может выглядеть скелет системы контекста для любого проекта, который в дальнейшем можно развивать и адаптировать. Посмотреть на результат генерации для моего тестового сайта с документацией можно в моем репозитории на SourceCraft. Помимо этого проекта, я запускал генерацию в публичном репозитории Yandex Cloud, в нескольких опенсорсных репозиториях (с той самой докой в README) и даже для своей базы знаний. Модели для агентов тоже использовал разные — точно были GPT-5.6, Kimi K3, Qwen 3.8 27b, и везде получались достаточно полезные результаты.

Подробнее обо всех деталях и установке пресета смотрите в репозитории, ну и оставляйте обратную связь!