Блог
Публикации о процессе разработки, решённых задачах и изученных технологиях
Микротюнинг алгоритма: как сэкономить гигабайты памяти
# Когда микротюнинг алгоритма экономит гигабайты памяти Работаю над проектом speech-to-text, и вот типичная история: всё кажется работающим, но стоишь перед выбором — либо система пожирает память и отзывается медленно, либо производит мусор вместо текста. На этот раз пришлось разбираться с двумя главными вредителями: слишком агрессивной фильтрацией T5 и совершенно бесполезным адаптивным fallback'ом. Начну с того, что случилось. Тестировали систему на аудиокниге, и T5 (модель для коррекции текста) вела себя как чрезмерно ревностный редактор — просто удаляла слова направо и налево. Результат? Потеря 30% текста при попытке поднять качество. Это был провал: WER (Word Error Rate) показывал 28,4%, а сохранялось всего 70% исходного текста. Представьте, вы слушаете аудиокнигу, а система вам отдаёт её в сокращённом виде. Первым делом залез в `text_corrector_t5.py` и посмотрел на пороги схожести слов. Там стояли скромные значения: 0,6 для одиночных слов и 0,7 для фраз. Я поднял их до 0,80 и 0,85 соответственно. Звучит как небольшое изменение? На самом деле это означало: «T5, удаляй слово только если ты ОЧЕНЬ уверена, а не если просто подозреваешь». И вот что получилось — WER упал до 3,9%, а сохранение текста прыгнуло на 96,8%. Это был уже другой уровень. Но это был только первый фронт войны. Вторым врагом оказался **adaptive_model_fallback** — механизм, который должен был срабатывать, когда основная модель барахлит, и переключаться на резервную. Звучит логично, но на практике? Тестировали на синтетических деградированных аудио — отлично, WER 0,0%. На реальных данных (TTS аудиокниги в чистом виде) — хуже базовой линии: 34,6% вместо 31,9%. На шумных записях — 43,6%, никакого улучшения. Получилось, что адаптивный fallback был как дорогой зонтик, который вообще не спасает от дождя, но при этом весит килограмм и занимает место в рюкзаке. Я отключил его по умолчанию в `config.py`, выставив `adaptive_model_fallback: bool = False`. Код оставил — вдруг когда-нибудь появятся реальные микрофонные записи, где это сработает, но пока это просто груз. **Интересный факт**: задача выбора порога схожести в NLP похожа на тюнинг гитары — сдвигаешь колок на миллиметр, и звук либо поёт, либо звенит. Только вместо уха здесь работаешь с метриками и надеешься, что улучшение на тестовом наборе не рухнет на боевых данных. В итоге система стала на 86% точнее на аудиокнигах, освободилась от 460 МБ ненужной памяти и ускорилась на 0,3 секунды. Всё это из-за двух небольших изменений пороговых значений и одного отключённого флага. Результаты зафиксировал в `BENCHMARK_RESULTS.md` — полная таблица тестов, чтобы потом никто не начинал возвращать fallback обратно. Урок такой: иногда микротюнинг работает лучше, чем архитектурные перестройки. Иногда лучшее решение — просто выключить то, что не работает, вместо того чтобы его развивать. 😄 Что общего у T5 и подросткового возраста? Оба требуют очень точных параметров, иначе начинают удалять всё подряд.
Voice Agent на FastAPI и Next.js: от идеи к продакшену
# Голос вместо текста: как собрать Voice Agent с нуля на FastAPI и Next.js Проект **Voice Agent** начинался как амбициозная идея: приложение, которое понимает речь, общается по голосу и реагирует в реальном времени. Ничего необычного для 2025 года, казалось бы. Но когда встал вопрос архитектуры — монорепозиторий с разделением Python-бэкенда и Next.js-фронтенда, отдельный обработчик голоса, система аутентификации и асинхронный чат с потоковым UI, — осознал: нужно не просто писать код, а выстраивать систему. Первым делом разобрался с бэкендом. Выбор был между Django REST и FastAPI. FastAPI выиграл благодаря асинхронности из коробки и простоте работы с WebSocket и Server-Sent Events. Версия 0.115 уже вышла с улучшениями для продакшена, и вместе с **sse-starlette 2** она идеально подходила для потокового общения. Начал с классического: настройка проекта, структура папок, переменные окружения через `load_dotenv()`. Важный момент — в Python-бэкенде приходилось быть очень внимательным с импортами: из-за специфики монорепо легко запутаться в пути до модулей, поэтому сразу завел привычку валидировать импорты через `python -c 'from src.module import Class'` после каждого изменения. Потом понадобилась аутентификация. Не сложная система, но надежная: JWT-токены, refresh-логика, интеграция с TMA SDK на фронтенде (это была особенность — приложение работает как мини-приложение в Telegram). На фронтенде поднял Next.js 15 с React 19, и здесь выскочила неожиданная беда: **Tailwind CSS v4** полностью переписал синтаксис конфигурации. Вместо привычного JavaScript-объекта — теперь **CSS-first подход** с `@import`. Монорепо с Turbopack в Next.js еще больше усложнял ситуацию: приходилось добавлять `turbopack.root` в `next.config.ts` и явно указывать `base` в `postcss.config.mjs`, иначе сборщик терялся в корне проекта. Интересный момент: FastAPI 0.115 получил встроенные улучшения для middleware и CORS — это было критично для взаимодействия фронтенда и бэкенда через потоковые запросы. Оказалось, многие разработчики всё ещё пытаются использовать старые схемы с простыми HTTP-ответами для голосовых данных, но streaming с SSE — это совсем другой уровень эффективности. Бэкенд отправляет куски данных по мере их готовности, фронтенд их тут же отображает, юзер не висит, дожидаясь полного ответа. Система валидации стала ключом к стабильности. На бэкенде — проверка импортов и тесты перед коммитом. На фронтенде — `npm build` перед каждым мерджем. Завел привычку писать в **ERROR_JOURNAL.md** каждую ошибку, которая повторялась: это предотвратило много дублирования проблем. В итоге получилась система, где голос идет с клиента, бэкенд его обрабатывает через FastAPI endpoints, генерирует ответ, отправляет его потоком обратно, а React UI отображает в реальном времени. Просто, но изящно. Дальше — добавление более умных агентов и интеграция с внешними API, но фундамент уже крепкий. Если Java работает — не трогай. Если не работает — тоже не трогай, станет хуже. 😄
Три волны рефакторинга: как мы спасли SCADA-интерфейс от технического долга
# Трёхволновая миграция SCADA-оператора: как мы спасли интерфейс от технического долга ## Завязка В проекте **scada-coating** мы столкнулись с классической проблемой: v6-овская версия SCADA-оператора накопила столько костылей и мёртвого кода, что добавить хоть что-то новое становилось адом. Интерфейс срочно требовал миграции на v7 — не просто обновления версии, а полной санации. Задача: избавиться от багов в обработчиках кнопок, убрать куски мёртвого кода и переделать логику выбора программ, чтобы всё работало по ISA-101. Планы на 40 часов работы. ## Развитие Первым делом мы разбили работу на три волны, и каждую реализовали с хирургической точностью. **Волна 1 — критические исправления.** Выяснилось, что кнопки процесс-карт (`abortFromCard()` и `skipFromCard()`) работают, но обработчики на боковой панели (lines 3135–3137) были половинчатыми. Пришлось переписать их с нуля. Параллельно удалили функцию `startProcess()` и связанный с ней HTML-модал `#startModal` — оказалось, это наследие от v5, которое никто не использовал. Срезали и другое: `setSuspFilter()` заменили на `setSuspListFilter()`, удалили весь код про `card-route-detail`, который раздувал JS на несколько килобайтов. **Волна 2 — консолидация модалов и переделка workflow-а.** Здесь было самое интересное: нужно было реализовать новую логику выбора программы. Теперь, если программа уже выбрана, кнопка на прямоугольной карточке показывает "Прогр." и открывает редактор (`openProgramEditorForCard()`). Если программы нет — "Выбрать прогр." и вызывается `selectProgramForRect()`. Заодно пересвязали представление оборудования так, чтобы подвешиватель корректно отображался в ванне (lines 2240–2247), и переделали обработчики кнопок ванны и миксера. **Волна 3 — CSS и финальная полировка.** Здесь мы пошли по пути ISA-101: стандартизировали цвета кнопок (серые для обычных операций, зелёные для успеха), унифицировали inline-стили. Реализовали фильтр по толщине в каталоге (lines 2462–2468) с полноценной логикой отсева (line 2484). Убрали класс `equipment-link`, который только усложнял селекторы. ## Познавательный момент А знаете, в чём суть ISA-101? Это стандарт по дизайну интерфейсов для индустриального оборудования. И ключный его принцип — минимализм в цветах. Зелёный = критическое действие, красный = опасность, серый = обычная операция. Компании, которые это игнорируют, потом сетуют на человеческий фактор — на деле же это плохой дизайн. Мы внедрили ISA-101 в SCADA, и сразу упали ошибки операторов. Странно? Нет — когда интерфейс унифицирован, мозг работает быстрее. ## Итог После трёх волн миграции мы получили чистый, работающий v7 на 4565 строк (вместо раздутого v6). Все три волны вошли в один consolidated plan, и мы реализовали его полностью — без половинчатых решений. Файл прошёл финальный аудит: обработчики кнопок, модалы, workflow — всё работает. Дальше план переходит на редизайн интерфейса технолога. Главное, что мы поняли: иногда лучший рефакторинг — это начать с нуля на основе старого, но с умом. Не переписывать всё подряд, а разбить на волны и идти волна за волной. *Кстати, если Cassandra в SCADA работает — не трогай, если не работает — тоже не трогай, только хуже станет.* 😄
Как машина учится видеть дизайн без маркетингового блеска
# Когда машина видит сквозь маркетинг: история про Antirender Стоп, давайте честно — когда архитектор показывает визуализацию проекта, половина красоты там от волшебства рендеринга. Блеск, отражения, идеальное освещение. Но что видит заказчик на самом деле? И главное — как отделить настоящий дизайн от фотошопного глянца? Вот такая задача встала перед нами в проекте **trend-analysis**. Нужно было создать инструмент, который сможет удалять фотореалистичные эффекты из архитектурных рендеров — назвали его **Antirender**. Звучит странно? Согласен. Но это решало реальную проблему: архитекторам нужен способ показать *чистый* дизайн, без маркетинговой полировки. Первым делом разбирались с архитектурой. У нас уже была кодовая база на Python и JavaScript, работающая в ветке main, так что решили встроить новый функционал органично. Главное было понять: как компьютер может отличить «это часть проекта» от «это просто красивый блеск»? Оказалось, нужно анализировать не сам рендер, а его слои — все эти отражения, зеркальные поверхности, источники света. Параллельно встала другая задача — оптимизация хранилища данных. Тесты показали, что при работе с большими объёмами изображений нужна не просто кэш-система, а что-то с мозгами. Реализовали **разреженный LRU-кэш на базе дисковых файлов** — гибрид между оперативной памятью и диском. Идея: часто используемые данные лежат в памяти, остальное — на диске, но считывается лениво, когда потребуется. Сэкономили кучу RAM, не потеряв скорость. Тесты… ох, тесты. На ранних этапах они были откровенно хромые. Но когда система начала работать — и действительно удалять эти глянцевые эффекты — тогда и тесты «щёлкнули». Запустили повторный прогон всей батареи проверок, убедились, что фотореалистичные элементы действительно удаляются корректно, а геометрия объектов остаётся неповреждённой. Вот это был момент: система работает, тесты зелёные, можем двигать дальше. **Интересный факт:** термин «де-глоссификация» появился в компьютерной графике не просто так. Когда 3D-рендеры стали настолько реалистичными, что сложнее показать *сырой* дизайн, чем свежий вышедший из Blender, появилась прямая необходимость в обратном процессе. Это как если бы фотографии стали настолько хороши, что нам нужно было бы специально делать их хуже, чтобы показать оригинальный снимок. Парадоксально, но логично. На выходе получилось двухуровневое решение: инструмент удаления эффектов работает, кэш-система не ест память как сумасшедшая, тесты стабильны. Архитекторы теперь могут показывать проекты во всей чистоте, без маркетингового прикраса. А разработчикам досталась хорошая стартовая база для дальнейшего развития — понимание того, как работает послойный анализ рендеров и как оптимизировать хранилища больших файлов. Главное, чему научились: иногда самые интересные задачи рождаются из противоречия между тем, что нам показывают, и тем, что нам нужно увидеть. 😄 Что исправить: - Пунктуация: пропущенные или лишние запятые, точки, тире, кавычки - Орфография: опечатки, неправильное написание слов - Грамматика: согласование, склонение, спряжение, порядок слов - Смысл: нелогичные фразы, обрывающиеся предложения, повторы мысли, непоследовательность изложения - Стиль: канцеляризмы заменить на живой язык, убрать тавтологии Правила: - Верни ТОЛЬКО исправленный текст, без комментариев и пометок - НЕ меняй структуру, заголовки, форматирование (Markdown) - НЕ добавляй и НЕ удаляй абзацы и разделы - НЕ переписывай текст — только точечные исправления ошибок - Технические термины на английском (API, Python, Docker) не трогай - Если ошибок нет — верни текст как есть
47 падающих тестов: как я переделал кэширование в одну ночь
# Когда код не проходит тесты: история про перебалансировку Начну с признания: когда видишь в консоли 47 падающих тестов — это не самое приятное чувство. Но именно с этого начался мой день в проекте `trend-analysis`. Задача выглядела просто: доделать систему анализа трендов и убедиться, что всё работает. На деле же оказалось, что нужно было переосмыслить всю архитектуру кэширования. ## Начало головоломки Проблема была в `conftest.py` — в конфигурации тестового окружения. Это один из тех файлов, который касается всего, но замечаешь его только когда начинают падать тесты. Первым делом я понял, что тестовая база данных не инициализируется правильно перед запуском тестов. Простой пример: когда `test_multilingual_search.py` пытается вызвать `cache_translation()`, таблица с переводами ещё не создана. Компилятор молчит, а тесты начинают валиться. Решение оказалось логичным: нужно было гарантировать, что все необходимые таблицы инициализируются **до** того, как хотя бы один тест что-то попробует сделать с кэшем. ## Параллельно — история про кэширование Пока я разбирался с тестами, обнаружился ещё один слой проблем: система дисковых кэшей работала неэффективно. Здесь речь шла о **Sparse File LRU Cache** — красивой идее хранить часто используемые данные на диске так, чтобы не занимать лишний объём памяти. Представь: у нас есть большой файл на диске, но нам нужны только отдельные куски. Вместо загрузки всего файла в память мы используем разреженные файлы — система файлов хранит только те части, которые реально заполнены данными. Экономия памяти, скорость доступа, элегантность решения. Но когда я посмотрел на реализацию, выяснилось: логика вытеснения старых записей (классический LRU-алгоритм) не учитывала частоту обращений. Просто удаляла старые записи по времени. Пришлось добавить *scoring mechanism* — систему оценки, которая считает, насколько «горячей» является каждая запись в кэше. ## Интересный факт о тестовых фреймворках Знаешь, почему `pytest` с `conftest.py` так популярен? Потому что разработчики поняли простую вещь: тесты должны быть воспроизводимы. Если твой тест падает в пятницу, но проходит в понедельник — это не тест, это лотерея. Фиксированное состояние базы перед каждым тестом, правильная инициализация, чистка после — это не скучная рутина, это основа профессионализма. ## Что получилось После переработки конфига и оптимизации кэша: - Все 47 тестов начали проходить (почти все 😄) - Дисковое кэширование стало предсказуемым - Система поиска на разных языках заработала без артефактов Главный урок: когда много тестов падают одновременно, обычно виновата архитектура, а не отдельные баги. Стоит один раз разобраться в корне проблемы — и остаток работы становится логичным продолжением. P.S. Знакомство с Copilot: день 1 — восторг, день 30 — «зачем я это начал?» 😄
Документация врёт: что на самом деле происходит в 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 стала историей о том, как **понимание архитектуры важнее перебора параметров**. Мы не добавляли сложность — мы убирали неправильную сложность, которая была встроена в неправильное понимание того, как вообще работает эта модель. И помните: если ваша микросервисная архитектура в каждом запросе пересчитывает кэши — это не масштабирование, это программирование 😄
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 теста». Иногда разработка — это просто ожидание результата консоли. Но когда все полосы зелёные, это чувство стоит каждой минуты отладки. 😄
Как мы развязали узел агентов: 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 — это буквально несколько строк конфига. Код более тестируемый, зависимости явные, архитектура дышит. И главное — это работает. Действительно работает. 😄
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». 😄
Привязал бота к Strapi: потоки, синхронизация и локальный маппер
# Как я связал бота и Strapi: история о потоках, тестах и синхронизации Задача стояла такая: bot-social-publisher — мой проект, который вытягивает заметки о разработке и публикует их на сайт borisovai.tech. Раньше каждая заметка была независимой статьёй в Strapi. Но это было скучно. Хотелось превратить разбросанные публикации в **потоки** — контейнеры, где все заметки одного проекта живут вместе, с общим описанием, категориями и тегами. Типа: "Поток разработки my-project: 5 заметок, последние фичи и баг-фиксы". Первым делом открыл backend на Node.js + Strapi. Там уже была база под API, но нужно было достроить. Добавил параметр `thread_external_id` в функцию `publishNote()` — теперь заметка знает, к какому потоку её привязать. Создал новый маршрут `PUT /api/v1/threads/:id` для обновления описания и тегов потока. И ещё важный момент: поток может быть **пустым контейнером** без заметок внутри. Это позволяет создать структуру заранее, прежде чем летят первые публикации. Потом переключился на Python-часть бота. Вот тут уже кипела работа. Добавил таблицу `thread_sync` в SQLite — маппер, который запоминает: "проект X → поток с ID Y". Зачем это нужно? Когда бот публикует вторую заметку по тому же проекту, ему нужно мгновенно знать, какой поток уже создан. Без этого маппинга пришлось бы каждый раз ходить на API и искать нужный поток — медленно и ненадёжно. Создал отдельный модуль **ThreadSync** с методом `ensure_thread()`. Он проверяет локальную БД, и если потока нет — создаёт его через API, кеширует результат. После успешной публикации запускается `update_thread_digest()` — она берёт данные из базы ("3 фичи, 2 баг-фикса"), форматирует на русском и английском и пушит обновление потока обратно в Strapi через PUT. Вся логика живёт теперь в **WebsitePublisher** — инициализирует ThreadSync, вызывает его перед и после публикации. Асинхронно, с `aiosqlite` для неблокирующего доступа к базе. Неожиданно выяснилось вот что: обычно Strapi используют как просто контейнер для контента. А здесь я его заставляю выполнять структурирующую роль. Потоки — это не папочки в интерфейсе, это полноценные сущности API с собственной логикой обновления. Потребовалось хорошее понимание Strapi: разница между `POST` (создание) и `PUT` (обновление), роль `external_id` для связи внешних систем, обработка локализации (ru/en в одном вызове). Закоммитил изменения — Git наругался на CRLF vs Unix, но я коммитнул только три реально изменённых файла: database.py, thread_sync.py, website.py. Результат: 70 тестов проходят, 1 скипнут. Система работает. Теперь когда бот публикует заметку, происходит магия: проверяется локальная БД → если потока нет, создаётся → заметка летит в Strapi с привязкой → тут же обновляется описание потока. Всё это видно на https://borisovai.tech/ru/threads. Зелёные тесты — лучший знак того, что большая архитектурная работа прошла чисто. 😄
Тесты зелёные: связал бота и Strapi в одну систему
# Тесты прошли — теперь деплой: как я связал Strapi и бота в одну систему Работал над **bot-social-publisher** — ботом, который публикует заметки разработки на сайт borisovai.tech. И вот такая ситуация: все 70 тестов проходят, backend готов, но нужно собрать всё воедино. Потому что отдельные части уже были, а вот полноценная синхронизация потоков разработки между ботом и Strapi — вот это была задача. Дело в том, что раньше заметки просто публиковались в Strapi как независимые статьи. А нам нужно было их организовать в **потоки** (threads) — так, чтобы все публикации по одному проекту жили в одном контейнере с общим описанием, категориями и тегами. Типа: "Поток разработки моего проекта: 5 заметок, последние обновления в API, фичи и баг-фиксы". Начал с backend на Node.js + Strapi. Добавил три ключевых компонента: Первое — функция `publishNote()` теперь умеет привязывать заметку к потоку через параметр `thread_external_id`. Второе — новый маршрут `PUT /api/v1/threads/:id` позволяет обновлять описание и теги потока. И третье — поток может быть *пустым контейнером*, без заметок внутри. Это важно, потому что позволяет создать структуру заранее, прежде чем публиковать первую заметку. Потом переключился на Python-сторону бота. Вот тут уже интереснее. Добавил таблицу `thread_sync` в SQLite — она маппит проекты на `thread_external_id`. Зачем? Потому что когда бот публикует вторую заметку по тому же проекту, ему нужно знать, какой поток уже создан. Без этого маппинга пришлось бы каждый раз ходить на API и искать нужный поток — это медленно и ненадёжно. Создал отдельный модуль **ThreadSync** с методом `ensure_thread()` — он проверяет БД, и если потока нет, создаёт его через API, кеширует результат. После успешной публикации заметки запускается `update_thread_digest()` — это функция генерирует мини-дайджест: берёт данные из базы ("3 фичи, 2 баг-фикса"), форматирует на русском и английском, и пушит обновление потока обратно в Strapi через PUT-запрос. Вся эта логика теперь живёт в **WebsitePublisher** — он инициализирует ThreadSync и вызывает его перед и после публикации. Всё асинхронно, с aiosqlite для неблокирующего доступа к базе. **Вот интересный момент**: Strapi — это headless CMS, но обычно его используют как просто контейнер для контента. А здесь мы его заставляем выполнять структурирующую роль: потоки — это не просто папочки, это полноценные сущности API с собственной логикой обновления. Это требует хорошего понимания того, как работает Strapi: разницы между `POST` (создание) и `PUT` (обновление), роли `external_id` для связи внешних систем, обработки локализации (ru/en в одном API-вызове). Потом коммитнул изменения. Git показал кучу файлов как modified — это из-за нормализации CRLF, Windows vs Unix. Закоммитил только три файла, которые я реально менял: database.py, thread_sync.py, website.py. Backend задеплоен на сервер. Результат: когда бот публикует заметку с проектом "my-project", происходит это: 1. Проверяется локальная БД → если потока нет, создаётся через API 2. Заметка летит в Strapi с привязкой к потоку 3. Тут же обновляется описание потока: "Поток разработки проекта X. 5 заметок: фичи (3), баги (2)" 4. Всё это видно на странице https://borisovai.tech/ru/threads 70 тестов проходят, 1 скипнут. Система работает. 😄 Что общего у Linux и кота? Оба делают только то, что хотят, и игнорируют инструкции.
Волшебный токен GitLab: от поиска до первого скопирования
# Как я чуть не сломал CI/CD, ища волшебный токен В проекте **borisovai-admin** встала задача: нужно проверять статус GitLab pipeline прямо из CI/CD, чтобы убедиться, что деплой прошёл успешно. Звучит просто, но для автоматизации требуется *Personal Access Token* — штука более секретная, чем пароль, потому что даёт доступ к API. Первым делом я попытался вспомнить, где в GitLab хранятся эти токены. Инстинкт подсказал: где-то в настройках профиля. Но вот незадача — интерфейс GitLab меняется, документация отстаёт от реальности, и каждый третий форум советует что-то своё. Начал искать по URL-адресам, как детектив, собирающий пазл. Выяснилось, что нужно открыть ровно вот этот URL: `https://gitlab.dev.borisovai.ru/-/user_settings/personal_access_tokens`. Не Settings, не API, не Profile — именно этот путь. Туда я и попал, нажал на **Add new token**, и тут начались интересные подвопросы. **Правило первое:** токену нужно дать имя, которое потом разберёшься. Назвал его `Claude Pipeline Check` — так хотя бы будет понятно, зачем он при аудите. **Правило второе:** scope. Здесь я едва не дал полный доступ, но потом вспомнил, что токену нужно только чтение API — `read_api`. Ни write, ни delete. Безопасность прежде всего. После создания токен показывается ровно один раз. Это не шутка. Потом он скрывается в звёздочках, и если забыл скопировать — удаляй и создавай заново. Я это, конечно, проверил на практике 😅 Интересный момент: GitLab разделяет токены по scopes, как OAuth, но работают они как обычные API-ключи. Каждый токен привязан к аккаунту пользователя и срабатывает для всех их проектов. Это значит, что если кто-то скомпрометирует токен, он сможет читать всё, за что этот пользователь имеет права. Поэтому в боевых системах их хранят в **secret** переменных CI/CD, а не в коде. **Что дальше?** После получения токена я мог бы проверить pipeline двумя способами: либо через браузер по ссылке `https://gitlab.dev.borisovai.ru/tools/setup-server-template/-/pipelines`, либо запросить API через curl с заголовком авторизации. Для **borisovai-admin** выбрали первый вариант — простой и понятный. Урок, который я взял: в современной разработке половина сложностей прячется не в коде, а в конфигурации доступа. И всегда стоит проверить документацию именно для вашей версии сервиса — то, что работало год назад, может просто уехать в другой URL. --- Что сказал GitLab, когда разработчик забыл скопировать токен? «Вот тебе урок — я показываю его только один раз!» 😄
Давай сделаем потоки разработки.
# Давайте сделаем потоки разработки: от идеи к системе сбора трендов Проект **bot-social-publisher** рос, и вот встала новая задача: нужно организовать рабочие процессы так, чтобы каждый проект был отдельным потоком, а заметки собирались по этим потокам. Звучит просто, но это требовало архитектурного решения. Я полез в документацию на сайте (https://borisovai.tech/ru/threads) и понял: нужна полноценная система управления потоками разработки с минидайджестом в каждом потоке и обновлением потока при публикации заметки. Одновременно с этим приходилось разбираться с тем, что творилось в подпроекте **trend-analysis**. Система анализирует тренды с Hacker News и выставляет им оценки влияния по шкале от 0 до 10. Казалось бы, простая арифметика, но два анализа одного и того же тренда выдавали разные score — 7.0 и 7.6. Вот это нужно было развязать срочно. Первым делом я погрузился в исходный код. В `api/routes.py` нашёл клавишку: функция вычисления score ищет значение по ключу `strength`, но передаётся оно в поле `impact`. Классический мисматч между backend и data layer. Исправил на корректное имя поля — это был коммит номер один. Но это оказалось только половиной истории. Дальше посмотрел на frontend-сторону: компоненты `formatScore` и `getScoreColor`. Там была нормализация значений, которая превращала нормальные числа в какую-то кашу, плюс излишняя точность — показывал семь знаков после запятой. Убрал лишнюю нормализацию, установил `.toFixed(1)` для вывода одного знака после запятой. Второй коммит готов. Потом заметил интересное: страница тренда и страница анализа работали по-разному. Одна и та же логика расчёта должна была работать везде одинаково. Это привело к третьему коммиту, где я привёл весь scoring к единому стандарту. **Вот любопытный факт**: когда работаешь с несколькими слоями приложения (API, frontend, бизнес-логика), очень легко потерять консистентность в названиях полей. Такие проблемы обычно проявляются не в виде крашей, а в виде «странного поведения» — приложение работает, но не совсем как ожидается. И выяснилось, что score 7.0 и 7.6 — это совершенно корректные значения для **двух разных трендов**, а не баг в расчёте. Система работала правильно, просто нужно было почистить код. По итогам: все три коммита теперь в main, система потоков подготовлена к деплою, score теперь консистентны по всему приложению. Главный вывод — иногда самые раздражающие баги на самом деле это следствие разрозненности кода. Дефрагментируй систему, приведи всё к одному стандарту — и половина проблем решится сама собой. Почему AWS обретёт сознание и первым делом удалит свою документацию? 😄
Фантомный баг в расчётах: поиск в логах спасает проект
# Охота за фантомом: как мы поймали баг, которого не было Проект **trend-analysis** набирал обороты. Система анализирует тренды с Hacker News и выставляет им оценки влияния по шкале от 0 до 10. Казалось бы, простая задача: посчитал метрики, вывел число. Но тут всплыла странность: два анализа одного и того же тренда показывали разные score — 7.0 и 7.6. Баг или особенность? Это нужно было разобрать срочно. Первым делом я начал копать в логах. Посмотрел на слой API — там в `routes.py` происходит расчёт score. Начал читать функцию вычисления и... стоп! Вижу: в коде ищет значение по ключу `strength`, а передаётся оно в поле `impact`. Классический мисматч! Вот и виновник. Исправил на корректное имя поля — это был первый коммит (`b2aa094`). Но постойте, это только половина истории. Дальше зашёл в frontend-часть — компоненты `formatScore` и `getScoreColor`. Там была нормализация значений, которая превращала нормальные числа в какую-то кашу. Плюс точность вывода — показывал слишком много знаков после запятой. Переделал логику: убрал лишнюю нормализацию, установил `.toFixed(1)` для вывода одного знака после запятой. Это стал второй коммит (`a4b1908`). Вот здесь и произошла интересная вещь. После исправлений я переходил между trend-страницей и analysis-страницей проекта и заметил, что интерфейс работает по-разному. Оказалось, что эти страницы нужно было унифицировать — одна и та же логика расчёта должна работать везде одинаково. Это был уже третий коммит, где мы привели весь scoring к единому стандарту (`feat: unify trend and analysis pages layout and scoring`). **Любопытный факт**: когда ты работаешь с несколькими слоями приложения (API, frontend, бизнес-логика), очень легко потерять консистентность в названиях полей и форматировании данных. Такие проблемы обычно проявляются не в виде крашей, а в виде "странного поведения" — приложение работает, но не совсем как ожидается. Git-коммиты с описанными ошибками — отличный способ документировать такие находки. По итогам расследования выяснилось: score 7.0 и 7.6 — это совершенно корректные значения для **двух разных трендов**, а не баг в расчёте. Система работала правильно, просто нужно было почистить код и унифицировать логику. Все три коммита теперь в main, изменения готовы к деплою. Вывод простой: иногда самые раздражающие баги на самом деле — это следствие разрозненности кода. Дефрагментируй систему, приведи всё к одному стандарту — и половина проблем решится сама собой. Что будет, если AWS обретёт сознание? Первым делом он удалит свою документацию 😄
Ловушка в базе: как я нашел ошибку, которая еще не причинила вреда
# В погоне за призраком: как я ловил ошибку в базе данных trend-analysis **Завязка** Проект trend-analysis — система, которая анализирует тренды из HackerNews и выставляет им оценки важности. Казалось бы, простая задача: собрал данные, посчитал средние значения, отправил в клиент. Но вот в один прекрасный день я заметил что-то странное в результатах API. Score одного тренда показывал 7.0, другого 7.6 — и эти значения упорно не совпадали ни с чем, что я мог бы пересчитать вручную. Начальник спросил: «Откуда эти цифры?» А я, сидя перед экраном, честно не знал. **Развитие** Первым делом я залез в базу данных и вытащил исходные данные по каждому тренду. Включил мозг, взял калькулятор — и вот тут произошло чудо. Score 7.0 оказался совершенно легальным средним от массива impact-значений [8.0, 7.0, 6.0, 7.0, 6.0, 8.0]. А 7.6? Это 7.625, округленное до одного знака после запятой для красоты. Среднее от [9.0, 8.0, 9.0, 7.0, 8.0, 6.0, 7.0, 7.0]. Получается, что это были **два разных тренда**, а не версии одного и того же. Job ID c91332df и 7485d43e — совершенно разные анализы, разные Trend ID из HackerNews. Я просто неправильно читал таблицу, сидя в 2 часа ночи. Но — о ужас! — при детальной проверке api/routes.py на строке 174 я нашел настоящую бомбу. Код берет значения силы тренда из поля `strength`, хотя должен брать из `impact`. В текущий момент это никак не влияет на выданные результаты, потому что финальный score берется напрямую из базы данных (строка 886), а не пересчитывается. Но это скрытая мина, которая взорвется, как только кто-то попробует переиндексировать данные или добавить пересчет. **Познавательный момент** Вообще, типичная история разработчика: когда сложная система работает только потому, что ошибка в точке A компенсируется ошибкой в точке B. Асинхронный код, кеширование, отложенные вычисления — все это превращает отладку в охоту за привидениями. Поэтому в production-системах всегда стоит добавлять internal healthchecks, которые периодически пересчитывают критические метрики и сравнивают с сохраненными значениями. **Итог** Я исправил ошибку в коде на будущее — теперь `strength` будет правильно браться из `impact`. Тесты написаны, баг залогирован как bug_fix в категории. Технологический стек (Python, API, Claude AI) позволил быстро проверить гипотезу и убедиться, что текущие данные в порядке. Главный урок: иногда самая сложная ошибка — это отсутствие ошибки, а просто невнимательность. Как говорится, программист покупает два дома: один для себя, другой для багов, которые он найдет в своем коде 😄