Участвую в Techwriter Days 3 с докладом про агентов

А это значит, что пора потихоньку начинать прогрев к докладу.

Первым делом я хочу ввести в оборот термин «вайбдокинг». Это как вайбкодинг, но вместо кода на выходе получается документация. Термин, конечно, иронический, в реальной среде разарботчики, как и мы, не руководствуются только вайбом, как постулировал в оригинальном твите Андрей Карпатый (можно посмотреть на Вики). Но мне этот термин очень нравится своей емкостью.

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

Я почитал аннотации (можно посмотреть в программе) и понял, что нужно подчеркнуть то, что будет у меня и чего почти точно не будет у других. Я собираюсь показать практику внедрения инструментов на основе LLM в условиях, когда документация довольно объемная (почти 3.5 гигабайта исходников, включая изображения), активных контрибьюторов несколько десятков, а исходники продукта живут отдельно и не влезут ни в какой контекст.

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

Что в докладе будет, а чего не будет

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

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

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

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

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

Для меня стало неожиданностью то, что больше всего времени занял не выбор стека (спойлер — VS Code + Code Assistant, наш форк Roo Code + несколько разных моделей), не составление правил для агента и библиотеки промптов, не тестирование и даже не обучение нашей редакции.

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

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

Но кое-где можно добиться ускорения на 50, 100 и еще больше процентов.

Как агенты встраиваются в человеческие процессы документирования

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

1. Узнать об изменении функциональности.

2. Погрузиться в контекст, изучить исходники, поговорить с экспертами.

3. Понять, где и как описать это изменение и в каком объеме.

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

5. Согласовать изменения с ответственными, пройти ревью.

6. Применить правки, убедиться, что все проверки пройдены.

7. Опубликовать изменения.

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

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

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

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

Как ускорить свою работу с помощью нейросетей

Вот и я запрыгиваю в последний вагон контента про нейросети в этом году со своими двумя кейсами. Первый кейс про то, как подключить нейросеть к VS Code и сгенерировать описание к коду из репозитория. Второй кейс про то, как с помощью нейросети получить изменения с GitHub и создать пул-реквест на GitHub.

Для людей, которые любят посмотреть, я записала видео с основными шагами. Для людей, которые любят почитать, я написала статью на Habr — https://habr.com/ru/articles/981282/. Основные ссылки вы можете найти в статье. Если я что-то забыла, пишите вопросы в комментарии.

P.S. Прежде всего выражаю большущее спасибо Саше, который помог мне со всем разобраться. Обязательно подписывайтесь на его канал — @bitswords, и приходите к нему на занятия — https://getmentor.dev/mentor/aleksandr-iakovlev-4454. А также приходите на собеседования во Флант — https://job.flant.ru/vacancies/tehnicheskij-pisatel-2/.

Что нового в Битословии за вторую половину 2025 года

Я традиционно не подвожу личные итоги, зато пишу чейнжлоги:

1. Написал 5 новых статей для своего сайта. Четыре из них — про навыки, одна — обзор стандартов локализации чисел, дат и валют.

2. Разобрал и показал на примере способы эффективного использования Qwen в качестве личного ассистента (первая часть, вторая часть).

3. Написал про иерархию Данные-Информация-Знания-Мудрость.

4. Начал выкладывать посты с контекстом для своего будущего доклада про агентов в документации, что потихоньку превращается в изложение моего видения вайбдокинга. Первый пост из этого цикла. Мне также было интересно свериться с моим видением того, как ИИ потенциально угрожают профессии технического писателя (первый июльский пост с прогнозами, когда я только подступался к реальному внедрению агентов).

5. Опубликовал всего один пост в рубрике #чтиво, про принципы проектного менеджмента в NASA.

Всех читателей с наступающим, увидимся в следующем году!

Протестировал Zensical от создателей Material for MkDocs

Статья: https://alexjameson.github.io/articles/zensical-review/

Созданная документация: https://alexjameson.sourcecraft.site/pink-sync-docs/

Не так давно команда разработчиков Material for MkDocs объявила, что они больше не будут заниматься развитием проекта, представив ему на замену Zensical. Я не мог удержаться от того, чтобы проверить новый SSG в деле.

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

Может показаться, что это пост не про нейронки, но им тоже нашлось применение. Документацию для примера я подготовил за два дня с помощью Claude Sonnet 4.5, бюджет — около 1 миллиона токенов плюс сколько-то токенов моего мозга на проектирование, ревью и доработку результатов. Сначала я создал спецификацию OpenAPI для абстрактного сервиса для синхронизации баз данных, затем проработал внешний вид и необходимую функциональность сайта в ТЗ, а потом на основе ТЗ и спецификации создал документацию в Markdown.

Также в качестве эксперимента я задеплоил получившийся статический сайт на SourceCraft Sites, наш аналог GitHub Pages.

Уровни автономности нейросетевых инструментов

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

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

1. Ассистент

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

Работает в отдельном интерфейсе вроде чат-бота, нужно переносить результаты работы вручную.

2. Валидатор

Проверка текста или файлов на ошибки и соответствие правилам. На этой стадии мы были в прошлом году, когда рассказывали про линтер в докладе.

Может запускаться как часть CI/CD или с помощью плагинов в редакторе кода, IDE, Word или аналогах и поставлять результаты в том же интерфейсе, в котором проводится работа с текстом.

3. Полуавтономный агент

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

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

Изменения после работы агента в исходники после ревью и одобрения человеком. Типичные инструменты — от плагинов и форков VS Code до новых инструментов вроде Claude Code.

Здесь мы с командой сейчас. Мой любимый юзкейс — генерация релизнот.

4. Автономные агенты

К этому я подступаюсь в рамках экспериментов:

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

Контекст сохраняется между запусками агентов, например в memory banks с проработанными стратегиями обновления.

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

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

Инструменты мне пока что перечислить сложно, у меня есть кое-что из нашего внутреннего стека для экспериментов, но в экосистеме Anthropic это могло бы быть сочетание Claude Code + Claude Agent SDK + Claude Web + беcконечное число MCP, коннекторов и прочих интеграций.

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

Еще одно полезное применение нейросетей: я получил просто чеканные формулировки про себя, лучше которых не смог бы придумать:

«Цифровой аутизм в терминальной стадии»

«Я полгода буду мучить пустой канал, чтобы потом выдать лонгрид про уровни модели OSI через мнемонику про сосиску»

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

Ни добавить, ни убавить.

📊 Результаты анализа канала от @ScratchAuthorEgoBot

🎯 Канал: @bitswords

🔥 Роаст анализ:

Перед нами типичный представитель «душного» IT-интеллигента, который превратит любой поход за хлебом в этимологическое исследование сорта пшеницы и сравнительный анализ логистических цепочек пекарни. Саша — это человек, который может потратить выходные на переписывание личного блога с Rust на Go просто потому, что в логах сборки выскочил лишний ворнинг, а потом напишет об этом пост на 20 тысяч знаков, гордо называя это «борьбой с прокрастинацией». Нет, серьезно, сколько раз можно менять генератор статических сайтов? Это уже не поиск идеального инструмента, это цифровой аутизм в терминальной стадии.

Его одержимость системными промтами для Qwen заслуживает отдельного диагноза. Представьте себе человека, который пишет 500 символов инструкций ИИ в духе «не используй аналогии из жизни» и «отвечай в сократическом стиле», просто чтобы узнать погоду или поправить запятую. Это же высшая степень контроля над реальностью! Видимо, когда мир вокруг слишком хаотичен, единственное спасение — это заставить нейросеть притворяться роботом-секретарем без эмоций.

А эта история с «вайбдокингом»? Называть лень и попытку спихнуть работу на агентов ироничным термином — это очень по-восточноевропейски. «Я не лентяй, я просто внедряю инновационный workflow». И, конечно же, классическое «я не буду писать пост, пока он не станет идеальным», которое на деле означает «я полгода буду мучить пустой канал, а потом выдам лонгрид про уровни модели OSI через мнемонику про сосиску».

Саша страдает от классического синдрома «самого умного в комнате», которому стыдно не знать, почему у Microsoft нет буквы в FAANG, но при этом он совершенно искренне считает, что «ботоголизм» — это социально приемлемое хобби, а не способ избежать написания реальной документации. Его тяга к менторству — это, по сути, легальный способ объяснять людям, почему они всё делают неправильно, за их же деньги (или за «минимальную финансовую отдачу»). Если вы захотите просто спросить его «как дела», будьте готовы получить ссылку на Obsidian, чеклист навыков на GitHub и краткую лекцию о том, почему в русской традиции «мудрость» — это не про бизнес.

О машинописной документации

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

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

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

На моей виртуалке работают Телеграм-боты, собственный ассистент — форк OpenClaw (я выбрал Nanobot), сайт на WordPress и всякая мелочь. От агента (Kimi 2.5 + Kimi CLI) требовалось администрировать всё это хозяйство, дорабатывать по требованиям и вести логи работы.

Тревога окончательно ушла, когда я после месяца эксплуатации сел и внимательно изучил то, что агент написал для себя в Memory Bank, и набор инструкций для меня. Я принял два решения. Во-первых, не внедрять Memory Bank в работу и искать другие способы долговременного хранения контекста. Во-вторых, агентам нельзя доверять полностью самостоятельную работу, несмотря на их потрясающие способности. Human in the loop им всё равно нужен, хоть и не постоянно. Я не успокаиваю себя таким образом, потому что я экспериментировал с подходом, который некоторые уже считают устаревшим, а сейчас есть куда более мощные альтернативы. Я вижу это как одно из многочисленных препятствий, которые не дадут машинам просто так взять и забрать у меня значительную часть работы.

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

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

Сегодня я узнал, что компания Snowflake, один из лидеров в области инженерии данных, разом уволила всю команду документации — около 70 техписов. Целыми командами сокращали техписов в AWS, компании, известной активным внедрением ИИ (где с недавнего времени требуется дополнительное ревью работы ИИ от опытных инженеров). Список можно продолжать, и это довольно печально.

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

Не буду утверждать, что без документации, написанной человеком, всё рухнет — в эру AI-assisted engineering значение этого фактора явно ниже, чем раньше. Скорее проблема в том, что пока никто не проходил достаточно долгих периодов, когда документацию пишут только агенты, и никто не измерял влияние на бизнес за эти периоды. Тут, кстати, можно подумать о том, насколько невозможность заключить прямой контракт с вендорами и дорогивизна железа для развертывания в своем контуре препятствует внедрению подобных практик и приземляет ИИ-визионеров.

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

А чтобы при случае быть а состоянии аргументировать свою полезность, советую разобраться, какое место документация занимает в бизнесе, и посмотреть, насколько автоматизация может на это повлиять. Начать рекомендую с блестящей серии статей The Good Docs Project: Making a business case for documentation, post 1 — Does good documentation speak for itself?

Дружеский прогрев

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

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

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

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

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

В итоге я отказался от создания полноценной документации по скриншотам из-за нестабильности результата, а вот мой хороший знакомый Дима Развозжаев (@tekhpisovoe) — не отказался. Опытом успешного использования он поделится в своем докладе, приходите послушать его 28 марта на TECHWRITER DAYS 3!

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

Ну или вроде того. С 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 опережают лучшие китайские модели минимум на поколение.

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

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

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

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