DESIGN.md: навіщо він потрібен після AGENTS.md

Що таке DESIGN.md і чого не охоплює AGENTS.md

DESIGN.md — це файл у форматі markdown у корені репозиторію. Він пояснює AI-агенту для написання коду, чому код має саме таку структуру. AGENTS.md відповідає на інше запитання: як працювати в цьому репозиторії. У ньому вказують команду складання, команду тестування, перевірки lint, які мають завершуватися успішно, і шляхи, яких не можна змінювати. 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.

Станом на August 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

Обидва документи описують design system. У них зазначено, який вигляд має мати продукт: кольори, типографіка, відступи та анімація. Не зосереджуйтеся на предметній області. Важливіша структура тексту, а не його тема.

Файл Nuxt містить приблизно 2,100 слів. Більша його частина — це правило з поясненням причини:

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 довший: станом на August 2026 він містить близько 6,500 слів. Він іде ще далі. Один із його заголовків — 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 — open source фреймворк для агентів, який також публікує власний файл. Тому сприймайте цей список як трекер, а не як нейтральний перепис. Стежити за ним усе одно варто через те, хто входить до цієї сімки. Це компанії, чий front-end код найчастіше копіюють інші розробники. Їхні файли стають практичним прикладом того, яким має бути DESIGN.md. Порівняйте цей шлях зі шляхом AGENTS.md: agents.md тепер налічує понад 60,000 open source проєктів, що використовують цей формат, а опікування ним здійснює Agentic AI Foundation у складі Linux Foundation. Угоди щодо файлів, придатних для читання агентами, швидко формуються, і формуються вони згори.

Що має містити DESIGN.md, якщо в проєкті немає інтерфейсу користувача

Більшість програмного забезпечення, що працює на VPS, не має візуальної мови, яку потрібно описувати. Водночас цей файл залишається корисним, оскільки його призначення не пов’язане з кольорами. Він фіксує обмеження, які впевнений редактор інакше міг би ненавмисно порушити.

Інваріанти. Одне речення для кожного інваріанта. Воно має описувати те, що повинно залишатися істинним після будь-якого редагування. "Кожен запис проходить через queue.enqueue(). Прямий запис у базу даних оминає журнал аудиту, а саме його читає compliance-експорт." Інваріант із поясненням причини залишається зрозумілим навіть у непередбаченому завданні. Інваріант без пояснення виглядає як уподобання, а уподобання зазвичай вилучають під час оптимізації.

Відхилені альтернативи. Очевидний варіант і причина, через яку його не обрали. "Ми не використовуємо Redis для кешування. Сервіс працює на одному VPS, тому map у процесі працює швидше, а підтримувати потрібно на один daemon менше. Поверніться до цього рішення, коли з’явиться другий сервер застосунків." Без цього абзацу агент, якому доручили пришвидшити кеш, додасть Redis, і це буде правильним рішенням: ви не повідомили йому про обмеження. Саме цей розділ виправдовує існування всього файлу.

Межі. Місця, де невелика зміна може мати значні наслідки. Схема бази даних. Префікс публічних маршрутів, з яким уже працюють клієнтські скрипти. Конфігураційний файл, який deploy читає перед запуском застосунку. Запис cron, що передбачає запуск лише однієї копії. Назвіть їх і вкажіть, якою буде вартість зміни кожного з них. Якщо агент також має доступ до відкритого вебу, наприклад через self-hosted інстанс SearXNG, підключений як його бекенд пошуку, це теж варто зафіксувати як межу. У файлі потрібно зазначити, який отриманий текст може впливати на код, а який дозволено лише цитувати вам.

Термінологія. Якщо в коді використовується tenant, а команда каже customer, зафіксуйте відповідність. Агент, який неправильно вгадає тут, створить код, що добре читається, але моделює не те. Це найскладніший тип помилки для виявлення під час review.

Файл 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. Має залишитися те, що ви сказали б уголос під час code review, — те, що починається словами: «Ми вже це пробували».

Як дізнатися, чи працює файл?

Для цього немає linter. Є перевірка, яку можна виконати за хвилину.

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

Також стежте за кількістю токенів, оскільки цей файл завантажується на кожному кроці. Якщо після додавання DESIGN.md використання контексту зростає, а відповіді не стають кращими, файл містить текст, який агент уже мав. У Читання лічильників токенів у Claude Code показано, куди витрачається цей бюджет.

Це особливо важливо, коли агент працює на сервері, а не на вашому ноутбуці. Агент, який працює в довготривалій сесії, як у прикладі робочого середовища Claude Code на VPS із tmux, не пам’ятає вчорашню розмову. Репозиторій є його пам’яттю. Усе, що ви пояснили в чаті й не зафіксували в репозиторії, зникне до наступної сесії. DESIGN.md — це місце, де потрібно зберігати такі пояснення, щоб вони не втрачалися.

Почніть із рішень, щодо яких у вас виникають суперечки

Перша версія займе двадцять хвилин. Відкрийте останні кілька pull request, у яких рецензент написав: «ні, тут ми робимо інакше». Кожен такий коментар — це інваріант, який ніколи не був задокументований, і кожен із них — місце, де агент припуститься тієї самої помилки швидше й частіше, ніж людина. Доповнюйте файл, коли він підводить вас, а не за розкладом. Якщо ви ще з’ясовуєте, як інтегрувати агентів у звичайний процес розроблення, посібник 2026 року з вивчення AI-агентів — цілком доречний наступний крок.

FAQ

DESIGN.md є офіційним стандартом?

Не в тому самому сенсі, що AGENTS.md. AGENTS.md має власний сайт agents.md, його використовують понад 60,000 open source проєктів, а опікується ним Agentic AI Foundation у складі Linux Foundation. Станом на August 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 (запис архітектурного рішення) — це датований запис про одне рішення. У добре організованому проєкті таких записів у каталозі накопичуються десятки. Це історія, а завантаження історії потребує ресурсів: агенту довелося б прочитати всі записи, щоб визначити, які з них досі актуальні. DESIGN.md описує поточний стан і призначений для повного прочитання під час кожного завдання. Якщо ви вже створюєте ADR, використовуйте обидва формати. ADR описує, що і коли було вирішено. DESIGN.md описує, що є актуальним сьогодні; саме на нього слід посилати агента.

Якої довжини має бути DESIGN.md?

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