Практика · навигация по коду
Карта кода вместо десятков MCP-инструментов для coding agent

В большом репозитории агенту редко нужно сразу читать весь файл. Обычно ему нужно ответить на более узкий вопрос: кто вызывает функцию, какие модули зависят от интерфейса и где меняется значение. Для этого полезнее сначала построить граф репозитория, а уже потом открывать несколько подтверждающих фрагментов.
Такой подход не отменяет grep, индексацию или MCP. Он меняет порядок действий: компактная карта помогает выбрать следующий файл, а полный текст используется для проверки гипотезы. В результате в контекст попадает не поток совпадений, а короткий маршрут по зависимостям.
Что именно измеряем
Сравним два сценария поиска одной и той же связи. Запрос сформулирован так: «найди путь от функции createInvoice до HTTP-обработчика и покажи места, где меняется объект платежа».
- Линейный поиск: несколько вызовов
grepилиrg, затем чтение найденных файлов. - Навигация по карте: чтение индекса узлов и рёбер, выбор короткого пути, затем чтение только нужных диапазонов.
Измеряем не «умность» агента, а стоимость навигации: число команд, объём выведенного текста и приблизительный объём контекста. Последняя величина здесь является оценкой: делим число байт UTF-8 на четыре. Реальное токенизирование зависит от модели и языка.
Минимальная модель графа
Для первого прохода достаточно трёх типов данных:
node— файл, функция или класс с координатой;edge— связь «вызывает», «импортирует» или «реализует»;evidence— строка и короткий фрагмент, подтверждающие связь.
Не стоит пытаться получить семантически совершенный граф одной регуляркой. Цель индекса — быстро сузить область поиска. Спорные связи помечайте как кандидаты и перепроверяйте чтением исходника.
nodes.tsv:
kind id file line name
fn src/billing/invoice.ts:12 src/billing/invoice.ts 12 createInvoice
fn src/billing/payment.ts:31 src/billing/payment.ts 31 createPayment
route src/http/billing.ts:18 src/http/billing.ts 18 POST /billing
edges.tsv:
from relation to
src/http/billing.ts:18 calls src/billing/invoice.ts:12
src/billing/invoice.ts:12 calls src/billing/payment.ts:31
Воспроизводимый сценарий построения карты
Ниже — безопасный пример для Unix-подобной среды. Команды только читают рабочее дерево и создают файлы в отдельном каталоге .agent-map. Перед запуском замените REPO на путь к копии репозитория или текущего проекта.
1. Подготовьте каталог результатов
set -eu
REPO="${REPO:-.}"
OUT="${OUT:-.agent-map}"
mkdir -p "$OUT"
: > "$OUT/nodes.tsv"
: > "$OUT/candidates.tsv"
Переменная OUT намеренно указывает на узкий каталог. Не направляйте вывод в системные директории и не запускайте команды с удалением файлов.
2. Соберите кандидатов на определения
Этот вариант рассчитан на TypeScript и JavaScript. Он ищет распространённые формы объявлений, но не является полноценным парсером.
rg -n --no-heading \
--glob '*.ts' --glob '*.tsx' --glob '*.js' --glob '*.jsx' \
'(^|[[:space:]])(export[[:space:]]+)?(async[[:space:]]+)?function[[:space:]]+[A-Za-z_$][A-Za-z0-9_$]*|(^|[[:space:]])(export[[:space:]]+)?(const|let)[[:space:]]+[A-Za-z_$][A-Za-z0-9_$]*[[:space:]]*=' \
"$REPO" \
> "$OUT/function-definitions.txt"
Если в репозитории есть сгенерированные файлы, vendor-каталоги или большие фикстуры, добавьте исключения:
rg -n --no-heading \
--glob '*.ts' --glob '*.tsx' \
--glob '!node_modules/**' \
--glob '!dist/**' \
--glob '!coverage/**' \
'createInvoice|createPayment' \
"$REPO" \
> "$OUT/target-search.txt"
3. Сформируйте индекс символов
Для практической навигации удобно хранить файл, строку и имя символа. Если в проекте уже есть LSP-индекс, tree-sitter или ctags, используйте его как источник узлов. Ниже — упрощённый TSV-формат, который можно заполнить из существующего вывода инструмента.
printf '%s\n' \
$'fn\tsrc/billing/invoice.ts:12\tsrc/billing/invoice.ts\t12\tcreateInvoice' \
$'fn\tsrc/billing/payment.ts:31\tsrc/billing/payment.ts\t31\tcreatePayment' \
$'route\tsrc/http/billing.ts:18\tsrc/http/billing.ts\t18\tPOST /billing' \
> "$OUT/nodes.tsv"
Это данные примера, а не утверждение о структуре конкретного проекта. В реальной сборке строки должны поступать из проверяемого индекса.
4. Извлеките кандидатов на вызовы
rg -n --no-heading \
--glob '*.ts' --glob '*.tsx' --glob '*.js' --glob '*.jsx' \
--glob '!node_modules/**' \
--glob '!dist/**' \
'createInvoice[[:space:]]*\(' \
"$REPO" \
> "$OUT/create-invoice-calls.txt"
rg -n --no-heading \
--glob '*.ts' --glob '*.tsx' --glob '*.js' --glob '*.jsx' \
--glob '!node_modules/**' \
'createPayment[[:space:]]*\(' \
"$REPO" \
> "$OUT/create-payment-calls.txt"
Далее агент или небольшой скрипт сопоставляет найденный файл с узлом и записывает ребро. Важно сохранять исходную строку как доказательство:
printf '%s\n' \
$'src/http/billing.ts:18\tcalls\tsrc/billing/invoice.ts:12\t18' \
$'src/billing/invoice.ts:12\tcalls\tsrc/billing/payment.ts:31\t27' \
> "$OUT/edges.tsv"
5. Найдите маршрут между узлами
Для небольшого TSV можно использовать Python только для чтения локальных файлов и обхода рёбер. Скрипт не исполняет код репозитория:
python3 - "$OUT/edges.tsv" <<'PY'
import collections
import sys
edges = collections.defaultdict(list)
with open(sys.argv[1], encoding="utf-8") as stream:
for line in stream:
parts = line.rstrip("\n").split("\t")
if len(parts) >= 3:
source, relation, target = parts[:3]
edges[source].append((target, relation))
start = "src/http/billing.ts:18"
goal = "src/billing/payment.ts:31"
queue = collections.deque([(start, [start])])
seen = {start}
while queue:
current, path = queue.popleft()
if current == goal:
print("\n".join(path))
break
for target, _relation in edges[current]:
if target not in seen:
seen.add(target)
queue.append((target, path + [target]))
else:
print("path not found")
PY
В production-индексе вместо координаты файла можно использовать стабильный идентификатор символа: имя модуля, qualified name и хэш сигнатуры. Это уменьшает число ложных совпадений при одинаковых именах функций.
Как сравнить карту с grep и чтением файлов
Сравнение должно быть одинаковым по задаче и правилам остановки. Например, агент останавливается, когда может назвать цепочку вызовов и показать по одному подтверждающему фрагменту на каждое ребро.
Метрики
| Метрика | Как считать | Зачем нужна |
|---|---|---|
| Команды | Число команд поиска и чтения | Показывает операционную стоимость |
| Вывод | wc -c для всех переданных фрагментов |
Приближает размер контекста |
| Открытые файлы | Уникальные пути в ответе | Показывает ширину разведки |
| Доказанные рёбра | Число связей с файлом и строкой | Проверяет полноту результата |
| Ложные кандидаты | Совпадения, исключённые после чтения | Показывает шум индекса |
Запустите одинаковые прогоны
Сначала сохраните вывод линейного поиска:
/usr/bin/time -v sh -c '
rg -n --glob "*.ts" --glob "*.tsx" "createInvoice" src
rg -n --glob "*.ts" --glob "*.tsx" "createPayment" src
sed -n "1,180p" src/http/billing.ts
sed -n "1,180p" src/billing/invoice.ts
sed -n "1,120p" src/billing/payment.ts
' > .agent-map/grep-run.txt 2> .agent-map/grep-time.txt
wc -c .agent-map/grep-run.txt
Затем сохраните вывод сценария с картой:
/usr/bin/time -v sh -c '
sed -n "1,120p" .agent-map/nodes.tsv
sed -n "1,120p" .agent-map/edges.tsv
python3 - .agent-map/edges.tsv < /dev/null
sed -n "1,80p" src/http/billing.ts
sed -n "1,100p" src/billing/invoice.ts
sed -n "1,80p" src/billing/payment.ts
' > .agent-map/graph-run.txt 2> .agent-map/graph-time.txt
wc -c .agent-map/graph-run.txt
Последняя команда в примере лишь показывает место, где запускается обход; подставьте в неё ваш валидный запрос маршрута. Для оценки токенов используйте одну и ту же формулу:
awk '{ total += $1 } END { printf "approx_tokens=%.0f\n", total / 4 }' \
< <(wc -c .agent-map/grep-run.txt .agent-map/graph-run.txt)
Полученные числа нельзя объявлять универсальным результатом. Они зависят от размера файлов, качества индекса, выбранных исключений и конкретного запроса. Их смысл — в сравнении двух подходов на одном репозитории и наборе задач.
Практический критерий успеха
Карта полезна, если она снижает объём первичной разведки, не скрывая неопределённость. Введите простой протокол из пяти шагов:
- Возьмите 10–20 реальных задач навигации из истории изменений или списка дефектов.
- Для каждой задачи зафиксируйте стартовый символ, целевой символ и критерий достаточного доказательства.
- Случайно выберите порядок: сначала grep или сначала граф.
- Запишите команды, байты вывода, уникальные файлы и найденные рёбра.
- Сравните медиану, а не только среднее: один огромный файл может исказить результат.
Основная метрика для контекстного бюджета — байты или токены до первого корректного маршрута. Вторая по важности — доля задач, где граф привёл к правильным файлам без дополнительных широких поисков.
Типовые ошибки
Индекс превращается в копию репозитория
Если в карту попадают тела функций, документация и большие сниппеты, преимущество исчезает. Храните в индексе координаты, тип связи и короткое доказательство; исходник открывайте только после выбора маршрута.
Регулярное выражение принимают за семантический анализ
Вызов через алиас, динамический импорт, реэкспорт или dependency injection может не совпасть с именем. Помечайте рёбра как «кандидат» и добавляйте confidence. Низкая уверенность должна запускать проверку файла, а не становиться фактом.
Не исключают generated и vendor-код
Сгенерированные файлы часто создают тысячи ложных совпадений. Используйте явные --glob '!path/**' и храните список исключений рядом с конфигурацией индекса.
Сравнивают разные правила остановки
Если grep-сценарий обязан доказать три связи, а графу достаточно назвать одну, измерение нечестно. До запуска эксперимента запишите одинаковый критерий готовности ответа.
Путают экономию контекста и экономию времени
Граф может уменьшить текст в контексте, но потребовать предварительной индексации. Измеряйте отдельно стоимость обновления карты и стоимость запроса. Для часто меняющегося монорепозитория инкрементальное обновление важнее полной пересборки.
Ограничения подхода
Граф не заменяет компилятор, language server и тесты. Он особенно слаб в динамических языках, метапрограммировании, рефлексии, генерации кода во время сборки и системах, где связь определяется конфигурацией.
Не следует давать агенту безоговорочное право менять код только на основании ребра из индекса. Карта отвечает на вопрос «куда смотреть дальше», а не «какое поведение гарантировано». Гарантией остаются исходник, типы, тесты и проверка результата.
Наконец, граф может быть устаревшим. Добавляйте к индексу версию коммита или хэш набора файлов и проверяйте её перед использованием. Если карта старше текущего состояния, агент должен явно сообщить об этом и перейти к локальной проверке.
Итог
Для coding agent полезна не коллекция из десятков узких инструментов, а компактный навигационный слой: узлы, рёбра, координаты и уровень уверенности. Он сокращает число широких поисков и помогает читать только те файлы, которые подтверждают конкретный маршрут.
Начните с TSV-индекса и измерения байтов вывода. Если на ваших задачах граф стабильно уменьшает первичный контекст при сохранении числа доказанных связей, его можно подключать к MCP как один инструмент навигации — с понятными командами обновления и проверкой актуальности.