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

И здесь на достаточно большой кодовой базе быстро появляется проблема: расход токенов начинает расти гораздо быстрее, чем объём написанного кода.

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

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

Гораздо интереснее посмотреть на расход токенов как на задачу управления контекстом.

Если агенту заранее понятно, где находится нужная информация, какие правила относятся именно к текущей задаче и какие реализации считаются эталонными, ему не приходится каждый раз исследовать значительную часть проекта. И здесь начинают работать хорошо знакомые разработчикам принципы: lazy loading, локальность данных, кэширование, разделение ответственности и удаление устаревшей информации. Только применяем мы их не к приложению, а к контексту AI‑агента.

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

---

1. Minimize Permanent Context — минимизируйте постоянный контекст

Первая попытка помочь AI‑агенту обычно выглядит примерно одинаково. Мы создаём AGENTS.md, CLAUDE.md или другой файл с инструкциями и начинаем складывать туда всё больше проектных знаний. Сначала там появляется общая архитектура и структура репозитория. Затем — правила написания кода и conventions отдельных сервисов. Потом добавляются особенности работы с базой данных, тестированием, CI/CD и внешними интеграциями.

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

Допустим, в одном репозитории находятся:

/apps/web
/apps/mobile

/services/auth
/services/billing
/services/notifications

/packages/database
/packages/shared

/infrastructure

При изменении billing‑сервиса агенту вряд ли нужны правила разработки мобильного приложения. При создании database migration ему не обязательно знать conventions UI.

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

Например:

AGENTS.md

Project structure:
- apps/ — user-facing applications
- services/ — backend services
- packages/ — shared packages
- infrastructure/ — deployment and infrastructure
- docs/ — architecture documentation

Common commands:
- make test
- make lint
- make build

Detailed instructions:
- Auth: services/auth/AGENTS.md
- Billing: services/billing/AGENTS.md
- Database: packages/database/AGENTS.md
- Infrastructure: infrastructure/AGENTS.md

Корневой файл в таком случае отвечает прежде всего на вопрос:

Где находится нужная информация?

а не:

Что вообще можно рассказать об этом проекте?

Отсюда первый принцип: Permanent context should contain only information useful for most tasks.

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

---

2. Progressive Context — загружайте знания слоями

Если убрать подробные инструкции из глобального контекста, возникает очевидный вопрос: где их хранить?

Здесь хорошо работает принцип progressive disclosure — постепенного раскрытия информации.

Контекст можно представить как несколько уровней:

Global context
      ↓
Domain / Service context
      ↓
Task-specific instructions
      ↓
Reference implementation
      ↓
Relevant source code

Представим задачу:

Добавить новый payment provider.

Вместо загрузки документации всего проекта агент может пройти примерно такой путь:

AGENTS.md
   ↓
services/payments/AGENTS.md
   ↓
skills/add-payment-provider.md
   ↓
existing provider implementation
   ↓
relevant source files

Для задачи в мобильном приложении путь будет совершенно другим:

AGENTS.md
   ↓
apps/mobile/AGENTS.md
   ↓
feature-specific instructions
   ↓
existing screen
   ↓
relevant source files

А для инфраструктурной задачи:

AGENTS.md
   ↓
infrastructure/AGENTS.md
   ↓
deployment instructions
   ↓
reference service
   ↓
relevant configuration

Таким образом, агент получает знания по мере уменьшения области задачи.

Условно вместо:

everything about project        20 000 tokens

мы можем получить:

global context                    500
service context                   700
task instructions                 600
reference implementation         800
relevant source files           2500

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

Task‑specific instructions

Особенно удобно выносить отдельно повторяемые сценарии:

create-api-endpoint
add-database-migration
add-message-consumer
create-background-job
add-ui-page
add-integration-test
create-service

Некоторые AI называют подобные механизмы skills. В других системах это могут быть instruction files, commands или собственный механизм подключения контекста. Название здесь не так важно. Важна архитектурная идея: Don't load everything upfront. Load context when it becomes relevant. По сути это обычный lazy loading, только загружаем мы не модули или данные, а знания о проекте.

---

3. Reduce Exploration — помогите агенту меньше исследовать репозиторий

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

Представим запрос:

Добавить новый тип уведомления после успешной оплаты.

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

Where is payment handled?
        ↓
Which service publishes events?
        ↓
Which message broker is used?
        ↓
Where are consumers?
        ↓
How are notifications created?
        ↓
Where are templates?
        ↓
How are they tested?

Для этого агент начинает искать и читать файлы:

search
↓
read
↓
search
↓
read
↓
read
↓
search
...

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

Project Map

Даже короткая карта значительно уменьшает область поиска:

HTTP handlers:
services/*/handlers/

Business logic:
services/*/domain/

Database access:
services/*/repositories/

Message consumers:
services/*/consumers/

Shared schemas:
packages/schemas/

Infrastructure:
infrastructure/

Агенту уже не нужно самостоятельно выяснять базовую структуру приложения.

Golden Examples

Ещё эффективнее работают ссылки на эталонные реализации. Предположим, нужно добавить новый message consumer. Можно подробно описывать:

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

А можно указать:

For a new message consumer follow:

services/orders/consumers/order-created/

Одна хорошая реализация сразу показывает:

• структуру директорий;

• naming;

• обработку ошибок;

• logging / validation;

• взаимодействие с другими слоями;

• подход к тестированию.

Причём этот подход не зависит от типа разработки. Для разных задач golden examples могут выглядеть так:

REST endpoint:
services/users/handlers/create-user/

Database migration:
database/migrations/20261001_add_orders.sql

Background job:
workers/email/send-notification/

UI feature:
apps/web/features/profile/

Infrastructure service:
infrastructure/services/example/

Golden example часто оказывается компактнее нескольких страниц документации и одновременно уменьшает вероятность того, что AI изобретёт новый pattern там, где в проекте уже существует принятый.

Search Before Read

Ещё один полезный принцип:

find
↓
narrow
↓
read

вместо:

read
↓
read
↓
read
↓
understand
↓
find

Перед чтением большого файла можно сначала воспользоваться поиском:

rg "PaymentCompleted"
git grep "NotificationService"

или использовать symbol search, LSP, AST‑based search и другие инструменты навигации. Если нужен один метод из файла на 2000 строк, необязательно сразу помещать в контекст весь файл.

Git тоже является источником контекста

При работе с существующими изменениями можно начинать с:

git status
git diff --stat
git diff
git log
git show

Например, для code review git diff зачастую полезнее полного чтения каждого изменённого файла. Чем быстрее агент понимает, куда ему идти, тем меньше токенов он тратит на понимание структуры системы.

---

4. Reuse Knowledge — не платите дважды за одно исследование

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

HTTP request
      ↓
order service
      ↓
billing service
      ↓
payment provider
      ↓
payment event
      ↓
message broker
      ↓
order consumer

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

Отправлять уведомление после подтверждения оплаты.

И новый агент снова начинает:

search
↓
read
↓
search
↓
read
↓
read
...

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

docs/payment-flow.md

с коротким описанием:

Payment flow:

order-service
→ billing-service
→ payment provider
→ PaymentCompleted event
→ message broker
→ order-service consumer

Relevant files:
- services/billing/payments/
- services/billing/events/
- services/orders/consumers/payment-completed/

Reference implementation:
- services/billing/providers/example/

Следующая AI‑сессия сможет начать с нескольких сотен токенов структурированного описания вместо повторного чтения файлов. Полезные знания можно сохранять в разных формах:

AGENTS.md
service instructions
documentation
task-specific skill
architecture note
golden example
code comment

Выбор зависит от области действия знания. Если оно важно практически для любой задачи — возможно, ему место в глобальном контексте. Если относится только к одному сервису — рядом с этим сервисом. Если описывает повторяемый workflow — в task‑specific инструкции. Если существующий код уже отлично показывает необходимый подход — иногда достаточно просто сослаться на него. Получается простой цикл:

Expensive discovery
        ↓
Structured knowledge
        ↓
Cheap future retrieval

Отсюда следует четвёртый принцип: Expensive discovery should produce reusable knowledge. В этом смысле документация становится не только способом передачи знаний между разработчиками. Она превращается в своеобразный кэш контекста для AI. И чем чаще определённое знание требуется агентам, тем выгоднее один раз сделать его легко доступным.

---

5. Keep Context Clean — регулярно очищайте контекст

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

REST
RabbitMQ
PostgreSQL

Позже архитектура изменилась:

gRPC
Kafka
PostgreSQL

Но в документации всё ещё подробно описаны старые RabbitMQ consumers, migration plan и временные compatibility layers, которых уже нет. Для разработчика исторический контекст иногда может быть интересен. Для AI‑агента он способен стать источником ошибок. Теперь в контексте модели одновременно присутствуют:

old architecture
+
current architecture

И модели приходится самостоятельно определять, какая информация всё ещё актуальна. И это не только увеличивает расход токенов. Устаревшая инструкция может отправить агента искать уже удалённый файл. А старый архитектурный пример может заставить воспроизвести pattern, от которого команда давно отказалась.

Получается такая цепочка: stale context → wrong assumptions → unnecessary exploration → wrong changes.

Поэтому AI‑контекст стоит оптимизировать не только по размеру, но и по signal‑to‑noise ratio. Периодически его полезно проверять: удалять завершённые migration instructions и временные workaround, убирать deprecated архитектуру и старые команды, исправлять ссылки на несуществующие директории, заменять устаревшие reference implementations и избавляться от дублирующихся инструкций. Исторические подробности при этом не обязательно удалять совсем, их достаточно не держать в рабочем контексте агента, если они больше не влияют на текущую разработку.

Для проверки конкретного блока документации можно задать простой вопрос:

Will this information change how the agent should perform a task today?

Если ответ «нет», стоит задуматься, должна ли эта информация находиться в рабочем контексте AI. Здесь появляется важное различие. Документация для человека вполне может отвечать на вопрос:

Почему система стала такой?

Рабочая документация для AI‑агента прежде всего должна отвечать:

Как система устроена сейчас и как правильно её изменять?

Отсюда последний принцип: Correct information is not necessarily useful context.

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

---

Вместо заключения: контекст становится частью архитектуры проекта

Все пять паттернов можно собрать в одну последовательность:

                 AI coding task
                       │
                       ▼
              Minimal global context
                       │
                       ▼
             Relevant domain/service
                       │
                       ▼
             Task-specific context
                       │
                       ▼
              Golden example
                       │
                       ▼
              Targeted search
                       │
                       ▼
              Minimum source code
                       │
                       ▼
                    Change
                       │
                       ▼
              Valuable discovery?
                  │         │
                 No        Yes
                            │
                            ▼
                   Save as reusable
                       knowledge

Получается пять довольно простых правил.

1. Minimize Permanent Context. Не помещайте в постоянные инструкции информацию, которая нужна только небольшой части задач.

2. Progressive Context. Загружайте знания слоями: проект → домен или сервис → задача → эталонная реализация → исходный код.

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

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

5. Keep Context Clean. Удаляйте устаревшую и нерелевантную информацию, иначе накопленные знания сами превращаются в источник лишних токенов и ошибок.

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

В каком‑то смысле у современной кодовой базы появляется ещё один интерфейс — интерфейс между кодовой базой и AI‑агентом.

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

Поэтому главный принцип экономии токенов при работе с кодовой базой можно сформулировать так:

Не нужно просто заставлять AI читать меньше кода. Нужно помочь ему как можно раньше понять, какой код ему вообще не нужно читать.

Это становится ещё одной инженерной задачей при проектировании и разработки.

А чтобы можно было применить на практике, ф собрал небольшой open‑source шаблон AI Context. В нём есть базовая структура, построенная вокруг тех же пяти паттернов.

GitHub: https://github.com/usach87/ai‑context