Лучшие практики

Разница между агентами, которые надёжно выпускают код, и агентами, которые крутят колёса? Контекст. Умение проектировать контекст и структурировать код так, чтобы помочь агентам достичь успеха — делает агентную разработку предсказуемой.

Контекстная инженерия

Контекстная инженерия — это дисциплина предоставления AI-агентам правильной информации в правильное время. Это не просто промт-инженерия — это вся система того, что агент знает, когда принимает решения.

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

Почему контекст важнее промтов

Идеальный промт с плохим контекстом проваливается. Средний промт с отличным контекстом часто succeed.

Контекст включает:

• Системные инструкции — Базовое поведение и ограничения агента
• Знание кодовой базы — Файлы, паттерны, конвенции, на которые агент может ссылаться
• История разговора — Что обсуждалось и было решено
• Выводы инструментов — Результаты чтения файлов, выполнения команд, поисков
• Внешняя документация — API-документация, спеки, требования

Промты — лишь одна часть. Всё контекстное окно агента определяет качество вывода.

Рабочий процесс контекстной инженерии

1. Отбирайте, что войдёт

Не всё принадлежит в контекст. Больше — не лучше — часто хуже. Нерелевантный контекст разбавляет сигнал и тратит токены.

Спросите: Что агенту нужно для выполнения этой задачи? Включите это. Исключите всё остальное.

2. Структурируйте для извлечения

Агенты сканируют контекст в поисках релевантной информации. Сделайте её находимой:

• Используйте чёткие заголовки и секции
• Помещайте критичные ограничения рано
• Группируйте связанную информацию вместе
• Используйте последовательное форматирование

3. Управляйте жизненным циклом контекста

Контекстные окна заполняются. Когда это происходит, более старый контент обрезается — агент буквально забывает его.

• Начинайте свежие разговоры для новых задач
• Суммаризируйте длинные обсуждения перед продолжением
• Повторно формулируйте критичные ограничения, когда контекст заполняется
• Используйте инструменты вроде AGENTS.md для сохранения важного контекста между сессиями

Практические техники работы с контекстом

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

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

Формулируйте ограничения явно. «Не меняй публичный API» — это контекст. «Следуй паттерну обработки ошибок в auth.ts» — это контекст. Делайте неявное знание явным.

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

Используйте персистентные файлы контекста. AGENTS.md, README файлы и подобные документы предоставляют контекст, сохраняющийся между сессиями. Держите их актуальными.

Антипаттерны контекста

Контекст-мусорка — Сваливать всё «на всякий случай». Разбавляет сигнал, тратит токены, сбивает агента с толку.

Устаревший контекст — Устаревшая документация или код, противоречащий текущему состоянию. Приводит к галлюцинациям и неверным предположениям.

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

Фрагментация контекста — Распространение связанной информации по множеству сообщений. Группируйте связанный контекст вместе.

Режимы отказов, на которые стоит обратить внимание

Агенты отказывают предсказуемым образом. Изучение этих паттернов помогает ловить проблемы рано.

Галлюцинации

Агенты используют API, методы или параметры, которые не существуют. Код выглядит правильно, но падает в рантайме.

Триггеры: Менее популярные библиотеки, недавно изменённые API, специфичные для предметной области инструменты.

Обнаружение: Будьте подозрительны к незнакомым именам методов. Проверяйте существование импортов. Запускайте код — не просто читайте.

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

Дрифт

Агент начинает решать вашу проблему, но постепенно смещается к другой, более лёгкой.

Триггеры: Длинные промты с множеством целей. Неоднозначные требования.

Обнаружение: Перечитывайте исходное требование после каждой итерации. Спрашивайте: «Это всё ещё решает мою реальную проблему?»

Предотвращение: Разбивайте на более мелкие, сфокусированные части. Формулируйте критерии успеха явно.

Зацикливание

Агент повторяет один и тот же неработающий подход с небольшими вариациями.

Триггеры: Ошибки, которые агент не понимает. Задачи за пределами возможностей. недостающий контекст.

Обнаружение: Отслеживайте итерации — если их больше 3-4, что-то не так.

Предотвращение: Предоставляйте контекст ошибки. Берите вручную и пробуйте другой подход.

Переоценка

Агент объявляет успех, когда код не работает, или заявляет уверенность в неверной информации.

Обнаружение: Никогда не доверяйте самооценке. Запускайте код сами. Пишите тесты для реальных требований.

Предотвращение: Спрашивайте, как он проверил корректность. Запрашивайте конкретные тесты граничных случаев.

Переполнение контекста

Ранний контекст «забывается» по мере роста разговора. Агент противоречит более ранним решениям или игнорирует ограничения.

Триггеры: Длинные разговоры. Большие кодовые базы в контексте. Сложные многошаговые задачи.

Обнаружение: Следите за несоответствиями. Замечайте, когда агент спрашивает информацию, которую вы уже давали.

Предотвращение: Держите разговоры сфокусированными и короткими. Начинайте заново для новых задач. Повторяйте критичный контекст.

Правдоподобная чушь

Код выглядит изощрённо, но фундаментально не понимает проблему или предметную область.

Обнаружение: Трассируйте логику мысленно — имеет ли это смысл? Получите ревью от эксперта предметной области.

Предотвращение: Предоставляйте контекст предметной области явно. Включайте примеры корректных решений.

Создание AI-совместимого кода

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

Структура

Держите файлы сфокусированными. Одна концепция на файл. Агенты запрашивают конкретные файлы — делайте эти запросы полезными.

Используйте описательные имена. UserAuthenticationService.ts лучше чем uas.ts. Агенты делают вывод о назначении из имён.

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

Держите функции короткими. До 50 строк. Единая ответственность. Чёткие входы и выходы.

Типы и контракты

Используйте типы щедро. TypeScript, type hints в Python. Типы — это машиночитаемая документация.

// Сложнее для агентов
function process(data) {
  /* что такое data? */
}

// Легче для агентов
function processOrder(order: Order): ProcessedResult {
  /* чёткий контекст */
}

Определяйте интерфейсы на границах. Явные интерфейсы предотвращают ошибки интеграции.

Избегайте any/unknown. Больше информации о типах позволяет лучше делать выводы.

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

Документируйте «почему», не «что». Агенты читают, что код делает. Они не могут прочитать ваши мысли.

// Менее полезно
// Эта функция вычисляет скидку
function calculateDiscount(order: Order): number;

// Более полезно
// Бизнес-правило: Премиум-клиенты получают 10% скидку на заказы от $100
// Эта скидка суммируется с промо-кодами
function calculateDiscount(order: Order): number;

Держите README актуальными. Агенты часто начинают с их чтения. Устаревшая документация вводит в заблуждение.

Документируйте неочевидные ограничения. Rate limits, известные ограничения, вещи, которые «просто так работают».

Тестирование

Пишите тесты как спецификацию. Тесты говорят агентам, что код должен делать.

Держите тесты быстрыми. Агенты запускают тесты часто. Медленные тесты ломают циклы обратной связи.

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

Используйте описательные имена. test_user_creation_fails_with_duplicate_email лучше чем test_user_3.

Паттерны, которых стоит избегать

• Магия и метапрограммирование — Динамическая генерация методов, heavy reflection сбивают агентов с толку
• Неявные зависимости — Service locators, ambient context скрывают нужную информацию
• Циклические зависимости — Сбивают агентов с толку относительно того, что от чего зависит
• Непоследовательные паттерны — Если вы делаете одно и то же тремя способами, агенты не будут знать, какому следовать

Инкрементальное улучшение

Не нужно переписывать всё. Касаясь кода:

• Улучшайте файл, который модифицируете
• Добавляйте типы там, где добавляете код
• Пишите тест, когда исправляете баг
• Обновляйте документы, когда обнаруживаете, что они неверны

Со временем кодовая база становится более дружелюбной к агентам — и более дружелюбной к людям.

Ресурсы

Контекстная инженерия

• Context Engineering for AI Agents – Tobi Lutke - CEO Shopify о том, почему контекстная инженерия — новый навык
• Context Engineering – Andrej Karpathy - «Промт-инженерия мертва, контекстная инженерия — король»
• AGENTS.md - Открытый формат для персистентного контекста агентов, используется в 60k+ open-source проектах

Режимы отказов и восстановление

• “I shipped code I don’t understand” – Jake Nations, Netflix - «Бесконечный кризис ПО» и как его избежать
• Agent Readiness – Eno Reyes, Factory AI - Восемь категорий для AI-готовых кодовых баз

Углублённые

• No Vibes Allowed – Dex Horthy, HumanLayer - Заставляем агентов работать в кодовых базах с 300k LOC
• RepoCoder: Repository-Level Code Completion - Фреймворк для использования контекста репозитория