Карта кодовой базы для AI-агентов — это локальный индекс файлов, символов, импортов, тестов и истории изменений репозитория, к которому агент может обращаться, чтобы находить нужный код за несколько вызовов, а не гонять grep и читать файл за файлом. Меньше прочитанных файлов — меньше в контекстном окне, а чем меньше в контекстном окне, тем дешевле каждый следующий ход.
В статье: почему агенты тратят токены на исследование, что должно быть в хорошей карте и как карта проекта AgentVera передаёт такой индекс по MCP Claude Code, Codex и другим CLI-агентам.
Как агенты исследуют репозиторий без карты
Дайте кодинг-агенту задачу вроде «добавь поле купона в оформление заказа» в незнакомом репозитории, и он сделает то же, что сделали бы вы с одним терминалом:
grep -r "checkout"и получает 200 совпадений- Открывает файлы, которые выглядят подходящими, часто целиком
- Идёт по импортам, читая новые файлы
- Снова ищет файл с тестами
Каждый шаг затягивает текст в контекст. Файл на 1000 строк, прочитанный один раз, остаётся в диалоге до конца сессии, а модель перечитывает диалог на каждом ходу. Если первые догадки были неверными, эти файлы всё равно лежат там. Это одна из главных причин, по которым сессия дорожает задолго до самого изменения. О другом крупном источнике, базовом контексте, читайте в статье как сократить расход токенов Claude Code.
Что содержит полезная карта кодовой базы
Списка файлов недостаточно. Агенту нужно отвечать на вопросы «где» и «что сломается, если я это изменю», не читая код. Хорошая карта хранит:
| Слой | На какой вопрос отвечает |
|---|---|
| Файлы и модули | Что есть в репозитории и как он устроен? |
| Символы с сигнатурами | Где applyCoupon и что она принимает? |
| Импорты | Кто использует этот файл и кто использует их? |
| Связанные тесты | Какие тесты покрывают этот код? |
| История совместных изменений | Какие файлы обычно меняются вместе с этим? |
| Точки входа и команда тестов | Откуда всё начинается и как запустить тесты? |
Два последних слоя важнее, чем кажется. История Git знает, что checkout.ts, checkout.test.ts и pricing.ts обычно меняются в одном коммите, даже если между ними нет импорта.
Как строится карта проекта AgentVera
AgentVera строит карту проекта для каждой папки проекта:
- Символы. tree-sitter читает функции, классы, методы, интерфейсы, типы, перечисления и константы с диапазонами строк, сигнатурами и первым предложением документирующего комментария для TypeScript, TSX, JavaScript, Python и Go. Ещё около 30 языков индексируются по путям.
- Импорты и тесты. Импорты разрешаются до файлов, а тесты связываются с кодом, который они покрывают.
- Совместные изменения. Связываются файлы, которые менялись вместе минимум в 2 из последних 500 коммитов. Коммиты, затрагивающие больше 40 файлов, игнорируются, чтобы крупное переименование не связало всё со всем.
- Что пропускается. Индексация начинается с
git ls-filesи учитывает.gitignore. Пропускаютсяnode_modules,dist,build, файлы больше 1 МБ и сгенерированные или минифицированные файлы. В репозиториях больше 20 000 файлов индексируются только папки с исходниками, такие какsrc,lib,appиpackages/*/src.
Карта строится на вашем компьютере и не тратит токены. Она следит за изменениями файлов, пересчитывает историю совместных изменений при появлении коммитов и перепроверяет файл, когда агент о нём спрашивает. Одна карта на папку общая для всех агентов, работающих в ней, поэтому у проекта и у каждого из его worktree своя карта. Она хранится в сжатом виде в папке данных приложения.
MCP-инструменты, которые использует агент
AgentVera добавляет каждому агенту MCP-сервер agentvera-map. Его инструкции говорят агенту начинать задачу с map_related, использовать map_outline перед чтением файла и map_usages перед изменением кода.
| Инструмент | Что возвращает |
|---|---|
map_related | Файлы, которых, вероятно, касается задача, в ранжированном виде с причинами (совпадение имени, импорты, совместные изменения, тесты) |
map_outline | Символы файла с диапазонами строк и сигнатурами, его импорты, импортёры и тесты |
map_usages | Кто вызывает или импортирует символ или файл; на глубине 2 импортёры импортёров, плюс покрывающие тесты |
map_find | Символы или файлы по нечёткому имени, с типом, file:line и сигнатурой |
map_overview | Модули, размеры, точки входа и команда тестов |
map_api | Реальный экспортируемый API установленного пакета в версии из node_modules, по его объявлениям типов |
map_related принимает задачу простыми словами, на любом языке. Турецкие слова вроде sepet, kupon или ödeme сопоставляются с английскими именами в коде: cart, coupon и payment.
map_api устраняет тихий источник багов: агент пишет вызовы по памяти для версии библиотеки, которой у вас нет. Он читает файлы .d.ts той версии, которая действительно установлена.
Новые агенты также получают в инструкциях краткую сводку модулей, точек входа и команды тестов, чтобы не тратить первые ходы на выяснение, как запускать тесты.
До и после: одна и та же задача
Вот как меняется задача с купоном. Шаги типичные, это не бенчмарк.
Без карты:
grep -rn "checkout" src # 200 lines of hits
cat src/checkout/index.ts # whole file
cat src/checkout/summary.tsx # whole file, not the right one
cat src/pricing/total.ts # whole file
grep -rn "total(" src test # find callers and testsС картой:
map_related "add a coupon field to checkout"
-> src/pricing/total.ts (name match, changed together with checkout)
-> src/checkout/CheckoutForm.tsx (imports total.ts)
-> test/pricing/total.test.ts (test)
map_outline src/pricing/total.ts # symbols and lines only
map_usages calculateTotal # callers and testsПосле этого агент читает только нужные строки. Первый вариант наполняет контекст ненужными файлами, второй — ранжированным списком и структурой файла.
Smart tools: когда агент всё равно читает
Агенты не всегда сначала спрашивают карту. Для Claude Code smart tools AgentVera вмешиваются через hooks:
- Первое полное чтение файла больше 800 строк и 24 КБ возвращает вместо этого структуру из карты проекта, чтобы агент мог прочитать нужную часть.
- Повторное чтение неизменившегося файла блокируется, поскольку содержимое уже в контексте.
- Запуск тестов сужается до тех, что важны.
Как hooks работают вообще, читайте в руководстве по hooks Claude Code.
Включение и выключение карты
Карта проекта включена по умолчанию и входит в бесплатный тариф.
- Откройте Settings → Token savings и найдите переключатель Project map. Он включён, если вы его не выключали.
- Чтобы оставить одного агента без карты, снимите флажок Project map в диалоге редактирования агента.
- Чтобы увидеть карту, откройте страницу Details проекта и вкладку Project map. Она рисует граф: импорты серым, связи совместных изменений пунктирными оранжевыми линиями. Введите задачу и нажмите Show, чтобы увидеть, что вернул бы
map_related.
Если карта ещё не готова, например сразу после открытия большого репозитория, инструменты отвечают ходом построения. Агент ждёт несколько секунд и затем переходит на обычные инструменты.
Правда ли это экономит токены?
Честный ответ: зависит от репозитория и задачи. В небольшом репозитории, где агент и так знает, куда смотреть, выигрыш невелик. В большом или незнакомом репозитории, где агент иначе прочитал бы десяток лишних файлов, выигрыш большой.
Вместо того чтобы верить цифре, измерьте на своей работе. На вкладке AI ROI есть карточка Project map impact, которая сравнивает диалоги с картой и без неё по успешности, прохождению с первого раза, токенам на задачу и доработкам.
Ограничения
- Детальные символы доступны для TypeScript, TSX, JavaScript, Python и Go. Другие языки индексируются на уровне путей.
- Агенты на удалённом SSH-хосте карту не получают.
- Агент читает только карту своей папки, поэтому агент в worktree видит свой worktree, а не основной checkout.
- Окно карты кода в обзоре проекта AgentVera — отдельная функция, чтобы вы сами исследовали код; карта проекта — это то, к чему обращаются агенты.
Итоги
Карта кодовой базы для AI-агентов заменяет слепое исследование через grep и чтение несколькими точными вопросами: какие файлы, какие символы, кто их использует и какие тесты их покрывают. Карта проекта AgentVera строит такой индекс локально через tree-sitter и git, поддерживает его актуальным и отдаёт каждому агенту с поддержкой MCP через agentvera-map, а smart tools перехватывают большие и повторные чтения в Claude Code. Дополните её общей памятью проекта, чтобы агенты знали и где находится код, и почему он такой, и скачайте AgentVera, чтобы попробовать на самом большом репозитории.