Практика · навигация по коду

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

Карта кода вместо десятков MCP-инструментов для coding agent
Temporary fallback cover; replace in editorial pass.
Продвинутый уровень До 12 минут Без внешних сервисов
Самое важное из мира AI — в канале MAX AgentLabОтдельные разборы, инструменты и практические схемы Читайте Agent Lab в Telegram Разборы, кейсы и новости о практических AI-агентах без лишней воды.

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

Такой подход не отменяет grep, индексацию или MCP. Он меняет порядок действий: компактная карта помогает выбрать следующий файл, а полный текст используется для проверки гипотезы. В результате в контекст попадает не поток совпадений, а короткий маршрут по зависимостям.

Что именно измеряем

Сравним два сценария поиска одной и той же связи. Запрос сформулирован так: «найди путь от функции createInvoice до HTTP-обработчика и покажи места, где меняется объект платежа».

  1. Линейный поиск: несколько вызовов grep или rg, затем чтение найденных файлов.
  2. Навигация по карте: чтение индекса узлов и рёбер, выбор короткого пути, затем чтение только нужных диапазонов.

Измеряем не «умность» агента, а стоимость навигации: число команд, объём выведенного текста и приблизительный объём контекста. Последняя величина здесь является оценкой: делим число байт UTF-8 на четыре. Реальное токенизирование зависит от модели и языка.

Минимальная модель графа

Для первого прохода достаточно трёх типов данных:

Не стоит пытаться получить семантически совершенный граф одной регуляркой. Цель индекса — быстро сузить область поиска. Спорные связи помечайте как кандидаты и перепроверяйте чтением исходника.

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)

Полученные числа нельзя объявлять универсальным результатом. Они зависят от размера файлов, качества индекса, выбранных исключений и конкретного запроса. Их смысл — в сравнении двух подходов на одном репозитории и наборе задач.

Практический критерий успеха

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

  1. Возьмите 10–20 реальных задач навигации из истории изменений или списка дефектов.
  2. Для каждой задачи зафиксируйте стартовый символ, целевой символ и критерий достаточного доказательства.
  3. Случайно выберите порядок: сначала grep или сначала граф.
  4. Запишите команды, байты вывода, уникальные файлы и найденные рёбра.
  5. Сравните медиану, а не только среднее: один огромный файл может исказить результат.

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

Типовые ошибки

Индекс превращается в копию репозитория

Если в карту попадают тела функций, документация и большие сниппеты, преимущество исчезает. Храните в индексе координаты, тип связи и короткое доказательство; исходник открывайте только после выбора маршрута.

Регулярное выражение принимают за семантический анализ

Вызов через алиас, динамический импорт, реэкспорт или dependency injection может не совпасть с именем. Помечайте рёбра как «кандидат» и добавляйте confidence. Низкая уверенность должна запускать проверку файла, а не становиться фактом.

Не исключают generated и vendor-код

Сгенерированные файлы часто создают тысячи ложных совпадений. Используйте явные --glob '!path/**' и храните список исключений рядом с конфигурацией индекса.

Сравнивают разные правила остановки

Если grep-сценарий обязан доказать три связи, а графу достаточно назвать одну, измерение нечестно. До запуска эксперимента запишите одинаковый критерий готовности ответа.

Путают экономию контекста и экономию времени

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

Ограничения подхода

Граф не заменяет компилятор, language server и тесты. Он особенно слаб в динамических языках, метапрограммировании, рефлексии, генерации кода во время сборки и системах, где связь определяется конфигурацией.

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

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

Итог

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

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