AGENTS.md и SKILL.md для AI coding agents: что хранить в Markdown, а что отдавать через MCP

AGENTS.md — это файл инструкций для coding agent внутри репозитория: он объясняет проект, команды проверки, стиль, ограничения и правила работы. SKILL.md — файл внутри переиспользуемого Skill: он описывает повторяемая процедура, входы, выходы, скрипты и reference-материалы. MCP — протокол и набор серверов, через которые агент получает управляемый доступ к инструментам, данным и ограниченным директориям.

Главная граница такая: Текстовые инструкции задают намерение и порядок работы, но не выдают полномочия. Доступ к Jira, GitLab, Confluence, CI, файлам, командам, секретам и внешним API нужно ограничивать через MCP, разрешенные директории, изолированную среду, права доступа, подтверждение действий и журналирование.

Если коротко: AGENTS.md нужен для общих правил проекта; SKILL.md — для повторяемой процедуры; MCP — для подключения источников и действий; изолированная среда и права доступа — для технических ограничений.

Эта таблица помогает не смешивать правила, процедуры и доступы в одном большом Markdown-файле. Чем ближе слой к действиям и внешним системам, тем строже нужны ревью, технические ограничения и журналирование.

Отдельный контекстный слой нужен, когда coding agent работает не с одной разовой задачей, а с реальным репозиторием, командными правилами, тестами, pull request и внутренними источниками. Чем больше у агента автономии, тем важнее отделить инструкции от доступа.

Такой слой стоит проектировать, если:

• в репозитории есть свои build/test команды, стиль кода и архитектурные ограничения;
• несколько разработчиков используют разные coding agents, но правила проекта должны быть общими;
• агенту нужно читать документацию, задачи, changelog или runbooks;
• часть действий можно разрешить автоматически, а часть требует human ревью;
• есть секреты, production-конфиги, приватные документы или опасные shell-команды;
• нужно разбирать, почему агент сделал изменение и откуда взял контекст.

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

AGENTS.md — это Markdown-файл с инструкциями для coding agents. Его удобно воспринимать как README для агента: не вместо человеческого README, а рядом с ним. В нём должны быть правила, которые помогают агенту быстро понять проект и не ломать командный процесс.

В AGENTS.md не стоит складывать всё подряд. Если инструкция длинная, редкая или зависит от отдельной процедуры, лучше вынести её в документация, runbook или Skill. Если правило связано с доступом, секретами или внешним сервисом, оно должно быть продублировано техническим ограничением, а не оставаться только просьбой в Markdown.

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

Markdown хорошо объясняет намерение, но плохо ограничивает полномочия. Если агенту написали “не читать секреты”, это не то же самое, что технически закрыть секреты. Если в файле написано “не запускать опасные команды”, это не заменяет подтверждение gate, изолированная среда или policy.

Одним Markdown нельзя надёжно решить:

• доступ к секретам, env-файлам, production-конфигам и хранилища учетных данных;
• запрет выхода за пределы рабочая область root;
• разделение только чтение и write-действий;
• контроль shell-команд, network egress и установки зависимостей;
• аудит tool calls, изменений файлов и причин решений;
• изоляцию экспериментов от host-машины и соседних репозиториев.

Правильная формула: важные правила можно описать в Markdown, но критичные границы должны быть enforced на уровне runtime, filesystem, MCP, изолированная среда, CI или ревью-процесса. Иначе агент может выполнить задачу формально успешно, но через путь, который команда не хотела разрешать.

MCP помогает подключать агента к инструментам и источникам данных через стандартизированный протокол. Для файловой системы важна идея roots: клиент показывает серверу только те директории, в которых тот может работать. Это не просто удобство навигации, а граница доступа.

Через MCP стоит отдавать то, что агент должен получать как инструмент или источник: задачи, документацию, ограниченный file tree, CI-сигналы, поиск по knowledge base. В Markdown стоит хранить объяснение, как этим пользоваться. Не наоборот: не превращать AGENTS.md в список секретных URL, токенов и ручных обходов.

Sandbox нужен там, где агент может выполнять код, менять файлы или ходить в сеть. Для личного только чтение сценария может хватить правила репозитория и ручного ревью. Для командного пилота лучше сразу считать агента процессом с делегированными полномочиями, а не “умным текстовым помощником”.

Отдельный рабочая область или изолированная среда особенно важен, если:

• агент запускает shell-команды или устанавливает зависимости;
• в репозитории есть production-конфиги, deploy скрипты или ключи;
• нужно разрешить агенту много попыток без риска для host-машины;
• команда использует cloud/background agents;
• агенту нужны MCP-инструменты с доступом к внутренним системам;
• результат должен проходить воспроизводимый ревью и audit.

Рабочий критерий простой: агент может делать всё, что нужно для задачи, но только внутри заранее выбранной границы. Если задача требует больше доступа, лучше расширить boundary явно и временно, чем давать общий доступ к домашняя папка, всем репозиториям или production учетные данные.

Для coding agents полезно проектировать доступы не как “можно/нельзя агенту”, а как несколько уровней. Чтение документации, чтение кода, изменение файлов, запуск команд, создание PR и доступ к внешним системам — разные классы действий с разным риском.

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

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

Контекст для агента устаревает так же быстро, как документация для людей. Разница в том, что агент может сразу применить устаревшее правило к коду. Поэтому AGENTS.md, Skills и MCP-конфигурации должны иметь владелец и ревью rhythm.

Минимальный порядок:

• хранить AGENTS.md в репозитории и ревьюить через обычный PR;
• назначить владелец для общих Skills и reusable скрипты;
• проверять команды после изменения менеджера пакетов, CI, среды запуска тестов или структуры монорепозитория;
• удалять устаревшие ограничения, которые агент больше не должен видеть;
• версионировать MCP-конфигурации и список roots;
• после инцидента обновлять не только инструкцию, но и технический guard.

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

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

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

После подготовки контекстного слоя у команды должен быть не один большой Markdown-файл, а понятный комплект артефактов:

• AGENTS.md с краткими правилами проекта, командами проверки и security notes;
• список Skills, если повторяемые процедуры вынесены из общего файла;
• описание MCP-источников и разрешенные директории;
• матрица чтение и запись доступов;
• список команд, которые требуют подтверждение;
• правила хранения секретов вне Markdown;
• порядок ревью, audit и обновления контекста.

Такой комплект можно использовать перед пилотом AI coding agents, при выборе между Codex, Claude Code и Cursor или при подключении MCP-интеграций. Он помогает обсуждать не “насколько агент умный”, а насколько безопасно и воспроизводимо он встроен в процесс разработки.