Инженерия с ИИ-агентами: карта трека и чего ждать от агента

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

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

Одно предложение, из которого следует весь трек

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

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

Отсюда сквозная тема трека: проверяемость. Не «доверяй, но проверяй», а жёстче — утверждение агента о поведении кода не имеет статуса свидетельства, пока вы не увидели прогон. Своими глазами, в своём терминале, на своей машине или в своём CI.

Зачем ещё один трек про ИИ

На портале уже есть два соседних трека, и границы между ними намеренно жёсткие.

Разница на примере. В треке ИИ-инженерии вопрос «как оценить качество агента» — это про evals, метрики и датасеты (Оценка и бенчмарки). Здесь тот же вопрос звучит иначе: «агент прислал 400 строк диффа и сказал, что тесты зелёные — что я делаю дальше и сколько это стоит моего внимания». Это разные профессии.

Если вы никогда не читали, как устроен трансформер, трек всё равно читается. Но главы про контекст и про отказы будут понятнее после Токены, контекстное окно и память диалога.

Рабочее определение агента

Слово «агент» затаскано до бессмысленности. В этом треке под агентом понимается конкретная вещь:

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

Три слова здесь несущие:

1. Цикл. Не один ответ, а последовательность шагов, где каждый следующий зависит от результата предыдущего. Каноническая формулировка этой петли — статья ReAct: Synergizing Reasoning and Acting in Language Models (Yao et al., 2022).
2. Инструменты. Модель не «умеет читать файлы». Харнесс даёт ей описание функции read_file, модель генерирует запрос на вызов, харнесс выполняет его сам и возвращает вывод текстом. Всё, что агент «делает», делает не модель.
3. Права. Агент, который может только читать, и агент, который может писать в репозиторий и выполнять bash, — разные объекты по уровню риска, даже если внутри одна модель.

Убираем любое из трёх — получаем не агента. Автодополнение в редакторе — не агент (нет цикла). Чат, который присылает вам код на копипаст, — не агент (нет инструментов). Разницу подробно разбирает Агент и чат.

Обратите внимание на два узла. F — единственное место, где в контур попадает реальность: настоящий вывод настоящей команды. Всё, что вне этого узла, — текст, сгенерированный по вероятностям. И I — единственное место, где реальность попадает к вам. Между H и I находится вся содержательная часть этого трека.

Что агент делает хорошо, а что не делает вовсе

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

Работает надёжнее всего:

• Массовые механические изменения с дешёвой проверкой: переименования по всему репозиторию, миграция вызовов устаревшего API, приведение сотни файлов к одному стилю. Проверка — компилятор, линтер, дифф.
• Написание тестов по существующему образцу, когда в проекте уже есть 200 похожих тестов и понятно, как выглядит правильный.
• Разведка в незнакомом коде: «где здесь обрабатывается таймаут», «какие вызовы идут в этот сервис». Ответ проверяется за минуту переходом по ссылкам, а ручной поиск занял бы час.
• Черновик, который вы всё равно перепишете, но с чистого листа начинать не хотите: скелет CLI, парсер формата, обвязка вокруг библиотеки.
• Рутина вокруг кода: описания коммитов, changelog, шаблонный boilerplate, разбор непонятного стектрейса.

Работает плохо и дорого:

• Задачи, где проверка дороже реализации. Оптимизация производительности без бенчмарка — классический пример: агент уверенно «ускорит» код, а измерять будете вы (Измерение производительности).
• Флейки и гонки. Агент видит один прогон, а проблема статистическая.
• Архитектурные решения. Агент выдаст обоснованный на вид выбор, но обоснование написано по частотности слов, а не по вашим ограничениям (Архитектурные решения и ADR).
• Всё, у чего последствия вне репозитория: миграции продовой БД, изменения инфраструктуры, рассылки. Не потому, что агент глупее человека, а потому что откат стоит дорого, а вероятность ошибки не ноль.

Не делает вовсе, хотя выглядит как будто делает:

• Не помнит вчерашнюю сессию. Всё, что «помнит», — файлы, которые вы ему дали прочитать. См. Память агента.
• Не знает, что происходило в вашем проекте после отсечки обучающих данных, и не знает версий ваших зависимостей, пока не прочитает lock-файл.
• Не различает уверенность и знание. Тон ответа не несёт информации о его правильности — это не «баг конкретной модели», а свойство способа генерации.
• Не берёт на себя ответственность. Подпись под PR — ваша. Об этом отдельно в Агенты в командной работе.

Где проходит граница: проверка против объёма

Простая двумерная модель, по которой стоит принимать решение «отдавать или делать руками». Ось X — насколько дёшево проверить результат. Ось Y — сколько механической работы в задаче.

Квадрант 4 — самый недооценённый. Там задачи, которые агент сделает правильно и быстро, но формулировка задачи для агента займёт больше времени, чем сама правка. Если объяснение задачи длиннее, чем диф, который вы бы написали руками, — пишите руками. Это не про экономию токенов, это про экономию вашего внимания: переключение контекста «сформулировал → подождал → прочитал → проверил» стоит дороже, чем кажется.

Квадрант 2 — там, где живёт большинство интересной работы, и там же большинство катастроф. Правило простое: если проверка дорогая, а объём большой, задача не отдаётся целиком. Она режется на шаги, каждый из которых заканчивается артефактом, который вы можете проверить за минуту. Как это делается — в Планирование и декомпозиция.

Как рождается ложное утверждение

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

Разберём последнюю реплику агента по частям. «Исправил» — проверяемо дифом, скорее всего правда. «Проблема была в округлении задержки» — объяснение, придуманное задним числом; правка могла случайно поменять что-то другое. «Тесты проходят» — чистая выдумка, инструмент запуска не вызывался ни разу.

Три разных по природе утверждения в одном предложении, и только первое имеет опору. Именно поэтому ревью кода от агента — отдельный навык, а не «то же ревью, только чужого кода»: у человека-автора эти три типа утверждений обычно коррелируют, у агента — нет. Подробно в Ревью кода от агента и Где агенты врут.

Шесть классов отказов, которые стоит знать до первой сессии

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

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

Три счётчика цены

Разговоры про «стоимость агента» обычно сводятся к счёту от провайдера. Это самый мелкий из трёх счётчиков.

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

Оранжевая полоса на схеме — обычно самая толстая и самая бесполезная. Вывод pytest -v на 300 тестов, полный git log, содержимое файла на 2000 строк, из которого нужна одна функция. Дисциплина «давать инструменту узкий запрос» экономит больше, чем любая настройка модели.

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

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

Что известно про ускорение — и почему цифры расходятся

Здесь важно быть точным, потому что именно тут обычно врут обе стороны спора.

Есть рандомизированный эксперимент The Impact of AI on Developer Productivity: Evidence from GitHub Copilot (Peng et al., 2023): 95 разработчиков, задача — написать HTTP-сервер на JavaScript с нуля; группа с Copilot справилась на 55,8% быстрее.

И есть рандомизированный эксперимент Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity (METR, 2025): 16 опытных контрибьюторов, 246 реальных задач в их собственных зрелых репозиториях. С ИИ-инструментами задачи занимали на 19% больше времени. При этом участники ожидали ускорения на 24% и постфактум считали, что ускорились примерно на 20%.

Оба результата, скорее всего, верны — они измеряют разные вещи. Синтетическая задача с нуля, где нет legacy, нет конвенций проекта и нет требований к качеству, — это лучший случай для агента. Реальная задача в репозитории, который автор знает наизусть, — худший: агент не знает того, что автор держит в голове, и цена объяснения превышает выигрыш.

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

Третий источник, полезный для баланса: отчёт DORA 2024 на данных опроса разработчиков сообщает, что рост внедрения ИИ на 25% ассоциирован со снижением стабильности поставки примерно на 7% и небольшим снижением пропускной способности. Это корреляция в опросных данных, а не причинно-следственная связь, и авторы это оговаривают. Но направление стоит держать в голове: скорость производства кода и скорость поставки работающего продукта — разные величины.

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

Жизненный цикл одной сессии

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

Два перехода, которые пропускают чаще всего.

Формулировка → Уточнение. Хороший агент останавливается и спрашивает, когда задача недоопределена. Плохой — угадывает. Угадывание выглядит эффективнее ровно до момента, когда выясняется, что угадано не то. Явное разрешение «если не хватает данных — спроси, не додумывай» в контракте проекта заметно меняет поведение. Об этом Промпт как спецификация.

Ревью → Новая_сессия. Сессия, в которой агент дважды исправил не то, редко выправляется на третий раз: неверные ходы уже лежат в контексте и продолжают влиять на генерацию. Дешевле сформулировать задачу заново, с учётом того, что вы поняли. Это не поражение, это нормальный ход.

Дисциплина, которую можно включить сегодня

Минимальный протокол, который работает независимо от инструмента и версии.

Первое: контракт проекта. Файл в корне репозитория, который харнесс читает автоматически (CLAUDE.md, AGENTS.md или аналог вашего инструмента). Не «инструкция по стилю» на пять страниц — короткий список того, что агент не может вывести из кода.

## Прогон
- Тесты: `make test` (не `pytest` напрямую — нужны фикстуры из docker-compose)
- Линтер: `make lint`. Изменение конфига линтера — отдельный PR.

## Границы
- Не менять файлы в `migrations/` — только руками.
- Не добавлять зависимости без явного разрешения в задаче.
- Тест, который начал падать, чинится в коде. Правка теста ради зелёного — запрещена.

## Отчётность
- Утверждение о поведении кода сопровождается выводом команды.
- Если данных не хватает — задать вопрос, не угадывать.
- Пункт задачи, который не сделан, называется явно.

Второе: свой прогон после каждой сессии. Не читать отчёт агента, а посмотреть на факты.

# 1. Что реально изменилось — до чтения любых объяснений
git diff --stat
git diff -- tests/            # правились ли тесты вместе с кодом

# 2. Не ослаблена ли проверка
git diff -U0 | grep -nE '^\+.*(skip|xfail|@ignore|catch \{|except.*: *pass)'

# 3. Не появились ли новые зависимости молча
git diff -- go.mod package.json pyproject.toml requirements.txt

# 4. Собственно прогон. Единственное доказательство
make lint && make test

Четыре команды, меньше минуты. Они ловят большинство отказов из таблицы выше — не потому что умные, а потому что смотрят на артефакт, а не на текст.

Третье: наш собственный пакет практик. В продукте портала есть набор шаблонов products/workbench/templates/memory/ — контракт памяти агента (AGENT-MEMORY-CONTRACT.md), протокол памяти (MEMORY-PROTOCOL.md), дисциплина рассуждения (REASONING-DISCIPLINE.md), правила выверенного кода (VERIFIED-CODE.md) и законы композиции (COMPOSITION-AND-LAWS.md). Каждое правило там имеет идентификатор и формулировку наблюдаемого нарушения — то есть его можно поймать в дифе или в отчёте.

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

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

Карта трека

Как читать

Трек линейный, но не строго. Минимальный маршрут для того, кто хочет начать завтра: 01 → 03 → 08 → 09 → 10. Этого достаточно, чтобы не сделать типичных дорогих ошибок.

Если вы уже работаете с агентом каждый день и хотите разобраться, почему получается неровно, — начните с 04, 09 и 12.

Если вы принимаете решение за команду — 12, 13, 14.

Чего в треке нет

Отдельно про инструменты. Трек не рекламирует ни Claude Code, ни Cursor, ни Codex, ни Aider, ни что-либо ещё. Категория меняется быстрее, чем пишутся статьи: всё, что можно сказать про конкретные флаги и кнопки, устареет за несколько месяцев. Поэтому в примерах инструменты называются там, где без этого не объяснить механику, всегда с оговоркой «проверьте документацию вашей версии», а сравнение вынесено в главу 15 и построено по свойствам (права доступа, прозрачность контура, воспроизводимость), а не по впечатлениям.

Готов ли ваш репозиторий к агенту

Проверка на входе. Если больше двух пунктов «нет» — начинать стоит не с агента.

• Есть команда, запускающая тесты, и она работает с чистого клона.
• Прогон тестов занимает время, за которое не остывает чай. Если полтора часа — цикл «правка → прогон» не замкнётся.
• Есть линтер и форматтер, конфиг лежит в репозитории.
• Изменения попадают в основную ветку через PR, а не прямым пушем (Совместная работа в git).
• Секреты не лежат в файлах, которые агент прочитает при первом же grep.
• Есть хотя бы один человек, который прочитает дифф перед мержем.
• Понятно, что считается «сделано»: критерий приёмки существует до начала работы.

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

Мини-итог

• Агент — это цикл «модель → инструмент → настоящий вывод → модель» с правом писать в вашу файловую систему. Не чат и не автодополнение.
• Единственная реальность в этом цикле — вывод инструментов. Всё остальное сгенерировано по вероятностям, включая отчёт об успехе.
• Утверждение агента о поведении кода не является свидетельством. Свидетельство — прогон, который сделали вы или CI.
• Цена состоит из токенов, времени и внимания. Третье дороже первых двух и не докупается.
• Ощущение ускорения не равно ускорению: в эксперименте METR участники замедлились на 19% и были уверены в обратном.
• Если объяснение задачи длиннее диффа — делайте руками. Это не поражение, это арифметика.
• Дисциплина, которая работает независимо от инструмента: контракт в репозитории, требование артефакта вместо утверждения, свой прогон после каждой сессии.

Источники

• Yao et al. ReAct: Synergizing Reasoning and Acting in Language Models — каноническая формулировка цикла «рассуждение — действие — наблюдение».
• METR. Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity — рандомизированный эксперимент на реальных задачах в зрелых репозиториях.
• Peng et al. The Impact of AI on Developer Productivity: Evidence from GitHub Copilot — рандомизированный эксперимент на синтетической задаче с нуля.
• Google Cloud / DORA. Accelerate State of DevOps Report 2024 — связь внедрения ИИ с метриками поставки в опросных данных.
• Perry et al. Do Users Write More Insecure Code with AI Assistants? — про расхождение между качеством кода и уверенностью в нём.
• Liu et al. Lost in the Middle: How Language Models Use Long Contexts — почему «положить всё в контекст» не равно «модель это учла».
• Anthropic. Building Effective Agents — разбор, когда агентная петля оправдана, а когда достаточно простой цепочки.
• Anthropic. Claude Code Best Practices — практики контракта проекта и работы в репозитории.
• Model Context Protocol — спецификация протокола подключения инструментов и данных.
• SWE-bench и SWE-bench Verified — про то, что именно измеряют бенчмарки агентов и почему их числа не переносятся на ваш репозиторий.
• Simon Willison. The lethal trifecta for AI agents — сочетание доступа к приватным данным, недоверенного контента и канала наружу.
• OWASP GenAI Security Project — Top 10 для приложений с LLM, включая инъекции и чрезмерные права агента.

Что дальше

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