Понимание веб-разработки [3/3]

Финальная часть цикла статей о знакомстве с основными составляющими веб-разработки.

Разбираемся с тем, как запустить Python HTTPServer без кода на Python, как работать с терминалом, сопоставляем адреса localhost, 0.0.0.0, 127.0.0.1 и [::], а также на практике убеждаемся, что веб-сервер — это просто программа, запущенная на чьём-то компьютере.

Читайте здесь: https://alexjameson.github.io/articles/web-server/

#навыки

Как эффективнее использовать Qwen в качестве ассистента [1/2]

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

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

🟡 Приложения — просто чуть более удобный интерфейс по сравнению с веб-версией, но на десктопе есть возможность подключать MCP-сервера. Я пользуюсь MCP для поиска в интернете, получения контента по ссылке и для выполнения кода. Раньше использовал также доступ к файловой системе и sequential thinking, но отключил.

🟡 В обоих типах приложений также есть возможность подключить режим исследования (deep research). Этот режим работает хуже, чем в условном Perplexity. Но несовершенство результата компенсируется удобством прохождения всех сценариев в одном интерфейсе.

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

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

🟡 Но самым главным прорывом для меня стало появление возможности управлять системным промтом и ролью модели. В Qwen уже предусмотрены пресеты того, как должна отвечать модель. Я выбрал режим «Кратко», что сразу сделало ответы куда менее раздражающими. Также можно выбрать сократический стиль, чтобы модель задавала как можно больше вопросов.

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

#ai

Как эффективнее использовать Qwen в качестве ассистента [2/2]

Обе настройки ограничены 500 символами. В целом этого достаточно, если понимать, чего хочешь добиться от ассистента.

Роль:

You are a user's AI assistant. The user is a technical writer possessing knowledge of technical concepts in several areas such as software engineering, cloud computing, cybersecurity, data analysis, project management, technical documentation, copywriting and related fields. He is also interested in finances and a bit in STEM.

Your goal is to provide information on these topics, help solving work tasks and create new relatable content.

Инструкция для модели:

1. Provide answers with minimal formatting without emojis
2. No general information and compliments are required. Get straight to the point
3. When explaining technical concepts, avoid analogies from everyday life
4. When given a task to create code or text, analyze it and ask follow-up questions in Socratic style. Don't do it when you are asked to explain something
5. Break down complexities into smaller steps with clear reasoning
6. Present several perspectives or solutions when possible

#ai

Data — Information — Knowledge — Wisdom (DIKW)

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

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

Модель восходит к ранним работам по управлению знаниями (Кливленд, 1982; Эйкофф, 1989). Модель применима к любой предметной области, но здесь я дам примеры из практики.

🟡 Данные — необработанные, неструктурированные значения без контекста. В нашей предметной области это могут быть необработанные логи, метрики, параметры API, значения в полях СУБД и т.д.

Пример: {"timeout": 50} в логах.

🟡 Информация — данные с контекстом и структурой.

Пример: «Параметр timeout в методе /submit принимает целое число».

🟡 Знания — интерпретация информации на основе опыта или правил.

Пример: «Если timeout менее 100 мс, запрос может прерываться при высокой нагрузке на сеть».

🟡 Мудрость — применение знаний с учётом целей, ценностей и последствий.

Пример: «Установите timeout не ниже 200 мс, чтобы избежать потери данных».

В технической документации DIKW помогает выстраивать контент от справочников (информация) к инструкциям по решению задач (знания).

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

Если пофантазировать, почему в принципе появился уровень мудрости, то я бы предположил, что в американской культуре wisdom часто ассоциируется с практической дальновидностью: «wise investment». В русской традиции «мудрость» связана философией — это уже вне деловой или технической сферы.

Поэтому в технических системах и документации достаточно остановиться на знаниях: проверяемых, передаваемых и применимых. Не просто так мы так или иначе имеем дело с управлением знаниями, но редко подступаемся к мудрости.

#знания

Участвую в 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!