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. Określa polecenie budowania, polecenie testów, linter, który musi zakończyć się powodzeniem, oraz ścieżki, których nie należy zmieniać. DESIGN.md zapisuje decyzje, które zostały już ustalone, oraz wskazuje, co przestanie działać po cofnięciu którejkolwiek z nich.

Agent programistyczny, czyli narzędzie takie jak Claude Code lub Cursor, które samodzielnie odczytuje i edytuje repozytorium, domyślnie działa z dużą pewnością siebie. Znajduje wzorzec, którego nie rozpoznaje, i go ulepsza. Ręcznie napisany mechanizm cache zostaje zastąpiony przez Redis (magazyn danych w pamięci), ponieważ tak wygląda cache w większości kodu, z którym model miał kontakt. AGENTS.md temu nie zapobiega, ponieważ make test działa w obu przypadkach. Zasada, która została naruszona, nie była nigdzie zapisana w miejscu dostępnym dla agenta.

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

Co znajduje się faktycznie w opublikowanym pliku DESIGN.md

Najszybszym sposobem poznania formatu jest przeczytanie plików publikowanych przez firmy na własny temat. Repozytorium official-design-md śledzi wyłącznie takie pliki. Zasada uwzględniania jest jednowierszowa. Ten wiersz stanowi istotę całej kolekcji:

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

Według stanu na październik 2026 lista obejmuje jedenaście pozycji: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel i VoltAgent. Każdy plik znajduje się pod publicznym adresem URL. Większość jest umieszczona we własnej domenie wydawcy, a pozostałe w publicznym repozytorium GitHub. Dzięki temu można już teraz przeczytać jeden z nich w terminalu.

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

Oba dokumenty opisują system projektowy. Określają wygląd produktu: kolorystykę, typografię, odstępy i animacje. Należy pominąć tematykę i zwrócić uwagę na użyteczny element, czyli strukturę tekstu.

Według stanu na 27 października 2026 plik Nuxt ma około 2,000 słów. Większość jego treści stanowią reguły wraz z uzasadnieniem. Na początku określono, że tryb ciemny jest domyślnym motywem. Wymieniono firmową zieleń #00DC82 wraz z uwagą: „Do logo, grafik w mediach społecznościowych i materiałów drukowanych. Nie używać jako surowych wartości w kodzie interfejsu użytkownika”. Pod koniec znajduje się sekcja zatytułowana Reject these, która zawiera:

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

Plik Vercel jest dłuższy i według stanu na październik 2026 ma około 6,000 słów. Idzie o krok dalej. Jeden z jego nagłówków brzmi Reject generated-design reflexes. Poniżej znajduje się lista elementów, po które sięga sprawny generator, gdy nie określono, 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 ustawień domyślnych, które generuje pewny siebie model. Publikuje się ją, aby model przestał je generować. Każdy plik DESIGN.md, który warto zatwierdzić, stanowi taką listę dla określonej domeny.

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

Społeczność zrobiła to jako pierwsza. awesome-design-md zawiera 84 pliki wyodrębnione z publicznych witryn, zgodnie z liczbą podaną w jego README na dzień 27 października 2026, a każdy z nich ma ten sam układ dziewięciu sekcji. Dzięki temu można wskazać agentowi jeden z nich i uzyskać rezultat zbliżony do danego wyglądu. Pliki te są użyteczne, ale nadal stanowią jedynie domysły. Żadna z przeanalizowanych firm ich nie zweryfikowała.

Plik pochodzący bezpośrednio od firmy jest inny, ponieważ stanowi źródło, a nie opis rezultatu. Gdy Vercel zmienia skalę typografii, vercel.com/design.md zmienia się razem z nią. Kopia pobrana w marcu nadal przekazuje agentowi informacje o starej skali, a w repozytorium nie ma niczego, co wskazywałoby, że kopia stała się nieaktualna.

Jedenaście firm to nadal niewielka liczba i repozytorium wyraźnie to zaznacza: standard jest nowy, a jego oficjalne przyjęcie postępuje. Obie kolekcje są utrzymywane przez VoltAgent, otwartoźródłowy framework agentowy, który również publikuje własny plik. Dlatego tę listę należy traktować jako zestawienie monitorujące, a nie neutralny spis. Nadal warto ją obserwować ze względu na znajdujące się na niej firmy. Kilka z nich to przedsiębiorstwa, których kod front-end najczęściej kopiują inni programiści. Nowsze wpisy, Ant Design, Microsoft FAST, Juspay i Oxide Computer, to systemy projektowe, na których budują inne zespoły. Ich pliki stają się praktycznym przykładem tego, czym jest DESIGN.md. Warto porównać tę drogę z drogą AGENTS.md: agents.md obejmuje obecnie ponad 60,000 projektów otwartoźródłowych korzystających z tego formatu, a nadzór nad nim sprawuje Agentic AI Foundation przy Linux Foundation. DESIGN.md rozpoczął tę samą drogę. 21 kwietnia 2026 Google udostępnił na zasadach open source projekt specyfikacji tego formatu, opublikowany jako google-labs-code/design.md, wraz ze schematem tokenów i CLI na licencji Apache-2.0. W październiku 2026 format ma wersję alpha i nadal jest aktywnie rozwijany. Jest utrzymywany przez Google Labs, a nie przez neutralną fundację, oraz opisuje tożsamość wizualną, więc nie określa niezmienników wymaganych przez plik backendu. Konwencje dotyczące plików czytelnych dla agentów szybko się utrwalają i są kształtowane odgórnie.

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ć. Mimo to plik pozostaje potrzebny, ponieważ mechanizm nie ma związku z kolorami. Chodzi o zapisanie ograniczeń, które edytor działający bez wątpliwości mógłby nieświadomie naruszyć.

Niezmienniki. Każdy niezmiennik powinien być jednym zdaniem opisującym warunek, który musi pozostać prawdziwy po każdej edycji. „Każdy zapis przechodzi przez queue.enqueue(). Bezpośredni zapis do bazy danych pomija dziennik audytowy, z którego korzysta eksport zgodności”. 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 opisać oczywistą opcję i wyjaśnić, dlaczego jej nie wybrano. „Redis nie jest używany do buforowania. Usługa działa na pojedynczym VPS, więc mapa w procesie jest szybsza i eliminuje konieczność utrzymywania dodatkowego demona. Do tego wyboru należy wrócić po uruchomieniu drugiego serwera aplikacji”. Bez tego akapitu agent poproszony o przyspieszenie bufora doda Redis. Będzie to właściwe działanie, ponieważ ograniczenie nie zostało opisane. To właśnie ta sekcja uzasadnia istnienie całego pliku.

Granice. Należy wskazać miejsca, w których mała zmiana może mieć duży zakres skutków. Dotyczy to schematu bazy danych, publicznego prefiksu ścieżek używanego już w skryptach klientów, pliku konfiguracyjnego odczytywanego podczas wdrażania przed uruchomieniem aplikacji oraz wpisu cron zakładającego działanie tylko jednej kopii. Każde takie miejsce należy nazwać i określić koszt jego zmiany. Jeżeli agent może również uzyskać dostęp do otwartego Internetu, na przykład przez samodzielnie utrzymywaną instancję SearXNG skonfigurowaną jako backend wyszukiwania, jest to również granica, którą warto opisać. Plik powinien określać, który pobrany tekst może wpływać na kod, a który można jedynie zacytować.

Słownictwo. Jeżeli w kodzie używane jest tenant, a zespół mówi customer, należy zapisać to mapowanie. Agent, który błędnie je odgadnie, wygeneruje kod wyglądający poprawnie, ale odwzorowujący niewłaściwe pojęcie. Taki błąd najtrudniej wykryć podczas przeglądu.

DESIGN.md, który można dziś skopiować

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

Należy wypełnić dwie sekcje, które można dziś napisać z pamięci: niezmienniki i odrzucone alternatywy. Pozostałe sekcje należy pozostawić jako nagłówki. Plik zawierający cztery rzetelne wiersze jest użyteczny. Plik zawierający czterdzieści zgadniętych wierszy — nie. Jeśli repozytorium zawiera kilka pakietów, jeden plik główny nie będzie odpowiedni dla wszystkich. Można zastosować ten sam podział na katalogi, który sprawdza się w przypadku zagnieżdżonych plików AGENTS.md w monorepo: krótki plik główny dla decyzji wspólnych dla całego repozytorium oraz mniejszy plik umieszczony obok każdego pakietu, który ma własne decyzje.

Niektóre narzędzia wczytują każdy plik markdown w katalogu głównym repozytorium, a inne wczytują tylko plik wskazany jawnie. Nie należy więc tego zakładać. Należy dodać odsyłacz do pliku 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 nieudana 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ę informacją o licencji. Każda z tych informacji znajduje się już w README, a żadna nie wyjaśnia, dlaczego przyjęto takie, a nie inne rozwiązanie.

To kosztuje dwa razy. Pierwszym kosztem jest kontekst. Plik odczytywany przez agenta na początku każdego zadania jest uwzględniany przy każdym zadaniu, a powtórzona sekcja dotycząca instalacji stanowi wyłącznie narzut w ramach stałego limitu. 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 być tekstem o największej wartości w repozytorium.

Drugi koszt jest większy. 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 sposobu, aby ustalić, która informacja ma wyższy priorytet, więc wybiera jedną z nich i na tej podstawie pisze kod. Plik, który czasami zawiera błędy, jest traktowany z takim samym zaufaniem jak plik, który zawsze zawiera poprawne informacje.

Test jest prosty. Jeśli akapit pasowałby do README, usuń go z DESIGN.md. Pozostała treść powinna obejmować to, co zostałoby powiedziane podczas przeglądu kodu, czyli część zaczynającą się od słów „próbowaliśmy już tego rozwiązania”.

Jak sprawdzić, czy plik działa?

Nie istnieje dla niego linter. Można jednak wykonać test, który zajmuje minutę.

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

Należy również obserwować liczbę tokenów, ponieważ ten plik jest wczytywany przy każdej turze. Jeżeli po dodaniu DESIGN.md zużycie kontekstu wzrasta, a odpowiedzi nie stają się lepsze, 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 komputerze lokalnym. 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. Pamięć stanowi repozytorium. Wszystko, co wyjaśniono na czacie i czego nigdy nie zatwierdzono w repozytorium, znika przed następną sesją. DESIGN.md jest miejscem, w którym należy zapisać to wyjaśnienie, aby przetrwał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 wtedy, gdy agent zawiedzie, a nie według harmonogramu. Jeśli nadal ustalasz, gdzie agenci pasują do zwykłego procesu wytwarzania oprogramowania, przewodnik po nauce pracy z agentami AI z 2026 roku będzie rozsądnym kolejnym krokiem.

FAQ

Czy DESIGN.md jest oficjalnym standardem?

Nie w takim znaczeniu jak AGENTS.md. AGENTS.md ma swoją stronę pod adresem agents.md, korzysta z niego ponad 60,000 projektów open source, a opiekę nad nim sprawuje Agentic AI Foundation, działająca w ramach Linux Foundation. DESIGN.md ma opublikowaną specyfikację, ale nie ma neutralnego opiekuna. Google opublikowało specyfikację roboczą jako open source 21 kwietnia 2026, a plik znajduje się w repozytorium google-labs-code/design.md na licencji Apache-2.0. W październiku 2026 jest w wersji alpha i nadal jest aktywnie rozwijany. Opisuje tożsamość wizualną: kolory, typografię, układ i komponenty. DESIGN.md ma również adopcję po stronie firm i projektów: jedenaście firm i projektów, w tym Vercel, Nuxt, Atlassian i Resend, publikuje własny taki plik, a zbiór społecznościowy zawierał 84 kolejne pliki wyodrębnione z publicznych witryn według stanu na 27 października 2026. W przypadku backendowego pliku zawierającego niezmienniki i odrzucone alternatywy należy traktować go jako konwencję, którą można przyjąć już teraz i swobodnie rozszerzać, ponieważ żadna specyfikacja nie obejmuje tych nazw sekcji.

Czy DESIGN.md powinien być po prostu 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 zostanie pominięty. Należy je rozdzielić, gdy AGENTS.md przestanie być łatwy do szybkiego przejrzenia albo gdy będzie widać, że obie części zmieniają się w różnym tempie. AGENTS.md zmienia się wraz ze zmianami procesu budowania. DESIGN.md zmienia się wraz ze zmianą decyzji, co zdarza się rzadziej i ma większe znaczenie. Po rozdzieleniu należy dodać w AGENTS.md jeden wiersz informujący agenta, aby przed edycją kodu odczytał DESIGN.md, ponieważ nie każde narzędzie ładuje każdy plik markdown w katalogu głównym.

Czym DESIGN.md różni się od architecture decision record?

ADR (architecture decision record) jest datowanym zapisem jednej decyzji, a w prawidłowo prowadzonym projekcie z czasem powstają dziesiątki takich zapisów w jednym katalogu. To historia, a wczytywanie historii jest kosztowne, ponieważ agent musiałby odczytać wszystkie wpisy, aby ustalić, które z nich nadal są aktualne. DESIGN.md przedstawia stan bieżący i jest przeznaczony do odczytania w całości przy każdym zadaniu. Jeśli ADR-y są już tworzone, należy zachować oba rozwiązania. ADR informuje, co zdecydowano i kiedy. DESIGN.md informuje, co jest prawdą obecnie, i to ten plik należy wskazywać agentowi.

Jak długi powinien być DESIGN.md?

Powinien być na tyle krótki, aby można go było ładować przy każdej turze bez poczucia straty czasu. Opublikowane przykłady są długie, ponieważ definiują cały język wizualny: plik Nuxt ma około 2,000 słów, a plik Vercel około 6,000 według stanu na październik 2026. Usługa backendowa zwykle potrzebuje znacznie mniej. 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 zrobiłby nieprawidłowo.