DESIGN.md: plik po AGENTS.md dla agenta AI

Czym jest DESIGN.md i czego nie obejmuje AGENTS.md

DESIGN.md to plik markdown w katalogu głównym repozytorium, który wyjaśnia agentowi AI do programowania, dlaczego kod ma określoną strukturę. AGENTS.md odpowiada na inne pytanie: jak pracować w tym repozytorium. Obejmuje ono polecenie kompilacji, polecenie testów, test lint, który musi przejść, oraz ścieżki, których nie należy modyfikować. DESIGN.md dokumentuje decyzje, które zostały już ustalone, oraz problemy powodowane przez ich cofnięcie.

Agent programistyczny, czyli narzędzie takie jak Claude Code lub Cursor, które samodzielnie odczytuje repozytorium i modyfikuje jego zawartość, domyślnie działa z dużą pewnością siebie. Gdy znajdzie nierozpoznany wzorzec, ulepsza go. Ręcznie napisany mechanizm pamięci podręcznej staje się Redis (magazynem danych w pamięci), ponieważ tak wygląda pamięć podręczna w większości kodu, z którym model miał kontakt. AGENTS.md tego nie powstrzymuje, ponieważ make test działa w obu przypadkach. Reguła, która została naruszona, nie była nigdzie zapisana w miejscu dostępnym dla agenta.

Jeśli pierwszy plik nie został jeszcze utworzony, należy zacząć od niego. AGENTS.md i plik HUMAN.md znajdujący się obok niego opisuje format oraz miejsca, w których poszczególne narzędzia go wyszukują. Poniżej przedstawiono kolejny rozdział.

Co znajduje się w opublikowanym pliku DESIGN.md

Najszybszym sposobem poznania formatu jest przeczytanie plików publikowanych przez firmy na swój temat. Repozytorium official-design-md śledzi wyłącznie takie pliki. Zasada uwzględniania ma jedną linię i właśnie na tym polega istota tej kolekcji:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

W sierpniu 2026 znajduje się na niej siedem firm: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel i VoltAgent. Każdy plik jest dostępny pod stałym publicznym adresem URL, dlatego można go od razu odczytać w terminalu.

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

Oba pliki są dokumentami systemu projektowego. Opisują, jak powinien wyglądać produkt: kolorystykę, typografię, odstępy i animacje. Należy wyjść poza tematykę, ponieważ użyteczna jest przede wszystkim forma tekstu, a nie jego temat.

Plik Nuxt ma około 2,100 słów i w większości składa się z reguły wraz z uzasadnieniem:

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"`.

Plik Vercel jest dłuższy — w sierpniu 2026 ma około 6,500 słów — i idzie o krok dalej. Jeden z jego nagłówków brzmi Reject generated-design reflexes. Poniżej znajduje się lista rozwiązań, po które sięga sprawnie działający generator, gdy nie otrzyma instrukcji, aby tego nie robić:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

To zdanie definiuje ten typ pliku. Jest to spisana lista domyślnych rozwiązań generowanych przez pewny siebie model, opublikowana po to, aby model przestał je generować. Każdy plik DESIGN.md, który warto zatwierdzić w repozytorium, jest taką listą dla określonej dziedziny.

Dlaczego firmy publikują własne pliki DESIGN.md?

Społeczność zrobiła to jako pierwsza. awesome-design-md zawiera 73 pliki odtworzone na podstawie publicznych witryn. Każdy plik ma ten sam format składający się z 9 sekcji. Dzięki temu można wskazać agentowi jeden z nich i uzyskać wynik zbliżony do danego wyglądu. Pliki te są przydatne, ale nadal stanowią jedynie przypuszczenia. Nikt z tych firm ich nie sprawdził.

Plik opublikowany przez producenta różni się tym, że jest źródłem, a nie opisem wyniku. Gdy Vercel zmienia skalę typografii, vercel.com/design.md również się zmienia. Kopia pobrana w marcu nadal uczy agenta poprzedniej skali. Żaden element repozytorium nie poinformuje, że kopia stała się nieaktualna.

Siedmiu wydawców to niewielka liczba i repozytorium wyraźnie to zaznacza: standard jest nowy, a jego oficjalne wdrażanie postępuje. Obie kolekcje są utrzymywane przez VoltAgent, platformę open source do tworzenia agentów, która publikuje również własny plik. Listę należy więc traktować jako zestawienie monitorujące, a nie neutralny spis. Nadal warto ją obserwować ze względu na to, kim jest tych siedmiu wydawców. Są to firmy, których kod front-endowy jest najczęściej kopiowany przez innych deweloperów. Ich pliki stają się praktycznym przykładem tego, czym jest DESIGN.md. Warto porównać tę sytuację z drogą, jaką przebył AGENTS.md: agents.md obejmuje obecnie ponad 60,000 projektów open source korzystających z tego formatu, a nadzór nad nim sprawuje Agentic AI Foundation działająca przy Linux Foundation. Konwencje dotyczące plików odczytywanych przez agentów szybko się utrwalają i są kształtowane przez największe podmioty.

Co należy umieścić w pliku DESIGN.md, gdy projekt nie ma interfejsu użytkownika

Większość oprogramowania działającego na VPS nie ma warstwy wizualnej, którą trzeba opisać. Plik nadal jest potrzebny, ponieważ mechanizm nie ma związku z kolorami. Chodzi o zapisanie ograniczeń, które doświadczony edytor w innym przypadku naruszyłby bez zauważenia tego.

Niezmienniki. Każdy niezmiennik powinien być jednym zdaniem określającym warunek, który musi pozostać prawdziwy po każdej edycji. „Każdy zapis odbywa się przez queue.enqueue(). Bezpośredni zapis do bazy danych pomija dziennik audytowy, a eksport zgodności korzysta właśnie z tego dziennika”. Niezmiennik wraz z uzasadnieniem pozostaje zrozumiały także w przypadku zadania, którego wcześniej nie przewidziano. Sam niezmiennik wygląda jak preferencja, a preferencje są pomijane podczas optymalizacji.

Odrzucone alternatywy. Należy wskazać oczywistą opcję oraz wyjaśnić, dlaczego jej nie wybrano. „Nie używamy Redis do buforowania. Usługa działa na pojedynczym VPS, więc mapa w procesie jest szybsza i eliminuje konieczność utrzymywania dodatkowego demona. Należy ponownie rozważyć tę decyzję po uruchomieniu drugiego serwera aplikacji”. Bez tego akapitu agent poproszony o przyspieszenie buforowania doda Redis. Będzie to właściwe działanie, ponieważ ograniczenie nie zostało opisane. Ta sekcja uzasadnia utworzenie całego pliku.

Granice. Należy wskazać miejsca, w których mała zmiana może mieć duży zasięg oddziaływania. Są to między innymi schemat bazy danych, prefiks publicznych tras, z którym klienci już współpracują za pomocą skryptów, plik konfiguracyjny odczytywany przez proces wdrażania przed uruchomieniem aplikacji oraz wpis cron zakładający uruchomienie tylko jednej kopii. Należy je nazwać i określić koszt zmiany każdego z nich.

Słownictwo. Jeżeli kod używa określenia tenant, a zespół określenia customer, należy zapisać tę zależność. Agent, który błędnie ją odgadnie, wygeneruje kod wyglądający poprawnie, lecz opisujący niewłaściwe pojęcie. Jest to najtrudniejszy do wykrycia podczas przeglądu rodzaj błędu.

Plik DESIGN.md do skopiowania już dziś

# 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.

Wypełnij dziś na podstawie pamięci dwie sekcje: niezmienniki i odrzucone alternatywy. Pozostałe sekcje pozostaw jako nagłówki. Plik zawierający cztery rzetelne wiersze jest użyteczny. Plik zawierający czterdzieści zgadniętych wierszy — nie.

Niektóre narzędzia wczytują każdy plik markdown w katalogu głównym repozytorium, a inne wczytują tylko plik wskazany w konfiguracji. Nie zakładaj więc, że działają tak samo. Dodaj odwołanie do AGENTS.md:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

Antywzorzec: DESIGN.md powtarzający zawartość README

Najczęstsza zła wersja dobrze się czyta, ale niczego nie uczy. Zaczyna się od opisu działania projektu, zawiera listę funkcji, wyjaśnia sposób instalacji i kończy się informacjami o licencji. Wszystkie te informacje znajdują się już w README, a żadna z nich nie wyjaśnia, dlaczego przyjęto dane rozwiązania.

To kosztuje podwójnie. Pierwszym kosztem jest kontekst. Za plik odczytywany przez agenta na początku każdego zadania płaci się przy każdym zadaniu, a powielona sekcja instalacji jest czystym narzutem przy stałym limicie kontekstu. Zarządzanie tym limitem jest osobną umiejętnością, opisaną w zarządzaniu oknem kontekstu w Claude Code. W skrócie: wszystko, co jest ładowane automatycznie, powinno mieć najwyższą wartość informacyjną w repozytorium.

Drugi koszt jest poważniejszy. Dwie kopie tego samego stwierdzenia z czasem zaczynają się różnić. README podaje, że usługa nasłuchuje na porcie 8080, a DESIGN.md nadal podaje 3000. Agent nie ma wtedy podstaw, aby ustalić, która informacja ma pierwszeństwo, więc wybiera jedną z nich i na jej podstawie tworzy kod. Plik, który czasami zawiera błędy, jest traktowany z takim samym zaufaniem jak plik, który zawsze zawiera poprawne informacje.

Weryfikacja jest szybka. Jeżeli akapit mógłby bez problemu znaleźć się w README, należy usunąć go z DESIGN.md. Pozostać powinna treść, którą wypowiedziałoby się podczas przeglądu kodu, zaczynająca się od słów: „próbowaliśmy już tego”.

Skąd wiadomo, że plik działa?

Nie ma do tego lintera. Można wykonać test, który zajmuje minutę.

Należy zlecić agentowi zadanie prowadzące bezpośrednio do niezmiennika. „Dodaj zadanie w tle, które oznacza nieaktualne wiersze jako wygasłe”. Plik wykonujący swoje zadanie ujawnia się w odpowiedzi jeszcze przed pojawieniem się kodu: agent powinien wskazać, że zadanie zapisuje dane przez queue.enqueue(), ponieważ bezpośredni zapis pominąłby dziennik audytowy. Jeśli agent otwiera połączenie z bazą danych i wykonuje zapis, prawdziwe jest jedno z dwóch stwierdzeń. Plik w ogóle nie jest odczytywany albo niezmiennik sformułowano na tyle ogólnie, że można go podważać.

Należy również obserwować liczbę tokenów, ponieważ ten plik jest ładowany przy każdej turze. Jeśli po dodaniu DESIGN.md zużycie kontekstu rośnie, a odpowiedzi się nie poprawiają, plik zawiera treść, którą agent już znał. Odczytywanie liczników tokenów w Claude Code pokazuje, na co przeznaczany jest ten budżet.

Ma to największe znaczenie, gdy agent działa na serwerze, a nie na laptopie. Agent pracujący w długotrwałej sesji, takiej jak konfiguracja opisana w workspace Claude Code na VPS z tmux, nie pamięta rozmowy z poprzedniego dnia. Repozytorium jest pamięcią. Wszystko, co wyjaśniono na czacie i czego nigdy nie zatwierdzono, znika podczas następnej sesji, a DESIGN.md jest miejscem, w którym należy umieścić to wyjaśnienie, aby zachować je na przyszłość.

Zacznij od decyzji, o które toczą się spory

Pierwsza wersja zajmuje dwadzieścia minut. Otwórz kilka ostatnich pull requestów, w których recenzent napisał: „nie, tutaj robimy to inaczej”. Każdy z tych komentarzy opisuje niezmiennik, którego nigdy nie zapisano. Każdy wskazuje też miejsce, w którym agent popełni ten sam błąd — szybciej i częściej niż człowiek. Uzupełniaj plik, gdy Cię zawiedzie, a nie według harmonogramu. Jeśli nadal ustalasz, jak włączyć agentów do zwykłego procesu programowania, przewodnik po nauce korzystania z agentów AI na 2026 będzie dobrym kolejnym krokiem.

FAQ

Czy DESIGN.md jest oficjalnym standardem?

Nie w takim znaczeniu jak AGENTS.md. AGENTS.md ma stronę główną pod adresem agents.md, korzysta z niego ponad 60,000 projektów open source, a za jego rozwój odpowiada Agentic AI Foundation, będąca częścią Linux Foundation. Według stanu na sierpień 2026 DESIGN.md nie ma organu zarządzającego ani opublikowanej specyfikacji. Jest natomiast stosowany przez producentów: siedem firm, w tym Vercel, Nuxt, Atlassian i Resend, publikuje taki plik pod publicznym adresem URL, a społecznościowy zbiór zawiera 73 kolejne pliki odtworzone na podstawie publicznych witryn. Należy traktować go jako konwencję, którą można przyjąć już teraz i dowolnie rozszerzać, ponieważ nic nie weryfikuje nazw sekcji.

Czy DESIGN.md powinien być tylko sekcją AGENTS.md?

W małym repozytorium tak. Jeden plik, który agent na pewno odczyta, jest lepszy niż dwa pliki, z których jeden może zostać pominięty. Należy je rozdzielić, gdy AGENTS.md przestaje być łatwy do szybkiego przeglądania albo gdy oba pliki zaczynają zmieniać się w różnym tempie. AGENTS.md zmienia się wraz ze zmianami procesu kompilacji. DESIGN.md zmienia się wraz ze zmianą decyzji, co zdarza się rzadziej i ma większe znaczenie. Po rozdzieleniu plików należy dodać do AGENTS.md jeden wiersz z poleceniem odczytania DESIGN.md przed edycją kodu, ponieważ nie każde narzędzie ładuje wszystkie pliki markdown z katalogu głównego.

Czym DESIGN.md różni się od rejestru decyzji architektonicznych?

ADR (architecture decision record) jest opatrzonym datą zapisem jednej decyzji, a w dojrzałym projekcie gromadzi się ich dziesiątki w jednym katalogu. Jest to historia, a wczytywanie historii jest kosztowne, ponieważ agent musiałby odczytać wszystkie wpisy, aby ustalić, które z nich nadal obowiązują. DESIGN.md opisuje bieżący stan i jest przeznaczony do odczytania w całości przy każdym zadaniu. Jeśli ADR są już stosowane, należy zachować oba rozwiązania. ADR określa, co i kiedy postanowiono. DESIGN.md określa, co obowiązuje obecnie, i do niego należy kierować agenta.

Jak długi powinien być plik DESIGN.md?

Powinien być na tyle krótki, aby można go było wczytywać przy każdej turze bez uzasadnionych obaw. Opublikowane przykłady są długie, ponieważ opisują kompletny język wizualny: według stanu na sierpień 2026 plik Nuxt ma około 2,100 słów, a plik Vercel około 6,500. Usługa backendowa zwykle wymaga znacznie mniej treści. Należy zacząć od jednej strony i rozbudowywać plik tylko wtedy, gdy agent popełni błąd, któremu zapobiegłoby jedno zdanie. Długość nie jest miarą jakości. Każdy wiersz powinien opisywać coś, co agent w przeciwnym razie mógłby wykonać nieprawidłowo.