OpenCode AGENTS.md: какой инструктаж получил агент - перепроверь сам

Опубликовано 19.11.20268 мин чтенияСредний
Артемий Миллер в кепке с логотипом OpenCode рядом с надписью «ПРОВЕРИТЬ АГЕНТА» и логотипами OpenCode.
Что узнаешь
  • Где OpenCode ищет проектные и вложенные AGENTS.md
  • Как проверить правила на отдельном проекте
  • Когда изменённым инструкциям нужна новая сессия
Средний

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. Замените команды и пути на действительные для своего проекта:

markdown
- После изменений 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 запишите:

markdown
В конце каждого ответа добавляй отдельную строку ROOT_A.

В packages/web/AGENTS.md запишите:

markdown
В начале каждого ответа добавляй отдельную строку WEB_A.

В packages/web/probe.mjs запишите:

javascript
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 и метки в ответе.

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

Сравните свою таблицу с ожиданиями, затем ищите причину расхождения.

Если вы собираете свои проекты с ИИ-агентами, посмотрите программу практикума СмыслоКода.

Практикум по вайб-кодингу
+Твой второй мозг
3 вечера - инструменты, метод, первый проект
Старт 24–26 ноября  ·  2 000 ₽
Записаться →

Изменил инструкцию - когда OpenCode получит новый текст?

Продолжите на том же проекте. Проверка зависит от способа загрузки файла:

Что изменилиОжидаемое поведениеЧто записать
Корневой при workspace в корнеОбновление до следующего запроса моделиОтметку об обновлении и ответ
Уже загруженный вложенныйАвтоматического обновления нетОтветы текущей и новой сессий
Противоречащие правилаОбъединение без разрешения конфликтаПодключённые файлы и выбранное завершение

В корневом AGENTS.md замените ROOT_A на ROOT_B. В сессии из корня отправьте запрос А. Проверяйте обновление по новому ответу и отметке о подключении: прежние ROOT_A остаются в переписке.

Кстати, я снял полный гайд «Связка для первого агента Hermes Agent», обязательно посмотрите.

Видео загрузится при скролле
Полный гайд - Связка для первого агента Hermes Agent

Внутри - правила навыка, образец и показатели, проверка на разных моделях: посмотрите, как связать инструкцию с проверяемым результатом. Ролик посвящён Hermes; загрузку AGENTS.md в OpenCode проверяйте на своём проекте.

В сессии из корня, где агент уже прочитал probe.mjs, замените WEB_A на WEB_B во вложенном AGENTS.md. Повторите чтение probe.mjs в текущей и новой сессиях из корня. Сравните ответы: старой сессии доступна и история.

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

Как продолжить задачу с учётом контекста и истории OpenCode, я разбираю в отдельной статье.

Конфликт проверьте отдельно. В корневом AGENTS.md оставьте только:

markdown
Завершай ответ ровно строкой END_ROOT.

В packages/web/AGENTS.md:

markdown
Завершай ответ ровно строкой 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. Исправляйте конкретное правило, не сбрасывайте всю конфигурацию.
  • После изменения вложенного файла сравните ответы текущей и новой сессий, как в предыдущем разделе.

Мне кажется, уже не так важно, какая у вас модель. Важно, какая у вас инструкция и понимаете ли вы сами, какой результат должен получиться.

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

Частые вопросы

Источники

Практикум по вайб-кодингу
+Твой второй мозг
3 вечера - инструменты, метод, первый проект
Старт 24–26 ноября  ·  2 000 ₽
Записаться →

Новые материалы - дайджестом, без спама

Гайды выходят регулярно. Подпишись, чтобы не пропускать: пришлю подборку в Telegram или на email. Раз в неделю или каждый день - выбираешь сам.

Была инструкция полезна?
Артемий Миллер
Автор
Артемий Миллер
Предприниматель и вайб-кодер

Артемий Миллер - предприниматель и вайб-кодер. Бывший программист, собирает продукты исключительно вместе с ИИ-агентами, без найма разработчиков.

Связанные инструкции

Obsidian MCP: нужен ли сервер и что агент видит в заметках

Если агент уже читает нужную папку Markdown, сначала проверьте прямое чтение. Для MCP-подключения выберите конкретный сервер и испытайте его на искусственных заметках.

8 мин

Figma MCP: передай макет и проверь цвета, шрифты, отступы

Figma MCP передаёт агенту компоненты, переменные и структуру макета. Дайте ссылку на нужный фрейм, укажите правила проекта и проверьте реализацию по коду и виду страницы.

10 мин

Claude Code не видит файлы проекта: почему так и что делать в 2026

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

12 мин

MarkItDown: как вытащить текст из PDF и Word для ИИ

MarkItDown от Microsoft переводит PDF и Word в Markdown. Для обычного извлечения языковая модель не нужна, а готовый .md нужно сверить с оригиналом до передачи агенту.

8 мин