Хватит улучшать промпт. ИИ агенту нужен контекст проекта

Даже подробный промпт не объясняет агенту, как устроен ваш проект. Для этого нужен отдельный, актуальный контекст.

Вы просите ИИ-агента добавить форму заявки на сайт.

Через пару минут форма готова. Выглядит нормально: кнопка нажимается, поля заполняются. Только стоит она не там. В ней появился email, хотя вам нужен телефон. Агент ещё продублировал форму в футере и слегка «улучшил» дизайн, который никто не просил трогать.

Формально задача выполнена. По факту опять нужно объяснять всё заново.

Я долго пытался лечить это более подробными промптами: добавлял формулировки, примеры и ограничения. Промпт сначала становился похож на небольшое ТЗ, потом — на большое. Но результат всё равно периодически приезжал боком.

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

Промпт может быть простым:

Добавь форму заявки на сайт.

Он задаёт действие. Но внутри этой фразы нет ответов на вполне практические вопросы:

Если ответы не переданы, модель заполняет пробелы наиболее вероятным вариантом.

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

Для той же задачи контекст может выглядеть так:

Проект: B2B-лендинг на Next.js. Форма открывается в правой боковой панели. Поля: — имя; — телефон; — описание задачи. Существующие компоненты и цвета не менять. Новые backend-сервисы не добавлять. После изменения запустить: — lint; — тесты; — smoke-тест формы.

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

Я храню такие вещи отдельно от команды. Часть находится в правилах проекта, часть — в описании текущей задачи.

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

Если скормить агенту весь репозиторий, историю чатов, заметки из Obsidian и пару лет переписки, лучше не станет.

Старые решения начнут спорить с текущими. В архиве найдётся стек, который уже заменили. Среди полезных заметок окажутся черновики и идеи, от которых давно отказались.

Мне нужен не максимальный объём информации, а актуальная выжимка под конкретную задачу:

Остальное можно подтянуть позже, если оно действительно понадобится.

Я использую такую последовательность:

Цель → контекст → план → микрозадачи → код → проверка → обновление контекста

Сначала я фиксирую измеримый результат. Затем агент читает актуальные правила проекта и предлагает план.

Большую работу мы разбиваем на небольшие изменения, каждое из которых можно проверить отдельно.

После написания кода запускаются реальные команды:

Фраза «готово» от агента ничего не доказывает, пока нет результата проверки.

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

Для небольшой задачи обычно хватает пяти блоков.

Что должно измениться для пользователя.

Какие файлы или модули можно менять.

Что трогать нельзя и какие технологии не нужно добавлять.

Какие команды необходимо запустить и какой результат ожидается.

По каким признакам человек примет работу.

Готовый шаблон:

Цель: Что должно измениться для пользователя. Область изменений: Какие файлы и модули можно менять. Ограничения: Что трогать нельзя. Какие технологии и зависимости нельзя добавлять. Проверки: Какие команды нужно запустить. Какой результат считается успешным. Definition of Done: По каким признакам задача считается выполненной.

Это можно хранить в описании задачи, Markdown-файле или трекере. Название инструмента здесь вторично.

Суть в том, чтобы агент видел один актуальный источник требований, а не собирал их по старым чатам.

API-ключ, access token, пароль, seed-фраза и данные карты не помогают модели понять проект. Они только увеличивают последствия возможной ошибки.

В контексте достаточно написать:

Используй переменную окружения API_KEY. Реальное значение не читать и не выводить в лог.

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

Я перестал ждать, что одна формулировка каким-то образом передаст агенту устройство всего проекта.

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

Агент всё ещё ошибается. Просто теперь ошибка быстрее обнаруживается и реже повторяется второй раз.

Для меня это намного полезнее, чем очередная коллекция «50 промптов, которые изменят вашу работу».

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

Продолжения и рабочие заметки публикую в Telegram-канале UnderCode.