Перейти к содержанию
Публикация AiManual

Контекст-инжиниринг для кодинг-агентов: как измерить, что реально влияет на результат

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

Коротко

Что будет в материале

  1. 01

    Суть эксперимента: что измеряли и почему через план

  2. 02

    Как воспроизвести методику: пошаговый порядок

  3. 03

    Что реально влияет на план: разбор по типам контекста

  4. 04

    Развилки, которые должен закрывать человек

Корпоративные правила и реальные примеры кода команды сильнее всего меняют план работы кодинг-агента: в эксперименте они получили балл 5 по пятибалльной шкале влияния. Повторы уже переданной информации, контрольные аудиты и уточнения решённого дали балл 1, план после них почти не двигался. Эксперимент описан в блоге Думейт, соавтором указан Дуэйд (doaid), полный разбор контекст-инжиниринга для кодинг-агента опубликован отдельной статьёй.

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

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

Суть эксперимента: что измеряли и почему через план

Автор ставил агенту задачу по разработке сервиса текстового поиска на Rust и смотрел, как реагирует план при добавлении новых данных: сообщений, файлов, репозиториев, документации, правил команды и примеров готового кода. Оценка привязана к одному вопросу: сдвинулась ли работа после этой порции.

Почему индикатор - план, а не итоговый код

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

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

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

Шкала влияния с баллами 1-5

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

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

Как воспроизвести методику: пошаговый порядок

Порядок в источнике выглядит так:

  1. Составить техническое задание.
  2. Положить ТЗ файлом в папку проекта.
  3. Попросить агента подготовить план реализации ТЗ.
  4. Добавлять контекст порциями: сообщения, файлы, репозитории, документация, правила.
  5. После каждой порции просить агента предложить изменения к плану и оценить влияние по шкале.
  6. Фиксировать результат: что добавлено, что изменилось в плане, какой балл.

Повторить это можно на любой задаче, где есть внятное ТЗ и обозримый объём работы. Для эксперимента такой задачей стал сервис текстового поиска на Rust, но сама механика не привязана к языку или типу проекта. Важнее другое: порции подаются по одной, а не всей папкой сразу, иначе вы снова получите один общий вывод вместо набора оценок.

ТЗ файлом, а не пересказом в чате

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

В наборе контекста из эксперимента, помимо ТЗ, были документация на внешний API, правила команды и примеры готового кода. Такой набор удобно держать файлами в проекте: агент читает их как часть рабочего окружения. Похожий принцип применяется и в более тяжёлых сценариях: в разборе виртуальных исполнителей в Jira контекст агента собирается из Confluence и GitLab, а ревью остаётся за человеком.

Что записывать в журнал запросов и оценок

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

ПолеЧто писать
Номер порцииПорядковый номер подачи контекста в сессии
Тип контекстаПравила, примеры кода, документация, повтор, аудит
Что переданоИмя файла или краткое содержание сообщения
Изменения в планеНовые шаги, снятые шаги, изменённая архитектура
БаллОценка 1-5 по принятой шкале
РазвилкаПометка, если нужен ответ человека

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

Что реально влияет на план: разбор по типам контекста

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

Правила и примеры кода: почему балл 5

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

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

Повторы, аудиты и уточнения: почему балл 1

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

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

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

Почему лишний контекст размывает внимание модели

Лишняя информация занимает место и размывает внимание модели. Пересказ уже известных агенту данных почти никогда не даёт прироста качества. Каждая порция конкурирует за внимание с остальными, и десяток «на всякий случай» приложенных файлов снижает шанс, что агент выделит действительно важное.

Критерий отсечения простой: если порция не может изменить шаг плана или архитектурное решение, скорее всего, она не нужна на этом этапе. Отложить её дешевле, чем потом разбираться, почему агент ушёл не туда. Это и есть контекст-инжиниринг для LLM в прикладном виде: не «добавить побольше», а «добавить то, что меняет решение».

Развилки, которые должен закрывать человек

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

Практика простая: порция контекста породила развилку - работа останавливается, варианты и вопрос фиксируются в журнале, решение принимает человек. Если продолжать без ответа, агент выберет вариант сам, и узнаете вы об этом на этапе ревью, когда переделка уже стоит времени. Схема «агент предлагает, человек утверждает» описана в разборе Agent-Ops 0.4.0 и там же разложена по шагам процесса.

Распознать развилку легко по формулировке в ответе агента: либо/или, «зависит от требований», «нужно уточнить у заказчика». Такие места и выносятся человеку. Конкретные развилки из эксперимента в источнике не перечислены, поэтому список типовых решений выше - обобщение, а не факт того разбора.

Ограничения эксперимента: чему верить, а чему нет

Ограничения в источнике названы прямо, и их три.

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

Что из этого следует практически. Методику стоит воспринимать как способ сравнить порции контекста внутри своей задачи, а не как универсальный закон. Баллы 5 и 1 - результат одного наблюдения, а не бенчмарк, на который можно ссылаться в споре о том, какие практики «доказанно работают». Для сравнения моделей или агентов между собой нужен отдельный набор задач и повторные прогоны, о чём подробно говорится в материале про собственный тест двух моделей на реальной разработке.

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

Как применить это на своей задаче

Минимальный набор шагов, который не требует перестройки процесса:

  • ТЗ - файлом в папку проекта, не пересказом в чате.
  • Корпоративные правила и примеры кода команды - в начале работы, до фиксации архитектуры.
  • Развилки - человеку, с записью вариантов в журнал.
  • Журнал запросов и оценок влияния - с первой порции, иначе сравнивать будет нечего.
  • Порция не изменила план - кандидат на удаление из контекста.

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

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

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

Подписаться на канал