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

AGENTS.md и SKILL.md полезны как переносимый контекст для AI coding agents, но они не должны становиться слоем доступа. В Markdown удобно хранить правила проекта, команды проверки, ограничения и повторяемые инструкции. Доступ к файлам, внешним системам, shell-командам, секретам и рабочим окружениям нужно выносить в контролируемый runtime: MCP, filesystem roots, sandbox, permissions, audit и human review.

Практическая рамка простая: AGENTS.md объясняет агенту, как работать в репозитории; SKILL.md описывает повторяемый процесс и подключает scripts или reference-файлы; MCP даёт управляемый доступ к источникам и инструментам; sandbox и права доступа ограничивают, где агент может читать, писать и выполнять команды.

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

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

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

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

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

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

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

SKILL.md — это файл внутри Skill: переиспользуемого пакета с инструкциями, metadata и, при необходимости, scripts, references и assets. Такой формат полезен, когда агенту нужно не просто помнить правило проекта, а выполнять повторяемый workflow.

Skill особенно полезен для процедур вроде подготовки отчёта, проверки документа, миграции payload, ревью API-контракта или сборки однотипного артефакта. Но Skill уже ближе к исполняемой поставке: если внутри есть scripts, external access или references, его нужно ревьюить почти как код и внутренний инструмент.

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

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

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

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

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

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

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

Отдельный workspace или sandbox особенно важен, если:

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

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

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

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

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

Важно проверять не только happy path. В пилоте нужно специально дать агенту задачу рядом с секретами, опасной командой, большим diff и приватной документацией. Если граница держится только потому, что агент “послушался инструкции”, это слабая защита.

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

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

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

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

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

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

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

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

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

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

Перед первым командным пилотом полезно собрать короткий пакет: текущий AGENTS.md, список повторяемых Skills, перечень MCP roots, матрицу доступов и правила human review. После этого можно запускать чек-лист пилота AI coding agents и отдельно сверить approval gates для ИИ-агента.