OpenCode объединяет найденные AGENTS.md, но не устраняет противоречия между ними. Поэтому проверьте отдельно, какие файлы получил агент и выполнил ли он их правила. Для проверки корневого и вложенного AGENTS.md создайте тестовый проект.
Навык, который я написал под маркетинговые задачи, после смены модели вдруг начинает отрабатывать по-другому. Текст инструкции тот же, результат другой.
Сначала задайте образ результата: какое правило должно сработать и как это увидеть в ответе. Затем выстраиваем проверку.
AGENTS.md - инструктаж проекта
Это как инструктаж для вашего сотрудника. В AGENTS.md OpenCode получает команды сборки и проверок, заметки об архитектуре, соглашения о коде.
Файл обнаружен → текст добавлен в контекст → модель выполнила правило. Проверяйте по порядку: путь файла, отметку о его подключении, ответ модели. Удачный ответ ещё не объясняет, откуда взялось правило.
Не путайте AGENTS.md с .opencode/agents/<name>.md: это профиль отдельного агента с системным запросом, моделью и разрешениями. Сам AGENTS.md проверяющего не создаёт.
Если вам нужен отдельный проверяющий, его настройку я разбираю в отдельной статье.
Текст «не редактируй файлы» технического запрета не даёт. Для ограничения действий проверьте разрешения инструментов выбранного агента.
Что писать в AGENTS.md, разобрано в отдельной статье.
Проверили инструкцию - расскажите в канале, какой результат получился:
Где OpenCode ищет корневые и вложенные AGENTS.md
Workspace - рабочий каталог текущей сессии. От него зависит начальная загрузка инструкций.
Порядок загрузки и ожидаемые результаты проверок взяты из документации OpenCode, проверенной 19 ноября 2026. Сверьте их со своей сборкой.
| Файл или настройка | Где ищется | Когда добавляется |
|---|---|---|
| Глобальный файл | ~/.config/opencode/AGENTS.md | Первым среди AGENTS.md |
| От workspace вверх | Внутри домашнего каталога - до него; вне домашнего - до корня проекта | При старте, все найденные |
| Ниже workspace | Между исследуемой целью и workspace | При чтении файла или перечислении каталога в этой области |
instructions | Файлы, маски, HTTP(S)-адреса; относительные записи - от workspace до корня проекта | После AGENTS.md, в порядке списка; уже добавленные указания сохраняются |
Например, сессия открыта в ~/code/my-project/packages/web. Тексты объединяются в таком порядке:
~/.config/opencode/AGENTS.md
packages/web/AGENTS.md
packages/AGENTS.md
AGENTS.mdПорядок в этом списке не определяет, какое правило модель выполнит при противоречии. Если workspace находится вне проекта, загружается только глобальный файл.
Общие проектные указания храните в корне репозитория, узкие - рядом с кодом. Проектные файлы правил добавляйте в Git для команды; личный глобальный файл оставьте вне репозитория.
В каталоге без AGENTS.md OpenCode читает CLAUDE.md. Если есть оба, выбирает AGENTS.md. Без глобального AGENTS.md используется ~/.claude/CLAUDE.md. Это выбор файла внутри каталога, а не приоритет правил из разных каталогов.
Что написать в правилах и как получить черновик через /init
Прежде чем писать агенту подробную инструкцию, дайте ему выполнить вашу задачу. Посмотрите, что пришлось исправить. И эти исправления вы и записываете в навык, чтобы в следующий раз не объяснять то же самое.
Этот принцип работы с навыками подходит и для отбора проектных указаний. Записывайте проверенный порядок действий. Цены, акции и условия агент каждый раз берёт из актуальных документов.
Для черновика:
- Запустите
opencodeиз каталога проекта. - Наберите
/, проверьте наличие/initв списке своей сборки. Введите/initи нажмите Enter. - Сверьте созданный или изменённый AGENTS.md с репозиторием.
В проверенном срезе исходников dev /init передаёт модели задание создать или обновить AGENTS.md. Модель должна изучить README, манифесты, настройки сборки и проверок, CI, инструкции и конфигурацию OpenCode. Важные вопросы без ответа в репозитории - уточнить у пользователя.
В существующем файле модель должна сохранить полезные проверенные пункты. Просмотрите изменения: команда даёт задание, но не гарантирует его выполнение. Если в вашей сборке /init нет, создайте AGENTS.md вручную.
Пример из документации OpenCode. Замените команды и пути на действительные для своего проекта:
- После изменений TypeScript выполняй bun typecheck.
- Запросы к базе данных размещай в src/database.
- Не редактируй сгенерированные файлы напрямую.Как проверить корневой и вложенный AGENTS.md
Для опыта задайте совместимые требования: правило из корня задаёт конец ответа, из packages/web - начало.
Шаг 1: создайте отдельный пустой тестовый репозиторий ~/code/agents-md-check. Рабочий продукт не меняйте:
agents-md-check/
├── AGENTS.md
└── packages/
└── web/
├── AGENTS.md
└── probe.mjsПроверьте, какие ещё инструкции могут подключиться: глобальный файл, AGENTS.md по пути к домашнему каталогу, резервные CLAUDE.md, настройки instructions. Запишите пути. Личную конфигурацию ради опыта не удаляйте и не публикуйте.
Шаг 2: заполните файлы тестовыми метками и уберите их после опыта.
В корневой AGENTS.md запишите:
В конце каждого ответа добавляй отдельную строку ROOT_A.В packages/web/AGENTS.md запишите:
В начале каждого ответа добавляй отдельную строку WEB_A.В packages/web/probe.mjs запишите:
export const probe = "sample";Шаг 3: запишите версию или идентификатор сборки, модель, workspace и идентификатор сессии, если виден. Запустите opencode из корня проекта. Для независимого повторения начните новую сессию через /new или Ctrl+X, затем N.
Шаг 4: начните сценарий А в новой сессии из корня. Отправьте запрос без меток:
Ответь одним коротким предложением: что такое проверка результата?
Не исследуй файлы и каталоги проекта.Корневой AGENTS.md загружается при старте. Вложенный packages/web/AGENTS.md пока не подключается. Ожидаемая метка - ROOT_A в конце.
Если агент всё-таки исследовал packages/web, начните сценарий А в новой сессии: здесь нужен ответ без исследования этого каталога.
Шаг 5: продолжите сценарий Б в той же сессии. Теперь попросите прочитать файл:
Прочитай @packages/web/probe.mjs и объясни, что экспортирует файл.Наберите @ и выберите файл через поиск. AGENTS.md явно не прикладывайте: проверяется автоматическое обнаружение. Запишите, прочитан ли probe.mjs и какие сведения о подключённых инструкциях показывает ваша сборка.
При чтении этого файла добавляются инструкции из packages/web/AGENTS.md. Ожидаемые метки - WEB_A в начале, ROOT_A в конце.
Шаг 6: начните сценарий В в отдельной новой сессии из ~/code/agents-md-check/packages/web. Запустите оттуда opencode, повторите запрос А без исследования файлов.
Теперь оба AGENTS.md загружаются при старте: они находятся на пути поиска вверх. Новый запрос сам по себе рабочий каталог не меняет.
Заполните бланк: общие версию и модель запишите над таблицей, изменения отмечайте в строке.
| Сценарий | Workspace и сессия | Запрос и вызовы инструментов | Ожидаемая загрузка и метки | Что видно о подключении файла | Фактический ответ и метки |
|---|---|---|---|---|---|
| А | Корневой; ROOT_A | ||||
| Б | Добавляется пакетный; WEB_A и ROOT_A | ||||
| В | Оба при старте; WEB_A и ROOT_A |
Слова модели «я прочитала инструкцию» не доказывают загрузку. Запишите отдельно вызов чтения probe.mjs, отметку о подключении AGENTS.md и метки в ответе.
Интерфейсу доступны сведения об изменившихся подключениях, но не полный текст инструкций. Если нужное подключение не показано, запишите ответ отдельно. Одних меток недостаточно, чтобы подтвердить загрузку.
Сравните свою таблицу с ожиданиями, затем ищите причину расхождения.
Если вы собираете свои проекты с ИИ-агентами, посмотрите программу практикума СмыслоКода.
Изменил инструкцию - когда OpenCode получит новый текст?
Продолжите на том же проекте. Проверка зависит от способа загрузки файла:
| Что изменили | Ожидаемое поведение | Что записать |
|---|---|---|
| Корневой при workspace в корне | Обновление до следующего запроса модели | Отметку об обновлении и ответ |
| Уже загруженный вложенный | Автоматического обновления нет | Ответы текущей и новой сессий |
| Противоречащие правила | Объединение без разрешения конфликта | Подключённые файлы и выбранное завершение |
В корневом AGENTS.md замените ROOT_A на ROOT_B. В сессии из корня отправьте запрос А. Проверяйте обновление по новому ответу и отметке о подключении: прежние ROOT_A остаются в переписке.
Кстати, я снял полный гайд «Связка для первого агента Hermes Agent», обязательно посмотрите.
Внутри - правила навыка, образец и показатели, проверка на разных моделях: посмотрите, как связать инструкцию с проверяемым результатом. Ролик посвящён Hermes; загрузку AGENTS.md в OpenCode проверяйте на своём проекте.
В сессии из корня, где агент уже прочитал probe.mjs, замените WEB_A на WEB_B во вложенном AGENTS.md. Повторите чтение probe.mjs в текущей и новой сессиях из корня. Сравните ответы: старой сессии доступна и история.
Правка уже загруженного вложенного файла автоматически не обнаруживается. После сжатия истории инструкция может загрузиться снова при чтении. Чтобы применить изменения сразу, начните новую сессию: просьба перечитать файл или перезапуск приложения её не заменяют.
Как продолжить задачу с учётом контекста и истории OpenCode, я разбираю в отдельной статье.
Конфликт проверьте отдельно. В корневом AGENTS.md оставьте только:
Завершай ответ ровно строкой END_ROOT.В packages/web/AGENTS.md:
Завершай ответ ровно строкой END_WEB.Начните новую сессию из packages/web, задайте вопрос без меток. Запишите отдельно подключённые файлы и последнюю строку ответа. По одному ответу нельзя решить, какое правило всегда будет побеждать. Затем верните совместимые правила.
Правило не сработало - перепроверьте сами
- Сверьте имя
AGENTS.mdи путь с таблицей. Правильный путь ещё не означает, что модель выполнит правило. - Проверьте рабочий каталог сессии и
OPENCODE_DISABLE_PROJECT_CONFIG=1: переменная отключает поиск проектных AGENTS.md, глобальный файл остаётся. - Найдите вызов чтения файла или просмотра каталога в
packages/web. Если его нет, повторите сценарий Б. - Проверьте, нет ли противоречий в CLAUDE.md и
instructions. Учтите настройки:OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1отключает CLAUDE.md;OPENCODE_DISABLE_CLAUDE_CODE=1также отключает навыки.claude. Исправляйте конкретное правило, не сбрасывайте всю конфигурацию. - После изменения вложенного файла сравните ответы текущей и новой сессий, как в предыдущем разделе.
Мне кажется, уже не так важно, какая у вас модель. Важно, какая у вас инструкция и понимаете ли вы сами, какой результат должен получиться.
А у вас где проблема: файл не подключился или модель не выполнила правило? Напишите в комментариях в канале, какой сценарий проверили и что получилось.
Частые вопросы
Источники
- OpenCode: Instructions - поиск, объединение и обновление инструкций.
- OpenCode: Agents - профили и разрешения.
- OpenCode: TUI - запуск, выбор файла через @ и новая сессия.
- OpenCode: команда init - регистрация в срезе dev.
- OpenCode: задание init - изучение репозитория и обновление файла.
Новые материалы - дайджестом, без спама
Гайды выходят регулярно. Подпишись, чтобы не пропускать: пришлю подборку в Telegram или на email. Раз в неделю или каждый день - выбираешь сам.

