Как научить ИИ-агента работать с вашими проектами

Главный страх топ-менеджера при внедрении ИИ-ассистентов звучит так: «Мы заплатим за цифровизацию, а получим дорогую игрушку, которая ломает наш рабочий процесс». Второй страх: «Без нас ИИ не справится, а с нами — зачем он тогда нужен?». Языковые модели натренированы на открытом коде и учебных идеалах, которые далеки от продуктовой реальности — и эти знания часто оказываются несовместимы с архитектурой, которая у вас живёт и работает годами. Но мы в Uplab нашли решение, как этого избежать, и это решение не сложнее, чем скормить агенту 50 страниц Wiki. В этой статье подробно рассказываем, как за 30 минут научить ИИ-агента говорить на архитектурном языке вашего проекта без ручного копирования документации в каждый промпт. А ещё покажем экономику подхода: когда ИИ перестает быть непредсказуемой игрушкой и превращается в инструмент, который окупается в первые месяцы применения.

Почему ИИ знает не каждый стек

У каждой компании есть своя история: внутренние фреймворки, написанные пять-десять лет назад; legacy-системы (устаревшие решения и специфичные схемы базы данных), которые работают и приносят деньги; нестандартные архитектурные решения, принятые в то время, просто потому, что тогда ещё не существовало стандартизованного подхода. Кто-то сидит на самописном ORM (программа-«переводчик» между кодом программы и базой данных), кто-то — на фреймворке, о котором три человека знают за пределами офиса. И всё это тоже нормально. Потому что бизнес подчиняется не моде, а решениям, которые выполняют свою задачу.

Но вот наступил момент, когда ИИ-ассистенты стали реальным инструментом для сотен тысяч компаний. И первое, что обнаруживается: они отлично справляются, особенно на старте, с React, Django, Spring Boot, но при этом могут совершенно не понять конкретный проект. Модель обучена на публичных репозиториях, документации популярных библиотек и Stack Overflow. Она знает, как устроен Express.js, но понятия не имеет, как организованы контроллеры, модели и очереди.

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

• сокращение времени на рутину;
• ускорение онбординга;
• снижение стоимости каждой фичи.

Но для этого агент должен понимать конкретный проект, а не среднестатистический. А это значит, что его нужно дополнительно дообучить, «познакомив» с основными документами.

Путь от «скопировать wiki в промпт» до системного решения

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

Попытка первая: ручное подключение по ситуации

"Сначала я пробовал вручную прикладывать нужные статьи к запросу. Например, так: работаем с бизнес-сущностью, нужно добавить новое поле — подключаем инструкцию по тому, как устроена работа с моделью в системе. Работаем с очередями — прикладываем страницу из документации про очереди.

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

Попытка вторая: подключить вообще всё

Логичный следующий шаг — загрузить в контекст всю документацию. Десятки страниц wiki, описания API, архитектурные заметки. Казалось бы, чем больше контекста, тем лучше.

На практике это привело к двум проблемам:

1. Лимит контекстного окна. При большом объёме подключённых инструкций на одну простую задачу контекст забивался до предела. Больше одной итерации изменений не выходило, потому что окно кончалось. Для моделей с большим окном (200K+ токенов) проблема менее острая, но она не исчезает: каждый перезапуск агента — это повторная загрузка всего массива.
2. Деградация качества. Парадоксально, но чем больше информации вы скармливаете модели, тем хуже она может работать. Вместо того чтобы сфокусироваться на нужных правилах, агент начинает путаться в контексте, смешивать концепции из разных слоёв, подменять реальное поведение проекта шаблонным. Проще говоря, с обширным контекстом модели галлюцинирует чаще.

Поворотный момент: пусть агент сам себе соберёт инструкции

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

Вместо «вот тебе 50 страниц, разберись» — «вот тебе план: пройди по проекту, извлеки архитектуру и сформулируй правила так, чтобы потом сама могла их использовать»".

Как мы это реализовали

В качестве механизма мы использовали концепцию skill.

В директорию skill можно положить абсолютно любую документацию в любом формате: markdown-статьи из wiki, текстовые заметки, описания API. Главное в дизайне skill дать вводную: с чего начинать чтение и как ориентироваться в материалах. Агент в результате должен получить карту для навигации.

Принцип: код первичен, а документация — для сверки

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

1. Сначала агент анализирует кодовую базу проекта: структуру папок, базовые классы, паттерны, соглашения.
2. Затем сверяет наблюдения с приложенной документацией (wiki, описания API и т.д.).
3. Если код и документация расходятся, то приоритет отдаётся коду, а расхождение фиксируется.

Такой подход гарантирует, что инструкции отражают реальное положение дел, а не идеализированное представление.

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

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

Только архитектура, без бизнес-логики

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

Бизнес-логика конкретных сущностей намеренно исключается по следующим причинам:

• Бизнес-логика дополняется при каждом спринте, когда проект в стадии активной разработки. Например, инструкция, описывающая конкретные поля модели «Заказ», устаревает при первой же задаче с добавлением нового поля. И даже если автоматизировать обновление (например, через хуки, которые поддерживают Claude Code и аналоги), это увеличивает «стоимость» каждого изменения за счёт дополнительной работы агента. А без автоматизации разработчик может просто забыть запустить обновление вручную.
• Архитектура стабильна. Как устроены контроллеры, как связаны модели с таблицами — всё это меняется крайне редко. Skill запускается один раз для проекта (с возможностью повторного запуска при изменении архитектуры). Не нужно пересобирать инструкции при каждом обновлении релиза в разработке.
• Если же для конкретного проекта нужны и бизнес-инструкции (например, описание конкретных сущностей или бизнес-правил) — ничто не мешает создавать их отдельно, вручную или другим skill. Главное — не смешивать это с архитектурной базой, которая должна оставаться стабильной.

Какие инструкции мы получили

В нашем случае по итогам работы в проекте появился набор файлов-инструкций — каждый отвечает за свою зону ответственности. Вот что получилось в нашем случае (состав будет отличаться в зависимости от конфигурации вашего приложения):

• Обзор архитектуры — как устроен проект: основные слои, модули и связи между ними. Это «карта» для агента.
• Конфигурация приложения — какие подключения используются, какие режимы работы, как связаны модули.
• Контроллеры — как принято обрабатывать входящие запросы, какие базовые классы и соглашения существуют.
• Модели данных — как описываются сущности, как устроены миграции, как связаны таблицы между собой.
• Обработчики и ресурсы — специфичные для проекта компоненты, их зоны ответственности.
• Работа с базой данных — какие методы API использовать для выборок, вставок, потоковой обработки.

Ключевой момент: каждая инструкция подключается автоматически — только когда разработчик работает с соответствующей частью проекта. Редактируете модель — агент видит инструкцию по моделям. Работаете с очередями — подгружается инструкция по очередям. Ничего лишнего в контексте.

Инкрементальное обновление

При повторных запусках skill не перезаписывает всё с нуля. Для каждой инструкции выполняется проверка:

• Описанное в инструкции всё ещё соответствует коду — не трогаем.
• Появились новые паттерны или изменились связи — обновляем точечно.

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

Что это даёт на практике

Самое интересное начинается после генерации инструкций — когда вы просто работаете. Вот пример запроса из нашей реальной практики.

Обратите внимание: в запросе нет ни слова про архитектуру. Нет объяснений, где лежат модели, как устроены очереди, какой формат конфигурации. Только бизнес-задача. И, тем не менее, агент правильно выполнил задачу, ведь весь архитектурный контекст подтянулся автоматически через инструкции. Агент не угадывал и не «сочинял», он следовал зафиксированным правилам.

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

Экономика подхода

Давайте приведём сухие цифры и на их основе оценим окупаемость подхода.

Затраты на внедрение (наш опыт):

• Проектирование подхода и сбор существующей документации: 2–4 рабочих дня (один раз).
• Первый запуск генерации инструкций: 15–30 минут работы агента, 5 минут вашего времени.
• Повторная актуализация при изменении архитектуры: 5–10 минут.

Что получаем:

• Каждая задача в промпте содержит только бизнес-требования, без технического контекста. Экономия 10–30 минут на формулирование запроса для каждой нетривиальной задачи.
• Результат с первой попытки. Это прямая экономия времени: «сгенерировал → проверил → объяснил ошибку → пересгенерировал».
• Онбординг новых разработчиков: вместо недели погружения агент уже знает и подсказывает. А при необходимости показывает на деле, генерируя код по принятым в проекте соглашениям.
• Контекстное окно используется эффективно: подгружается только то, что нужно для текущего файла, а не вся база знаний разом.
• Экономия на подписке: меньше токенов на запрос — меньше расход. Особенно ощутимо на платных тарифах с премиум-моделями, где каждый лишний килотокен контекста — это немалые деньги.

Для кого это работает

Подход не привязан к конкретной технологии и применим, если у вас есть две вещи.

1. Любая документация, пусть даже несистематизированная, разбросанная по wiki, README-файлам или комментариям в коде. Можно и без неё, в таком случае за основу берётся сам код.
2. Понимание структуры проекта на уровне «где лежат модели, где контроллеры, что отвечает за конфигурацию». Это нужно только на этапе инициализации, и обычно это знает любой разработчик в команде.

Типичные сценарии, где наш подход даёт результат:

1. Внутренние фреймворки без публичной документации — самый очевидный кейс.
2. Legacy-проекты — где архитектура сложилась исторически и не описана в документации.
3. Проекты на малоизвестных фреймворках — где модель обучения ИИ не покрывает вашу технологию.
4. Любой проект с нестандартной архитектурой — микросервисы с необычной оркестрацией, монолиты с собственными паттернами, гибридные решения.

Вместо саммари

Суть подхода укладывается в одно предложение: вместо того чтобы бесконечно объяснять ИИ ваш проект, научите его один раз объяснить проект самому себе.

Такой подход анализирует код, формализует архитектуру в виде точечных инструкций и раскладывает их так, чтобы каждая подключалась ровно тогда, когда нужна. После этого задачи формулируются на языке бизнеса, а не на языке «в папке X создай файл Y по шаблону Z».

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