Навигационные указатели: короткий путь к важному файлу

Зачем это нужно

Миграции в Cadence продолжают ломаться по одной причине: агент меняет схему и не трогает scripts/seed.ts. Файл важный, но при поиске агент на него не выходит. Он идёт по проекту «просёлочными дорогами»: просматривает директории, открывает файлы по одному, проходит по цепочкам импортов. Рано или поздно он доберётся, но каждый открытый по пути файл ложится в контекст и тратит токены, которые нужны для самой задачи.

Можно построить «шоссе» — одну строку, которая отправляет агента прямо к нужному месту.

Как это устроено

Что такое навигационный указатель

Навигационный указатель — короткая строка в CLAUDE.md или AGENTS.md, которая ведёт агента к важной части кода без поиска. Это тот же context pointer, но с другой задачей: он говорит не что делать, а где смотреть. Для Cadence это одна строка:

## Navigation

- `scripts/seed.ts` - the database's starting data, rebuilt from scratch on every `npm run db:seed`. Every schema change lands here too.

Вторая половина строки — триггер. Агент, который правит схему, читает «every schema change lands here too» и сам идёт в seed-скрипт, без всякого skill.

Документация Claude Code советует то же: писать проверяемые инструкции вроде «API handlers live in src/api/handlers/», а не «держи файлы в порядке».

Где шоссе нужны, а где нет

Шоссе ко всему строить не нужно: это значит вытащить в контекст всё дерево файлов. Указатель окупается, если файл:

• трудно найти поиском;
• обязательно нужно менять при решении задачи;
• входит в неочевидный процесс — например, «новый skill в этой папке требует записи ещё в трёх местах».

Остальное агент найдёт сам: «шоссе» доводит до места, а последний участок он проходит обычными дорогами.

Тот же механизм на один turn

Внутри одного промпта роль указателя играет @. Напишите @scripts/seed.ts в сообщении, и Claude Code включит содержимое файла в разговор, не дожидаясь, пока агент его прочитает. Заодно в контекст попадут CLAUDE.md из директории этого файла и директорий выше.

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

Практика

В Cadence задайте агенту вопрос, ответ на который лежит в seed-скрипте:

Which courses exist in the starting data of this project?

Нажмите Ctrl+O и посчитайте, сколько файлов агент открыл, прежде чем дошёл до scripts/seed.ts. Выполните /clear, добавьте в файл инструкций навигационный указатель из примера выше и задайте тот же вопрос. Сравните путь: агент должен пойти к файлу сразу. Наберите @ в поле ввода: появится меню с подсказками путей. Так вы направите агента к файлу на один turn.

Подводные камни

• Устаревший указатель молчит. Вы перенесли файл и забыли поправить строку в AGENTS.md. Ничего не упадёт, сборка зелёная, предупреждений нет. Агент доверяет указателю, идёт по старому пути и тратит токены, выясняя, куда пропал файл. Устаревшее шоссе хуже, чем никакое, потому что агент ему верит. Меняете структуру проекта — проверяйте навигационные указатели. Найти ссылки на несуществующие файлы поможет /doctor prompt-audit.
• Указатель на всё подряд. Чем больше указателей, тем больше строк нужно поддерживать при каждом рефакторинге. Оставляйте только те, без которых агент промахивается.

Вывод: строка-указатель на файл, который трудно найти, но обязательно нужно менять, экономит агенту поиск, если вы обновляете её вместе со структурой проекта.

Проверь себя

Источники

• Anthropic, How Claude remembers your project
• Anthropic, Common workflows
• Anthropic, Interactive mode
• По мотивам AI Coding Crash Course, AI Hero