Принято считать, что искусственный интеллект особенно хорош в разработке с нуля: он отлично пишет новый код, когда ему не мешает легаси-багаж. А вот разработка в существующей кодовой базе (“brownfield-разработка”), когда ИИ приходится трогать уже работающие системы, — зона, где всё становится опаснее. Это мнение понятно. И не совсем ошибочно.

Пару месяцев назад я разговаривал с руководительницей инженерной команды, которая почти разочаровалась в AI-инструментах. Её команда экспериментировала с Claude: хотели с его помощью отрефакторить восьмилетний Django-монолит. Ничего драматичного — просто агент выдавал чистые, уверенные на вид патчи, которые незаметно ломали интеграции с парой внешних сервисов. После нескольких откатов, поисков неочевидных регрессий и распутывания слишком оптимистичных изменений команда свернула эксперимент и вернулась к ручному подходу.

Она мне сказала: «Я не против искусственного интеллекта как такового. Просто в настоящих системах очень много невидимого контекста».

И она права. Похожих историй полно на reddit в ветке r/vibecoding.

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

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

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

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

Ниже поговорим о трех принципах, которые я считаю полезными.

Тесты как границы системы

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

Раньше я по возможности избегал интеграционных тестов: их долго писать и неприятно поддерживать. Но искусственный интеллект меняет математику. В одной недавней миграции мне удалось быстро написать больше 120 Playwright-тестов для приложения на ванильном JavaScript. Claude изучил HTML и JavaScript, нашёл важные структурные маркеры и действия, а затем с помощью Playwright определил, какими должны быть побочные эффекты кликов по ссылкам и кнопкам. По сути, это стало функциональной спецификацией, относительно которой агент мог себя проверять.

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

Тесты — основной механизм безопасности для миграции. Они не поймают каждый инвариант или регрессию производительности, зато резко снижают риск тихих поломок, пока система находится в движении.

Документация как контекст

Тесты говорят агенту, что что-то сломалось. Документация объясняет, почему всё устроено именно так.

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

Мы начали поддерживать рядом с кодовой базой документацию, ориентированную на агентов: обзоры архитектуры, карты интеграций — весь тот контекст, который понадобился бы новому участнику команды, но который редко кто записывает. Стандартные файлы CLAUDE.md или AGENTS.md помогают, но для работы в существующей кодовой базе часто нужно больше: объяснить, почему поток аутентификации такой странный, какие внешние сервисы чувствительны ко времени, где спрятаны самые неприятные места.

Документация не обязана быть идеальной с самого начала. Мы используем команду /learn: когда агент на чём-то спотыкается, он анализирует сбой и предлагает обновления для документации. С каждым шагом система становится умнее. Это превращается в институциональную память, которая постепенно накапливается и усиливается.

Инкрементальный подход как управление рисками

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

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

Агенты лучше всего справляются с задачами, у которых есть понятные границы и чёткие критерии успеха. «Перенести модальное окно загрузки на React» — вполне подъёмная задача. «Модернизировать приложение» — нет.

Здесь стоит отметить ещё одну вещь: скорость работы искусственного интеллекта не отменяет дисциплину рефакторинга. То, что вы двигаетесь заметно быстрее, не значит, что можно выбросить за борт рабочие практики. Паттерны рефакторинга Мартина Фаулера и малые шаги Кента Бека по-прежнему важны.

Это обычная хорошая гигиена рефакторинга: она удерживает изменения, выполняемые агентом, достаточно маленькими, чтобы сбои оставались понятными, обратимыми и дешёвыми. Оказывается, фундаментальные вещи всё так же раздражающе фундаментальны.

Компромисс как стратегия

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

// Выносим функции в глобальную область видимости. Неэлегантно, но работает
window.handleUpload = handleUpload;

// Оборачиваем унаследованные визуализации. Неидеально, но стабильно
import LegacyChartRenderer from './legacy/charts';

// BLOCKER: Проблема безопасности, нужно исправить до merge
// TODO: Заменить на нормальную аутентификацию
if (user === 'admin') { ... }

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

Сложность работы с ИИ в том, что модели по умолчанию тянутся к «лучшим практикам», когда вам нужно что-то реально работающее. Они часто предлагают масштабные рефакторинги, которые быстро разрастаются и становятся практически невозможными для merge. На самом деле нужны точечные изменения, которые открывают путь к следующему шагу. Навык здесь в том, чтобы направлять ИИ к прагматичным решениям, а не к теоретическим идеалам.

Структура как условие безопасной работы

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

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

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

Вторая оговорка: структура делает помощь ИИ возможной, но не обязательно превращает её в автоматизацию. Мы начали отслеживать «автономность агента» в разных проектах — соотношение ходов агента к промптам человека. Где-то получается 95%, где-то показатель держится на уровне 60%. Разница сводится к тому, насколько хорошо вы передаёте намерение и сколько контекста агент может получить без вашего участия.

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

Обе оговорки ведут к одному выводу: ИИ действительно может помогать в brownfield-разработке. Но он не спасёт сломанную архитектуру и не будет сам себя контролировать. Создайте условия, оставайтесь вовлечёнными — и он окажется удивительно эффективным. Пропустите подготовку — и, скорее всего, закончите примерно как та команда с Django.

Читайте больше об AI-агентах:

- Как прокачать ИИ-агента без дообучения: Agent Skills
- Как создать своего первого ИИ-агента за 30 минут
- Почему AI-агенты ломаются на длинных задачах — и как обвязка помогает им дописывать приложения
- Как работают ИИ-агенты для разработки

Работа с AI в существующей кодовой базе быстро упирается не только в код, но и в инженерное управление: как задавать границы, объяснять решения бизнесу, выбирать метрики и не терять контроль в условиях неопределённости. В OTUS как раз пройдут бесплатные уроки для тех, кто движется в роль CTO — приходите познакомиться с экспертами и задать свои вопросы:

• 8 июля в 20:00. «Метрики CTO: как доказать бизнесу, что инженерная команда работает эффективно». Записаться

• 16 июля в 20:00. «Как CTO говорить с бизнесом и командой на одном языке». Записаться

• 22 июля в 20:00. «Как CTO управляет неопределённостью: оценки, планы и ожидания бизнеса». Записаться