AGENTS.md для Codex и Claude Code. Что писать в инструкции и что вынести в Skills

AI-агент может неплохо разобраться в коде и всё равно предложить решение, которое не подходит проекту.

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

Возможна и обратная ситуация. Агент меняет публичный API, не учитывая, что его используют сторонние разработчики.

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

Как работает AGENTS.md

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

Разница в том, что инструменты вроде Codex и Claude Code умеют находить такие файлы и использовать их содержимое как дополнительные инструкции для модели. Поэтому необходимые правила не приходится повторять в каждом запросе.

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

Например, структура проекта может выглядеть так.

MyApp/
├── AGENTS.md
├── Sources/
├── Features/
└── MyAppUI/
    └── AGENTS.md

Корневой файл описывает общие ограничения приложения, а вложенный содержит правила, относящиеся к MyAppUI.

Codex и Claude Code поддерживают AGENTS.md, но механизмы загрузки инструкций немного отличаются. Codex учитывает иерархию файлов относительно рабочего каталога. Claude Code также умеет работать с AGENTS.md, хотя в нём сохраняется поддержка собственного формата CLAUDE.md.

Если в проекте используются оба файла, стоит проверить настройки и правила их приоритета. Особенно если разработчики работают с разными AI-инструментами.

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

Получается довольно простой механизм. Мы заранее передаём агенту информацию о проекте, а он использует её вместе с текущим запросом и найденным кодом.

Остаётся решить, какую именно информацию стоит передавать.

Что писать в AGENTS.md

Современные coding agents уже умеют исследовать репозитории. Они могут открыть Package.swift, найти тесты, посмотреть зависимости и разобраться, как связаны основные компоненты.

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

Гораздо интереснее информация, которой в коде может вообще не быть.

Представим отдельный репозиторий MySDK. Это публичная Swift-библиотека, которую сторонние разработчики подключают через Swift Package Manager.

В таком случае AGENTS.md можно начать с нескольких строк.

# Project

MySDK is a public Swift SDK distributed
through Swift Package Manager.

Third-party applications depend on its public API.

## Constraints

- Preserve public API compatibility.
- Do not introduce breaking changes without approval.
- Keep the SDK independent of application-specific code.

Здесь нет ничего сложного. Но теперь при изменении публичного метода у агента есть причина задуматься о совместимости.

А если бы MySDK был внутренней библиотекой, правила могли оказаться другими.

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

Разумеется, это не относится ко всем внутренним библиотекам. Если у них десятки потребителей с независимыми релизами, требования могут быть почти такими же, как у публичного SDK.

Но именно подобные различия и хочется зафиксировать.

Агент способен увидеть, как написан метод. Гораздо сложнее самостоятельно понять, насколько свободно этот метод разрешено менять.

С архитектурой история похожая. Если в проекте действительно есть устойчивые ограничения, которые неочевидны из кода, их имеет смысл описать. А вот перечислять все классы, экраны и текущие зависимости вряд ли полезно.

Причём дело не только в размере файла.

Почему длинные инструкции могут мешать

С AGENTS.md легко повторить историю обычной проектной документации.

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

В итоге получается документ на несколько сотен строк.

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

И здесь интересно посмотреть на исследования.

В феврале 2026 года исследователи ETH Zürich опубликовали работу Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?

Они проверяли влияние репозиторных инструкций на работу coding agents. В исследованных условиях автоматически сгенерированные файлы немного ухудшали успешность выполнения задач, а написанные разработчиками давали лишь небольшое улучшение. При этом стоимость инференса увеличивалась примерно на 20% и более.

Агенты действительно следовали инструкциям, чаще исследовали код и выполняли дополнительные проверки. Но это не всегда приводило к лучшему результату.

В другой работе, On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, опубликованной в январе 2026 года, авторы сообщили о сокращении медианного времени выполнения задач на 28,64%.

Методики исследований различались, поэтому сравнивать эти результаты напрямую нельзя. Но они показывают, что польза AGENTS.md не так очевидна, как может показаться.

В январе 2026 года Matt Pocock тоже предложил пересмотреть содержимое AGENTS.md и CLAUDE.md. В частности, удалить противоречия, очевидные рекомендации и правила, которые не нужны агенту постоянно.

Сложно не согласиться, когда встречаются инструкции вроде этих.

## Guidelines

- Write clean code.
- Follow SOLID principles.
- Use meaningful names.
- Avoid bugs.

Всё написано правильно, но едва ли эти строки сообщают модели что-то полезное о конкретном проекте.

С другой стороны, полностью удалять проектный контекст я бы тоже не стал. Несколько строк о назначении репозитория и ограничениях его публичного API могут оказаться полезнее длинного набора общих рекомендаций.

Есть и ещё одна причина не увлекаться подробными инструкциями. Со временем они устаревают.

Представим, что мы описали в AGENTS.md архитектуру приложения, навигацию, основные экраны и расположение сервисов.

Через несколько месяцев часть модулей переписали, навигацию изменили, а некоторые компоненты вынесли в отдельный Swift Package.

Сам код уже другой, но файл с инструкциями остался прежним.

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

Особенно неприятно это в больших приложениях, где архитектура неоднородна. Один модуль написан на SwiftUI, другой использует UIKit, а третий сохранил собственный подход к навигации.

Если в корневом AGENTS.md объявить единую архитектуру для всего приложения, можно только добавить проблем.

Поэтому я бы предпочёл небольшие инструкции, которые не придётся переписывать после каждого рефакторинга.

Отдельные инструкции для модулей

Вернёмся к MyApp.

Допустим, приложение достаточно большое и содержит собственную библиотеку UI-компонентов MyAppUI.

MyApp/
├── AGENTS.md
├── App/
├── Features/
│   ├── Checkout/
│   └── Vouchers/
└── Packages/
    ├── MyAppUI/
    │   └── AGENTS.md
    └── MyAnalytics/
        └── AGENTS.md

В корневом AGENTS.md можно описать само приложение и несколько общих ограничений.

А внутри MyAppUI указать, что компоненты предназначены для повторного использования и не должны зависеть от конкретных экранов приложения.

# MyAppUI

This package contains reusable UI components
used across multiple application features.

## Constraints

- Keep components independent of feature-specific logic.
- Avoid dependencies on application navigation.
- Preserve existing component APIs unless a change is approved.

Для MyAnalytics ограничения будут другими. Например, модуль не должен зависеть от UI и содержать бизнес-логику отдельных фич.

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

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

С несколькими репозиториями ситуация похожая.

Допустим, отдельно существуют MyApp, MyAppUI и MySDK. У каждого своё назначение и ограничения, поэтому собственный AGENTS.md выглядит вполне логично.

Но если во всех трёх репозиториях используются одинаковые правила тестирования или рефакторинга, копировать их между файлами не хочется. Такие инструкции рано или поздно начнут расходиться.

И здесь мы подходим к Skills.

Что лучше вынести в Skills

Допустим, для Swift-проектов есть определённые требования к unit-тестам. Как организовывать фикстуры, использовать моки, проверять асинхронный код и работать со Swift Testing.

Всё это можно подробно расписать в AGENTS.md.

Но зачем агенту читать несколько страниц о тестировании, если текущая задача заключается в изменении небольшого UI-компонента?

Для таких случаев лучше подходят Skills.

.agents/
└── skills/
    ├── swift-testing/
    │   └── SKILL.md
    ├── api-compatibility/
    │   └── SKILL.md
    └── code-quality/
        └── SKILL.md

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

Это позволяет не держать все процедуры в постоянном контексте.

Например, в swift-testing можно описать принятый подход к тестированию. В code-quality собрать требования к читаемости кода, обработке ошибок и рефакторингу. А в api-compatibility оставить подробную процедуру проверки публичных интерфейсов.

Причём один и тот же Skill можно использовать в нескольких репозиториях, если инструмент и способ установки это позволяют.

Но есть важная граница между AGENTS.md и Skills.

Если репозиторий содержит публичный SDK, требование сохранять совместимость API должно быть известно агенту независимо от того, загрузил ли он Skill для проверки совместимости.

Поэтому само ограничение я бы оставил в AGENTS.md, а подробную процедуру его проверки вынес в Skill.

Это не идеальный механизм. Агент может не выбрать нужный Skill, а разные инструменты по-разному работают с их обнаружением и загрузкой. Но идея разделять постоянный контекст и подробные рабочие инструкции кажется мне разумной.

Кто должен писать AGENTS.md

Здесь возникает ещё один вопрос. Стоит ли поручать создание AGENTS.md самому агенту?

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

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

Допустим, в проекте много классов с суффиксом Manager. Модель может решить, что это принятое соглашение по именованию, и записать соответствующее правило.

Хотя команда, возможно, давно старается отказаться от таких названий.

То же касается singleton, архитектурных паттернов и организации модулей. Не всё, что есть в репозитории, стоит превращать в инструкцию для будущих изменений.

Поэтому AI вполне можно использовать для подготовки черновика. Например, попросить найти потенциально важные ограничения и показать, на каких файлах или документах основано каждое предложение.

Но окончательный текст я бы проверял и редактировал самостоятельно.

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

AGENTS.md имеет смысл дополнять тогда, когда ошибка повторяется и связана с устойчивой особенностью проекта, которую агенту действительно нужно знать заранее.

Выводы

AGENTS.md работает лучше всего, когда он короткий и описывает только назначение репозитория и ограничения, которых не видно в коде. Подробные процедуры лучше вынести в Skills, а черновик от AI обязательно проверить самому.

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

---

Полезные ссылки

• AGENTS.md и документация Codex. Формат и работа с проектными инструкциями.
• Claude Code Memory. Работа с AGENTS.md, CLAUDE.md и проектными инструкциями.
• Matt Pocock, январь 2026. Рекомендации по сокращению проектных инструкций.
• Evaluating AGENTS.md, февраль 2026. Исследование влияния инструкций на работу coding agents.
• On the Impact of AGENTS.md Files, январь 2026. Исследование эффективности AGENTS.md.
• Anthropic Agent Skills. Организация специализированных инструкций.