Технический долг в легаси-коде: как «Совкомбанк Технологии» отдала рефакторинг ИИ-агенту

Ира, лид группы проектов в «Совкомбанк Технологии», описала в корпоративном блоге компании, как её команда закрывает технический долг на фронтенд-проекте с несколькими архитектурными эпохами. Проект написан на React, частично переведён на Feature-Sliced Design (FSD, архитектурный стандарт для фронтенда, где код делится на слои по бизнес-смыслу), а остальная часть остаётся легаси. В коде одновременно живут SCSS, CSS Modules, Tailwind с кастомным префиксом, инлайн-стили и устаревшие библиотеки. Именно такой «зоопарк» делает ручной рефакторинг дорогим и рискованным.

Почему «перепиши нормально» ломает продакшен?

Главный тезис статьи: размытый промпт (prompt, текстовая инструкция для ИИ) вроде «перепиши нормально» опасен. Модель может вынести функции, поменять архитектуру, заменить библиотеку, изменить API или переименовать сущности. Для ИИ всё это «рефакторинг», а для рабочей системы каждое действие несёт разный уровень риска. Хуже того, при повторном запросе с тем же размытым заданием модель может принять другое решение.

Команда пришла к выводу: промпты должны быть разбиты на два уровня.

• Правила фиксируют то, что нельзя нарушать: «никогда не изменяй data-testid», «ищи аналоги утилит в src/shared», «используй только SCSS для стилей».
• Повторяемые операции описывают конкретные шаги: зафиксировать поведение тестами, вынести утилиты, разделить крупный JSX, запустить проверки, просмотреть итоговый diff.

Единым источником истины для этих правил стал файл AGENTS.md, который ИИ-агент (agent, программа, способная выполнять цепочку действий без ручного контроля на каждом шаге) читает перед каждой задачей.

Что понадобится

• Легаси-проект на React (или аналогичном фреймворке) с накопленным техническим долгом.
• ИИ-ассистент для кода с поддержкой навыков и файла правил (команда использовала формат AGENTS.md).
• Линтер и тестовый фреймворк, уже настроенные в проекте.
• Доступ к репозиторию и право создавать ветки.
• Время: подготовка AGENTS.md и навыков занимает один-два дня, дальше каждый компонент рефакторится в полуавтоматическом режиме.

Пошаговая инструкция

1. Заполните AGENTS.md общими правилами проекта. Опишите стек, структуру папок, пометьте легаси-директории и библиотеки. Укажите стадию миграции (например, «проект переходит на FSD, часть кода уже переведена, остальное требует рефакторинга»). Пропишите соглашения по неймингу, документации JSDoc, тестам, веткам и коммитам.

``` # AGENTS.md — фрагмент ## Legacy - Папки src/old-modules и src/legacy-components помечены как legacy. - Библиотека tf-ui (Tailwind) подлежит замене на SCSS.

## Соглашения - Вместо TypeScript enum используйте as const. - Стили: только SCSS, никакого Tailwind и inline styles. - Не изменяйте data-testid. ```

1. Создайте навыки (skills) для повторяемых операций. Каждый навык описывает одну атомарную задачу с чёткими триггерами «когда запускать» и «когда не запускать».

2. Навык test-first: зафиксируйте поведение до рефакторинга. Он пишет unit-тесты для компонента, чтобы гарантировать, что рефакторинг не сломает логику.

``` # Навык test-first — триггеры Используй, когда: - пользователь собирается отрефакторить компонент - особенно legacy .js или классовый компонент - звучат фразы: «зафиксируй поведение тестами», «покрой тестами до рефакторинга», «защити рефакторинг тестами»

НЕ используй, когда: - пишутся тесты для нового кода - запускается npm test - задаются вопросы о стеке ```

1. Навык tailwind-to-scss-conversion: приведите стили к единому стандарту. В проекте «Совкомбанк Технологий» Tailwind покрывал около 20% кода, и команда решила вернуться к SCSS. Навык автоматически заменяет Tailwind-классы на SCSS-эквиваленты и убирает инлайн-стили.

2. Создайте навык-оркестратор refactor. Он анализирует компонент, составляет план и вызывает нужные навыки в правильном порядке: сначала test-first, потом вынос утилит, разделение компонента, конвертация стилей, финальные проверки.

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

4. Просмотрите итоговый diff вручную. Даже с жёсткими правилами модель может внести неожиданные изменения. Финальное ревью остаётся за человеком.

Что делать с этим прямо сейчас?

Разработчикам и тимлидам в РФ. Формат AGENTS.md и навыков можно адаптировать под любой стек и любой ИИ-ассистент с поддержкой файлов правил. Структуру из статьи «Совкомбанк Технологий» можно взять как шаблон и заполнить своими соглашениями за день.

Авторам Дзена и контент-маркетологам. Сам принцип «не давайте ИИ размытое задание, разбейте работу на правила и атомарные операции» работает и для текстов. Системный промпт (system prompt, базовая инструкция, которую модель читает перед каждым запросом) с правилами бренда, тона, запрещённых слов, это ваш AGENTS.md для контента.

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

Кто работает с легаси, тот знает: технический долг не исчезает сам, он только дорожает. Подход с AGENTS.md и атомарными навыками не уберёт его за ночь, но превратит бесконечную задачу «когда-нибудь перепишем» в конвейер, где каждый компонент проходит через одни и те же проверенные шаги.