DESIGN.md: файл після AGENTS.md для рішень у коді

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

DESIGN.md — це markdown-файл у корені репозиторію. У ньому пояснюється, чому код має саме таку структуру. 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.

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

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

Станом на October 27, 2026 файл Nuxt містить приблизно 2,000 слів, і більшість його положень — це правило з поясненням причини. На початку зазначено, що темна тема є темою за замовчуванням. У ньому вказано фірмовий зелений колір #00DC82 із приміткою, що фірмові кольори призначені «для логотипів, зображень для соціальних мереж і друкованих матеріалів. Не використовуйте їх як вихідні значення в коді UI». Ближче до кінця розділ із заголовком Reject these містить:

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

Файл Vercel довший — приблизно 6,000 слів станом на October 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, який варто додати до репозиторію, є таким списком для певної предметної області.

Чому компанії публікують власні DESIGN.md?

Спільнота започаткувала це першою. У репозиторії awesome-design-md зібрано 84 файли, вилучені з публічних вебсайтів, за підрахунком у його README станом на October 27, 2026. Кожен файл написано в однаковому форматі з дев’яти розділів, тому агенту можна вказати на один із них і отримати результат, близький до цього стилю. Ці файли корисні, але вони все одно є припущеннями. Ніхто з відповідних компаній їх не перевіряв.

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

Одинадцять видавців — це все ще невелика кількість, і репозиторій прямо це зазначає: стандарт новий, а офіційне впровадження розширюється. Обидві колекції підтримує VoltAgent — open source фреймворк для агентів, який також публікує власний файл. Тому сприймайте цей список як трекер, а не як нейтральний перепис. За ним усе одно варто стежити з огляду на представлені в ньому компанії. Деякі з них — це компанії, чий front-end код найчастіше копіюють інші розробники. Новіші записи, Ant Design, Microsoft FAST, Juspay і Oxide Computer, — це design systems, на яких будують свої рішення інші команди. Їхні файли стають практичним прикладом того, яким має бути DESIGN.md. Порівняйте шлях AGENTS.md: agents.md тепер налічує понад 60,000 open source проєктів, що використовують цей формат, а опікування ним здійснює Agentic AI Foundation у складі Linux Foundation. DESIGN.md почав рухатися тим самим шляхом. On April 21, 2026, Google опублікувала у відкритому доступі проєкт специфікації цього формату під назвою google-labs-code/design.md, зі схемою токенів і CLI за ліцензією Apache-2.0. Станом на October 2026 формат має версію alpha і все ще активно розробляється. Його підтримує Google Labs, а не нейтральний фонд. Крім того, формат описує visual identity, тому не визначає інваріанти, необхідні для backend-файлу. Конвенції для файлів, які читають агенти, швидко формуються, і цей процес іде згори.

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

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

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

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

Межі. Місця, де невелика зміна має великий радіус впливу. Схема бази даних. Префікс публічних маршрутів, із яким уже працюють клієнтські скрипти. Файл конфігурації, який deploy читає перед запуском застосунку. Запис cron, що передбачає запуск лише однієї його копії. Назвіть їх і вкажіть, чого коштує зміна кожного з них. Якщо агент також має доступ до відкритого вебу, наприклад через self-hosted екземпляр 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 у monorepo: короткий кореневий файл для рішень, спільних для всіх, і менший файл поруч із кожним пакетом, який має власні рішення.

Деякі інструменти завантажують усі 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. Є перевірка, яку можна виконати за хвилину.

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

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

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

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

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

FAQ

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

Не в тому сенсі, як AGENTS.md. AGENTS.md має власну сторінку на agents.md, його використовують понад 60,000 open source проєктів, а опікується ним 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, публікують такий файл. Станом на 27 жовтня 2026 року спільнота зібрала ще 84 файли, вилучені з публічних сайтів. Для backend-файлу з інваріантами та відхиленими альтернативами сприймайте його як угоду, яку можна використовувати вже зараз і вільно розширювати, оскільки жодна специфікація не визначає назви цих розділів.

Чи має DESIGN.md бути просто розділом AGENTS.md?

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

Чим DESIGN.md відрізняється від architecture decision record?

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

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

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