Почему форматов несколько и что с этим делать
До августа 2025 года картина выглядела так: Cursor хотел .cursorrules, Claude Code — CLAUDE.md, GitHub Copilot — .github/copilot-instructions.md, Aider — CONVENTIONS.md. Серьёзный проект поддерживал пять почти одинаковых файлов чтобы каждый агент работал нормально.
В августе 2025 OpenAI предложил AGENTS.md как вендор-нейтральный стандарт. В декабре 2025 формат передали в Linux Foundation вместе с Model Context Protocol. К маю 2026 AGENTS.md читают нативно все крупные агенты и он используется в 60 000+ публичных репозиториев.
Но старые форматы живы — и у каждого есть причина существовать.
Пять форматов: чем отличаются
AGENTS.md — универсальный стандарт
Самый простой и самый совместимый. Markdown-файл в корне репозитория без обязательной структуры. Читают: Cursor, Claude Code, GitHub Copilot, Gemini CLI, Aider, Windsurf, Zed и ещё 20+ агентов.
Принцип nearest-file-wins: можно положить AGENTS.md в корень для глобальных правил, и отдельные AGENTS.md в подпапки — для пакетных правил. OpenAI держит в своём монорепозитории 88 таких файлов.
Когда использовать: если в команде разные инструменты, если проект open-source, если нужен один источник правды для всех.
CLAUDE.md — для Claude Code с памятью
То же что AGENTS.md, но с трёхуровневой моделью памяти:
- ~/.claude/CLAUDE.md — личные предпочтения, работают во всех проектах на машине
- ./CLAUDE.md в корне проекта — командный файл, коммитится в git
- ./CLAUDE.local.md — личные правки для проекта, в .gitignore
Плюс Claude Code сам пишет заметки о проекте в ~/.claude/projects/ /memory/ по ходу работы. Это отдельно от CLAUDE.md который пишешь ты.
Anthropic рекомендует: прямые императивы вместо описаний. «Никогда не используй inline-моки — используй src/test/factories/*» работает лучше чем «мы обычно избегаем inline-моков». Маркеры IMPORTANT, YOU MUST, NEVER статистически повышают точность следования правилам. Файл лучше держать до 200 строк — длиннее и важные правила начинают теряться.
Когда использовать: если работаешь в основном с Claude Code и хочешь персональные + командные + локальные правила раздельно.
.cursor/rules — для Cursor с glob-активацией
Cursor первым добавил условную активацию правил. Файлы живут в .cursor/rules/<название> .mdc с YAML-фронтматтером:
---
description: Правила для GraphQL-слоя
globs:
- "src/graphql/**/*.ts"
alwaysApply: false
---
Четыре режима активации: всегда, по glob-паттерну файлов, по решению агента, вручную. Это самый гибкий формат из всех — но только для Cursor. Другие инструменты его не читают.
Когда использовать: если Cursor — основной инструмент и нужны правила которые включаются только при работе с конкретными файлами. Совместно с AGENTS.md в корне для других агентов.
SKILL.md — задачный контекст по требованию
Принципиально другой формат. Не постоянный контекст, а упакованная экспертиза которая загружается когда задача совпадает с описанием.
---
name: design-system-tokens
description: |
Создаёт, проверяет и документирует токены дизайн-системы.
Используй когда пользователь говорит о токенах, цветах,
типографике, отступах или компонентах.
---
# Правила токенов
- Все цвета в CSS-переменных в `app/globals.css`
- Никогда не создавай новые компоненты если есть существующий
- ...
Фронтматтер — нагрузочная часть. description — это то что Claude читает чтобы решить включать ли скилл. Тело файла читается только после активации. Один скилл на одну задачу, тело — правила а не полная документация.
Когда использовать: для упаковки конкретной экспертизы — токены дизайн-системы, паттерны компонентов, правила публикации.
.cursorrules — устаревший формат Cursor
Предшественник .cursor/rules/. Cursor до сих пор его читает, но новый проект лучше начинать с MDC-формата в .cursor/rules/. Другие инструменты его игнорируют.
DESIGN.md — отдельная история для дизайнеров
Все форматы выше отвечают на вопрос «как работать с кодом». DESIGN.md отвечает на другой вопрос: «как выглядит этот продукт».
Формат придумал Google Stitch — Stitch генерирует его как артефакт дизайн-системы и передаёт агентам. В апреле 2026 Google открыл спецификацию под Apache 2.0. Сейчас его читают Stitch, Claude Code, Cursor, v0 — и любой другой инструмент который захочет поддержать.
DESIGN.md содержит машиночитаемые токены в YAML и человекочитаемые объяснения почему именно такие решения:
## Colors
primary: "#1A1A2E"
accent: "#E94560"
surface: "#F5F5F0"
Цветовая система основана на контрасте тёмного фона и тёплого акцента.
Нейтральный поверхностный цвет используется для карточек и секций.
## Typography
display: "Fraunces"
body: "Bricolage Grotesque"
mono: "JetBrains Mono"
Не использовать: Inter, Roboto, Open Sans.
## Do Not
- Фиолетово-синие градиенты
- Glassmorphism без функционального смысла
- Создавать новые варианты кнопок — использовать существующие
Разница между DESIGN.md и CLAUDE.md с правилами дизайна: CLAUDE.md говорит как работать, DESIGN.md говорит как выглядеть. На практике дизайнеры часто держат оба — DESIGN.md с визуальными правилами и AGENTS.md или CLAUDE.md с рабочими конвенциями.
Repo awesome-claude-design на GitHub собрал 68 готовых DESIGN.md для известных брендов — от Notion до Stripe. 71 000 звёзд за несколько недель после запуска. Это не установка — просто кладёшь нужный файл в корень проекта и AI работает в этом стиле.
Что конкретно писать дизайнеру
Содержание зависит от формата, но логика одна: конкретные правила, а не пожелания.
Для AGENTS.md / CLAUDE.md — рабочие правила:
## Компоненты
- Использовать существующие компоненты по имени: Button/Primary, Card/Default
- Никогда не создавать новый компонент если похожий уже есть
- Называть новые компоненты по схеме: [Категория]/[Вариант]
## Файлы
- Все CSS-переменные только в `app/globals.css`
- Не трогать `src/lib/billing/*`
## Запрещено
- Inter, Roboto, Open Sans, Arial
- Inline-стили — только CSS-переменные и Tailwind-классы
- Фиолетово-синий градиент на белом фоне
Для SKILL.md — дизайн-система как навык:
---
name: brand-design-system
description: |
Правила бренда и дизайн-системы. Используй при работе
с UI, компонентами, токенами, цветами, типографикой.
---
# Токены
| Токен | Значение | Использование |
|-------|----------|---------------|
| --color-primary | #1A1A2E | Фоны, CTA |
| --color-accent | #E94560 | Акценты, hover |
| --font-display | Fraunces | Заголовки H1–H2 |
| --font-body | Bricolage Grotesque | Основной текст |
Таблицы вместо прозы — плотнее по токенам, быстрее читает модель.
Три ошибки которые убивают смысл этих файлов
Писать пожелания вместо правил. «Используй красивую типографику» AI проигнорирует — у него нет понятия «красивый». «Никогда не использовать Inter, Roboto, Open Sans» — конкретное ограничение которое работает. Каждое правило должно быть проверяемым: либо сделано, либо нет.
Делать файл слишком длинным. Anthropic напрямую пишет в документации: если CLAUDE.md слишком длинный, важные правила теряются в шуме. 200 строк — ориентир для одного файла. Если нужно больше — разбить на несколько SKILL.md по темам, каждый загружается только когда нужен.
Написать один раз и забыть. Инструменты меняются, компоненты добавляются, токены переименовываются. Файл который не обновляли три месяца начинает противоречить реальному коду — и AI работает по устаревшим правилам. Раз в квартал достаточно: прочитать, убрать неактуальное, добавить новое.
Какой файл заводить первым
☐ Работаешь в Cursor и больше никуда не планируешь → .cursor/rules/ + AGENTS.md в корне
☐ Работаешь с Claude Code → CLAUDE.md (+ CLAUDE.local.md для личного)
☐ В команде разные инструменты → AGENTS.md как основа
☐ Хочешь упаковать дизайн-систему → SKILL.md для токенов и правил
☐ Хочешь визуальное единство между сессиями → DESIGN.md рядом с AGENTS.md
Реалистичный минимум на старт: один AGENTS.md с запрещёнными шрифтами, именами компонентов и списком папок которые нельзя трогать. Это занимает 20 минут и работает во всех инструментах сразу.
Источник и полная версия: VibeCode Wiki