Переносимый слой: AGENTS.md, схемы инструментов и MCP

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

В прошлых частях серии мы разобрали формулу «агент = модель + harness» и пять слоёв обвязки. Сегодня — про то, какие части этой обвязки стоит строить так, чтобы они пережили смену вендора. Я называю это переносимым слоем, и у меня в нём три главных актива: файл правил AGENTS.md, схемы инструментов и MCP-серверы.

Что переносимо, а что нет

Сначала жёсткое разделение. Настройки, привязанные к конкретному агенту, — вендорские файлы правил, скиллы под одну платформу, промпты, вылизанные под поведение одной модели, — при переезде умирают почти полностью. Это не значит, что их не надо делать. Это значит, что их надо делать дешёво и без иллюзий.

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

Правило, которым я руководствуюсь: дешёвое и вендорское живёт рядом с IDE, дорогое и долговечное — в переносимом слое. Ошибка многих команд в том, что они инвестируют наоборот: неделями полируют конфиг конкретного агента, а файл правил проекта пишут за десять минут на коленке.

AGENTS.md: онбординг для агента

AGENTS.md — это файл в корне репозитория, который агенты читают перед началом работы. По сути это онбординг-документ, только не для нового разработчика, а для агента. Хорошая мысленная модель: представьте, что к вам в команду выходит очень быстрый junior без контекста. Что он должен узнать в первый час, чтобы не наломать дров? Ровно это и пишем.

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

Теперь антипаттерны, на которые я сам наступил. Первый — роман. AGENTS.md на несколько тысяч слов не читает никто, включая модель: под давлением контекста длинный файл начинает теряться, и правила из его середины просто перестают существовать. Мой текущий потолок — две сотни строк, и это уже с натяжкой. Второй антипаттерн — дублирование документации. Если правило можно вывести из кода или из README, не пишите его агенту: при расхождении он поверит не тому источнику. Третий — просьбы вместо механизмов. Помните из прошлой части: «не трогай миграции» в файле правил — это пожелание, а CODEOWNERS с обязательным ревью — механизм. Файл правил нужен для контекста, а не для безопасности.

Есть у AGENTS.md и приятный побочный эффект: его читают люди. Несколько раз новые коллеги говорили мне, что этот файл — лучшее введение в проект. Знания, которые раньше жили в головах, теперь лежат в репозитории и работают на обе стороны.

Схемы инструментов: контракт вместо инструкции

Про правило «сначала схема, потом вызов» я писал в посте про QA-агентов, но повторю, потому что это фундамент переносимого слоя. У каждого инструмента должно быть машиночитаемое описание: какие параметры принимает, что возвращает, какие ошибки бывают. JSON Schema, типы, OpenAPI — формат вторичен, важно, что схема существует и агент читает её перед вызовом.

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

И тот самый эффект давления снизу вверх: когда агент ошибается в вызовах, первый вопрос теперь не «что с моделью не так», а «что со схемой не так». Плохая схема — плохие вызовы. Хорошая — работает сама. Качество инструментов растёт, потому что их начинают проверять самым беспощадным пользователем — моделью без чувства такта.

MCP: единый разъём для внутренних систем

Третья опора переносимого слоя — MCP, протокол, через который агенты подключают внешние инструменты и данные. Практический смысл для команды простой: вы один раз пишете сервер, который даёт доступ к вашим внутренним системам (тикетам, базе знаний, стендам, метрикам), и этот сервер могут использовать все агенты, понимающие протокол. Не «интеграция под Cursor» и не «плагин под Claude», а один разъём под всех.

У меня через MCP у агентов ходят в тестовую инфраструктуру и в пару внутренних сервисов. До MCP каждая смена агента означала переписывание интеграций. После — копирование одной строчки конфига. Это, наверное, самая ощутимая экономия из всех, что дал переносимый слой.

Два предостережения из опыта. Первое: каждый MCP-инструмент — это ещё и новая поверхность риска. Давайте агенту узкие инструменты («получить тикет по номеру», «список упавших тестов за сутки»), а не широкие («выполнить SQL»). Там, где хватает чтения, делайте инструменты read-only: инструмент, который не умеет писать, не может ничего испортить, и это лучшая из защит. Второе: схемы MCP-инструментов — часть контракта, относитесь к ним как к публичному API. Описание параметра «string» без пояснений — это будущая ошибка вызова.

Собираем вместе: что делаю на новом проекте

Когда я подключаю агента к новому проекту, порядок теперь стабильный. Пишу короткий AGENTS.md: команды, карта, правила, запреты. Проверяю, что у всех инструментов есть схемы, и чиню те, где их нет. Внутренние системы подключаю через MCP-серверы с узкими read-only инструментами, где это возможно. И только потом, если осталось желание, настраиваю вендорские мелочи конкретного агента — с полным пониманием, что через полгода их, возможно, придётся выбросить.

Заметьте, чего в этом списке нет: нет выбора модели и нет тюнинга промптов. Не потому что это не работает, а потому что это не накапливается. Переносимый слой накапливается: каждый написанный блок правил, каждый инструмент со схемой и каждый MCP-сервер остаются с вами при любом раскладе на рынке агентов.

Главный вывод

Инструменты и модели будут меняться и дальше, быстрее, чем нам удобно. Поэтому обвязку стоит делить на две части: вендорскую, которую делаем дёшево и без сожалений, и переносимую, которую делаем тщательно и надолго. Переносимый слой — это AGENTS.md с командами, картой и запретами; схемы инструментов как контракты; MCP-серверы как единый разъём к внутренним системам.

Это не самая зрелищная часть harness engineering. Но именно она отличает команду, которая «попробовала агентов», от команды, у которой агенты работают годами и переживают любую смену флагов.

Практический чеклист

В корне репозитория лежит AGENTS.md: команды сборки и тестов, карта проекта, правила, запретные зоны, процесс. Не длиннее двухсот строк.
В AGENTS.md нет дублирования README и нет «безопасности словами» — запреты подкреплены механизмами.
У каждого инструмента агента есть машиночитаемая схема, и ошибки вызовов вы сначала ищете в схеме, а не в модели.
Доступ агентов к внутренним системам идёт через MCP-серверы, а не через скрипты, привязанные к одному агенту.
Инструменты узкие; где хватает чтения — read-only.
Вендорские настройки вы готовы выбросить без боли: ничего критичного в них не зашито.

Следующая часть — верификация и evals: чем «тесты зелёные» отличаются от «результату можно доверять», и как отлаживать агента по трассам. А если недавно переезжали между агентами — расскажите, что у вас переехало, а что сгорело. Любопытно сравнить.