Файлы контекста

Файлы контекста​

Файлы контекста — это документы Markdown, которые вставляются между системным промптом и твоим вводом. Они дают агентам память о проекте без повторных объяснений: архитектуру, соглашения, команды сборки, ограничения.

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

AGENTS.md — стандарт​

На практике файл контекста — это AGENTS.md. Это отраслевой стандарт: обычный Markdown, который используют более 60 000 открытых проектов и развитием которого управляет Agentic AI Foundation при Linux Foundation. Большинство агентов для программирования читают его напрямую. Исключение — Claude Code: он обращается к AGENTS.md только тогда, когда в проекте нет отдельного файла контекста Claude.

Именно повсеместность делает этот файл столь мощным — и столь рискованным. AGENTS.md не ограничивается сессией, задачей или инструментом. Он попадает в фиксированный префикс каждого вызова, каждого агента, который работает с репозиторием, на любой задаче, у всех, кто впоследствии клонирует репозиторий. Измени одну строку — и сразу изменится поведение всех этих агентов, а тесты этого не заметят. Ни один файл исходного кода не имеет такого охвата.

Поскольку файл находится в префиксе, перед каждым запросом, его размер — общая цена, а не личная. Диаграмма выше показывает смещение в одном разговоре; общий AGENTS.md вызывает его во всех разговорах сразу. Каждый добавленный токен отодвигает запрос каждого участника дальше от начала и глубже в мёртвую середину окна. Раздутый файл не просто замедляет одного агента: он ухудшает работу всех, на каждой задаче, пока остаётся раздутым.

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

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

Как писать AGENTS.md​

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

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

Затем сокращай. Модели улучшаются, и правило, исправлявшее прошлогоднюю модель, может оказаться лишним для нынешней: модель уже усвоила его или оно защищает код, которого больше нет. Периодически перечитывай файл и удаляй всё, что больше не заслуживает места. AGENTS.md, который только растёт, — и есть то раздувание, о котором предупреждает диаграмма выше.

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