Czym jest plik DESIGN.md w repozytorium projektu?

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

DESIGN.md to plik w formacie markdown znajdujący się w głównym katalogu repozytorium, który wyjaśnia agentowi programistycznemu AI, dlaczego kod ma taką, a nie inną strukturę. AGENTS.md odpowiada na inne pytanie: jak pracować w tym środowisku. Obejmuje to polecenie budowania, polecenie testowania, wymagane testy lint oraz ścieżki, których nie należy modyfikować. DESIGN.md dokumentuje podjęte już decyzje oraz wskazuje, co ulegnie awarii w przypadku ich zmiany.

Agent programistyczny, czyli narzędzie takie jak Claude Code lub Cursor, które samodzielnie odczytuje i edytuje repozytorium, domyślnie wykazuje się dużą pewnością siebie. Gdy napotka wzorzec, którego nie rozpoznaje, próbuje go „ulepszyć”. Ręcznie napisana pamięć podręczna może zostać zamieniona na Redis (magazyn danych w pamięci RAM), ponieważ tak właśnie wygląda pamięć podręczna w większości kodu, z którym zapoznał się model. AGENTS.md nie powstrzyma takiego działania, ponieważ make test przejdzie w obu przypadkach. Złamaną zasadę zapisano w miejscu, do którego agent nie miał dostępu.

Jeśli pierwszy plik nie został jeszcze utworzony, należy zacząć właśnie od niego. AGENTS.md oraz towarzyszący mu HUMAN.md omawia format oraz lokalizacje, w których poszczególne narzędzia go szukają. Poniższa treść stanowi kolejny rozdział.

Co faktycznie zawiera opublikowany plik DESIGN.md

Najszybszym sposobem na poznanie formatu jest lektura plików, które firmy publikują na swój temat. Repozytorium official-design-md gromadzi wyłącznie takie dokumenty. Zasada włączenia do niego jest jednowierszowa i ten jeden 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 sierpień 2026 r. lista obejmuje siedem pozycji: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel oraz VoltAgent. Każdy plik znajduje się pod stabilnym publicznym adresem URL, więc można go przeczytać bezpośrednio w terminalu.

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

Oba te dokumenty dotyczą systemów projektowych. Opisują one, jak powinien wyglądać produkt: kolorystykę, typografię, odstępy oraz animacje. Należy wyjść poza samą tematykę, ponieważ użyteczną częścią jest struktura tekstu, a nie jego przedmiot.

Plik Nuxt liczy około 2100 słów, a jego większą część stanowią zasady 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, liczy około 6500 słów (stan na sierpień 2026 r.) i idzie o krok dalej. Jeden z jego nagłówków to Reject generated-design reflexes. Poniżej znajduje się lista elementów, po które sięga sprawny generator, jeśli nikt mu tego nie zabroni:

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 typ pliku. Jest to spisana lista wartości domyślnych generowanych przez pewny siebie model, opublikowana po to, aby model przestał je stosować. Każdy plik DESIGN.md, który warto dodać do repozytorium, stanowi taką właśnie listę dla określonej dziedziny.

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

Społeczność była pierwsza. awesome-design-md zawiera 73 pliki odtworzone metodą inżynierii wstecznej z publicznych witryn. Każdy z nich został napisany zgodnie z tym samym dziewięciosekcyjnym formatem, dzięki czemu agent może zostać skierowany na jeden z nich i wygenerować coś zbliżonego do danego wyglądu. Pliki te są użyteczne, ale pozostają jedynie przypuszczeniami. Nikt wewnątrz tych firm ich nie weryfikował.

Plik pierwszej strony (first-party) różni się tym, że stanowi źródło, a nie interpretację wyniku. Gdy Vercel zmienia swoją skalę typograficzną, vercel.com/design.md zmienia się wraz z nią. Kopia pobrana w marcu wciąż uczy agenta starej skali, a nic w repozytorium nie poinformuje o dezaktualizacji tej kopii.

Siedmiu wydawców to niewielka liczba, o czym wspomina samo repozytorium: standard jest nowy, a oficjalna adopcja rośnie. Obie kolekcje są utrzymywane przez VoltAgent, framework agentów typu open source, który również publikuje własny plik, więc listę tę należy traktować jako narzędzie śledzące, a nie jako neutralny spis. Mimo to warto ją obserwować ze względu na to, kim jest ta siódemka. Są to firmy, których kod front-endowy jest najczęściej kopiowany przez innych programistów, a ich pliki stają się wzorcem tego, czym jest DESIGN.md. Warto porównać ścieżkę, jaką przebył plik AGENTS.md: agents.md liczy obecnie ponad 60 000 projektów open source korzystających z tego formatu, a pieczę nad nim sprawuje Agentic AI Foundation pod egidą Linux Foundation. Konwencje dotyczące plików czytelnych dla agentów ustalają się szybko i dzieje się to odgórnie.

Co zawierać w pliku DESIGN.md, gdy projekt nie posiada interfejsu użytkownika

Większość oprogramowania działającego na VPS nie posiada języka wizualnego, który należałoby definiować. Plik ten nadal jest jednak przydatny, ponieważ mechanizm działania nie ma związku z kolorystyką. Chodzi o spisanie ograniczeń, które pewny siebie edytor mógłby nieświadomie naruszyć.

Niezmienniki. Po jednym zdaniu określającym stan, który musi zostać zachowany po każdej edycji. "Każdy zapis przechodzi przez queue.enqueue(). Bezpośredni zapis do bazy danych pomija dziennik audytu, a to właśnie z dziennika audytu korzysta eksport zgodności". Niezmiennik wraz z uzasadnieniem przetrwa konfrontację z zadaniem, którego nie przewidziano. Sam niezmiennik jest traktowany jako preferencja, a preferencje są optymalizowane i usuwane.

Odrzucone alternatywy. Oczywista opcja i powód jej odrzucenia. "Nie używamy Redis do buforowania. Usługa działa na pojedynczym VPS, więc mapa wewnątrz procesu jest szybsza i stanowi jeden demon mniej do utrzymania. Powrót do tego punktu nastąpi, gdy pojawi się drugi serwer aplikacji". Bez tego akapitu agent poproszony o przyspieszenie pamięci podręcznej doda Redis i będzie miał rację: ograniczenie nie zostało mu przekazane. To sekcja, która uzasadnia istnienie całego pliku.

Granice. Miejsca, w których niewielka edycja ma duży zasięg rażenia. Schemat bazy danych. Publiczny prefiks ścieżki, pod który klienci już podpięli swoje skrypty. Plik konfiguracyjny, który wdrożenie odczytuje przed uruchomieniem aplikacji. Wpis w cron, który zakłada, że działa tylko jedna kopia. Należy je nazwać i określić koszt zmiany każdego z nich. Jeśli agent ma również dostęp do otwartej sieci, na przykład poprzez samodzielnie hostowaną instancję SearXNG podpiętą jako backend wyszukiwania, jest to granica warta odnotowania. Plik powinien określać, który pobrany tekst może wpływać na kod, a który jest jedynie cytowany.

Słownictwo. Jeśli kod używa tenant, a zespół używa customer, należy zapisać to mapowanie. Agent, który zgadnie błędnie, wygeneruje kod, który wygląda poprawnie, ale modeluje niewłaściwy obiekt. Jest to najtrudniejszy do wykrycia rodzaj błędu podczas przeglądu.

Plik DESIGN.md gotowy do użycia

# 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 dwie sekcje, które możesz przygotować z pamięci: niezmienniki oraz odrzucone alternatywy. Pozostałe sekcje pozostaw jako nagłówki. Plik zawierający cztery rzetelne linie jest lepszy niż plik z czterdziestoma domysłami. Jeśli repozytorium zawiera wiele pakietów, jeden główny plik nie będzie wystarczający. Zastosuj 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 oraz mniejsze pliki przy każdym pakiecie, który posiada własne ustalenia.

Niektóre narzędzia wczytują każdy plik markdown w katalogu głównym repozytorium, inne tylko te wskazane bezpośrednio. Nie zakładaj z góry, jak działa dane narzędzie. Dodaj odnośnik do AGENTS.md:

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

Antywzorzec: plik DESIGN.md powielający zawartość README

Najczęstsza błędna wersja tego pliku dobrze się czyta, ale niczego nie uczy. Zaczyna się od opisu działania projektu, wymienia funkcje, wyjaśnia sposób instalacji i kończy licencją. Każda z tych informacji znajduje się już w README i żadna z nich nie wyjaśnia, dlaczego rozwiązania zostały zaprojektowane w określony sposób.

Kosztuje to podwójnie. Pierwszym kosztem jest kontekst. Plik, który agent odczytuje na początku każdego zadania, jest opłacany przy każdym z nich, a zduplikowana sekcja instalacji stanowi czysty narzut w ramach ograniczonego okna kontekstowego. Zarządzanie tym oknem to osobna umiejętność, omówiona w zarządzanie oknem kontekstowym w Claude Code. W skrócie: wszystko, co jest ładowane automatycznie, powinno być tekstem o najwyższej wartości 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, DESIGN.md nadal wskazuje 3000, a agent nie ma możliwości oceny, która informacja jest ważniejsza, więc wybiera jedną z nich i pisze kod w oparciu o nią. Plik, który bywa błędny, jest traktowany z taką samą pewnością, jak plik, który zawsze zawiera poprawne dane.

Test jest szybki. Jeśli dany akapit pasowałby do README, usuń go z DESIGN.md. To, co pozostanie, powinno stanowić treść, którą wypowiedziałbyś podczas przeglądu kodu – tę część, która zaczyna się od słów „próbowaliśmy już tego”.

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

Nie istnieje narzędzie typu linter do tego celu. Dostępna jest jednak procedura weryfikacji, którą można wykonać w minutę.

Zleć agentowi zadanie, które bezpośrednio narusza niezmiennik. Przykład: „Dodaj zadanie w tle, które oznacza przestarzałe wiersze jako wygasłe”. Plik, który spełnia swoje zadanie, ujawnia się w odpowiedzi przed jakimkolwiek kodem: agent powinien poinformować, że zadanie zapisuje dane przez queue.enqueue(), ponieważ bezpośredni zapis pominąłby dziennik audytu. Jeśli agent otwiera połączenie z bazą danych i wykonuje zapis, oznacza to jedną z dwóch rzeczy. Plik nie jest w ogóle odczytywany lub niezmiennik został sformułowany zbyt luźno, by można było z nim polemizować.

Należy również monitorować liczbę tokenów, ponieważ plik ten jest ładowany w każdej turze. Jeśli zużycie kontekstu wzrasta po dodaniu DESIGN.md, a odpowiedzi nie stają się lepsze, oznacza to, że plik zawiera treści, które agent już posiadał. Odczytywanie liczników tokenów w Claude Code pokazuje, na co przeznaczany jest ten budżet.

Ma to kluczowe znaczenie, gdy agent działa na serwerze, a nie na lokalnym komputerze. Agent pracujący w długotrwałej sesji, takiej jak konfiguracja w obszarze roboczym Claude Code na VPS z tmux, nie posiada pamięci wczorajszej konwersji. Pamięcią jest repozytorium. Wszystko, co zostało wyjaśnione na czacie i nie zostało zatwierdzone (commit), znika przed kolejną sesją, a DESIGN.md jest miejscem, w którym te wyjaśnienia są utrwalane.

Rozpocznij od decyzji, które wywołują spory

Pierwsza wersja zajmuje dwadzieścia minut. Otwórz kilka ostatnich pull requests, w których recenzent napisał „nie, tutaj robimy to inaczej”. Każdy z tych komentarzy stanowi niezmiennik, który nigdy nie został spisany, i każdy z nich jest miejscem, w którym agent popełni ten sam błąd, szybciej i częściej niż człowiek. Dodawaj wpisy do pliku, gdy zawiedzie, a nie według harmonogramu. Jeśli nadal ustalasz, w jaki sposób agenci wpisują się w standardowy proces programistyczny, przewodnik po nauce agentów AI na rok 2026 będzie odpowiednim kolejnym krokiem.

FAQ

Czy DESIGN.md jest oficjalnym standardem?

Nie w taki sposób jak AGENTS.md. Plik AGENTS.md posiada swoją stronę domową pod adresem agents.md, jest używany w ponad 60 000 projektów open source i znajduje się pod opieką Agentic AI Foundation, będącej częścią Linux Foundation. Stan na sierpień 2026 roku wskazuje, że DESIGN.md nie posiada organu zarządzającego ani opublikowanej specyfikacji. Posiada natomiast adopcję przez twórców: siedem firm, w tym Vercel, Nuxt, Atlassian i Resend, publikuje taki plik pod publicznym adresem URL, a społecznościowa kolekcja zawiera 73 kolejne pliki, odtworzone metodą inżynierii wstecznej z publicznych witryn. Należy traktować go jako konwencję, którą można przyjąć już teraz i dowolnie rozszerzać, ponieważ żadne narzędzie nie weryfikuje poprawności nazw sekcji.

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

W przypadku małego repozytorium – tak. Jeden plik, który agent na pewno odczyta, jest lepszy niż dwa pliki, z których jeden zostanie zignorowany. Należy je rozdzielić, gdy AGENTS.md przestanie być przejrzysty lub gdy zauważalne stanie się, że obie części zmieniają się w różnym tempie. Plik AGENTS.md zmienia się wraz ze zmianami w procesie budowania. Plik DESIGN.md zmienia się wraz ze zmianami decyzji projektowych, co zdarza się rzadziej i ma większą wagę. Po rozdzieleniu plików należy dodać w AGENTS.md jedną linię z poleceniem dla agenta, aby przed edycją kodu odczytał DESIGN.md, ponieważ nie każde narzędzie wczytuje wszystkie pliki markdown znajdujące się w katalogu głównym.

Czym DESIGN.md różni się od dokumentacji decyzji architektonicznych (ADR)?

ADR (architecture decision record) to opatrzony datą zapis pojedynczej decyzji, a zdrowy projekt gromadzi ich dziesiątki w jednym folderze. Jest to historia, a historia jest kosztowna w wczytywaniu, ponieważ agent musiałby przeczytać wszystkie wpisy, aby ustalić, które z nich są nadal aktualne. DESIGN.md to stan obecny, napisany tak, aby był w całości odczytywany przy każdym zadaniu. Jeśli projekt już korzysta z ADR, warto zachować oba rozwiązania. ADR informuje o tym, co i kiedy postanowiono. DESIGN.md informuje o tym, co jest prawdą dzisiaj i to właśnie na ten plik należy kierować agenta.

Jak długi powinien być DESIGN.md?

Na tyle krótki, aby można go było wczytywać przy każdym kroku bez obciążenia. Opublikowane przykłady są długie, ponieważ definiują cały język wizualny: plik Nuxt liczy około 2 100 słów, a plik Vercel około 6 500 słów (stan na sierpień 2026 roku). Usługa backendowa zazwyczaj wymaga znacznie mniej. Należy zacząć od jednej strony i rozbudowywać ją tylko wtedy, gdy agent popełni błąd, któremu zapobiegłoby jedno zdanie wyjaśnienia. Długość nie jest wyznacznikiem jakości. Każda linia powinna zawierać informację, którą agent w przeciwnym razie zinterpretowałby błędnie.