Что такое 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. Каждый файл доступен по постоянному публичному URL, поэтому вы можете прочитать любой из них прямо в терминале.

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, предполагающая запуск только одной копии процесса. Перечислите их и укажите стоимость изменения для каждого. Если агент также имеет доступ к открытому интернету, например, через самостоятельно развернутый экземпляр SearXNG, подключенный в качестве поискового бэкенда, это тоже граница, которую стоит зафиксировать. Файл должен определять, какой полученный извне текст может влиять на код, а какой — только цитироваться в ответах.

Словарь. Если в коде используется 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.

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

Некоторые инструменты загружают все 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 года. Для бэкенд-сервиса обычно требуется гораздо меньше. Начните с одной страницы и увеличивайте объем только тогда, когда агент совершает ошибку, которую можно было бы предотвратить одной фразой. Объем — не показатель качества. Каждая строка должна содержать информацию, которую агент в противном случае интерпретировал бы неверно.