Модули 2.6–2.7: файл инструкций AGENTS.md и MCP

Ведущая: Привет-привет! С вами AIStudy — бесплатный курс про искусственный интеллект, который можно слушать за рулём, в метро или на кухне. Записывать ничего не нужно: файлы-образцы, настройки и таблицы лежат на сайте.

Ведущий: Привет! Это четвёртый выпуск трека «Кодинг с агентами». В прошлый раз мы закончили на обещании: рассказать, как один файл инструкций понимают разные агенты и как подключать инструменты через MCP. Сегодня выполняем обещание. Два модуля сразу: «AGENTS.md и документация» и «MCP».

Ведущая: Два модуля в одном выпуске? Что у них общего?

Ведущий: Общая мысль: агент хорош ровно настолько, насколько хорошо ты его снабдил. Файл инструкций рассказывает ему про твой проект. MCP даёт ему руки: доступ к файлам, базам данных, трекерам задач и сервисам. Сначала знания, потом возможности.

Ведущая: Какой план?

Ведущий: Шесть частей. Первая: зачем агенту документация. Вторая: AGENTS.md, единый стандарт, его структура и готовые шаблоны. Третья: файлы для конкретных инструментов, CLAUDE.md, GEMINI.md и правила Cursor, и как всё это сочетать. Четвёртая: что такое MCP. Пятая: как подключать серверы и какие они бывают. Шестая: протокол A2A, проверка себя и итоги.

Ведущая: Поехали!

Ведущий: Поехали!

Ведущая: Часть первая. Зачем агенту документация? Он же умный, сам разберётся.

Ведущий: Представь: ты передал проект новому разработчику. Первый день, он открывает папку и ничего не знает. Какая тут архитектура? Какие правила именования? Какими библиотеками можно пользоваться? Как запустить тесты? Что здесь категорически нельзя делать? Агент в начале работы с проектом находится в точно таком же положении.

Ведущая: И что он делает, когда не знает?

Ведущий: Догадывается. Пишет код по общим знаниям, а не по вашим соглашениям. Пропускает важные правила. Тратит контекст на уточнения, а потом приходится много раз переделывать. Урок показывает пример: вы просите «добавь вход на страницу» в проекте на React. Агент без документации пишет компонент в старом стиле, хранит токен в небезопасном месте, берёт не ту библиотеку для запросов, вставляет стили прямо в разметку и оставляет отладочный вывод. А в вашем проекте всё это делается по-другому.

Ведущая: А если файл инструкций есть?

Ведущий: В нём записано: компоненты пишем функциями, вот такой стиль, вот эта библиотека, токен хранить так-то, а вот это не используем. Агент пишет сразу правильно, и код уходит в запрос на слияние с первого раза. Контекст остаётся для сложной логики, а не для уточнений.

Ведущая: Прямо как онбординг нового сотрудника.

Ведущий: Урок так и строит аналогию. Разработчику дают документацию команды, агенту дают файл инструкций. Разработчик смотрит примеры кода в репозитории, агент анализирует существующий код. Разработчик спрашивает, что нельзя делать, агент читает раздел запретов. И у обоих первые правки получаются точнее.

Ведущая: И какие бывают такие файлы?

Ведущий: Четыре основных. AGENTS.md: открытый универсальный стандарт, под все инструменты. CLAUDE.md: файл для Claude Code. GEMINI.md: для терминального агента Google, Antigravity CLI. И правила для Cursor: старый файл cursorrules и новая папка правил. Подробно пройдёмся по каждому, а пока главная мысль: документация проекта нужна как часть разработки, а не как бонус.

Ведущая: Это польза только для агентов?

Ведущий: Нет. Урок отдельно отмечает: документация помогает людям, новичкам в команде и тебе самому через месяц. Проще писать задачи и делать ревью чужого кода. Это одна из причин, почему практика так быстро растёт.

Ведущая: Как понять, что моему проекту пора?

Ведущий: Урок даёт пять вопросов к своему проекту. Описаны ли архитектура и структура папок? Записаны ли соглашения: имена, стиль, примеры правильного и неправильного кода? Понятно ли, какие приёмы использовать нельзя? Ясно ли, как запускать тесты и какое нужно покрытие? Задокументированы ли сборка и развёртывание? Если «нет» больше чем на три вопроса, пора заводить файл инструкций.

Ведущая: Что унести из первой части?

Ведущий: Агент как новый разработчик. Без документации он догадывается, с документацией работает по вашим правилам. Файл инструкций экономит и ваше время, и контекст агента.

Ведущий: Часть вторая. AGENTS.md. Расскажи про универсальный стандарт.

Ведущая: Это открытый стандарт для инструкций агентам: обычный файл в формате Markdown, лежит в корне проекта или в подпапках. Урок называет его стандартом под крылом Linux Foundation и приводит цифру: к концу две тысячи двадцать пятого года им пользовались больше шестидесяти тысяч открытых проектов.

Ведущий: И кто его понимает?

Ведущая: По уроку: Codex от OpenAI, Cursor, Antigravity CLI, GitHub Copilot и ряд других инструментов. Но есть оговорка: Claude Code в первую очередь читает свой файл CLAUDE.md. Можно сделать так, чтобы CLAUDE.md отсылал к AGENTS.md. Идея стандарта простая: один файл вместо пяти разных, одинаковое поведение везде и лёгкий перенос между инструментами.

Ведущий: Из чего он состоит?

Ведущая: Жёсткого формата нет, но урок называет шесть основных секций. Первая: обзор проекта. Что проект делает, на каком стеке, для кого, какие ключевые библиотеки. Два-три предложения, а не роман. Вторая: соглашения разработки. Как пишется код: стиль, имена, структура файлов, порядок подключений, обработка ошибок.

Ведущий: Дальше?

Ведущая: Третья: тестирование. Какой фреймворк, как запускать, какое нужно покрытие, как писать тесты. В примере урока там есть полезное правило: не делать настоящих сетевых запросов в тестах, а подменять внешние сервисы. Четвёртая: сборка и развёртывание. Команды сборки, нужные переменные окружения, как выкатывать на разные среды. Пятая: архитектура. Как устроены папки, что делает каждый модуль, как данные идут через систему.

Ведущий: А шестая?

Ведущая: Моя любимая: что можно и чего нельзя. Запреты на типичные ошибки. Не писать бизнес-логику в обработчиках запросов. Не записывать в журнал пароли и токены. Не прописывать значения прямо в код. Не менять базу без миграций. Не коммитить файлы с секретами. Эти правила агент нарушает чаще всего, когда их не знает.

Ведущий: Какого размера должен быть файл? Не хочется писать книгу.

Ведущая: Урок настаивает: чем короче и сфокусированнее, тем лучше. Слишком длинный файл, и модель теряется в деталях: середина как будто выпадает. Для больших проектов заводят вложенные файлы в подпапках, и ближайший к тому, над чем работает агент, имеет приоритет. Точные цифры по строкам в разных уроках немного расходятся, поэтому запомните правило: компактно и по делу, а подробности во вложенных файлах.

Ведущий: Что в файле важнее всего?

Ведущая: Примеры. Агент лучше учится на примерах, чем на описаниях. Рядом с правилом положи кусочек настоящего кода из своего проекта. Урок подчёркивает: заменить образцы из шаблона своими примерами и есть самая важная часть.

Ведущий: Вот, кстати, про шаблоны. Не писать же всё с нуля.

Ведущая: Пятый урок модуля даёт четыре готовых шаблона: веб-приложение на React, сервер на Python, конвейер обработки данных и мобильное приложение. В каждом заготовка со стеком, соглашениями, структурой папок, командами и запретами. Адаптировать их предлагается за пять шагов.

Ведущий: Каких?

Ведущая: Первый: скопировать шаблон подходящего типа. Второй: заполнить основное: что делает проект, для кого, какие главные возможности. Третий: обновить стек, указать настоящие версии и библиотеки. Четвёртый: подогнать соглашения под свой стиль и инструменты проверки кода. Пятый, самый важный: заменить примеры кодом из своего проекта.

Ведущий: И как понять, что файл работает?

Ведущая: Проверить на агенте. Положили файл в корень, попросили сделать небольшую новую функцию и смотрите: стиль правильный? Архитектура та? Технологии те? Если нет, добавляете правило и пробуете снова. Плюс чек-лист: все секции заполнены, примеры соответствуют проекту, команды правда работают, версии актуальны.

Ведущий: А сколько времени это занимает?

Ведущая: Урок предлагает два варианта. Быстрый, на полчаса: выбрать тип проекта, скопировать шаблон, заполнить основные секции. Полный, на пару часов: заполнить всё, добавить свои примеры, поработать с агентом и улучшить файл по результатам. А главное: даже короткий файл лучше, чем никакого. Файл живёт в репозитории рядом с кодом, так что поделиться им с командой проще простого.

Ведущая: Часть третья. Если есть универсальный файл, зачем остальные? Зачем отдельный файл для Claude?

Ведущий: Урок отвечает через сравнение. AGENTS.md: полная документация проекта для всех, хранилище знаний, обновляется редко, когда меняется сам проект. CLAUDE.md: инструкции именно для Claude Code, быстрые правила, которые вы пополняете по ходу работы. И размер у него компактнее, до пары сотен строк. Остальное предлагается выносить в отдельные файлы правил и подключаемые документы.

Ведущая: А как Claude Code эти файлы читает?

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

Ведущая: А как проверить, что агент вообще видит мои правила?

Ведущий: В Claude Code есть служебные команды. Одна показывает, какие файлы правил сейчас загружены и сколько места занимают. Другая диагностирует проект и предупреждает, если главный файл разросся. Названия команд смотрите в уроке.

Ведущая: Хорошо, файл написан. Что дальше?

Ведущий: Самое ценное в уроке: улучшать файл итерациями по ошибкам агента. Агент ошибся: допустим, написал код без типов и без обработки ошибок. Вы понимаете проблему и добавляете в файл правило. Пробуете тот же запрос снова. Стало лучше, готово. Нет, уточняете правило. Потом новая ошибка, например неосторожная работа с хранилищем в браузере, и ещё одно правило. Файл растёт из реальных промахов, а не из фантазий.

Ведущая: Это как в прошлом выпуске про Cursor: проверяем правила простой задачей.

Ведущий: Тот же принцип. Теперь GEMINI.md.

Ведущая: Это для Google?

Ведущий: Да, аналог CLAUDE.md для терминального агента Google. Название файла осталось прежним, и его читают и Antigravity CLI, и оставшийся Gemini CLI. Причём рядом лежит AGENTS.md, и агент читает оба. Структура похожа на CLAUDE.md. Урок напоминает: обычному пользователю Gemini CLI уже закрыт, а ученику курса ставить Antigravity.

Ведущая: А Cursor?

Ведущий: Его мы разбирали в прошлом выпуске. Актуальный формат: папка правил, а в ней отдельные файлы с расширением эм-ди-си. В заголовке каждого можно указать описание, к каким файлам относится правило и применять ли его всегда. Старый файл cursorrules урок называет больше не рекомендуемым.

Ведущая: Хорошо, а если у меня всё сразу? Писать четыре файла?

Ведущий: Урок говорит: не усложняй. Начни с AGENTS.md как с основы. Потом добавь короткие файлы только для тех инструментов, которыми реально пользуешься: небольшой CLAUDE.md, небольшой GEMINI.md, правила Cursor. В CLAUDE.md хватит строки: базовая документация лежит в AGENTS.md, а здесь только то, что относится к Claude. Тогда дублирования нет. И цитата из выводов: даже AGENTS.md плюс CLAUDE.md лучше, чем четыре файла с повторами.

Ведущая: А по принципу «что у меня основное»?

Ведущий: Урок рисует дерево. Пользуешься Cursor, берёшь правила проекта. Claude Code, берёшь CLAUDE.md. Агент Google, берёшь GEMINI.md. Ничего из этого, берёшь AGENTS.md для всех. Только помни, что AGENTS.md и так читают многие инструменты, поэтому он всегда основа, а специальные файлы лишь дополняют.

Ведущая: Подведём часть.

Ведущий: AGENTS.md база для всех. CLAUDE.md, GEMINI.md и правила Cursor короткие дополнения. А все файлы растут из ошибок агента.

Ведущий: Часть четвёртая. Переходим ко второму модулю. MCP: что это вообще такое?

Ведущая: Model Context Protocol, открытый стандарт от Anthropic для подключения к моделям и агентам внешних инструментов, данных и сервисов. Урок даёт простую аналогию: MCP для ИИ как USB для компьютеров. Один стандартный разъём, в который можно воткнуть мышку, принтер, сканер. Так и здесь: один протокол, к которому подключаются самые разные сервисы.

Ведущий: А зачем? Агент и так читает файлы.

Ведущая: Встроенные инструменты у него ограничены. Без MCP агент по сути работает с текстом чата и тем, что в него заложено. С MCP он может подключиться к файловой системе, работать с GitHub и трекерами задач, делать запросы к базам данных, отправлять сообщения в Slack, читать и создавать документы в облачных хранилищах. И всё через единый стандарт, без переписывания кода самого агента.

Ведущий: Как это устроено?

Ведущая: Четыре звена. Хост: приложение, с которым вы работаете, например Claude Code или редактор. Клиент: часть хоста, которая управляет подключениями. Сервер: программа, которая предоставляет возможности, скажем, сервер для файлов или для GitHub. И инструменты с ресурсами: то, что сервер даёт агенту.

Ведущий: Покажи на примере.

Ведущая: Вы просите: прочитай файл с настройками. Хост понимает, что нужна функция чтения. Клиент передаёт запрос серверу. Сервер идёт к ресурсу, получает содержимое и возвращает клиенту, клиент отдаёт хосту, и агент рассказывает вам, что в файле. Для вас это выглядит так, будто агент просто умеет читать файлы.

Ведущий: А что уже подключено в экосистеме?

Ведущая: Урок приводит категории. Файлы. Код: GitHub и GitLab. Данные: базы вроде Postgres. Общение: Slack и Discord. Документы: облачные диски и Notion. Поиск в интернете. Мониторинг ошибок. Трекеры задач. Браузер. По цифрам урока, в официальном реестре на начало октября двадцать шестого года было около тридцати девяти тысяч публичных серверов.

Ведущий: А кто MCP понимает?

Ведущая: Почти все герои нашего трека. Claude Code со встроенным клиентом, Cursor, Antigravity CLI, Copilot в терминале, OpenCode, Devin Desktop, Cline и Zed. Урок называет больше трёхсот клиентов. А управляется стандарт с декабря двадцать пятого года тем же фондом при Linux Foundation, что и AGENTS.md.

Ведущий: И чем это лучше, чем писать интеграции самому?

Ведущая: Урок сравнивает. До MCP каждую интеграцию писали вручную, у каждой свой код, масштабировать сложно. После: один стандарт, поставил сервер и работает, легко добавлять новые инструменты, а агент сам решает, какой из них применить. Пример из урока: агент читает требования из файла, ищет похожие задачи в GitHub, создаёт новую задачу и отправляет уведомление в Slack. Без MCP это четыре разные интеграции, с MCP достаточно настроить конфигурацию.

Ведущий: Мини-итог?

Ведущая: MCP это единый разъём между агентом и внешним миром. Агент остаётся тем же, а возможности подключаются снаружи.

Ведущая: Часть пятая. Хорошо, MCP это разъём. А как в него воткнуть сервер?

Ведущий: Сначала предупреждение, оно стоит в начале урока. MCP-серверы расширяют доступ агента к файловой системе, базам данных и внешним сервисам. Значит, и риск потерять данные выше. Урок советует практиковаться на отдельном сервере или второй машине, а на основной делать резервные копии.

Ведущая: Принято. Что дальше?

Ведущий: В Claude Code серверы описываются в файле настроек. Мест два: общий файл в домашней папке для всех проектов и файл в корне конкретного проекта. Важная деталь из урока: обычный файл настроек Claude Code для MCP не используется. Внутри перечень серверов, у каждого своё имя. Для каждого указано, что запускать и с какими параметрами, а для удалённого сервера адрес. Токены и пароли урок советует задавать через переменные окружения, а не прописывать в параметрах запуска.

Ведущая: Серверы бывают разные?

Ведущий: Двух видов. Локальный: программа запускается у вас на машине, например через Node, через Python или в контейнере Docker. Удалённый: вы просто подключаетесь по адресу, часто с подтверждением доступа в браузере, ничего не устанавливая. У GitHub, Slack и таск-трекера Linear есть официальные удалённые серверы.

Ведущая: А если я ошибусь в настройках?

Ведущий: Урок советует три проверки. Первая: убедиться, что файл корректный, ведь одна лишняя запятая ломает всё. Вторая: заглянуть в журналы. Третья: после изменений перезапустить Claude Code и вывести список серверов. Должны быть видны все, с количеством инструментов. Потом попросить агента сделать то, что требует нового сервера, например найти документацию, и он должен сам вызвать нужный инструмент.

Ведущая: А собственный сервер можно сделать?

Ведущий: Можно, и проще, чем кажется. Урок показывает на Python с библиотекой FastMCP. Пишешь обычные функции с понятными описаниями: поиск по документации, список документов, получение нужного документа, погода по названию города. Помечаешь их как инструменты, и агент получает возможность их вызывать. Потом регистрируешь сервер в том же файле настроек, как любой другой.

Ведущая: Какие серверы ставить в первую очередь?

Ведущий: В уроке десять популярных. Файловый: нужен почти всем. GitHub: создавать задачи и запросы на слияние, искать по репозиториям. База данных: спросить человеческим языком, сколько пользователей в таблице. Slack: уведомления и чтение каналов. Облачные документы. Поиск Brave для интернета. Playwright для управления браузером: открыть страницу, нажать кнопку, сделать снимок экрана. Docker для контейнеров. Sentry для ошибок приложения. И трекеры задач, Linear и Jira.

Ведущая: Что взять новичку?

Ведущий: Минимальный набор для начинающего: файлы, GitHub и поиск в интернете. Для бэкенд-разработчика набор побольше: файлы, GitHub, база данных, Docker, Sentry и Slack. Урок советует начать с минимума и добавлять по необходимости.

Ведущая: Заманчиво. Но если агент получает доступ к базе, к GitHub, к Slack, не страшновато?

Ведущий: Резонный вопрос. Урок отвечает на него только предупреждением про резервные копии, поэтому добавлю от себя несколько простых правил. Давайте минимально нужные права: токен только с теми правами, которые нужны задаче. Базу сначала подключайте тестовую или только для чтения. Файл настроек с токеном не кладите в общий репозиторий. И смотрите, что агент собирается вызвать.

Ведущая: И последнее. Про названия пакетов.

Ведущий: Урок тут очень настойчив. Часть старых серверов из официальной коллекции снята с поддержки: для GitHub и Postgres прежние пакеты устарели. А для Docker и для Jira готовых пакетов под теми названиями, которые встречаются в гайдах, нет вообще. Не ставьте «похожие» имена наугад. Актуальный сервер ищите в официальном реестре MCP. И помните: для каждого сервера нужны свои токены и ключи, получаются они один раз.

Ведущая: Итог части?

Ведущий: Настройка лежит в одном файле, серверы бывают локальные и удалённые. Начинайте с трёх: файлы, GitHub, поиск. Права минимальные, а названия пакетов проверяйте в официальном реестре.

Ведущий: Часть шестая. Последняя. Остался A2A. Это то же самое, что MCP?

Ведущая: Нет, и это главная разница модуля. A2A, агент к агенту: протокол общения нескольких ИИ-агентов между собой. Его предложила Google, а сейчас он тоже под Linux Foundation, так что это уже не «только Google». Аналогия из урока: MCP это интерфейс между агентом и инструментами, A2A это интерфейс между агентом и другим агентом.

Ведущий: Если совсем просто?

Ведущая: MCP расширяет возможности одного агента: он читает файл, ходит в базу. A2A делит работу между несколькими агентами: один ищет информацию, другой пишет отчёт. MCP, по уроку, готов к использованию. A2A развивается, и на практике большинство редакторов и фреймворков пока опираются именно на MCP.

Ведущий: А как агенты друг про друга узнают?

Ведущая: Три понятия. Карточка агента: имя, описание, какие задачи решает и какой результат возвращает. Задача: что нужно сделать, с параметрами и контекстом, в том числе с результатами других агентов. И результат работы: то, что агент возвращает, иногда вместе со следующей задачей. По уроку, первая полноценная версия спецификации вышла в марте двадцать шестого года, а в экосистеме больше ста пятидесяти организаций.

Ведущий: Примеры из жизни?

Ведущая: Исследователь и писатель: один ищет информацию и передаёт найденное второму, тот пишет отчёт. Проверяющий код и исправляющий: один находит проблемы, второй их чинит. Аналитик и тот, кто рисует графики: один находит тренды в данных, второй строит диаграммы. Плюсы, по уроку: каждый агент лучше в своём деле, легче добавлять новых и проще отлаживать, ведь каждого можно проверять отдельно. И отдельный проверяющий, как считает урок, объективнее, чем один агент, который сам себя проверяет.

Ведущий: Когда это нужно, а когда лишнее?

Ведущая: Нужно, когда в проекте разные роли, когда нужна специализация, когда работу можно разделить и вести параллельно, и в корпоративных процессах с согласованиями. Лишнее, когда задача простая, ролей нет и всё решается инструментами MCP. Совет из урока: не спешите, сначала освойте MCP, потом при необходимости изучайте A2A. А потренироваться можно вручную: два окна агента, в первом исследователь, во втором писатель, а результат вы переносите копированием.

Ведущий: Давай соберём всё в план действий. С чего начинать?

Ведущая: По шагам. Первое: файл инструкций. Возьмите шаблон, адаптируйте за пять шагов, положите в корень проекта и проверьте на небольшой задаче. Второе: добавляйте правила по ошибкам агента. Третье: подключите два-три сервера MCP, начиная с файлов, GitHub и поиска, и с минимальными правами. Четвёртое: когда понадобится что-то своё, напишите свой сервер. Пятое: A2A оставьте на потом.

Ведущий: Проверим себя?

Ведущая: Три вопроса про себя. Первый: какие три правила вашего проекта агент нарушил бы, не зная о них? Их и записывайте в AGENTS.md первыми.

Ведущий: Второй: какие два-три сервиса вы сегодня открываете вручную, чтобы потом передать результат агенту? Что из них можно подключить через MCP и с какими минимальными правами?

Ведущая: И третий: есть ли в вашей работе задача, где нужны два агента с разными ролями, или одному агенту с инструментами хватит?

Ведущий: Теперь итог. Первое: агент как новый разработчик. Без документации он догадывается, с документацией работает по вашим правилам. Второе: AGENTS.md открытый универсальный стандарт, коротко, с примерами из своего кода, а CLAUDE.md, GEMINI.md и правила Cursor короткие дополнения. Третье: файл растёт из ошибок агента: ошибся, добавили правило, проверили. Четвёртое: MCP единый разъём между агентом и инструментами. Начинайте с файлов, GitHub и поиска, права давайте минимальные, а названия пакетов проверяйте в официальном реестре. Пятое: A2A про общение агентов между собой, и сначала лучше освоить MCP.

Ведущая: Образцы файлов, настройки, список серверов и таблицы лежат в уроках на сайте. Ссылки на все девять уроков в описании выпуска.

Ведущий: Дальше в курсе модуль про российские модели для разработчиков. А если хочется попробовать разные нейросети в одном месте, без VPN и с оплатой рублями, это наш сервис arckep.ru. Ссылка в описании.

Ведущая: Спасибо, что слушали!

Ведущий: До встречи!

Ведущая: До встречи!