OpenCode AGENTS.md — текстовый файл в корне репозитория, куда команда записывает общие правила для кодового агента: структуру проекта, команды проверки и границы допустимых правок. OpenCode читает его при старте каждой сессии, поэтому правило, записанное один раз, действует на всех участников. Файл помогает, пока его держат короче одного экрана и проверяют на новой сессии, а соблюдение гарантируют разрешения и ревью.
Что пишут в файл
В AGENTS.md кладут то, что агент иначе вынужден угадывать: устройство проекта, команды сборки и тестов, соглашения по коду и список каталогов, где править нельзя.
Файл описывает репозиторий, а ролям и инструментам отдельных агентов посвящена статья про агентов OpenCode: роли, инструменты и передачу задачи. Здесь разговор о другом: об общей инструкции, которую читает любой агент в этом проекте. Повторяемые процедуры вроде подготовки релиза удобнее оформлять отдельными пакетами, как показано в материале про повторяемые процедуры команды.
- Архитектура в трёх-пяти строках: где лежит прикладной код, где тесты, где конфигурация.
- Команды проверки дословно: запуск тестов, линтера, сборки.
- Соглашения: стиль имён, принятые библиотеки, образец оформления нового модуля.
- Область действия: каталоги и файлы, которые агент читает, но правит только по прямой просьбе.
- Порядок завершения работы: что запустить и что сообщить в ответе.
Формулируйте правила утвердительно и конкретно. Запись «тесты запускаются командой pytest из корня» исполнима, а запись «следи за качеством» оставляет простор для толкований. Каждая строка должна отвечать на вопрос, который агент в противном случае задаст сам или решит за вас. Такой отбор сразу ограничивает объём файла.
Условный пример: репозиторий сервиса уведомлений на Python. В файле записано, что код лежит в папке app, тесты запускаются командой pytest, линтер называется ruff, а каталог migrations изменяется только вручную после согласования. Четыре строки закрывают большую часть угадываний.
Где лежит файл
По документации OpenCode, правила читаются из AGENTS.md в корне проекта и из глобального файла ~/.config/opencode/AGENTS.md. Первый общий для команды и живёт в Git, второй личный и действует во всех проектах разработчика. Совместимость с Claude Code сохранена: при отсутствии AGENTS.md подхватывается CLAUDE.md.
| Источник | Область действия | Кто владеет |
|---|---|---|
| AGENTS.md в корне проекта | Репозиторий и все его участники | Команда, правки через ревью |
| ~/.config/opencode/AGENTS.md | Все проекты одного разработчика | Сам разработчик |
| CLAUDE.md в проекте или ~/.claude/CLAUDE.md | Запасной вариант для пользователей Claude Code | Тот, кто его вёл раньше |
| Поле instructions в opencode.json | Дополнительные файлы и шаблоны путей | Команда, через конфигурацию |
Порядок поиска по документации такой: локальный AGENTS.md или CLAUDE.md, поднимаясь от текущего каталога вверх, затем глобальный файл, затем ~/.claude/CLAUDE.md. В каждой категории побеждает первое найденное, а AGENTS.md приоритетнее CLAUDE.md. Переменные OPENCODE_DISABLE_CLAUDE_CODE и родственные отключают чтение файлов Claude Code, если они мешают.
Чтобы узнать, какие файлы реально подхвачены, спросите агента в новой сессии, какие правила он видит и откуда они взяты. Ответ быстро выявляет опечатку в имени файла, неверный регистр букв или файл, лежащий в каталоге выше рабочего. Имя AGENTS.md пишется заглавными буквами, как в документации.
Для монорепозитория в opencode.json есть поле instructions: оно принимает шаблоны путей вроде packages/*/AGENTS.md и адреса URL, а ответ по адресу ждётся ограниченное время. Все найденные файлы объединяются с корневым AGENTS.md, поэтому противоречия между ними будут читаться агентом одновременно.
Общий файл коммитят в Git и меняют через запрос на слияние, как код: история показывает, когда и почему появилось правило. Личные пожелания разработчика, например язык пояснений в ответах, держат в глобальном файле, чтобы коллеги получали только общие правила.
Команда init
Команда /init просматривает репозиторий и создаёт AGENTS.md, выделяя команды сборки, архитектурные приёмы и соглашения. Если файл уже есть, по документации /init улучшает его на месте и сохраняет прежние записи. Это удобная заготовка, но до готового правила ей далеко: сгенерированный текст нужно прочитать и сократить.
Проверьте заготовку по трём признакам. Каждая команда запускается так, как записана. Каждое утверждение об архитектуре подтверждается структурой папок. Пункты свободны от очевидного: фраза «пишите чистый код» пуста для агента, поэтому её удаляют. Оставьте то, что отличает проект от типового.
Ссылку на другой файл внутри AGENTS.md OpenCode читает как обычный текст, а загрузка самого файла требует отдельной инструкции. Если подробный регламент лежит в отдельном документе, напишите в AGENTS.md прямую инструкцию: читать такой-то файл, когда задача касается такой-то области. Так большой документ подгружается по требованию и перестаёт раздувать каждый запрос.
Какие правила вашего репозитория живут только в головах разработчиков?
Проверка на новой сессии
- Откройте новую сессию OpenCode в корне репозитория, чтобы прежние диалоги оставались вне контекста.
- Задайте вопросы на знание: какими командами проверяется проект, где лежит прикладной код, какие каталоги закрыты для правок. Сравните ответы с файлом.
- Дайте задачу, где правило должно сработать: например, поправить поле в файле каталога migrations. Корректный ответ агента — вопрос или отказ со ссылкой на правило.
- Дайте обычную задачу и по завершении убедитесь, что агент запустил команды проверки из файла.
- Отметьте расхождения и поправьте формулировку правила, а затем повторите ту же проверку.
Ответ на вопросы подтверждает лишь одно: файл прочитан. Соблюдение проверяется поведением на задачах, где правило мешает. Если агент нарушил запрет, сначала усильте и сократите формулировку, а при повторе вынесите защиту из текста в настройки: разрешения на действия задаются конфигурацией, как показано в разборе OpenCode CLI и контроля прав.
Принцип простой: AGENTS.md сообщает агенту, чего хочет команда, а запрет на уровне прав гарантирует исполнение. Поэтому критичные ограничения, вроде каталога с миграциями, дублируйте и в тексте, и в разрешениях, и в ревью.
Результат проверки зависит от модели. Если команда переключилась на другую модель или обновилась версия OpenCode, пройдите те же пять шагов заново: одна и та же инструкция читается двумя моделями по-разному, и запрет, который держался вчера, сегодня способен потеряться среди других строк.
Поддержка файла
Файл устаревает вместе с проектом. Закрепите правило: изменение команды сборки, структуры папок или соглашения сопровождается правкой AGENTS.md в том же запросе на слияние. Ревьюер проверяет это наравне с тестами. Периодически прогоняйте проверку на новой сессии, особенно после крупных рефакторингов.
Держите файл коротким. Чем длиннее инструкция, тем выше шанс, что важное правило затеряется среди второстепенных, а каждая строка расходует контекст при каждом запуске. Правила, нужные лишь для отдельных задач, выносите в отдельные документы и подключайте по требованию, как описано выше. Личные предпочтения разработчика вроде любимого формата ответа живут в глобальном файле, а в общий их тянуть нельзя.
Новому разработчику файл служит коротким введением в проект: прочитав его, он знает, как запускать проверки и какие каталоги закрыты, ещё до первого обращения к коллегам. Если эти сведения приходится пересказывать устно, значит, они пока отсутствуют в файле и пора их туда внести.
Запустите /init в тестовой ветке, сократите результат до одного экрана и пройдите пять шагов проверки на новой сессии. Затем покажите файл тому, кто отвечает за репозиторий. Нужна единая политика правил и прав для нескольких репозиториев? Обсудите с нами внедрение ИИ-агентов, состав работ определим после разбора вашей кодовой базы.