Что такое файл DESIGN.md и зачем он нужен AI-агентам

Что такое DESIGN.md и чего не охватывает AGENTS.md

DESIGN.md — это файл в формате Markdown в корне вашего репозитория, который объясняет AI-агенту для написания кода, почему архитектура проекта устроена именно так. AGENTS.md отвечает на другой вопрос: как здесь работать. Сюда входят команды сборки, тестирования, линтеры, которые должны проходить проверку, и пути, которые нельзя трогать. В DESIGN.md фиксируются уже принятые решения и описывается, что сломается, если одно из них будет отменено.

Агент для написания кода — например, инструмент вроде Claude Code или Cursor, который самостоятельно читает и редактирует ваш репозиторий, — по умолчанию действует самоуверенно. Он находит шаблон, который ему не знаком, и «улучшает» его. Самописный кэш превращается в Redis (хранилище данных в оперативной памяти), потому что именно так выглядит кэш в большинстве кода, на котором обучалась модель. Файл AGENTS.md не предотвращает это, так как make test проходит в обоих случаях. Правило, которое было нарушено, нигде не было записано в доступном для агента виде.

Если вы еще не создали первый файл, начните с него. AGENTS.md и файл HUMAN.md, который находится рядом описывает формат и места, где каждый инструмент ищет эти файлы. Далее следует глава, идущая после этой.

Что на самом деле находится внутри опубликованного DESIGN.md

Самый быстрый способ изучить формат — прочитать файлы, которые компании публикуют о себе. Репозиторий official-design-md отслеживает только такие файлы. Правило включения в него состоит из одной строки, и эта строка — главный смысл всей коллекции:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

По состоянию на август 2026 года в списке семь компаний: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel и VoltAgent. Каждый файл доступен по постоянной публичной ссылке, поэтому вы можете прочитать любой из них в терминале прямо сейчас.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

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

Файл Nuxt содержит около 2100 слов, и большая его часть представляет собой правило с приложенным к нему обоснованием:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

Файл Vercel длиннее, около 6500 слов на август 2026 года, и он идет на шаг дальше. Один из его заголовков — Reject generated-design reflexes. Под ним находится список того, к чему обращается функциональный генератор, если ему не дали иных указаний:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

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

Почему компании публикуют собственные DESIGN.md?

Сообщество опередило их. В репозитории awesome-design-md собрано 73 файла, полученных методом обратной разработки публичных веб-сайтов. Каждый из них написан по единому формату из девяти разделов, что позволяет направить агента на такой файл и получить результат, близкий к оригиналу. Эти файлы полезны, но они остаются лишь предположениями. Никто из представителей компаний их не проверял.

Файл от первого лица отличается тем, что он является первоисточником, а не интерпретацией результата. Когда Vercel меняет масштаб шрифтов, vercel.com/design.md меняется вместе с ним. Копия, полученная парсингом в марте, продолжает обучать вашего агента старым параметрам, и в вашем репозитории нет механизмов, которые сообщили бы об устаревании этой копии.

Семь издателей — это небольшое число, о чем прямо говорится в репозитории: стандарт новый, и его официальное принятие растёт. Обе коллекции поддерживаются VoltAgent, фреймворком для агентов с открытым исходным кодом, который также публикует свой собственный файл. Поэтому воспринимайте этот список как инструмент отслеживания, а не как нейтральную перепись. Тем не менее, за ним стоит следить из-за того, кто именно входит в эту семёрку. Это компании, чей фронтенд-код разработчики копируют чаще всего, и их файлы становятся эталонным примером того, что такое DESIGN.md. Сравните путь, который прошел AGENTS.md: agents.md сейчас насчитывает более 60 000 проектов с открытым исходным кодом, использующих этот формат, а управление им перешло к Agentic AI Foundation под эгидой Linux Foundation. Соглашения для файлов, читаемых агентами, быстро устоялись, и они формируются «сверху вниз».

Что включать в DESIGN.md, если у проекта нет пользовательского интерфейса

Большинство программ, работающих на VPS, не имеют визуальной составляющей, которую нужно описывать. Тем не менее, этот файл необходим, так как его назначение не связано с цветами или оформлением. Он нужен для фиксации ограничений, которые уверенный в себе редактор кода может нарушить, даже не заметив этого.

Инварианты. По одному предложению на каждый, описывающему условие, которое должно оставаться истинным после любого изменения. «Любая запись проходит через queue.enqueue(). Прямая запись в базу данных минует журнал аудита, а именно из него данные попадают в отчет для проверки соответствия требованиям». Инвариант с указанием причины переживет задачу, которую вы не могли предвидеть. Инвариант без пояснения воспринимается как предпочтение, а предпочтения часто оптимизируют до их исчезновения.

Отклоненные альтернативы. Очевидный вариант и причина, по которой он был отвергнут. «Мы не используем Redis для кэширования. Сервис работает на одном VPS, поэтому встроенная в процесс карта (in-process map) быстрее, к тому же это на один демон меньше, который нужно поддерживать в рабочем состоянии. Вернуться к этому вопросу, когда появится второй сервер приложений». Без этого абзаца исполнитель, получивший задачу ускорить кэш, добавит Redis, и он будет прав: вы не сообщили ему об ограничении. Этот раздел окупает создание всего файла.

Границы. Места, где небольшое изменение имеет большой радиус поражения. Схема базы данных. Префикс публичного маршрута, по которому клиенты уже настроили свои скрипты. Файл конфигурации, который считывается перед запуском приложения. Запись в cron, предполагающая, что запущена только одна копия процесса. Перечислите их и укажите стоимость изменения для каждого.

Словарь. Если в коде используется tenant, а команда называет это customer, запишите это соответствие. Исполнитель, который угадает неверно, напишет код, который выглядит корректно, но моделирует не то, что нужно. Это самый сложный тип ошибок для обнаружения при проверке кода.

Проектировочный документ DESIGN.md для использования сегодня

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

Заполните два раздела, которые вы можете описать прямо сейчас: инварианты и отвергнутые альтернативы. Остальные разделы оставьте в виде заголовков. Файл из четырех честных строк лучше, чем файл из сорока догадок.

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

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

Инварианты

Отвергнутые альтернативы

Архитектура

Модель данных

Антипаттерн: файл DESIGN.md, дублирующий README

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

Это обходится вам вдвойне. Первая цена — контекст. Файл, который агент считывает в начале каждой задачи, оплачивается при каждом выполнении, и дублирующийся раздел установки — это чистые накладные расходы в рамках фиксированного окна. Управление этим окном — отдельный навык, описанный в управлении контекстным окном в Claude Code. Кратко: всё, что загружается автоматически, должно быть самым ценным текстом в репозитории.

Вторая цена хуже. Две копии одного и того же утверждения со временем расходятся. В README сказано, что сервис слушает порт 8080, в DESIGN.md всё ещё указан 3000, а у агента нет способа определить, какой из них верный, поэтому он выбирает один и пишет код на его основе. К файлу, который иногда ошибается, относятся с тем же доверием, что и к файлу, который всегда прав.

Проверка проста. Если абзац органично смотрится в README, удалите его из DESIGN.md. То, что останется, должно быть тем, что вы произнесли бы вслух на код-ревью — тем, что начинается со слов «мы уже пробовали это».

Как понять, что файл работает?

Линтера для этого не существует. Есть проверка, которую можно выполнить за минуту.

Дайте агенту задачу, которая напрямую затрагивает инвариант. Например: «Добавь фоновую задачу, которая помечает устаревшие строки как истекшие». Файл, который выполняет свою функцию, проявит себя в ответе еще до написания кода: агент должен сообщить, что задача выполняет запись через queue.enqueue(), так как прямая запись пропустила бы аудит-лог. Если агент открывает соединение с базой данных и пишет напрямую, верно одно из двух: файл вообще не считывается или инвариант сформулирован недостаточно строго, что позволяет его игнорировать.

Также следите за количеством токенов, так как этот файл загружается на каждом шаге. Если потребление контекста резко возрастает после добавления DESIGN.md, а качество ответов не улучшается, значит, файл содержит текст, который агент и так уже «знает». В чтении счетчиков токенов в Claude Code показано, на что расходуется этот бюджет.

Это особенно важно, когда агент работает на сервере, а не на вашем ноутбуке. Агент в долгоживущей сессии, например, в конфигурации рабочего пространства Claude Code на VPS с tmux, не хранит память о вчерашнем разговоре. Репозиторий — это и есть память. Все, что вы объяснили в чате и не зафиксировали в коммите, исчезнет к следующей сессии, поэтому DESIGN.md — это место, где такие пояснения сохраняются.

Начните с решений, по которым возникают споры

Первая версия занимает двадцать минут. Откройте последние несколько pull requests, где рецензент написал «нет, у нас это делается иначе». Каждый такой комментарий — это инвариант, который никогда не был зафиксирован письменно. Это те места, где агент совершит ту же ошибку, причем быстрее и чаще, чем человек. Добавляйте правила в файл, когда он вас подводит, а не по расписанию. Если вы все еще определяете место агентов в обычном процессе разработки, руководство по изучению AI-агентов 2026 года станет подходящим следующим шагом.

FAQ

Является ли DESIGN.md официальным стандартом?

Не в том смысле, в каком им является AGENTS.md. У AGENTS.md есть официальный ресурс agents.md, его используют более 60,000 проектов с открытым исходным кодом, а его развитие курирует Agentic AI Foundation, входящий в состав Linux Foundation. По состоянию на август 2026 года у DESIGN.md нет управляющего органа и опубликованной спецификации. Однако он получил поддержку от первоисточников: семь компаний, включая Vercel, Nuxt, Atlassian и Resend, публикуют его по общедоступному URL, а в сообществе собрано еще 73 примера, восстановленных по публичным сайтам. Рассматривайте это как соглашение, которое можно принять прямо сейчас и свободно расширять, поскольку названия разделов ничем не регламентированы.

Должен ли DESIGN.md быть просто разделом в AGENTS.md?

Для небольшого репозитория — да. Один файл, который агент гарантированно прочитает, лучше, чем два файла, один из которых будет проигнорирован. Разделяйте их, когда AGENTS.md перестает легко читаться или когда вы замечаете, что эти две части меняются с разной частотой. AGENTS.md меняется при изменении сборки. DESIGN.md меняется при изменении проектного решения, что происходит реже и имеет больший вес. При разделении добавьте в AGENTS.md одну строку с указанием агенту читать DESIGN.md перед внесением правок в код, так как не каждый инструмент загружает все файлы markdown из корня проекта.

Чем DESIGN.md отличается от записи архитектурного решения (ADR)?

ADR (architecture decision record) — это датированная запись об одном конкретном решении, и в здоровом проекте их накапливаются десятки в отдельной папке. Это история, а историю дорого загружать, так как агенту пришлось бы прочитать их все, чтобы понять, какие из них все еще актуальны. DESIGN.md — это текущее состояние, написанное для того, чтобы его читали целиком при каждой задаче. Используйте оба формата, если вы уже ведете ADR. ADR фиксирует, что было решено и когда. DESIGN.md фиксирует, что является истинным на сегодняшний день, и именно на него вы ссылаетесь при работе с агентом.

Каким по объему должен быть DESIGN.md?

Достаточно коротким, чтобы его можно было загружать при каждом обращении без лишних затрат. Опубликованные примеры велики, потому что они описывают целый визуальный язык: файл Nuxt содержит около 2,100 слов, а файл Vercel — около 6,500 по состоянию на август 2026 года. Для бэкенд-сервиса обычно требуется гораздо меньше. Начните с одной страницы и увеличивайте её только тогда, когда агент совершает ошибку, которую можно было бы предотвратить одним предложением. Длина — не показатель. Каждая строка должна содержать информацию, которую агент иначе интерпретировал бы неверно.