Документ и указатель: правило, которое загружается по требованию

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

В Cadence у изменения схемы БД есть скрытый второй шаг. Поменяли таблицу или колонку в app/db/schema.ts — обновите и scripts/seed.ts, скрипт, который заполняет базу стартовыми данными. Забыли — после следующего reseed данные не совпадут со схемой, и ошибка всплывёт где-то ниже. Ещё одна деталь: база в проекте одноразовая, она лежит в data.db, игнорируется git и содержит только seed-данные, поэтому её можно смело пересоздавать.

Из кода этого не вывести, значит, агенту нужно сказать. Первое желание — дописать все шаги в CLAUDE.md. Но тогда каждый запрос каждой сессии несёт процедуру миграции, даже когда агент правит вёрстку и базы не касается. Десять таких процедур — и файл инструкций становится главным потребителем контекста.

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

Доступна из любого запроса

Процедура миграции не нужна в каждом запросе. Она нужна так, чтобы до неё можно было дойти из любого запроса. Это разные требования, и паттерн «документ плюс указатель» закрывает второе:

1. Шаги переезжают в отдельный документ, например docs/database-migrations.md. Документ живёт сам по себе: над ним больше нет файла инструкций, поэтому заголовки поднимаются на уровень выше.
2. В CLAUDE.md или AGENTS.md на их месте остаётся одна строка:

When you change the database schema, read `docs/database-migrations.md` first and follow its steps.

Context load сжимается до одного предложения. Полный текст попадёт в контекст, только когда агент поймёт, что меняет схему, и откроет файл.

Из чего состоит указатель

У context pointer две части, и важны обе:

• Стабильный путь. Агент должен знать, где лежит материал.
• Условие. Агент должен понять, когда стоит переходить по ссылке. Голый путь — указатель, по которому у агента нет причины идти. Формулируйте условие так, как задача выглядит в работе: «когда меняешь схему БД», а не «см. документацию по миграциям».

Именно текст условия попадает в контекст каждой сессии, поэтому он должен быть коротким и точным. Слишком узкое условие («перед правкой вот этого файла») пропустит часть случаев. Чуть более широкое («при любом изменении базы данных») надёжнее, и его проще читать.

Указатель — это не @-импорт

В CLAUDE.md есть синтаксис @path/to/file. Он похож на указатель, но работает наоборот: импортированный файл разворачивается и загружается в контекст при старте вместе с CLAUDE.md. Документация Claude Code прямо предупреждает: импорты помогают организовать длинный файл, но не снижают его цену в контексте. Чтобы путь остался указателем, пишите его в обратных кавычках, как в примере выше: `docs/database-migrations.md` внутри code span не импортируется.

Практика

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

Move the database migration steps from AGENTS.md into docs/database-migrations.md.
Leave one line in AGENTS.md that says when to read that document.

Прочитайте получившуюся строку-указатель. Ответьте себе на два вопроса: виден ли путь и понятно ли из условия, в какой задаче агент должен его открыть. Если условие описывает файл, а не задачу, перепишите его. Затем выполните /clear, попросите агента о небольшом изменении схемы и откройте transcript viewer клавишей Ctrl+O: среди вызовов инструментов должно быть чтение docs/database-migrations.md.

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

• Указатель без условия. Строка «Docs: docs/database-migrations.md» ничего не говорит о том, когда открывать документ, и агент легко пройдёт мимо.
• @ вместо обратных кавычек. @docs/database-migrations.md вне code span — это импорт: документ снова грузится в каждую сессию, и экономии нет.

Вывод: держите в файле инструкций условие и путь, а саму процедуру — в документе, который агент откроет, когда задача совпадёт с условием.

Проверь себя

Источники

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