Понимание кодовой базы

Зачем это отдельная тема

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

Отсюда же типичная жалоба «ассистент не видит, что у нас уже есть такой хелпер». В 90% случаев хелпер существует, но не попал в контекст: он лежит в модуле, который поиск не вернул, а агент не догадался туда заглянуть.

Три механизма контекста

Механизм	Как работает	Сильная сторона	Слабое место
Окно целиком	В запрос кладут файлы или документацию полностью	Максимальная точность, ничего не теряется	Дорого, ограничено размером окна
Поиск	grep, glob, поиск по символам, эмбеддинги фрагментов	Масштабируется на большой репозиторий	Промахи поиска не видны: нашлось «похожее», а не нужное
Структурированный контекст	AGENTS.md, README, архитектурные заметки, repo map	Дешёво, задаёт рамку и соглашения	Устаревает без сопровождения

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

Repo map и поиск по символам

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

• Repo map — компактная карта проекта: список файлов, классов, функций и их сигнатур без тел. Модель видит структуру целиком и сама просит открыть нужный файл. Так работает, например, Aider: карта строится по графу зависимостей и ранжируется относительно текущей задачи.
• Индекс символов — точный поиск по определениям и ссылкам (LSP, tree-sitter, SCIP). Он не «семантический»: он отвечает на вопрос «где объявлен этот метод и кто его вызывает», и для кода это часто важнее векторного сходства.

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

Где ломается

• Устаревший индекс. Код переименовали, индекс не обновился — агент правит несуществующий метод с уверенным видом.
• Неявные соглашения. DI-контейнеры, магические хуки, регистрация через конфиг: связь между файлами не видна статически, и агент её не находит.
• Монорепозитории. Границы сервисов и пакетов не выводятся из структуры папок; без карты зависимостей агент правит не тот пакет.
• Только «похожее». Retrieval возвращает 20 файлов, из которых релевантны три, а модель уверенно опирается на остальные.
• Отсутствие документации решений. Код отвечает «как», но не «почему». Агент предлагает решение, которое команда уже отвергла два года назад.

Что делать в проекте

1. Заведите AGENTS.md — короткий файл о том, как запускать сборку, тесты и линтеры, какие границы у модулей и чего делать нельзя. См. Контекст для агентов.
2. Фиксируйте архитектурные решения. Один абзац в docs/specs/ или ADR дешевле, чем десять объяснений в чате, и работает для всех инструментов сразу.
3. Держите имена честными. retryWithBackoff находит нужное в поиске; process2 — нет.
4. Проверяйте качество поиска отдельно. Если инструмент приносит не те файлы, никакая модель не поможет. Это задача RAG, просто на корпусе кода.
5. Следите за свежестью индекса. Для локальных индексов это вопрос настройки, для внешних — политики обновления.

Задачи, которые это закрывает

• Онбординг. «Объясни, как здесь проходит запрос от роутера до БД» — самый частый и самый полезный сценарий для нового человека в проекте.
• Поиск точки изменения. «Где формируется цена заказа» — с проверкой по цепочке вызовов, а не по одному совпадению.
• Анализ влияния. «Что сломается, если я поменяю сигнатуру этого метода» — ответ должен опираться на реальные вызовы, а не на догадку.
• Миграции. «Где ещё используется этот устаревший API» — здесь поиск по символам точнее любого ассистента.

Связанные материалы

• Генерация кода и структурные правки — что делать с найденным контекстом.
• Ассистенты и среды — какие продукты строят индекс, а какие ищут на лету.
• RAG и знания — та же механика поиска, но для документов.
• Контекст для агентов — файлы-контракты проекта.

Материалы и источники

• Aider: repo map — как строится и ранжируется карта репозитория
• Sourcegraph code intelligence и SCIP — индекс символов и перекрёстные ссылки
• Anthropic: Claude Code best practices — работа с контекстом и исследованием кодовой базы
• tree-sitter — парсинг кода для структурного поиска и правок