Всё о деятельности технических писателей
GigaChat 3.5 вышел в июле этого года, а в начале сентября были выложены открытые веса этой модели. И многие сейчас задаются вопросом: насколько эта модель подходит для решения бизнес‑задач? Мы провели тесты(забеги ИИ‑агента) на нашем бенчмарке, где мы сравнили работу на модели GigaChat 3.5 по сравнению с другими моделями: китайскими и российскими.
Российское ПО + оборудование в одном решении ещё не ПАК для Минцифры, но почти ПАК. Эксперты будет отдельно смотреть на программную и аппаратную части, права на них и главное — действительно ли они образуют единый комплекс.
Давайте разбираться, как включить ПАК в реестр Минцифры в этом году, что проверить и как подготовиться, чтобы получить заветные налоговые льготы от государства.
Меня зовут Антон Богун, я старший разработчик ПО в Axenix. В прошлой статье мы говорили о Doc as Code как об инженерной практике: документация живет в Git, проходит review, проверяется автоматически и становится частью процесса разработки. Это важная база, но сегодня у нее появляется следующий уровень применения.
Разработчик подключает ИИ-агента уже не к абстрактной документации, а к собственному проекту: к кодовой базе, OpenAPI спецификациям, Markdown страницам, release notes, задачам в трекере и интеграционным схемам. От агента ждут не пересказа документации, а понимания текущего поведения системы.
Именно здесь возникает новая проблема. Метод API может называться так же, путь может остаться прежним, request body может почти не измениться, но поведение системы уже стало другим. Например, заказ больше не создается сразу в финальном статусе, часть заказов уходит на дополнительную проверку, после создания публикуется событие, а обработка продолжается в другом сервисе через брокер сообщений.
Для человека такие изменения часто понятны из задачи, pull request, обсуждения или кода. Для ИИ-агента это неочевидно, если код, спецификация, документация и задачи не связаны между собой.
Doc as Code отвечает на вопрос: как хранить и проверять документацию. Но для ИИ-агента важнее следующий вопрос: как понять, что изменилось в поведении системы и где это отражено.
ИИ-агенту нужен контекст проекта, а не просто набор файлов
Когда мы говорим «дадим ИИ-документацию», часто подразумевается, что достаточно открыть агенту доступ к репозиторию, где лежат openapi.yaml, README и несколько Markdown страниц. Но в реальном проекте этого мало.
Вам в наследство досталось руководство пользователя МИС на 1160 страниц в формате .docx, тысячи повторяющихся скриншотов, процесс обновления вызывает глубокую грусть. Что с этим «добром» делать?
В этой статье я расскажу о своём проекте по переводу такой документации на рельсы docs-as-code: переосмысление структуры, укрощение размера скриншотов, борьба с кириллицей в Asciidoctor, настройка автоматической сборки HTML и PDF через GitLab CI/CD.
Беседуем с Дмитрием Разиным, специалистом службы эксплуатации и технического обслуживания.
– Расскажите, пожалуйста, о вашей компании, ее сфере деятельности и отличительных чертах.
– Компания занимается производством высококачественных марок стали. На заводе установлен высокоскоростной стан нового поколения, есть собственные транспортные мощности. Это позволяет в короткие сроки производить и доставлять продукцию стабильно высокого качества. Строится рельсобалочный цех, который станет самым большим в России.
– Как давно ваша компания пользуется продуктами «Нанософт» и какое именно ПО сейчас в работе на предприятии?
– Компания перешла на nanoCAD три года назад, в этой линейке работают более 20 специалистов. У нас много различных отделов, они используют Платформу nanoCAD, nanoCAD BIM Строительство, nanoCAD Конструкции PS, nanoCAD BIM Электро, nanoCAD комплект Инженерия, nanoCAD Металлоконструкции. Геодезический отдел работает в nanoCAD GeoniCS.
Одним из первых пробных проектов в nanoCAD стала работа над объектом «Станция растапливания бигбэгов». Он представляет собой кран на монорельсе. У верхнего края конструкции поднимается большой мешок с материалами, который впоследствии на нижней площадке открывает работник производства. Далее реагенты перемещаются на конвейере производственной линии.
Через дата-инженеров Далее проходят десятки описаний интеграций в совершенно разных форматах, даже в Excel. Формально такая API-документация есть, но пользоваться ей больно, а иногда и вовсе невозможно.
Разбираем, чем «болеют» документации, как сделать понятное руководство со Swagger и без него, посмотрим лучшие практики создания API-документации.
В конце — чек-лист для написания и проверки документации.
На примере сервиса мультифакторной аутентификации MULTIFACTOR: от лицензирования компании и подготовки продукта до испытаний, аттестации облачной части и нескольких десятков неудобных вопросов к архитектуре
«Посмотри эти коммиты, потом ещё вот этот фикс» — сколько раз вы так вводили AI-агента в курс командной задачи?
Я организовал OpenSpec так, чтобы фронтенд и бэкенд работали в своих зонах, а контекст передавался вместе с изменениями. У каждой стороны — собственные спецификации, правила и проверки. Следующий разработчик может подхватить работу коллег без пересказа всей истории агенту.
В статье разбираю, как это устроено, как синхронизироваться после нескольких задач в develop и когда фронтендер может сам сделать небольшую доработку бэкенда — и наоборот. Внутри — схема процесса, пример запроса агенту и шаблон передачи работы, которые можно адаптировать под свою команду.
Очереди в Bitrix Framework выполняют задачи в фоне. Это помогает разгрузить систему, если какие-то операции требуют много времени или ресурсов.
Разбираем подробнее, как они работают и как их настраивать — на примере.
Компании и разработчики часто относятся к договору на разработку ПО как к формальности, считая, что главное – договориться о цене, сроке и результате. Но на практике именно договор определяет, что именно должен сделать подрядчик, что обязан дать заказчик, кто получает права на код и что делать, если проект пошел не по плану.
В статье подробно разбираются в частности следующие вопросы:
1.Какой договор заключать на разработку ПО?
2.Что именно создаем, предмет договора и техническое задание
3.Когда начинается и заканчивается разработка, сроки и этапы разработки ПО
4.Как управляем изменениями, оформление изменений в ТЗ и дополнительных работ
5.Как платим за разработку, стоимость разработки и порядок оплаты
6.Как принимаем разработанное ПО?
7.Кому принадлежит исключительное право на ПО?
8.Что делать со сторонними компонентами?
9.Что происходит при расторжении договора?
10.Гарантия, ответственность, NDA и персональные данные
В конце материала представлен чек-лист проверки договора на разработку ПО
Поле описания merge request пустое или содержит список commit messages. Ревьюер открывает diff на несколько десятков файлов и не понимает, с чего начать. Писать описание руками — рутина, на которую забивают, а задача при этом формализуется идеально: на входе diff, на выходе текст по шаблону. Идеальная работа для LLM.
Так появился AI Describer — CLI‑инструмент, который запускается одним шагом пайплайна, берёт git diff относительно целевой ветки, отдаёт его модели и публикует структурированное описание обратно в merge/pull request. Работает и в GitLab CI, и в Jenkins на Windows‑агентах: у нас два хостинга репозиториев и столько же систем сборки.
Как я отдал агенту четыре репозитория и увидел то, что в коде не видно в принципе.
Каждый из четырёх репозиториев по отдельности выглядит прилично. Отдал их агенту, попросил восстановить архитектуру — и увидел на диаграмме три сервиса, пишущих в одну базу. О том, что вайбкод прячет между репозиториями.
Привет, на связи команда документирования СберТеха и авторы этой статьи — Маша Бурханова, Лида Ковач и Саша Яковлев.
Мы уже рассказывали, как создали глоссарий ИТ-терминов в удобном для разработки документации формате и с какими трудностями при этом столкнулись. Мы поняли: главная проблема технического писателя — это даже не отсутствие правил, а их соблюдение.
Представьте, что у вас есть больше 700+ терминов, а в коде на каждую десятую строчку приходится ошибка. Исправлять вручную — всё равно что пешком подниматься на 150-этажный небоскреб. У нас родилась идея: проверять текст прямо во время написания, в редакторе.
Расскажем, как за несколько часов собрали прототип ИИ-агента технического писателя, с какими «подводными камнями» столкнулись при переходе к промышленной эксплуатации и почему в итоге написали собственное решение на Python.
В своей же справке я нашёл фразу, которая была неправдой. Не устарела - была неправдой с самого начала. Дальше про то, как сделать так, чтобы кодовая база физически не могла врать в документации, и почему главная сложность тут не в тестах, а в списке исключений.
Аналитик на вебинаре поинтересовался иерархическими индексами для нормативки: дерево «документ → статья → пункт», модель спускается от корня и выбирает ветку, как человек листает оглавление. И сразу про затраты: индексация — это проход по всему корпусу.
Я сравнил такой индекс с B-деревом. Потом сел считать, и сравнение выдержало.
В B-дереве на диске узел подгоняют под блок, чтобы реже перемещать головку. Здесь блок — эффективное окно маленькой модели, а движение головки — обращение к ней.
Прикинем. Шесть актов на ~200 страниц — глубина 2. 2M токенов — глубина 3. Навигатор читает 8–12 тысяч токенов вместо всего корпуса. А само дерево в законах уже есть: главы, статьи, части, пункты. Строится регекспами по нумерации, без модели. Затраты один раз и только за краткое описание внутренних узлов.
Навигатору остаётся выбрать одну из пятидесяти веток по короткому описанию. Это ближе к классификации, чем к рассуждению. В зале спросили, справится ли с этим модель на 1,5–3 млрд параметров. Интрига.
В статье разберём, какие есть способы получать точные ответы по юридически значимой документации.
Внешний сервис может вернуть 500 вместо ожидаемого 400, принять запрос с ошибкой или ответить успешным статусом, но потерять часть данных внутри ответа.
Разберём, какие негативные сценарии стоит проверять заранее, как проектировать слой защиты между системами и почему надежная интеграция начинается с анализа того, как она может сломаться.
Для описания архитектуры важно выбрать подход, который будет понятен всей команде. Одним из них является нотация C4, разработанная Саймоном Брауном.
Данная статья — это продолжение и значительное дополнение моей предыдущей статьи по C4, опубликованной в 2023 году. Здесь я детально разобрала для вас каждый уровень и элемент нотации, распространённые ошибки и спорные вопросы, а также инструменты для создания диаграмм, в частности графический редактор Draw.io и Structurizr для создания C4 через код.
Внутри — много схем, картинок и практических примеров для монолитной и микросервисной архитектуры, готовый код Structurizr и промпт для ИИ. Статья организована таким образом, чтобы вы могли открыть её, последовательно пройти все разделы и самостоятельно разобраться с C4.
Статья будет полезна системным и бизнес-аналитикам, архитекторам, разработчикам, менеджерам проектов и всем, кто участвует в проектировании архитектуры систем.
В одной крупной финансовой компании, где я работал системным аналитиком, технические задания оформляют не в Confluence и не в Word...
В эпоху AI код становится дешевле, а качественное инженерное решение — ценнее.
Поэтому важнее не просто уметь быстро писать код, а уметь спроектировать систему так, чтобы человек и агент одинаково понимали: что нужно изменить, зачем, где проходят границы и каким должен быть результат.
Viaduct помогает превратить архитектурное проектирование в структурированный, проверяемый и доступный AI-агентам контекст — от модели системы до Change Set, по которому можно безопасно реализовать изменение.
В 2023 году RAG был единственным способом засунуть знания в LLM — контекстное окно было маленьким, часто были галлюцинации. RAG постепенно стал одной из самых популярных технологий, чтобы получить базу знаний, по которой можно искать данные через натуральный язык.
Но с другой стороны — RAG-пайплайн тяжёлый и трудозатратный. Компания хочет чат по своей документации. Разработчик говорит: нужен пайплайн — чанкинг, эмбеддинги, векторная база, реранкер. Два-три месяца работы плюс сервис, который надо вечно поддерживать, ради 400-страничной документации. И всё это занимает месяцы, тратит ресурсы ради не такой уж и большой выгоды.
Сегодня многие модели держат 1M токенов, а то и больше, а в это окно контекста чаще всего спокойно влезает вся документация. Но если не влезет — то обязательно ли сразу строить весь RAG самому? А как понять, когда есть альтернатива RAG, а когда нет?
В этой статье мы разберём, почему RAG стал выбором по умолчанию (и почему это было оправдано), посмотрим, как падает качество при Long Context, сравним подходы и узнаем, что, как и когда использовать.