Context Engineering для Coding Agents: почему доступа к репозиторию недостаточно

Claude Code пишет рабочий код за несколько минут. Я пользуюсь этим каждый день и не спорю с тем, что написание кода перестало быть узким местом.

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

Когда я впервые публиковал этот материал, эксперимент был только планом. Теперь он проведён: одна задача, один репозиторий, одна модель, 6 прогонов — 3 без контекста и 3 с пакетом контекста. Ниже — что такое Context Engineering, какие приёмы работают и что изменили 520 слов правильно отобранного текста.

Короткий ответ

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

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

Правильный код и неправильное решение

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

В GIT
─────────────
source code
tests
dependencies
configs

ВНЕ GIT
─────────────
Architecture
ADR
API contracts
Business rules
Security policies
Engineering standards
Tasks
Incidents
History

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

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

Агент, получивший только задачу и репозиторий, написал аккуратный код: слои соблюдены, деньги в копейках, сеть не трогает, тесты зелёные во всех 3 прогонах. А цену самовывоза он назначил сам: 199, 0 и 150 рублей в трёх прогонах. Утверждённая цена — 99 рублей, бесплатно от 3000. Флага выкатки, выключенного по умолчанию, не было ни разу; правило возврата было неверным во всех 3 прогонах. Подробный разбор этих решений — в статье почему Coding Agent недостаточно одного репозитория. Здесь важен вывод:

Repository ≠ Engineering Context

Почему «дать всё» не работает

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

Это не работает, и причина описана в исследованиях:

• «Lost in the Middle» (Stanford и соавторы, 2023): модели заметно хуже используют информацию из середины длинного контекста, чем из начала или конца. Измерения делались на моделях 2023 года, сейчас эффект может быть слабее, но сама проблема длинного контекста осталась.
• Chroma в 2025 году проверила 18 моделей, включая GPT-4.1, Claude 4, Gemini 2.5 и Qwen3: с ростом длины входа качество становится нестабильным даже на простых задачах. Эффект назвали context rot. Единого процента падения исследование не даёт, и я его не привожу.
• Anthropic формулирует это как бюджет внимания: у модели он конечен, и каждый лишний токен его расходует.

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

Что такое Context Engineering

Это работа, которая происходит на каждую задачу:

TASK
  ↓
определить нужный контекст
  ↓
найти его в источниках
  ↓
проверить права доступа
  ↓
собрать в вид для модели
  ↓
передать агенту

Я свожу её к трём условиям:

ПРАВИЛЬНЫЙ КОНТЕКСТ   то, что агент иначе придумал бы сам
ПРАВИЛЬНАЯ ЗАДАЧА     отобран под эту задачу, а не «про доставку вообще»
ПРАВИЛЬНЫЙ МОМЕНТ     доступен тогда, когда агент принимает решение

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

Приёмы Anthropic и что из них было видно в прогонах

Anthropic описывает несколько приёмов для длинных агентных задач. Это рекомендации инженеров, а не измеренные эффекты, но они хорошо объясняют, что происходило в эксперименте.

Загрузка по требованию. Агент держит в контексте не сами документы, а знание о том, где они лежат, и читает нужное в момент, когда оно понадобилось. В прогоне B1 агент уже после общей разведки отдельно перечитал ADR-011 — чтобы проверить точное правило именования флага перед тем, как писать код.

Сжатие (compaction). Когда история работы разрастается, её сворачивают в краткую сводку и продолжают с неё. Наши прогоны были короткими — 5–9 минут, — и в их журналах сжатия нет.

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

Субагенты. Разведку делает отдельный агент со своим контекстом и возвращает основному только выжимку. Это было видно лучше всего: во всех 3 прогонах B основной агент сначала запускал субагента, тот читал документы контекста и репозиторий и возвращал сжатый отчёт. В условии A так было в 2 прогонах из 3.

Все 4 приёма решают одну задачу: не тратить бюджет внимания на лишнее.

Эксперимент B: тот же агент плюс 520 слов

Условие B отличалось от A одним: к той же задаче и тому же репозиторию добавлялся каталог с инженерным контекстом и одна фраза в промпте — «контекст лежит там, используй его». Модель (claude-sonnet-5), версия Claude Code, набор разрешённых инструментов и стартовое состояние кода — одинаковые.

Вот весь пакет контекста:

ПАКЕТ КОНТЕКСТА ДЛЯ ЗАДАЧИ «САМОВЫВОЗ»        слов

requirements/PRD-pickup.md                     91
  6 бизнес-правил: цена, срок, вес, города,
  выбор пункта, возвраты
contracts/delivery-options.openapi.yaml       137
  поля и коды ошибок, согласованные с web и mobile
adr/ADR-011-delivery-rollout.md                43
  новый способ доставки — за флагом delivery_<code>,
  выключенным по умолчанию
adr/ADR-003-layering.md                        37
  домен не зависит от инфраструктуры
architecture.md                                88
  слои и точка сборки
engineering-rules.md                           44
  деньги в копейках, тест на каждое правило,
  контракт не переименовывать
security-policy.md                             40
  никаких сетевых вызовов к партнёрам в пути запроса
history/INC-2025-031.md                        42
  экспресс запустили без правила возврата —
  возвраты не проходили 2 дня
                                             ────
                                              522

Меньше 2 страниц текста. Это не документация компании — это ровно то, что нужно для одной задачи. Например, требования — это 6 строк, по одной на бизнес-правило. Инцидент — 3 строки: что случилось, почему и что теперь делаем всегда.

Результаты, одни и те же проверки для обоих условий. Проверки я записал до прогонов: 7 статических (тесты, название способа по контракту, поле контракта, флаг выкатки, правило возврата, слои, отсутствие сетевых вызовов) и 10 приёмочных, которые писал отдельный агент-валидатор только по требованиям, контракту и ADR.

                          A: задача + код    B: + контекст
                          (3 прогона)        (3 прогона)

собственные тесты агента  зелёные 3 из 3     зелёные 3 из 3
проверки по контексту     4, 4, 5 из 7       7, 7, 7 из 7
независимая приёмка       2, 4, 4 из 10      10, 10, 10 из 10
цена самовывоза           199 / 0 / 150 ₽    99 ₽ во всех
флаг выключен по умолч.   0 из 3             3 из 3
правило возврата верное   0 из 3             3 из 3
время прогона             4:22–7:14          4:35–9:07
стоимость прогона         $0,80–1,13         $1,03–1,85

В условии B агент реализовал цену 99 рублей с бесплатной доставкой от 3000, срок 2 дня, общий лимит 15 кг вместе с лимитом конкретного пункта, флаг delivery_pickup_point, выключенный по умолчанию, правило «стоимость доставки при возврате не возвращается» и отдельный тест на него.

Две вещи в этой таблице важнее итоговых баллов.

Первая: собственные тесты агента зелёные в обоих условиях. Они проверяют то, что агент сам понял из задачи. Если он придумал бесплатную доставку, его тест её и закрепит. Разницу показала только независимая приёмка по требованиям — об этом отдельно в статье почему зелёные тесты AI-кода ещё не значат, что задача решена.

Вторая: контекст не сделал агента быстрее и дешевле. Прогоны B шли от 4,5 до 9 минут и стоили от 1 до 1,85 доллара, прогоны A — от 4 до 7 минут и от 0,80 до 1,13 доллара. Самый долгий и дорогой прогон B2 потратил время не на контекст, а на правила доступа: 16 раз подряд пытался запустить тесты командой, которой не было в списке разрешённых. Эта история — в статье про права агента: Allow / Ask / Deny.

Контекст меняет не скорость написания кода, а то, насколько код соответствует задаче. А это и есть время до продакшена: меньше возвратов с ревью и исправлений после релиза.

Контекст делает решения проверяемыми

Есть эффект, который в таблицу не попал. В условии B агент объяснял свои шаги ссылками на документы. В пересказе с английского:

• «Добавляю флаг выкатки в config.py — по ADR-011: имя delivery_<code>, по умолчанию выключен».
• «Добавляю правило возврата — обязательно по INC-2025-031, а 6-й пункт требований говорит, что стоимость доставки не возвращается».

Каждое решение привязано к источнику. Ревьюер, который спросит «почему 99 рублей?», получит ответ ссылкой на требования. В условии A ответа нет: цена взялась из ниоткуда, и проверить её можно только у человека, который помнит договорённость.

Это и есть практический смысл формулы:

Relevant
  + Authorized
  + Task-specific
  → Context

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

Ограничения эксперимента

Чтобы не выдавать демонстрацию за исследование:

• 6 прогонов, один синтетический репозиторий, одна модель — claude-sonnet-5;
• проверки и пакет контекста писал я сам, и пакет идеально совпадает с проверками — в реальной компании документы будут неполными, противоречивыми и частично устаревшими;
• задача небольшая, на 5–9 минут работы агента, а приёмы вроде сжатия и заметок раскрываются на задачах длиннее.

Это демонстрация механизма, а не бенчмарк. Но механизм воспроизвёлся стабильно: если знания нет в контексте, агент его придумает.

CLAUDE.md — хорошее начало, но не всё

Первый шаг, который делают почти все, — файл с правилами проекта: CLAUDE.md у Claude Code, AGENTS.md и аналоги у других инструментов. Это правильный шаг. Из 8 документов нашего пакета часть — архитектура, слои, инженерные правила — меняется редко и нужна в каждой задаче; ей самое место в таком файле.

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

От ручного пакета к Context Platform

Главный подвох эксперимента: контекст для условия B собрал я. Руками. Нашёл требования, контракт, вспомнил решение про флаги и инцидент с экспрессом. Самую ценную работу — отбор — сделал человек, который знает систему.

Для одной задачи это полчаса. Для команды, где агенты берут десятки задач в день, это либо чья-то полная ставка, либо никто этого делать не будет — и тогда все возвращаются в условие A.

          TASK
            ↓
    CONTEXT PLATFORM
            ↓
  ┌──────────────────┐
  │ CODE             │
  │ ADR              │
  │ ARCHITECTURE     │
  │ API CONTRACTS    │
  │ REQUIREMENTS     │
  │ POLICIES         │
  │ INCIDENTS        │
  └──────────────────┘
            ↓
    RELEVANT CONTEXT
            ↓
      CODING AGENT
            ↓
   CODE → TEST → PR

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

Что делать

1. Возьмите одну недавнюю задачу, которую агент сделал неудачно, и выпишите, какого знания ему не хватило. Обычно это 2–3 документа.
2. Выберите 3 самых частых типа задач и соберите для каждого пакет контекста руками — как пакет выше: требования, контракт, решения, один-два инцидента.
3. Проверяйте пакет вопросом: что из этого агент иначе придумал бы сам? Всё, что он и так видит в коде, — лишнее.
4. Правила репозитория вынесите в CLAUDE.md или AGENTS.md, знание под задачу — нет.
5. Добавьте независимую приёмку по требованиям: только она покажет, что контекст сработал.
6. Автоматизируйте сбор после того, как станет понятно, из чего пакеты состоят.

Контекст — одна из шести частей платформы вокруг агента, наряду с моделью, инструментами, политиками, проверками качества и наблюдаемостью. Как они складываются вместе — в статье AI Development Platform.

Насколько ваша разработка готова к Coding Agents?

Пройдите бесплатный AI Engineering Assessment: вы получите профиль по семи измерениям, возможные ограничения и риски и шаги на 30 и 90 дней. Результат — сразу, без регистрации и контактов, ответы анонимны. Это ориентировочная диагностика, а не аудит.

Пройдите бесплатный AI Engineering Assessment

Источники

• Effective context engineering for AI agents — Anthropic, Engineering blog, 2025.
• Lost in the Middle: How Language Models Use Long Contexts — Liu et al. (Stanford, UC Berkeley, Samaya AI), 2023; TACL, 2024.
• Context Rot: How Increasing Input Tokens Impacts LLM Performance — Chroma, 2025.
• How Claude remembers your project — документация Claude Code, Anthropic, 2026.
• Эксперимент автора «От Coding Agent к AI Development Platform»: 6 прогонов Claude Code с моделью claude-sonnet-5 на синтетическом репозитории, сентябрь 2026.