Что такое 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 года в списке одиннадцать компаний: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel и VoltAgent. Каждый файл доступен по публичному URL: большинство размещено на собственных доменах издателей, остальные — в публичных репозиториях GitHub, поэтому вы можете прочитать любой из них прямо в терминале.

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

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

Файл Nuxt содержит около 2000 слов по состоянию на 27 октября 2026 года, и большая его часть представляет собой правило с приложенным обоснованием. Он начинается с утверждения, что темная тема является стандартной. В нем указан фирменный зеленый цвет #00DC82 с примечанием, что фирменные цвета предназначены «для логотипов, изображений в социальных сетях и печати. Не используйте их как исходные значения в коде пользовательского интерфейса». Ближе к концу раздел с заголовком Reject these включает:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

Файл Vercel длиннее, в нем около 6000 слов по состоянию на октябрь 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 содержится 84 файла, извлеченных с публичных веб-сайтов (по данным README на 27 октября 2026 года). Каждый из них написан в одном и том же формате из девяти разделов, поэтому агенту можно указать на один из них, чтобы он воспроизвел похожий стиль. Эти файлы полезны, но они остаются лишь предположениями. Никто в этих компаниях их не проверял.

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

Одиннадцать издателей — это все еще небольшое число, о чем говорится и в самом репозитории: стандарт новый, и официальное принятие растет. Обе коллекции поддерживаются VoltAgent, фреймворком для агентов с открытым исходным кодом, который также публикует свой собственный файл, поэтому воспринимайте этот список как инструмент отслеживания, а не как нейтральную перепись. За ним все же стоит следить из-за того, кто в нем представлен. Некоторые из них — это компании, чей фронтенд-код другие разработчики копируют чаще всего, а более новые участники, такие как Ant Design, Microsoft FAST, Juspay и Oxide Computer, представляют собой дизайн-системы, на которых строят свои решения другие команды. Их файлы становятся эталонными примерами того, что такое DESIGN.md. Сравните путь, который прошел AGENTS.md: agents.md сейчас насчитывает более 60 000 проектов с открытым исходным кодом, использующих этот формат, а руководство осуществляется Agentic AI Foundation при Linux Foundation. DESIGN.md начал движение по тому же пути. 21 апреля 2026 года Google опубликовала черновик спецификации формата с открытым исходным кодом как google-labs-code/design.md со схемой токенов и CLI под лицензией Apache-2.0. По состоянию на октябрь 2026 года формат находится в версии alpha и все еще активно разрабатывается; он поддерживается Google Labs, а не нейтральным фондом, и описывает визуальную идентичность, поэтому в нем ничего не говорится об инвариантах, необходимых для бэкенд-файла. Соглашения для файлов, читаемых агентами, быстро формируются, и они формируются «сверху».

Что включать в 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. У DESIGN.md есть опубликованная спецификация, но нет нейтрального управляющего органа. Google опубликовала черновик спецификации 21 апреля 2026 года, и он находится в репозитории google-labs-code/design.md под лицензией Apache-2.0. По состоянию на октябрь 2026 года он находится в версии alpha, все еще активно разрабатывается и описывает визуальную идентичность: цвета, типографику, макеты и компоненты. У DESIGN.md также есть принятие от первых лиц: одиннадцать компаний и проектов, включая Vercel, Nuxt, Atlassian и Resend, публикуют его, а коллекция сообщества содержала еще 84 файла, извлеченных с публичных сайтов по состоянию на 27 октября 2026 года. Для бэкенд-файла с инвариантами и отклоненными альтернативами рассматривайте это как соглашение, которое вы можете принять сейчас и свободно расширять, поскольку ни одна спецификация не охватывает эти названия разделов.

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