CONTEXT.md и AGENTS.md

Подробное руководство для разработчиков и пользователей сайта

Представьте ситуацию: вы нанимаете гениального программиста-сеньора. Он знает десятки языков, пишет идеальный код с первого раза и никогда не устает. Вы ставите ему задачу: «Сделай мне интернет-магазин».

Что он сделает? Скорее всего, начнет задавать сотни вопросов. На каком языке писать? Какие платежные системы подключать? Нужна ли админка? Где лежат доступы к базе данных? А может быть, он просто выдаст вам дефолтный шаблон магазина из 2010 года, потому что именно так его учили в университете нейросетей.

Именно это происходит сегодня, когда разработчики дают сложные задачи популярным нейросетям (Claude, GPT, Gemini). Модель умная, но она ничего не знает о вашем конкретном проекте. Она видит только текст вашего запроса. Чтобы превратить универсальную модель в узкоспециализированного эксперта по вашему репозиторию, ей нужны инструкции.

До недавнего времени эти инструкции были хаотичными: кто-то писал огромный промпты прямо в чат, кто-то создавал файлы .cursorrules или copilot-instructions. Но индустрия пришла к двум понятным стандартам, которые решают разные задачи: CONTEXT.md и AGENTS.md. Если вы разрабатываете плагины, модули или шаблоны CMS (как это делается на сайте denkon.ru), понимание разницы между ними сэкономит вам десятки часов отладки.

Что такое CONTEXT.md: Паспорт проекта и оперативная память

Файл CONTEXT.md — это статическая база знаний о вашем проекте. Его главная задача — дать модели фундаментальное понимание того, что перед ней находится. Это ответ на вопросы новичка: «Куда я попал?», «На чем это написано?» и «Какие здесь правила игры?».

Если провести аналогию со стройкой дома, то CONTEXT.md — это генеральный план участка, чертежи фундамента, спецификация материалов и список всех рабочих бригад с их контактами. Это сухие факты, которые редко меняются.

Что обычно пишут в CONTEXT.md:

1. Архитектура приложения. Не просто «это сайт на PHP», а описание слоёв: где контроллеры, где сервисы, как устроен слой доступа к данным (DAL), какие используются паттерны проектирования (например, Repository или CQRS).
2. Технологический стек. Версии языков (PHP 8.3, а не просто PHP), версии фреймворков, базы данных, кеширования (Redis) и очередей.
3. Ключевые зависимости. Список нестандартных библиотек, самописных компонентов и критичных пакетов. Например, если вы используете специфическую обертку над API Сбера для оплаты, об этом нужно написать.
4. Соглашения по коду (Code Style). Используете ли вы PSR-12? Применяете ли Strict Types? Есть ли запрет на использование глобальных переменных?
5. Пути к важным файлам. Где лежит конфигурация БД? Где хранятся миграции? В какой папке находятся шаблоны вашей CMS?
6. Ограничения производительности. Лимиты памяти скриптов, таймауты запросов, требования к скорости ответа главной страницы.
7. Краткая история рефакторинга. Куда перенесли старый модуль авторизации и почему новый написан иначе.

Пример фрагмента CONTEXT.md для разработки плагина под условную CMS:

# CONTEXT.md — Проект "DenKon Shop"

## Общая информация
Мы разрабатываем плагин доставки СДЭК для CMS [Название]. Текущая версия ядра CMS: 2.4.1.

## Технический стек
- Язык: PHP 8.2+
- Фреймворк: Собственный MVC ядра CMS.
- Шаблонизатор: Twig 3.x.
- База данных: MySQL 8.0 (движок InnoDB).

## Архитектурные правила
- Весь код плагина должен находиться строго в директории `/plugins/cdek_delivery/`.
- Модели данных наследуются от базового класса `\Core\Model`. Использование чистого PDO запрещено.
- Все внешние запросы к API СДЭК должны проходить через сервис-обертку `app/services/CdekApiWrapper.php` с автоматическим повтором при ошибке 5xx.
- Логирование ведется через PSR-3 логгер в файл `var/log/plugins/cdek.log`.

## Доступы
Тестовый API-ключ СДЭК хранится в .env: `CDEK_API_TOKEN_TEST`. Пароль от тестовой БД: root/qwerty.

Когда агент читает этот файл, он перестает предлагать решения на Python или использовать синтаксис старых версий языка. Он понимает границы дозволенного.

Что такое AGENTS.md: Инструкция по применению и кодекс поведения

Если CONTEXT.md говорит модели, где она находится, то AGENTS.md говорит ей, как именно нужно действовать. Это динамический свод правил, сценариев и предпочтений. Это должностная инструкция для сотрудника.

В строительной аналогии AGENTS.md — это технологические карты: «кирпич класть только на цемент марки М500», «штробить стены только алмазной коронкой после 11 утра», «каждое утро прораб проверяет вертикаль уровнем». Это правила процесса.

Что обычно пишут в AGENTS.md:

1. Алгоритм работы над задачей. Сначала пишем юнит-тест -> затем реализуем функцию -> запускаем линтер -> коммитим изменения. Или наоборот: сначала черновик архитектуры, потом реализация.
2. Стиль написания кода. «Всегда добавляй doc-блоки к публичным методам», «Называй переменные только на английском», «Не используй короткие имена вроде $i или $n вне циклов».
3. Правила тестирования. «Перед тем как отдать код, ты обязан запустить команду phpunit --filter=DeliveryTest», «Никогда не мокай базу данных, используй транзакции тестов».
4. Запрещенные действия. «Никогда не изменяй миграционные файлы, которые уже применены на production», «Не трогай ядро CMS, только хуки и события».
5. Формат вывода результата. «Сначала присылаешь diff изменений, затем краткое резюме текстом», «Если нашел уязвимость, опиши ее до того, как покажешь исправление».
6. Работа с секретами. Алгоритм действий, если в коде обнаружен hardcoded пароль (остановиться, удалить, сообщить пользователю).

Пример фрагмента AGENTS.md для той же задачи:

# AGENTS.md — Правила разработки

## Порядок действий при создании новой функции
1. Проанализируй существующие контроллеры в /controllers/. Следуй их структуре.
2. Прежде чем писать код бэкенда, создай макет формы в Twig. Согласуй поля со списком обязательных параметров API СДЭК (см. документацию в /docs/sdek_api_v2.pdf).
3. Реализуй логику. Всегда оборачивай вызов внешнего API в блок try-catch.
4. Напиши Unit-тест для сервиса `CdekApiWrapper`. Проверь сценарий, когда API возвращает ошибку "Неверный город".
5. Запусти линтер: `vendor/bin/phpcs --standard=PSR12 ./plugins/cdek_delivery/`.

## Стиль ответов
- Если я прошу "исправь баг", не переписывай весь файл целиком. Дай точечный дифф.
- Если решение требует выбора из нескольких вариантов, предложи Вариант А (быстрый, но с костылем) и Вариант Б (правильный, долгий). По умолчанию делай Вариант Б.
- Никогда не выводи реальные значения из .env файла в консоль или комментарии.

Этот файл заставляет модель следовать вашим внутренним процессам, а не общепринятым нормам из интернета.

В чем принципиальная разница: Контекст против Поведения

Главная ошибка новичков — сваливать всё в один файл или путать их назначение.

Контекст нужен, чтобы модель дала релевантный ответ. Агентские правила нужны, чтобы модель дала качественный и ожидаемый ответ. Без контекста искусственный интеллект предложит подключить PayPal к вашему магазину на российской CMS, используя библиотеки для Node.js. Без агентов он напишет рабочий, но кривой, недокументированный и непроверенный код, который развалится при первом же пулл-реквесте.

Типичные ошибки пользователей и разработчиков

За последний год сформировался целый антипаттерн работы с этими файлами. Вот самые частые ловушки:

Ошибка 1: Смешивание жанров («Мусорный бак») Разработчик создает CONTEXT.md и начинает писать туда: «Когда работаешь с заказами, всегда проверяй наличие товара на складе». Это правило поведения, оно должно лежать в AGENTS.md. В контексте должна остаться лишь констатация факта: «Проверка остатков реализована в сервисе InventoryService::checkStock()». Когда файлы смешаны, модель начинает игнорировать важные технические детали, теряясь в потоке инструкций.

Ошибка 2: Дефицит конкретики (Проект-призрак) Писать в контексте «Используем современные подходы» или «Код должен быть чистым» — бесполезно. Для модели слова «современный» и «чистый» означают миллионы строк кода из обучающей выборки. Нужно конкретно: «Используй типажи (Traits) для переиспользования методов сущностей вместо абстрактных родителей» или «Максимальная длина строки — 120 символов».

Ошибка 3: Ложные пути и устаревшие данные Указание в CONTEXT.md путей к файлам, которые поменялись три месяца назад во время рефакторинга — лучший способ свести ИИ с ума. Нейросеть будет упорно искать класс UserManager.php по старому адресу, генерировать импорт, получать ошибку от интерпретатора и пытаться исправить её еще более странными способами, попадая в бесконечный цикл. Правило простое: обновил структуру — обнови контекст.

Ошибка 4: Игнорирование масштаба (Монолит в правилах) Попытка описать правила для монолита на 500 тысяч строк и для маленького одностраничного плагина одними и теми же требованиями. Для тяжелого энтерпрайза важны строгие контракты и DDD, для плагина CMS важна легкость и отсутствие прямых запросов к таблицам ядра. Избыточные правила делают агента медленным и слишком консервативным.

Ошибка 5: Конфиденциальность в открытом доступе Хардкод реальных паролей, токенов продакшена или персональных данных клиентов прямо в теле файлов. Эти файлы часто попадают в репозиторий. Используйте плейсхолдеры (YOUR_TOKEN_HERE) или ссылки на защищенное хранилище секретов.

Понятные примеры: От теории к практике

Давайте разберем реальную задачу, близкую аудитории разработчика модулей: нам нужно добавить в наш компонент поле «ИНН клиента» и передавать его в API транспортной компании.

Как сработает модель БЕЗ этих файлов: Она посмотрит на название вашей CMS, погуглит (виртуально) документацию, найдет самую популярную CRM в мире (например, Salesforce или Magento) и попытается применить их архитектуру. Она создаст отдельный микросервис на Go, хотя у вас процедурный PHP, забудет экранировать данные перед записью в БД и назовет таблицу user_inn_data_raw_final_v2. Код придется переписывать с нуля.

Как сработает модель С правильными CONTEXT.md и AGENTS.md:

1. Чтение CONTEXT.md: Модель видит, что мы работаем внутри компонента /components/my_courier/. Она знает, что таблицы создаются через файл install.sql, а ORM не используется, запросы пишутся через $db->query(). Она находит, что API-токен курьера берется из config.php.
2. Чтение AGENTS.md: Модель видит инструкцию: «При изменении схемы БД всегда предоставляй UP и DOWN миграции», «Любые новые поля ввода должны проходить валидацию через стандартный валидатор ядра CMS», «После добавления поля обнови языковые файлы lang/ru.php».
3. Результат: Модель выдает готовый SQL-запрос для ALTER TABLE, добавляет строку в массив локализации, правит шаблон .tpl, вставляет проверку if (!preg_match('/^\d{10,12}$/', $inn)) и меняет запрос к API курьера, добавив туда параметр &customer_inn=.... Вам остается только нажать кнопку «Применить». Время на ревью сокращается с часа до пяти минут.

Почему это особенно важно для экосистемы WordPress, Bitrix и других CMS

Разработка плагинов и модулей для популярных систем имеет свою специфику. У них есть жесткие рамки безопасности и структуры.

• WordPress: В CONTEXT.md стоит указать версию PHP, факт использования хуков (actions/filters) вместо ООП-внедрения зависимостей и путь до wp-content/plugins/. В AGENTS.md обязательно прописать: «Все выводы в браузер пропускать через esc_html() или wp_kses_post()», «Прямые SQL-запросы запрещены, используем $wpdb->prepare()».
• 1С-Битрикс: В контексте указываем D7 или старую архитектуру, местоположение /local/templates/ и ключи кеша. В правилах агента: «Инфоблоки создавать только через миграционную систему, руками не лезть в БД», «Обязательно проверять права доступа пользователя через CMain::CanDoOperation()».

Без этих файлов ИИ будет постоянно пытаться тащить в Битрикс чистый Composer без учета ядра, а в WordPress — изобретать собственные функции очистки данных, забывая про встроенные sanitize_text_field().

Как внедрить это в свой проект: пошаговая стратегия

1. Начните с малого. Не пытайтесь сразу описать монолит на 10 лет разработки. Начните с одного репозитория или даже одной сложной папки (например, /engine/payments/).
2. Соберите Context методом интервью. Откройте терминал, выполните ls -la, посмотрите версии в composer.json или package.json. Выпишите главные архитектурные решения. Достаточно 50–100 строк текста.
3. Выпишите свои боли. Вспомните последние 5 комментариев тимлида к вашему коду или коду джуна. «Почему опять нет тестов?», «Зачем ты написал эту функцию на 150 строк?». Переведите эти претензии на язык инструкций для робота и положите в AGENTS.md.
4. Разместите файлы правильно. Обычно их кладут в корень репозитория. Некоторые IDE и агенты (например, Cursor или Zed) ищут их автоматически. Если используете кастомного агента, убедитесь, что в системном промпте передана команда: Read files CONTEXT.md and AGENTS.md before generating any code.
5. Версионируйте вместе с кодом. Эти файлы — часть вашего продукта. Изменилась архитектура — создайте новую ветку, поправьте .md файлы и отправьте в PR. Это отличный способ документировать изменения для всей команды, включая людей.
6. Проведите аудит. Скормите ваши файлы пустой модели и попросите: «Я даю тебе CONTEXT.md и AGENTS.md нашего проекта. Перескажи своими словами архитектуру и основные правила работы». Если модель поняла всё верно — файлы составлены удачно.

Будущее стандартизации

Появление CONTEXT.md и AGENTS.md — это естественный этап взросления индустрии разработки с помощью ИИ. Подобно тому, как раньше появились README.md (для людей) и .gitignore (для инструментов), теперь появился стандарт общения с автономными агентами.

Крупные платформы постепенно подтягиваются: GitHub Copilot официально поддерживает мнемонику настроек, JetBrains интегрирует чтение этих файлов в локальные LLM-модели. Рано или поздно поддержка станет нативной везде. Те, кто научится писать качественные инструкции сейчас, получат колоссальное преимущество в скорости разработки завтра. Ваши агенты будут тратить 90% времени на написание полезной бизнес-логики и только 10% — на борьбу с синтаксисом и структурой проекта.