Файлы контекста для ИИ-агентов: AGENTS.md, SKILL.md, DESIGN.md

В корне репозитория проекта с coding-агентами накапливаются markdown-файлы: AGENTS.md, SKILL.md, .cursorrules, .windsurfrules, copilot-instructions.md. Это руководство объясняет, какой файл за что отвечает, и как не дублировать контекст в пяти местах.

Материал основан на обзоре Jaydeep Karale, проверен по первоисточникам и не проверялся запуском. Данные приведены на сентябрь 2026 года.

Зачем агентам файлы контекста

Новый инженер читает README, задаёт вопросы и перенимает соглашения по ходу работы. У агента этого нет: при каждом старте сессии ему нужен явно записанный контекст. Markdown подошёл, потому что это обычный текст, который одинаково читают люди и модели, а изменения видны в diff.

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

Карта файлов: что за что отвечает

AGENTS.md: общий стандарт

Файл AGENTS.md выпущен в августе 2025 года, а затем передан под управление Agentic AI Foundation (AAIF) при Linux Foundation. По данным OpenAI, к моменту передачи стандарт приняли более 60 000 проектов, а читают его основные агентные инструменты: Codex, Cursor, GitHub Copilot, Gemini CLI, VS Code и другие. Это один канонический файл на репозиторий: команды сборки и тестирования, стиль кода, обязательные для агента ограничения.

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

SKILL.md: переносимая возможность

Если AGENTS.md описывает проект, то SKILL.md описывает отдельную возможность. Навык (skill) — это папка с файлом SKILL.md и, при необходимости, со скриптами и справочными материалами. Формат переносим между Claude Code, Codex, Copilot и другими совместимыми агентами.

Для библиотеки повторных промптов и процедур такой формат удобнее, чем один раздутый AGENTS.md. Поэтому выросли и каталоги вроде skills.sh: навык — обычная папка с Markdown, его легко опубликовать и установить.

Практические правила:

• описание во frontmatter должно быть точным: по нему агент решает, открывать ли файл; размытое описание сводит экономию на нет;
• в SKILL.md выносят возможности, нужные время от времени (деплой, внутренний API); правила для каждой сессии остаются в AGENTS.md;
• десяток невостребованных навыков почти ничего не стоит: агент оплачивает токенами только их описания.

Файлы конкретных инструментов

До общего стандарта каждый инструмент придумал собственное соглашение; эти файлы поддерживаются до сих пор ради обратной совместимости (соответствие инструментов — в карте выше).

Рабочий паттерн для команды с несколькими инструментами: AGENTS.md остаётся единственным источником истины, остальные файлы генерируются из него. Это закрывает типичный сбой: один файл обновили, четыре забыли, и рассинхронизация вернулась.

Пример простейшего скрипта синхронизации:

#!/usr/bin/env bash
# sync-agent-context.sh: AGENTS.md как единый источник истины
set -euo pipefail

cp AGENTS.md .cursorrules
cp AGENTS.md .windsurfrules
mkdir -p .github
cp AGENTS.md .github/copilot-instructions.md

DESIGN.md и узкие форматы

Рядом с универсальными файлами появляются узкие. Например, DESIGN.md кодирует визуальную систему проекта: машиночитаемые дизайн-токены (цвета, отступы, типографика) и обоснования, почему выбраны именно они. Агент, генерирующий интерфейс, получает вместе со значениями и логику выбора. Формат ранний, но направление понятно: отдельные файлы под конкретный срез контекста.

Эталонный шаблон AGENTS.md

Минимальный собранный пример, от которого можно оттолкнуться:

# AGENTS.md

## Команды
<!-- Точные команды с флагами -->
- Сборка: `pnpm build`
- Тесты: `pnpm test -- --run`
- Линт и типы: `pnpm lint && pnpm typecheck`

## Границы
<!-- Что нельзя трогать без отдельной задачи -->
- Не менять миграции в `db/migrations/`
- Не добавлять зависимости без пункта в описании PR

## Критерии готовности
<!-- Задача выполнена, когда всё ниже соблюдено -->
- Сборка, тесты и линт проходят
- Изменения ограничены файлами задачи
- AGENTS.md обновлён, если менялись команды или границы

Дисциплина поддержки

К этим файлам стоит относиться как к коду:

• ревью в том же pull request, что и описываемое изменение;
• устаревшие разделы удаляются сразу;
• раз в несколько месяцев аудит: правила, переехавшие в код, линтеры и типы, из файла убирают;
• каждая строка AGENTS.md читается в каждой сессии, то есть это постоянный расход токенов; очевидное из репозитория в файл не кладут.

Чеклист быстрой проверки

Следующий шаг

Контекст-инжиниринг: как собирать рабочий контекст для моделей нового поколения

Связанные материалы

Статья: Как мы мигрировали AGENTS.md под GPT‑5.6 Sol и не потеряли контроль

Блог: AGENTS.md как операционная дисциплина: десять правил Вайбхава Шристава из OpenAI

База знаний: AGENTS.md / SESSION_NOTES — проектная память для coding-агентов

Собрать такую систему под конкретный репозиторий и стек инструментов проще на живом разборе, чем по общему руководству, особенно если в команде несколько агентов и редакторов.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov