Блог
Публикации о процессе разработки, решённых задачах и изученных технологиях
Документация врёт: что на самом деле происходит в production
# Когда документация на месте, а реальность — в другой комнате Работаю с проектом voice-agent уже несколько месяцев. Классический случай: архитектура идеально описана в CLAUDE.md, правила параллельного выполнения агентов расписаны до мелочей, даже обработка ошибок задокументирована. На бумаге всё правильно. Но потом приходит первая задача от пользователя, и выясняется: между документацией и реальностью — целая бездна. Начнём издалека. У нас есть агентская система с разделением ролей: Opus для архитектуры и bash-команд, Sonnet для имплементации, Haiku для шаблонного кода. Казалось бы, идеально. Параллельное выполнение до 4 агентов одновременно, жёсткое разделение backend'а и frontend'а. На практике же выяснилось, что в последний день активности было ноль пользовательских взаимодействий. Ноль! При 48 инсайтах от агентов. Это сигнал. Первым делом я решил проверить ERROR_JOURNAL.md — документация требует начинать с него. И тут первая проблема: файл либо не существует, либо пуст. Глобальное правило говорит: *проверь журнал ошибок перед любым диагнозом*, а его попросту нет. Это уже что-то значит. Значит, либо команда срезала углы, либо инцидентов попросту не было. Третьего не дано. Дальше я посмотрел на то, что описано в phase-плане для TMA (53 задачи во всех этапах). Документация обещает методичное разбиение работы. Проверил git log — и вот странность: некоторые коммиты с описаниями, но судя по датам, AgentCore рефакторинг якобы прошёл, но в коде я его не нашёл. Это очень типичная ситуация в больших проектах: документация отстаёт от реальности, или наоборот — расходилась на раннем этапе и никто не синхронизировал. Здесь я выучил важный урок. Когда я читал правила про управление контекстом субагентов, там чётко сказано: *не дублируй информацию, передавай минимум*. Казалось бы, конфликт с thorough-подходом. Но это не конфликт — это оптимизация. Если в документации написано, что sub-agents не выполняют Bash (автоматический deny), то параллельное выполнение задач оказывается иллюзией: все команды приходится сериализовать после файловых операций. И документация об этом ничего не говорит. **Неожиданно полезный инсайт**: читал про constraint-driven design. Оказывается, это вообще методология — начинать не с возможностей, а с ограничений. Если системе запрещены Bash-команды в параллель, нужно проектировать workflow с этим в голове с дня первого. Большинство проблем возникают потому, что документация описывает идеал, а ограничения считаются деталями. В итоге я сделал простую вещь: создал pre-flight checklist для каждого нового взаимодействия. Сначала — Read на PHASES.md, потом Git log для валидации, потом Grep для проверки реальности кода. Только *потом* я предлагаю следующие шаги. Документация классная, но реальность — источник истины. Ключевой урок: никогда не отождествляй то, что написано, с тем, что сделано. И всегда начинай с проверки, не с веры 😄
Whisper медленнее речи: как мы выиграли 200 миллисекунд
# Ловушка Whisper: как мы разогнали транскрипцию до 0,8 секунды Проект **speech-to-text** нашёл себе больное место: даже на самых "быстрых" моделях Whisper первая фраза обрабатывалась дольше, чем её произносили. Целевой показатель стоял железобетонный — менее одной секунды на стандартном CPU. К началу оптимизации мы знали, что проблема не в коде, а в том, как мы неправильно используем сам Whisper. Первым делом выяснилось нечто контринтуитивное: **Whisper всегда кодирует ровно 30 секунд аудио**, даже если вы скормили ему полтора. Это архитектурная особенность энкодера, которая в streaming-режиме оборачивается катастрофой. Мы записывали аудио на лету и попытались сделать per-chunk транскрипцию — буквально каждые 1,5 секунды гоняли Whisper через полный проход. Математика ужасна: четыре полных прохода энкодера вместо одного. Решение оказалось хирургическим: перешли в режим *record-only*, где во время записи ничего не обрабатывается. Только когда пользователь наконец закрыл микрофон — бах! — один единственный вызов Whisper на полную акустическую ленту. Это потребовало переписать логику в `streaming_pipeline.py` и финализатор в `main.py`, но скорость выросла разительно. Дальше начались микрооптимизации. **beam search с beam=2** — классический параметр для качества — оказался избыточным на CPU. Бенчмарк показал: beam=1 финишировал в 1,004 секунды, beam=2 влачился в 1,071. Разница в качестве была незаметна человеческому уху, зато T5 TextCorrector в постобработке компенсировал любые огрехи. Параллельно зафиксировали, что 32 потока CPU создают контенцию вместо ускорения — откатились на 16. Отключили expensive re-decoding для low-confidence сегментов. Добавили **model warm-up** при старте приложения: сразу после загрузки Whisper и T5 прогреваем фиктивным проходом, чтобы CPU-кэши прогрелись. Первая реальная транскрипция ускоряется на 30% благодаря горячему старту. И вот вишня на торт: добавили поддержку модели **"base"**. Почему раньше никто не пробовал? Наверное, потому что в 2020-е годы принято считать, что нужна максимальная точность. Но бенчмарк открыл истину: `base + T5 = 0,845 секунды`. Это ниже целевого порога! `tiny + T5` едва за ним — 0,969. Даже `small` без постобработки не дотягивал до целевой отметки. В результате история Whisper стала историей о том, как **понимание архитектуры важнее перебора параметров**. Мы не добавляли сложность — мы убирали неправильную сложность, которая была встроена в неправильное понимание того, как вообще работает эта модель. И помните: если ваша микросервисная архитектура в каждом запросе пересчитывает кэши — это не масштабирование, это программирование 😄
Четыре теста, одна ночь отладки: как спасти CI/CD
# Когда четыре теста разваливаются в один день: история отладки trend-analisis Понедельник, утро. Проект **trend-analisis** решил напомнить мне, что идеально работающий код — это миф. Четыре тестовых файла сразу выплюнули красные ошибки, и нужно было их чинить. Ситуация была классическая: код выглядел нормально, но CI/CD не согласен. Как оказалось, причин было несколько, и каждая скрывалась в разных углах проекта. Первым делом я запустил тесты локально, чтобы воспроизвести проблемы в контролируемой среде. Это был правильный ход — иногда баги исчезают при локальном запуске, но не в этот раз. Началось с проверки зависимостей. Оказалось, что некоторые модули были загружены с неправильными версиями — классическая ситуация, когда разработчик забывает обновить package.json. Второй проблемой стали асинхронные операции: тесты ожидали завершения промисов, но таймауты были установлены слишком жёстко. Пришлось балансировать между скоростью выполнения и надёжностью. Третий вызов был психологический. Между тестами оказалось «грязное» состояние — один тест оставлял данные, которые ломали следующий. Пришлось добавить правильную очистку состояния в каждом `beforeEach` и `afterEach` блоке. Четвёртая ошибка была совсем коварной: неправильный путь для импорта одного модуля на Windows-машине соседа по команде. Интересный факт о **JavaScript тестировании**: долгое время разработчики игнорировали изоляцию тестов, думая, что это усложнит код. Но история показала, что тесты, которые зависят друг от друга, — это бомба замедленного действия. Один изменённый тест может сломать пять других, и потом начинается детективная работа. После трёх часов кропотливой работы все четыре файла прошли проверку. Я запустил полный набор тестов на CI/CD, и зелёная галочка наконец появилась. Главное, что я выучил: при работе с AI-помощниками вроде Claude в проекте важно тестировать не только конечный результат, но и процесс, по которому код был сгенерирован. Часто боты пишут рабочий код, но забывают про edge cases. Теперь каждый коммит проходит через эту строгую схему проверок, и я спокойно сплю 😄
Четыре теста, одна ночь отладки: как спасти CI/CD
# Когда четыре теста разваливаются в один день: история отладки trend-analisis Понедельник, утро. Проект **trend-analisis** решил напомнить мне, что идеально работающий код — это миф. Четыре тестовых файла сразу выплюнули красные ошибки, и нужно было их чинить. Ситуация была классическая: код выглядел нормально, но CI/CD не согласен. Как оказалось, причин было несколько, и каждая скрывалась в разных углах проекта. Первым делом я запустил тесты локально, чтобы воспроизвести проблемы в контролируемой среде. Это был правильный ход — иногда баги исчезают при локальном запуске, но не в этот раз. Началось с проверки зависимостей. Оказалось, что некоторые модули были загружены с неправильными версиями — классическая ситуация, когда разработчик забывает обновить package.json. Второй проблемой стали асинхронные операции: тесты ожидали завершения промисов, но таймауты были установлены слишком жёстко. Пришлось балансировать между скоростью выполнения и надёжностью. Третий вызов был психологический. Между тестами оказалось «грязное» состояние — один тест оставлял данные, которые ломали следующий. Пришлось добавить правильную очистку состояния в каждом `beforeEach` и `afterEach` блоке. Четвёртая ошибка была совсем коварной: неправильный путь для импорта одного модуля на Windows-машине соседа по команде. Интересный факт о **JavaScript тестировании**: долгое время разработчики игнорировали изоляцию тестов, думая, что это усложнит код. Но история показала, что тесты, которые зависят друг от друга, — это бомба замедленного действия. Один изменённый тест может сломать пять других, и потом начинается детективная работа. После трёх часов кропотливой работы все четыре файла прошли проверку. Я запустил полный набор тестов на CI/CD, и зелёная галочка наконец появилась. Главное, что я выучил: при работе с AI-помощниками вроде Claude в проекте важно тестировать не только конечный результат, но и процесс, по которому код был сгенерирован. Часто боты пишут рабочий код, но забывают про edge cases. Теперь каждый коммит проходит через эту строгую схему проверок, и я спокойно сплю 😄
127 тестов против одного класса: как пережить рефакторинг архитектуры
# Когда архитектура ломает тесты: история миграции 127 ошибок в trend-analisis Работал над проектом **trend-analisis** — это система анализа трендов, которая собирает и обрабатывает данные через REST API. Задача была неприятная, но неизбежная: мы решили полностью переделать подсистему управления состоянием анализа, заменив рассыпанные функции `api.routes._jobs` и `api.routes._results` на единую архитектуру с классом `AnalysisStateManager`. На бумаге всё казалось просто: один класс вместо двух модулей — красивая архитектура, лучшая тестируемость, меньше магических импортов. На практике выяснилось, что я разломал 127 тестов. Да, сто двадцать семь. Каждый упорно ссылался на старую структуру. **Первым делом** я решил не паниковать и правильно измерить масштаб проблемы. Запустил тесты, собрал полный список ошибок, разделил их по категориям. Выяснилось, что речь идёт всего о двух типах проблем: либо импорты указывают на несуществующие модули, либо вызовы функций используют старый API. Остальное — семь реальных падений в тестах, которые указывали на какие-то более глубокие проблемы. Напомню: как древние мастера Нураги на Сардинии создавали огромные каменные статуи Гигантов из Монте-Прама, фрагментируя их на части для тонкой работы, — так я решил разбить фиксинг на параллельные потоки. Запустил сразу несколько агентов: один изучал новый API `AnalysisStateManager`, другой проходил по падающим тестам, третий готовил автоматические замены импортов. Документация проекта вдруг обрела смысл — она подробно описывала новую архитектуру. Поскольку я работал с Python и JavaScript в одном проекте, пришлось учитывать нюансы обеих экосистем. В Python использовал встроенные инструменты для анализа кода, в JavaScript включил регулярные выражения для поиска и замены. **Неожиданно выяснилось**, что некоторые тесты падали не из-за импортов, а потому что я забыл про асинхронность. Старые функции работали синхронно, новый `AnalysisStateManager` — асинхронный. Пришлось добавлять `await` в нужные места. Вот интересный факт о тестировании: популярный unittest в Python часто считают усложнённым инструментом для описания тестов, потому что тесты становятся декларативными, отвязанными от реального поведения кода. Поэтому лучшие практики рекомендуют писать тесты одновременно с фичей, а не потом. После двух часов систематической работы все 127 ошибок были исправлены, а семь реальных падений проанализированы и залочены. Архитектура стала чище, тесты — понятнее, и код готов к следующей итерации. Чему я научился? **Никогда не переписывай архитектуру без хорошего плана миграции тестов.** Это двойная работа, но она окупается чистотой кода на годы вперёд. 😄 Что общего между тестами и подростками? Оба требуют постоянного внимания и внезапно ломаются без видимых причин.
Укротил консоль Claude CLI на Windows одной строкой кода
# Консоль Claude CLI срывалась с цепи: как я её укротил Проект `bot-social-publisher` — это наша система автоматической публикации и обогащения контента в социальных сетях. В нём есть весь микс: асинхронные операции, работа с API, обработка данных. И вот в один прекрасный день во время тестирования на Windows заметил странное: каждый раз, когда система вызывает Claude CLI для обогащения заметок, ей вдруг охота открыть полноценное окно консоли. Просто так, ни с того ни с сего. Задача была простая на первый взгляд: найти, почему это происходит, и избавиться от этого раздражения. Потому что пользователям совсем не нужно видеть чёрные окошки, которые мельком появляются и исчезают. Выглядит как баг, а на самом деле — просто недостаток в реализации. **Первым делом** я открыл файл `cli_client.py`, где происходит запуск Claude CLI через `subprocess.run()`. И понял проблему на лету: когда мы вызываем subprocess из графического приложения на Windows, операционная система по умолчанию выделяет для этого процесса собственное консольное окно. Это поведение встроено в Windows — она думает, что subprocess нужно взаимодействовать с пользователем через консоль. **Неожиданно выяснилось**, что решение находилось буквально в одной строке кода. Windows поддерживает специальный флаг `CREATE_NO_WINDOW` (магическое число `0x08000000`), который говорит: «Дружище, создай процесс, но без консоли, спасибо». Я добавил этот флаг в параметры `creationflags` для вызова `subprocess.run()`, но только на Windows — на других платформах флаг просто игнорируется. Вот здесь полезно знать: Windows и POSIX-системы совершенно по-разному управляют процессами и их потоками ввода-вывода. На Linux и macOS концепция отдельного консольного окна просто не существует — процесс запускается в той среде, откуда его вызвали. На Windows же это полноценный механизм с флагами и правами. Именно поэтому в боевом коде всегда нужно проверять `sys.platform == "win32"` перед тем, как применять специфичные для Windows флаги. **После исправления** система работает как надо: Claude CLI вызывается в фоне, обогащает заметки, возвращает результаты, а пользователь ничего не видит. Никаких мелькающих консолей, никаких помех. Просто чистая работа. Закоммитил изменения в `main`, и проблема ушла в историю. Оказалось, что те микро-раздражители, которые кажутся мелочью, часто это просто небольшие знания о платформе, на которой работаешь. Windows не враг, она просто работает не так, как мы привыкли 😄
От хаоса к объектам: как переделали API для трендов
# Регистрируем API эндпоинт: как архитектура трендов выросла из хаоса документации Мне нужно было разобраться с проектом **trend-analysis** — системой для отслеживания трендов из GitHub и Hacker News. Проект жил в состоянии «почти готово», но когда я начал читать логи и документацию, выяснилось: база данных хранит обычные статьи, а нужно хранить **объекты** — сущности вроде React.js или ChatGPT, за которыми стоит десятки упоминаний. Первым делом я столкнулся с классической проблемой: эксперты предложили одну методологию определения трендов, а Глеб Куликов (архитектор системы) независимо пришёл к другой — и они совпадали на **95%**. Но Куликов заметил то, что упустили эксперты: текущая архитектура создаёт дубликаты. Одна статья о React — один тренд, вторая статья о React — второй тренд. Это как хранить 10 постов о Путине вместо одной записи о самом Путине в каталоге. Я решил реализовать **гибридную модель**: добавить слой entity extraction, чтобы система извлекала объекты из статей. Значит, нужны новые таблицы в БД (`objects`, `item_objects`, `object_signals`) и, самое важное, новые API эндпоинты для управления этими объектами. **Вот тут начинается интересная часть.** API эндпоинты я размещал в `api/auth/routes.py` — стандартное место в проекте. Но admin-endpoints для работы с объектами требовали отдельного маршрутизатора. Я создал новый файл с роутером, настроил префикс `/admin/eval`, и теперь нужно было **зарегистрировать его в main.py**. На фронтенде добавил страницу администратора для управления объектами, обновил боковую панель навигации, реализовал API-клиент на TypeScript, используя существующие паттерны из проекта. По сути, это была целая цепочка: api → typescript-client → UI components → i18n ключи. **Занимательный факт о веб-архитектуре**: корневая ошибка новичков — писать эндпоинты, не думая о регистрации роутеров. Flask и FastAPI не магическим образом находят ваши функции. Если вы создали красивый эндпоинт в отдельном файле, но забыли добавить `app.include_router()` в main.py — для клиента это будет 404 Not Found. Поэтому регистрация в точке входа приложения — это не «формальность», это **фундамент**. В итоге система сегодня: - Не ломает текущую функциональность (backward compatible) - Может извлекать объекты из потока статей - Отслеживает свойства объектов: количество упоминаний, интенсивность сентимента, иерархию категорий - Готова к полной дедупликации в Q3–Q4 Документировал всё в `KULIKOVS-METHODOLOGY-ANALYSIS.md` — отчёт на 5 фаз имплементации. Теперь архитектура стройная, и следующие разработчики не будут гадать, почему в системе 10 записей о React вместо одной. 😄 Почему Ansible расстался с разработчиком? Слишком много зависимостей в отношениях.
121 тест в зелёном: как переписать сердце системы и ничего не сломать
# Когда 121 тест встают в строй: история запуска первого зелёного набора Проект `ai-agents` подошёл к критической точке. За спиной — недели работы над `ProbabilisticToolRouter`, новой системой маршрутизации инструментов для AI-агентов. На столе — 121 новый тест, которые нужно было запустить в первый раз. И вот, глубоко вдохнув, запускаю весь набор. Ситуация была напряженная. Мы переписывали сердце системы — логику выбора инструментов для агента. Раньше это был простой exact matching, теперь же появилась вероятностная модель с четырьмя слоями оценки: регулярные выражения, точное совпадение имён, семантический поиск и ключевые слова. Каждый слой мог конфликтовать с другим, каждый мог сломаться. И при этом нельзя было сломать старый код — обратная совместимость была святым. Первый запуск ударил болезненно: **120 пройдено, 1 упал**. Виноват был тест `test_threshold_filters_low_scores`. Оказалось, что exact matching для "weak tool" возвращает score 0,85, что выше порога в 0,8. Сначала я испугался — неужели роутер работает неправильно? Но нет, это было *корректное поведение*. Тест ловил старую логику, которую мы переделали. Исправил тест под новую реальность, и вот — **121 зелёный**, всё завершилось за 1,61 секунды. Но главное — проверить, что мы ничего не сломали. Запустил старые тесты. **15 пройдено за 0,76 секунды**. Все зелёные. Это было облегчение. Интересный момент здесь в том, как мы решали задачу покрытия. Тесты охватывали не просто отдельные модули, а целые стеки: пять абстрактных адаптеров (AnthropicAdapter, ClaudeCLIAdapter, SQLiteAdapter и прочие) плюс их реализации, система маршрутизации с её четырьмя слоями, оркестратор агентов с обработкой tool calls, даже desktop-плагин с трей-иконками и Windows-уведомлениями. Это был не просто набор модульных тестов — это была интеграционная проверка всей архитектуры. **А знаете интересный факт?** Первый фреймворк для юнит-тестирования `SUnit` создал Кент Бек в 1994 году для Smalltalk, но идея "красный-зелёный-рефакторинг" стала массовой только в нулевых с приходом TDD. Когда вы видите 121 зелёный тест, вы смотрите на эволюцию подхода к качеству, который менял индустрию. После этого запуска система стала более уверенной в себе. Мы знали, что новая маршрутизация работает, что обратная совместимость целая, что все интеграции функционируют. Это дало зелёный свет для дальнейших оптимизаций и рефакторинга кода. А главное — мы получили надёжный фундамент для развития: теперь каждое изменение можно будет проверить против этого «стандарта качества из 121 теста». Иногда разработка — это просто ожидание результата консоли. Но когда все полосы зелёные, это чувство стоит каждой минуты отладки. 😄
Логи в системном трее: как простая отладка спасла меню устройств
# Охота на баги в системном трее: как логи спасили день Проект **speech-to-text** — это приложение для распознавания речи с поддержкой выбора аудиоустройства прямо из системного трея. Казалось бы, простая задача: пользователь кликает по иконке микрофона, видит список устройств, выбирает нужное. Но реальность оказалась хитрее. ## Когда старая сборка не хочет уходить Всё началось со стандартной проблемы: после изменения кода сборка падала, потому что старый EXE-файл приложения всё ещё работал в памяти. Казалось бы, что здесь сложного — убить процесс, запустить новый. Но разработчик пошёл дальше и решил запустить приложение в **режиме разработки** прямо из Git Bash, чтобы видеть логи в реальном времени. Это сыграло ключевую роль в том, что произошло дальше. Задача была конкретной: разобраться, почему меню выбора аудиоустройства в системном трее работает странно. Пользователь кликает на "Audio Device", но что происходит дальше — неизвестно. Здесь-то и нужны были логи. ## Логирование как инструмент детектива Первое, что сделал разработчик — добавил логирование на каждый шаг создания меню устройств. Это классический подход отладки: когда ты не видишь, что происходит внутри системного трея Windows, логи становятся твоим лучшим другом. Приложение запущено в фоновом режиме. Инструкция для тестирования была простая: наведи курсор на "Audio Device" в трее, и система начнёт логировать каждый шаг процесса. Процесс загрузки моделей искусственного интеллекта занимает 10–15 секунд — это время, когда нейросетевые модели инициализируются в памяти. Кстати, это напоминает, как работают трансформеры в современных AI-системах. По сути, когда речь преобразуется в текст, система использует архитектуру на основе multi-head attention: звук кодируется в токены, каждый токен переходит в векторное представление, а затем контекстуализируется в рамках контекстного окна с другими токенами параллельно. Это позволяет системе "понять", какие части речи важны, а какие можно проигнорировать. ## Жизненный цикл одного багфикса Разработчик делал это методично: добавил логирование, перезапустил приложение с новым кодом, ждал инициализации, затем попросил выполнить действие (клик по "Audio Device"). После этого — проверка логов. Это не просто отладка. Это **итеративный цикл** обратной связи: код → перезапуск → действие → анализ логов → новое понимание. Каждая итерация приносила всё больше информации о том, как именно система ведёт себя на уровне системного трея. Главный вывод: когда ты работаешь с компонентами операционной системы (вроде системного трея Windows), логирование становится не просто удобством, а необходимостью. Без логов ты работаешь вслепую. ## Что дальше На этот момент приложение работало, логирование было активно, и любое действие пользователя оставляло след в логах. Это была база для настоящей отладки — уже известно, как и где начать искать проблему. Разработчик научился важному уроку: **никогда не недооценивай силу логирования при работе с системными компонентами**. Это, конечно, не панацея, но когда ты охотишься на баги в чёрном ящике операционной системы, логи — это твой фонарик. Если NumPy работает — не трогай. Если не работает — тоже не трогай, станет хуже. 😄
Как мы развязали узел агентов: adapter pattern в боевых условиях
# От паттерна к реальности: как мы завернули AI-агентов в красивую архитектуру Полгода назад я столкнулся с классической проблемой: проект `ai-agents` рос как на дрожжах, но код превратился в сложный клубок зависимостей. LLM-адаптеры, работа с БД, поиск, интеграции с платформами — всё смешалось в одном месте. Добавить новый источник данных или переключиться на другую модель LLM стало настоящим квестом. Решение было очевидным: **adapter pattern** и **dependency injection**. Но дьявол, как всегда, сидит в деталях. Первым делом я создал иерархию абстрактных адаптеров. `LLMAdapter` с методами `chat()`, `chat_stream()` и управлением жизненным циклом, `DatabaseAdapter` для универсального доступа к данным, `VectorStoreAdapter`, `SearchAdapter`, `PlatformAdapter` — каждый отвечает за свой слой. Звучит скучно? Но когда ты реализуешь эти интерфейсы конкретно — начинает быть интересно. Я написал **AnthropicAdapter** с полной поддержкой streaming и tool_use через AsyncAnthropic SDK. Параллельно сделал **ClaudeCLIAdapter** — суперсредство, позволяющее использовать Claude через CLI без затрат на API (пока это experimental). Для работы с данными подключил **aiosqlite** с WAL mode — асинхронность плюс надёжность. **SearxNGAdapter** с встроенным failover между инстансами. **TelegramPlatformAdapter** на базе aiogram. Всё это управляется через **Factory** — просто конфиг меняешь, и готово. Но главная фишка — это **AgentOrchestrator**. Это сердце системы, которое управляет полным chat-with-tools циклом через адаптеры, не зная о деталях их реализации. Dependency injection через конструктор означает, что тестировать проще простого: подай mock'и — и программа думает, что работает с реальными сервисами. Вторая часть истории — **ProbabilisticToolRouter**. Когда у агента сто инструментов, нужно понимать, какой из них нужен на самом деле. Я построил систему с четырьмя слоями scoring: regex-совпадения (вес 0,95), точное имя (0,85), семантический поиск (0,0–1,0), ключевые слова (0,3–0,7). Результат — ранжированный список кандидатов, который автоматически инжектится в system prompt. Никаких случайных вызовов функций. А потом я подумал: почему бы не сделать это ещё и десктопным приложением? **AgentTray** с цветовыми индикаторами (зелёный — работает, жёлтый — обрабатывает, красный — ошибка). **AgentGUI** на pywebview, переиспользующий FastAPI UI. **WindowsNotifier** для уведомлений прямо в систему. И всё это — тоже адаптеры, интегрированные в ту же архитектуру. **Интересный факт**: паттерн adapter родился в 1994 году в книге «Gang of Four», но в эру микросервисов и облачных приложений он переживает второе рождение. Его главная суперсила — не столько в самом коде, сколько в психологии: когда интерфейсы чётко определены, разработчики начинают *думать* о границах компонентов. Это спасает от копипасты и циклических зависимостей. По итогам: 20 новых файлов, полностью переработанная `config/settings.py`, обновленные requirements. Система теперь масштабируется: добавить нового LLM-провайдера или переключиться на PostgreSQL — это буквально несколько строк конфига. Код более тестируемый, зависимости явные, архитектура дышит. И главное — это работает. Действительно работает. 😄
Реставрация после краха: как чекпоинты спасли мой ML-марафон
# Марафон обучения модели: как я перезагрузил сервер посередине тренировки Проект **llm-analysis** требовал обучения нескольких моделей параллельно. На доске стояла амбициозная задача: запустить шесть вычислительных процессов (их называют квартами — Q1 и Q2, по 3 чекпоинта каждая), каждый из которых должен пройти 150 эпох обучения. Время было критично: каждый день задержки — это дополнительная неделя на GPU. Первым делом я запустил квартет Q1. Все три модели (1.1, 1.2, 1.3) стабильно обучались, постепенно повышая accuracy. Первый квартет завершился успешно — все чекпоинты сохранились на диск. Так что Q1 был зелёным сигналом. Затем начал Q2. Запустил пару 2.1 и 2.4 параллельно, оставляя GPU свободным для 2.2 и 2.3 после их завершения. Модели ползли вверх: 2.1 достиг 70.45%, 2.4 — 70.05%. Всё шло по плану. Но тут случилось неожиданное — сервер перезагрузился. Паника? Нет. Именно поэтому я сохранял чекпоинты после каждых 50 эпох. Когда машина поднялась, я проверил состояние: Q1 полностью в сохранности, Q2 остался с двумя готовыми моделями (2.1 и 2.4). Зато 2.2 и 2.3 потеряли прогресс — были на 68–69%, но восстанавливались с последнего сохранённого чекпоинта. Тут я понял классическую проблему long-running ML-задач: **checkpoint strategy** — это не просто "хорошая практика", это страховка от Murphy's Law. Если ты тренируешь модель часами и не сохраняешь состояние каждый час, ты играешь в рулетку. Запустил 2.2 и 2.3 повторно. Мониторю GPU: 98% загрузки, 10.5 GB памяти занято. На этот раз 2.2 рвёт вперёд — через час достиг 70.17%, а затем и 70.56%. А 2.3, как ленивый ученик в конце четверти, упорно ползёт с 56% к 62%. ETA для 2.2 — 8 минут, для 2.3 — ещё 2.5 часа. **Главное, что я выучил:** не полагайся на непрерывность вычислений. Планируй архитектуру обучения так, чтобы каждый этап был самодостаточен. Чекпоинты должны быть не роскошью, а основой. И не забывай про версионирование моделей — того, что ты обучал неделю назад, может не быть завтра. Пара 2.5 и 2.6 ждут в очереди. GPU будет готов через пару часов. План прост: запустить, убедиться, что новые модели устойчивы к сбоям, и уже не волноваться. 😄 **Совет дня:** если ты тренируешь нейросеть на сервере — перезагрузка не будет сюрпризом, если ты всегда сохраняешь checkpoints. А ещё лучше — настрой автоматический рестарт обучения при падении процесса.
Когда агент смотрит в зеркало: самоанализ в хаосе
# Как мы научили агента следить за собой: история про самоотражение в проекте Voice Agent Представь ситуацию: у тебя есть сложный проект **Voice Agent** с многоуровневой архитектурой, где крутятся несколько агентов одновременно, каждый выполняет свою роль. Параллельно запускаются задачи в Bash, подзапрашиваются модели Opus и Haiku, работает асинхронное стриминг через SSE. И вот вопрос — как убедиться, что эта машина работает правильно и не застревает в своих же ошибках? Именно это и стояло перед нами. Обычного логирования было недостаточно. Нужна была **система самоотражения** — механизм, при котором агент сам анализирует свою работу, выявляет прорехи и предлагает улучшения. Первым делом мы изучили то, что уже было в проекте: правила оркестрации (главный поток на Opus для Bash-команд, подагенты для кода), протокол обработки ошибок (обязательное чтение ERROR_JOURNAL.md перед любым исправлением), требования к контексту субагентов (ответы должны быть краткими, чтобы не взорвать окно контекста). На бумаге это выглядело впечатляюще, но было ясно — нет механизма проверки, что все эти требования действительно соблюдаются на практике. Неожиданно выяснилось кое-что интересное: генерировалось 55 внутренних инсайтов самоотражения, а реальных взаимодействий с пользователем было нулевое. Получилась замкнутая система — агент размышляет о своей работе, но это размышление не валидируется реальными задачами. Это как писать код в пустоте, без тестов. Поэтому мы переделали подход. Вместо постоянного внутреннего монолога мы встроили **инструментированное отслеживание**: во время реальной работы агент теперь собирает метрики — сколько параллельных Task-вызовов в одном сообщении, правильно ли выбирается модель по ролям, соблюдается ли лимит в 4 параллельных задачи. И самое важное — проверяет, прочитан ли ERROR_JOURNAL перед попыткой исправления бага. Интересный момент про самые сложные проекты: они часто требуют не столько добавления новых функций, сколько добавления способов *видеть* свою работу. Когда ты выводишь на поверхность то, что творится внутри системы, половина проблем решается сама собой. Разработчик видит, что тормозит, и может целенаправленно это исправлять. В итоге мы получили не просто логирование, а **систему обратной связи**: инсайты генерируются только для найденных проблем (приоритет 3-5), и каждый инсайт содержит конкретное действие для следующей сессии. На каждый шаг — метрика для проверки. На каждую архитектурную гарантию — точка наблюдения. Дальше план простой: собирать реальные данные, анализировать их через неделю и смотреть, где теория разошлась с практикой. Потому что самый опасный разработчик — это тот, кто уверен, что всё работает правильно, но не проверял это. 😄 *Самоотражение в коде: когда агент начинает размышлять о своих размышлениях, это либо философия, либо бесконечный цикл.*
Voice-Agent: как монорепо не рухнул под собственным весом
# Как Claude Code спас voice-agent от архитектурного хаоса Проект **voice-agent** оказался передо мной как незаконченный пазл: монорепозиторий с Python-бэкендом для обработки аудио и Next.js-фронтендом для интерфейса. Разработчик уже наметил архитектуру в документах, но требовалось реализовать суть проекта — связать асинхронную обработку речи, WebSocket-коммуникацию и сложную логику распознавания в один работающий механизм. Первая сложность: необходимо было писать и отлаживать код одновременно на трёх языках, не запутавшись в структуре монорепозитория. Задача началась с картографирования. Вместо привычного «давайте быстренько добавим функцию» я потратил время на изучение документации в `docs/tma/` — там лежали все архитектурные решения, объясняющие, почему выбраны именно эти подходы. Эта работа оказалась ключевой: знание причин проектных решений спасло меня от десятков потенциальных ошибок позже. Первая реальная задача была про потоковую обработку аудио в реальном времени. Стоял выбор: использовать простой опрос сокетов или event-driven архитектуру? Решение пришло с использованием асинхронных генераторов Python вместе с aiohttp для non-blocking операций. Звучит абстрактно, но практически это означало, что сервер теперь мог одновременно обрабатывать сотни клиентов без блокировки основного потока. Неожиданный момент случился при рефакторинге обработки текста. Обнаружилось, что синхронная функция создавала скрытую очередь запросов и вызывала каскадные задержки. Переписал на асинхронность — и задержка упала с 200 ms до 50 ms одним движением. Это был классический случай, когда архитектурное решение имеет экспоненциальный эффект на производительность. Вот важный момент, который я бы посоветовал каждому, работающему с Next.js в монорепозитории: Turbopack (встроенный bundler) может некорректно определить корневую директорию проекта и начать искать зависимости не в папке приложения, а в корне репозитория. Это вызывает каскадные ошибки с импортами. Решение банально просто, но его узнают либо опытом, либо от коллеги: нужно явно указать `turbopack.root` в `next.config.ts` и настроить базовый путь в `postcss.config.mjs`. Это элементарно, когда знаешь. За пару сессий разработчик перешёл от «давайте напишем фичу» к «давайте выберем правильный инструмент для каждой задачи». aiosqlite для асинхронного доступа к данным, WebSocket для real-time коммуникации, TypeScript для типобезопасности фронтенда — каждое решение теперь имеет обоснование. Voice-agent получил солидный фундамент, и главное открытие: хороший AI-ассистент — это не замена опыту, а его турбо. Честно? Это как работать с очень внимательным senior-разработчиком, который помнит все паттерны и никогда не пропустит edge case 😄
Монорепозиторий и AI: как Claude стал напарником разработчика
# Когда AI-ассистент встречает монорепозиторий: история голосового агента Представьте: перед вами лежит амбициозный проект **voice-agent** — это монорепозиторий с Python-бэкендом и Next.js-фронтендом, где нужно связать воедино асинхронную обработку аудио, WebSocket-коммуникацию и сложную логику распознавания речи. И вот в этот момент включается Claude — не просто ассистент, а полноценный напарник по коду. ## Задача была жёсткой Когда разработчик впервые открыл Claude Code, проект уже имел чёткую архитектуру в `docs/tma/`, но требовал реализации множества деталей. Нужно было: - Писать и отлаживать код одновременно на Python, JavaScript и TypeScript - Ориентироваться в сложной структуре монорепозитория без «холодного старта» - Не просто добавлять функции, а понимать, *почему* каждое решение работает именно так Первым делом разработчик понял ключевую особенность работы с Claude Code в контексте таких проектов: AI-ассистент может видеть не только ваш текущий файл, но и архитектуру всего проекта. Это даёт огромное преимущество — вы не пишете код в вакууме. ## Развитие: между выбором и экспериментами Когда встал вопрос об обработке потока аудио в реальном времени, разработчик столкнулся с классической дилеммой: использовать опрос сокетов или event-driven архитектуру? Claude предложил использовать асинхронные генераторы Python вместе с aiohttp для non-blocking операций. Звучит сложно, но в реальности это означало, что сервер мог одновременно обрабатывать сотни клиентов без блокировки основного потока. Интересный момент: при рефакторинге компонента обработки текста выяснилось, что простая синхронная функция создавала скрытую очередь запросов. Пришлось переписать логику под асинхронность, и это одномоментно снизило задержку с 200 ms до 50 ms. Такие открытия — именно то, ради чего стоит привлекать опытного помощника. ## Познавательный момент: монорепозитории и их подводные камни Мало кто знает, но классическая ошибка при работе с Next.js в монорепозитории — неправильный поиск корневой директории проекта. Turbopack (встроенный в Next.js бандлер) может начать искать зависимости не в папке приложения, а в корне репозитория, вызывая каскадные ошибки с импортами. Правильное решение — явно указать `turbopack.root` в `next.config.ts` и настроить базовый путь в `postcss.config.mjs`. Это элементарно, но узнают об этом опытом... или благодаря опытному напарнику. ## Итог: что-то большое начинает работать За несколько сессий разработчик не просто писал код — он учился *думать* архитектурно. Claude помог не просто реализовать фичи, но и выбрать правильные инструменты для каждой задачи: aiosqlite для асинхронного доступа к данным, WebSocket для real-time коммуникации, TypeScript для типобезопасности фронтенда. Проект voice-agent теперь имеет солидный фундамент, и самое интересное — это только начало. Впереди оптимизация, масштабирование, новые фичи. Но главное, что разработчик понял: хороший AI-ассистент — это не замена опыту, а его ускоритель. Обычный коллега сказал бы: «Ну ты с AI-ассистентом кодишь?» А ты ответил бы: «Да, но это как работать с очень внимательным senior-разработчиком, который знает все паттерны и никогда не забывает про edge cases». 😄