# Карта кодовой базы для AI-агентов: поиск без grep

URL: https://agentvera.dev/ru/blog/codebase-map-for-ai-agents/ · Опубликовано: 2026-10-24

Карта кодовой базы для AI-агентов: как локальный индекс файлов, символов, импортов и тестов помогает Claude Code и Codex быстрее находить код и читать меньше файлов.

**Коротко:**

- Агенты без карты исследуют код через grep и чтение файлов целиком. Каждый прочитанный файл попадает в контекстное окно и оплачивается заново на каждом следующем ходу.
- Карта проекта AgentVera индексирует файлы, символы, импорты, связанные тесты и файлы, которые меняются вместе; она строится локально через tree-sitter, поэтому не тратит токены.
- Агенты обращаются к ней по MCP: map_related для файлов, которых касается задача, map_outline перед чтением, map_usages перед изменением кода, map_api для реального API установленного пакета.

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

В статье: почему агенты тратят токены на исследование, что должно быть в хорошей карте и как карта проекта AgentVera передаёт такой индекс по MCP Claude Code, Codex и другим CLI-агентам.

## Как агенты исследуют репозиторий без карты

Дайте кодинг-агенту задачу вроде «добавь поле купона в оформление заказа» в незнакомом репозитории, и он сделает то же, что сделали бы вы с одним терминалом:

1. `grep -r "checkout"` и получает 200 совпадений
2. Открывает файлы, которые выглядят подходящими, часто целиком
3. Идёт по импортам, читая новые файлы
4. Снова ищет файл с тестами

Каждый шаг затягивает текст в контекст. Файл на 1000 строк, прочитанный один раз, остаётся в диалоге до конца сессии, а модель перечитывает диалог на каждом ходу. Если первые догадки были неверными, эти файлы всё равно лежат там. Это одна из главных причин, по которым сессия дорожает задолго до самого изменения. О другом крупном источнике, базовом контексте, читайте в статье [как сократить расход токенов Claude Code](/ru/blog/claude-code-token-usage/ "Как сократить расход токенов Claude Code на 61%").

## Что содержит полезная карта кодовой базы

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

| Слой | На какой вопрос отвечает |
| --- | --- |
| Файлы и модули | Что есть в репозитории и как он устроен? |
| Символы с сигнатурами | Где `applyCoupon` и что она принимает? |
| Импорты | Кто использует этот файл и кто использует их? |
| Связанные тесты | Какие тесты покрывают этот код? |
| История совместных изменений | Какие файлы обычно меняются вместе с этим? |
| Точки входа и команда тестов | Откуда всё начинается и как запустить тесты? |

Два последних слоя важнее, чем кажется. История Git знает, что `checkout.ts`, `checkout.test.ts` и `pricing.ts` обычно меняются в одном коммите, даже если между ними нет импорта.

## Как строится карта проекта AgentVera

AgentVera строит [карту проекта](/ru/features/project-map/ "Карта проекта") для каждой папки проекта:

- **Символы.** 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` той версии, которая действительно установлена.

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

## До и после: одна и та же задача

Вот как меняется задача с купоном. Шаги типичные, это не бенчмарк.

**Без карты:**

```text
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
```

**С картой:**

```text
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](/ru/features/smart-tools/ "Smart tools") AgentVera вмешиваются через hooks:

- Первое полное чтение файла больше 800 строк и 24 КБ возвращает вместо этого структуру из карты проекта, чтобы агент мог прочитать нужную часть.
- Повторное чтение неизменившегося файла блокируется, поскольку содержимое уже в контексте.
- Запуск тестов сужается до тех, что важны.

Как hooks работают вообще, читайте в [руководстве по hooks Claude Code](/ru/blog/claude-code-hooks-guide/ "Руководство по hooks Claude Code").

## Включение и выключение карты

Карта проекта включена по умолчанию и входит в бесплатный тариф.

1. Откройте **Settings → Token savings** и найдите переключатель **Project map**. Он включён, если вы его не выключали.
2. Чтобы оставить одного агента без карты, снимите флажок **Project map** в диалоге редактирования агента.
3. Чтобы увидеть карту, откройте страницу 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. Дополните её [общей памятью проекта](/ru/blog/shared-memory-for-ai-coding-agents/ "Общая память для AI-агентов"), чтобы агенты знали и где находится код, и почему он такой, и [скачайте AgentVera](/ru/download/), чтобы попробовать на самом большом репозитории.

## Частые вопросы

**Что такое карта кодовой базы для AI-агентов?** Индекс репозитория, к которому агент может обращаться вместо слепого поиска: какие файлы есть, какие символы в них определены, кто их импортирует, какие тесты их покрывают и какие файлы обычно меняются вместе.

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

**Какие языки понимает карта проекта AgentVera?** Символы она читает для TypeScript, TSX, JavaScript, Python и Go, с диапазонами строк, сигнатурами и первым предложением документирующего комментария. Ещё около 30 языков индексируются по путям.

**Тратит ли построение карты токены?** Нет. Карта строится на вашем компьютере через tree-sitter и git и обновляется по мере изменения файлов и появления коммитов. В контекст агента попадают только ответы на его запросы.

**Какие агенты могут использовать карту проекта?** Все CLI-агенты в AgentVera, которые принимают MCP-серверы: Claude Code, Codex, opencode, Copilot, Gemini и Cursor. Агенты на удалённом SSH-хосте её не получают.

---

**Об AgentVera.** AgentVera — настольное приложение для macOS, Windows и Linux от Solviera Teknoloji. Оно запускает 18 ИИ-агентов для программирования (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) рядом, по проектам, в настоящих терминалах с собственными установками CLI и входами пользователя. В бесплатном тарифе количество агентов не ограничено. Скачать: https://agentvera.dev/ru/download/ · Цены: https://agentvera.dev/ru/pricing/