DESIGN.md: файл після AGENTS.md для AI-агента

Що таке 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

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

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

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

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

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

Відхилені альтернативи. Очевидний варіант і причина, через яку його не обрали. «Ми не використовуємо Redis для кешування. Сервіс працює на одному VPS, тому карта в пам’яті процесу працює швидше, а також не потрібно підтримувати роботу ще одного демона. Поверніться до цього рішення, коли з’явиться другий сервер застосунків». Без цього абзацу агент, якого попросили пришвидшити кеш, додасть 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. Має залишитися те, що ви сказали б уголос під час перевірки коду, — те, що починається словами: «ми вже це пробували».

Як визначити, що файл працює?

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

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

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

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

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

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

FAQ

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

Не в тому самому сенсі, що AGENTS.md. Для AGENTS.md є сайт agents.md, його використовують понад 60,000 проектів із відкритим кодом, а опікування ним здійснює 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?

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