Rejestry decyzji w sterowanym przez AI procesie tworzenia oprogramowania

Rejestr decyzji to brakujący warstwę pamięci w asystowanym przez AI programowaniu. Zapisują one nie tylko to, co zostało zbudowane, ale także dlaczego – a ta różnica staje się krytyczna, gdy narzędzia AI tworzą Twój kod.

Rejestry decyzji to brakująca warstwa pamięci

Programowanie napędzane przez AI zmienia ekonomię rozwoju oprogramowania, czyniąc kod tańszym do wygenerowania, łatwiejszym do refaktoryzacji i szybszym do odrzucenia. To jest użyteczne. Jest też niebezpieczne, ponieważ gdy kod staje się łatwiejszy do produkcji, zasobem rzadkim przestaje być pisanie klawiaturą – zasobem rzadkim staje się osąd.

Dlaczego zespół wybrał PostgreSQL zamiast DynamoDB? Dlaczego produkt wymaga przeglądu przez człowieka przed wysłaniem e-maili wygenerowanych przez AI? Dlaczego interfejs wyświetla sugestie w panelu bocznym zamiast stosować je bezpośrednio? Dlaczego prostsze podejście zostało odrzucone sześć miesięcy temu? Kod może pokazywać, co istnieje, ale rzadko wyjaśnia, dlaczego to istnieje.

Rejestry decyzji rozwiązują ten problem, zapewniając krótki, kontrolowany wersjami dokument, który odzwierciedla ważny wybór, kontekst stojący za nim, rozważane alternatywy oraz konsekwencje, które zespół zaakceptował. W kodzie asystowanym przez AI te rejestry stają się czymś więcej niż dokumentacją – stają się trwałą pamięcią projektu, którą zarówno ludzie, jak i agenci kodujący AI mogą odczytać przed wprowadzeniem przyszłych zmian. Praktyczna zasada działania jest prosta: trzymaj rejestry decyzji jako pliki Markdown w repozytorium, przeglądaj je jak kod i pozwól przyszłym narzędziom AI na ich odczyt przed proponowaniem lub wdrażaniem zmian.

Czym są rejestry decyzji?

Rejestr decyzji to zapisany na piśmie rejestr znaczącej decyzji, ustrukturyzowany w sposób odpowiadający na cztery podstawowe pytania: co postanowiliśmy, dlaczego to postanowiliśmy, jakie alternatywy rozważyliśmy i jakie konsekwencje zaakceptowaliśmy? Najczęstszą formą jest Rejestr Decyzji Architektonicznej, skrócony do ADR. ADR-y są powszechnie stosowane do dokumentowania decyzji technicznych, a ten sam wzorzec można rozszerzyć poza architekturę na prace produktowe i projektowe.

W przypadku programowania napędzanego przez AI szczególnie przydatne są trzy typy:

Razem ADR-y, PDR-y i DDR-y opisują nie tylko strukturę systemu, ale także intencję produktu oraz rozumowanie stojące za doświadczeniem użytkownika. Ta kombinacja ma znaczenie, ponieważ agenci AI mogą odczytywać kod, ale sam kod nie zawiera wystarczająco kontekstu, aby podejmować dobre decyzje. Rejestry decyzji dostarczają systemom AI zweryfikowane, trwałe, zatwierdzone przez człowieka źródło intencji projektu.

Rejestry Decyzji Architektonicznych

Rejestry Decyzji Architektonicznych (ADR) odzwierciedlają decyzje techniczne i strukturalne. Użyj ADR, gdy decyzja wpływa na kształt systemu – jego granice, zależności, model operacyjny lub długoterminową utrzymywalność.

Przykłady decyzji wartych zapisania jako ADR obejmują:

• Wybór PostgreSQL jako głównej bazy danych
• Użycie architektury napędzanej zdarzeniami do przetwarzania w tle
• Pozostawienie aplikacji jako modułowego monolitu
• Wprowadzenie kolejki wiadomości
• Wybór REST zamiast GraphQL
• Użycie renderowania po stronie serwera dla aplikacji internetowej
• Wymaganie, aby wszystkie zadania tła były idempotentne
• Przyjęcie konkretnego modelu uwierzytelniania i autoryzacji

ADR nie jest pełnym dokumentem architektonicznym – jest celowo mały, odnotowując jedną ważną decyzję w konkretnym momencie czasu. Dobry ADR zapobiega amnezji architektonicznej: bez niego przyszli współtwórcy mogą ponownie odkryć te same kompromisy, otworzyć stare debaty lub przypadkowo cofnąć ważne ograniczenia.

W programowaniu napędzanym przez AI ADR-y mają jeszcze większą wagę. Narzędzia AI są często biegłe w optymalizacji lokalnej i mogą zaproponować technicznie plausywalną zmianę, która narusza szersze ograniczenia architektoniczne. ADR daje AI wyraźną granicę: “Tak ma wyglądać ten system”.

Rejestry Decyzji Produktowych

Rejestry Decyzji Produktowych (PDR) odzwierciedlają behawior produktu, zakres i intencje skierowane do użytkownika. Jest to mniej powszechne niż ADR-y, ale często równie wartościowe – decyzje produktowe są często rozproszone w zgłoszeniach, narzędziach do roadmap, wątkach czatu, notatkach z spotkań i pamięci ludzi, co sprawia, że są one łatwe do zapomnienia przez ludzi i prawie niemożliwe do wiarygodnej wnioskowania przez narzędzia AI.

Użyj PDR, gdy decyzja wpływa na to, co produkt robi, kogo obsługuje, co jest celowo poza zakresem lub jak powinna zachowywać się funkcja skierowana do użytkownika. Przykłady obejmują:

• Wiadomości wygenerowane przez AI muszą pozostać jako szkice do czasu przeglądu przez człowieka
• Użytkownicy warstwy darmowej mogą tworzyć do trzech projektów
• Usunięte przestrzenie robocze są przywracalne przez 30 dni
• Rozliczanie zespołów jest poza zakresem wersji 1
• Użytkownicy mogą eksportować swoje dane bez kontaktowania się z pomocą techniczną
• Podsumowania AI o niskim zaufaniu wyświetlają ostrzeżenie zamiast być ukryte

PDR jest szczególnie przydatny, gdy wybór produktowy wygląda na arbitralny z perspektywy kodu. Kod może zawierać limit trzech projektów dla użytkowników darmowych, a bez PDR narzędzie AI może potraktować tę liczbę jako magiczną stałą i zasugerować jej zmianę. Dzięki PDR AI może zobaczyć, że limit jest powiąany ze strategią cenową, kosztem onboardingu lub obciążeniem wsparcia – oraz że jego zmiana wymaga świadomej decyzji produktowej, a nie szybkiej edycji.

Rejestry Decyzji Projektowych

Rejestry Decyzji Projektowych (DDR) odzwierciedlają decyzje dotyczące doświadczenia użytkownika, interakcji, wyglądu i projektu treści. Użyj DDR, gdy decyzja wpływa na to, jak użytkownicy interakują z produktem, jak prezentowane są informacje lub jak zasada projektowa powinna być stosowana w przyszłych pracach.

Przykłady decyzji projektowych wartych zapisania obejmują:

• Użycie walidacji inline zamiast tylko przy wysyłaniu
• Umieszczenie sugestii AI w panelu bocznym zamiast bezpośrednio w edytorze
• Użycie stopniowej ekspozycji dla zaawansowanych ustawień
• Wymaganie potwierdzenia przed niszczącymi akcjami
• Użycie “Szkic” i “Opublikowany” zamiast “Nieaktywny” i “Aktywny”
• Pozostawienie głównych akcji widocznych na ekranach mobilnych

Intencja projektowa jest łatwo tracona podczas wdrożenia. Programista może uprosścić przepływ lub agent AI może wygenerować komponent, który technicznie działa, ale łamie zamierzony model interakcji. Na przykład DDR może odnotować: “Wyświetlamy sugestie pisania AI obok dokumentu, a nie wewnątrz niego, ponieważ użytkownicy muszą porównać wygenerowany tekst ze swoim szkicem przed akceptacją zmian.” Ten rejestr daje przyszłym współtwórcom zasadę do zachowania, a nie tylko układ do skopiowania.

Dlaczego rejestry decyzji mają większe znaczenie z AI

Narzędzia kodujące AI są potężne, ale często są bezstanowe lub tylko częściowo świadome historii projektu. Mogą inspekcjonować pliki, wnioskować wzorce i generować zmiany – ale nie wiedzą automatycznie, które decyzje są intencjonalne, które przypadkowe, a które już zostały omówione i rozwiązane. To tworzy kilka odrębnych ryzyk.

AI może ponownie otworzyć rozstrzygnięte debaty

Jeśli zespół już postanowił użyć modułowego monolitu, agent AI może nadal proponować wyodrębnienie usługi, ponieważ wygląda to czysto w izolacji. Bez ADR AI nie ma trwałego sposobu, aby wiedzieć, że zespół już rozważył i odrzucił tę ścieżkę, a wynikiem jest marnowanie wysiłku lub subtelna regresja w spójności systemu.

AI może optymalizować lokalnie i uszkadzać globalnie

Wygenerowana refaktoryzacja może uczynić jeden plik czystszym, łamiąc jednocześnie granice systemu. Zmiana UI może zmniejszyć złożoność komponentu, osłabiając jednocześnie zamierzone doświadczenie użytkownika. Zmiana produktowa może uproszczenie wdrożenia, łamiąc założenia dotyczące cen lub zgodności. Rejestry decyzji dają AI szerszy punkt odniesienia przed działaniem na wąsko zakreślonych sygnałach.

AI może zachować kod, ale stracić intencję

Model może podążać za istniejącymi wzorcami w bazie kodu, ale wzorce nie są tym samym co zasady. Czasem istniejący kod jest kompromisem. Czasem jest przejściowy. Czasem istnieje z powodu zewnętrznego ograniczenia, które nie jest widoczne w pliku. Rejestry decyzji wyjaśniają różnicę między “tak to działa” a “dlaczego to zostało zbudowane w ten sposób”.

AI może generować plausywalne, ale błędne rozumowanie

AI może tworzyć rejestry decyzji, ale może też wymyślać brzmiące pewnie wyjaśnienia, które nie odpowiadają rzeczywistej decyzji. Dlatego przegląd przez człowieka jest bezwarunkowy: AI może wygenerować pierwszą wersję rejestru, ale człowiek musi zweryfikować, czy dokładnie opisuje rzeczywistą decyzję, alternatywy i konsekwencje przed scaleniem rejestru.

Rejestry decyzji jako część szerszej metodologii

Rejestry decyzji to nie tylko dokumentacja – są częścią szerszego sposobu pracy, który znajduje się na styku lekkiego zarządzania architekturą, dokumentacji jako kodu, procesów zarządzania wiedzą z udziałem AI, odkrywania produktu, uzasadnienia projektowej, zarządzania AI i przeglądu kodu. Przydatnym sposobem opisu szerszego procesu jest Rozwój Oparty na Decyzjach (Decision-Oriented Development).

Większość przepływów pracy napędzanych przez AI koncentruje się wężo na pętli generuj-przeglądaj-scalar:

Ten cykl jest zbyt cienki dla poważnej pracy systemowej. Mocniejszy przepływ pracy traktuje repozytorium jako magazyn zarówno kodu, jak i intencji – diagramy tutaj używają Mermaid, lekkiego formatu, który dobrze działa również wewnątrz rejestrów decyzji Markdown:

Ten proces przekształca repozytorium w coś więcej niż magazyn kodu. Staje się źródłem prawdy dla wdrożenia, intencji i rozumowania – trwałym artefaktem, który kumuluje wartość z każdą podjętą decyzją.

Rejestry decyzji i dokumentacja jako kod

Rejestry decyzji działają najlepiej, gdy stosują się do zasad dokumentacji jako kodu, co oznacza, że powinny być przechowywane w tym samym repozytorium co kod, napisane w prostym Markdown, przeglądane w pull requestach, wersjonowane z Git, powiązane z powiązanymi zgłoszeniami i pull requestami oraz przeszukiwane przez zarówno ludzi, jak i narzędzia AI. To jest znacznie bardziej niezawodne niż przechowywanie ważnych decyzji w czatach, stronach wiki, prezentacjach czy notatkach ze spotkań – te narzędzia mogą nadal być przydatne do dyskusji, ale zaakceptowana decyzja powinna zawsze żyć blisko kodu.

Dobrze zorganizowana struktura repozytorium dla rejestrów decyzji może wyglądać tak:

docs/
  decisions/
    architecture/
      0001-use-postgresql-for-primary-storage.md
      0002-keep-billing-inside-the-core-app.md
    product/
      0001-ai-generated-email-requires-human-review.md
      0002-free-tier-project-limit.md
    design/
      0001-use-inline-validation.md
      0002-place-ai-suggestions-in-side-panel.md

Dla mniejszych projektów równie dobrze sprawdzi się płaska struktura. Dokładna organizacja folderów ma mniejsze znaczenie niż spójność – rejestry muszą być łatwe do znalezienia, łatwe do przeglądu i łatwe do załadowania jako kontekst przez narzędzia AI przed działaniem na bazie kodu. Dla zespołów Go, ta struktura docs/decisions/ naturalnie pasuje obok układu cmd/, internal/ i api/ opisanego w Struktura Projektu Go: Praktyki i Wzorce, która zaleca docs/ jako dom dla decyzji architektonicznych i referencji API.

Praktyczny szablon rejestru decyzji

Przydatny szablon rejestru decyzji powinien być na tyle krótki, aby ludzie go faktycznie używali. Oto praktyczny szablon Markdown, który zawiera opcjonalną, ale cenną sekcję wytycznych dla AI:

# Decyzja: Krótki tytuł

Status: Proponowany | Akceptowany | Nadpisany | Zdezaktualizowany
Data: YYYY-MM-DD
Typ: Architektura | Produkt | Projekt
Właściciele: Zespół lub imiona

## Kontekst

Opisz problem, ograniczenia, cele, potrzeby użytkowników, fakty techniczne
oraz czynniki biznesowe, które doprowadziły do tej decyzji.

## Decyzja

Jasno sformułuj decyzję.

## Rozważane alternatywy

### Opcja 1

Zalety:
- ...

Wady:
- ...

## Konsekwencje

Opisz, co staje się łatwiejsze, co staje się trudniejsze, oraz jakie ryzyka
lub prace podążające za tym tworzy.

## Wytyczne dla AI

Gdy asystent AI pracuje w tej dziedzinie, powinien:
- Zachowywać ...
- Unikać ...
- Preferować ...
- Prosić o przegląd, gdy ...

## Linki

- Powiązane zgłoszenia:
- Powiązane pull requesty:
- Powiązane pliki:
- Nadpisuje:
- Nadpisany przez:

Sekcja “Wytyczne dla AI” jest opcjonalna, ale w przypadku programowania napędzanego przez AI jest niezwykle cenna – przekształca rejestr decyzji w trwałą instrukcję dla przyszłych agentów pracujących w tej samej części bazy kodu.

Co należy umieścić w rejestrze decyzji?

Nie każdy wybór zasługuje na rejestr, a jeśli każdy mały szczegół implementacyjny stanie się rejestrem decyzji, proces zapadnie w szum. Stwórz rejestr decyzji, gdy wybór jest znaczący i prawdopodobnie będzie miał znaczenie później.

Dobrymi kandydatami są decyzje, które:

• Wpływają na wiele części systemu
• Kodują obietnicę produktową
• Rozwiązują rzeczywistą debatę
• Wprowadzają długoterminowy kompromis
• Opierają się na ograniczeniach biznesowych, zgodności lub operacyjnych
• Byłyby kosztowne do ponownego odkrycia później
• Przyszłe narzędzia AI mogłyby plausywalnie zinterpretować błędnie
• Przyszli współtwórcy mogliby być skłonni odwrócić bezmyślnie

Złymi kandydatami są małe wybory refaktoryzacji, oczywiste poprawki błędów, tymczasowe eksperymenty, lokalne decyzje nazewnictwa i szczegóły implementacyjne bez trwałych konsekwencji. Dobrą zasadą kciuka jest prosta: jeśli odwrócenie decyzji wymagałoby dyskusji, zarejestruj decyzję.

Wartości statusu i cykl życia

Rejestry decyzji powinny mieć cykl życia, aby sygnować ich obecny status. Najprostsze wartości statusu są wystarczające.

Proponowany — Decyzja jest rozważana, ale jeszcze nie akceptowana. Użyj tego, gdy zespół chce omówić decyzję w pull request, zanim zobowiąże się do niej.

Akceptowany — Decyzja jest aktywna i powinna kierować przyszłą pracą. Większość przydatnych rejestrów decyzji spędzi większość swojego życia w tym stanie.

Nadpisany — Decyzja została zastąpiona nowszym rejestrem. Nie usuwaj starych rejestrów; trzymaj je dla historii i powiąż z nowszą decyzją, aby ewolucja myślenia pozostała widoczna.

Zdezaktualizowany — Decyzja nie jest już zalecana, ale może nadal opisywać istniejące części systemu. To jest szczególnie przydatne podczas migracji, gdy stare wzorce istnieją w bazie kodu obok nowszych podejść.

Ważną zasadą jest, że rejestry decyzji powinny być przyjazne do dodawania. Gdy zespół zmienia kierunek, stwórz nowy rejestr i powiąż stary, zamiast przepisywać historię, aby przeszłość wyglądała czystej.

Jak AI powinno generować rejestry decyzji

AI może pomóc w tworzeniu rejestrów decyzji, a to jedno z lepszych zastosowań AI w rozwoju oprogramowania – jest szybkie w tworzeniu ustrukturyzowanych dokumentów z kontekstu. Po dyskusji, przeglądzie architektonicznym lub pull request, możesz poprosić asystenta AI o stworzenie rejestru:

Stwórz Rejestr Decyzji Architektonicznej dla decyzji w tym pull request.
Dołącz kontekst, alternatywy, konsekwencje i wytyczne dla AI.
Zapisz jako Markdown pod docs/decisions/architecture.

Dla prac produktowych:

Stwórz Rejestr Decyzji Produktowej wyjaśniający, dlaczego wiadomości wygenerowane przez AI
muszą pozostać jako szkice do czasu przeglądu przez użytkownika.
Dołącz wpływ na użytkownika, zachowanie poza zakresem, kompromisy i wytyczne dla AI.

Rejestr wygenerowany przez AI nie powinien być jednak automatycznie ufać. Przegląd przez człowieka powinien zweryfikować, czy kontekst jest dokładny, czy AI nie wymyśliło uzasadnienia, czy wymienione alternatywy są rzeczywiste, czy konsekwencje są szczere i czy wytyczne dla AI odpowiadają rzeczywistej intencji zespołu. AI jest asystentem do tworzenia szkiców – nie jest właścicielem decyzji.

Jak AI powinno czytać rejestry decyzji

Drugą połową praktyki jest instrukowanie AI do odczytu rejestrów przed działaniem. Przed poproszeniem asystenta AI o wdrożenie zmiany, dołącz instrukcję taką jak:

Przed modyfikacją tej funkcji, przeczytaj docs/decisions.
Zidentyfikuj wszystkie Rejestry Decyzji Architektonicznych, Produktowych lub Projektowych, które mają zastosowanie.
Postępuj zgodnie z zaakceptowanymi decyzjami. Jeśli Twoja proponowana zmiana koliduje z rejestrem
decyzji, wyjaśnij konflikt przed zmianą kodu.

Dla większych zadań, wzmocnij rolę rejestrów jako pamięci projektu:

Użyj rejestrów decyzji jako pamięci projektu.
Nie odwracaj zaakceptowanych decyzji bez proponowania nowej decyzji nadpisującej.
Gdy generujesz kod, wyjaśnij, które rejestry decyzji wpłynęły na wdrożenie.

To zmienia rolę AI z “przewidywania plausywalnego kodu” na “działanie wewnątrz udokumentowanego systemu ograniczeń” – znaczną poprawą niezawodności dla złożonych lub długotrwałych projektów.

Rejestry decyzji w pull requestach

Rejestry decyzji powinny być częścią normalnego przeglądu pull request, a nie osobnym procesem. Prosty wpis w checklist PR sprawia, że nawyk jest widoczny:

## Lista kontrolna rejestrów decyzji

- [ ] Ten PR nie wprowadza znaczącej decyzji architektonicznej, produktowej lub projektowej.
- [ ] Ten PR wprowadza znaczącą decyzję i zawiera nowy rejestr decyzji.
- [ ] Ten PR zmienia poprzednią decyzję i zawiera nadpisujący rejestr.
- [ ] Rozważono istotne istniejące rejestry decyzji.
- [ ] Kod wygenerowany przez AI stosuje się do zaakceptowanych rejestrów decyzji.
- [ ] Rejestry decyzji wygenerowane przez AI zostały przeglądnięte przez człowieka.

Ta lista jest prosta, ale zmienia zachowanie, przypominając zespołowi, że kod nie jest jedynym artefaktem, który ma znaczenie w pull request. Ułatwia też naturalne wychwytywanie, gdy zmiana wygenerowana przez AI cicho łamie poprzednią decyzję.

Rejestry decyzji i zarządzanie architekturą

Tradycyjne zarządzanie architekturą często zawodzi, ponieważ jest zbyt ciężkie, zbyt powolne lub zbyt odłączone od wdrożenia – centralne rady zatwierdzające, duże wstępne dokumenty i procesy gatekeepingowe, które blokują zamiast kierować. Rejestry decyzji oferują lżejszą alternatywę, która integruje się bezpośrednio z przepływem pracy deweloperskim.

Nie wymagają one centralnej rady architekturalnej dla każdej zmiany, ani nie blokują zespołów od uczenia się i adaptacji. Zamiast tego tworzą ślad decyzji, który może być przeglądany, odwoływany i budowany przez czas. To wspiera ewolucyjną architekturę: architektura może się zmieniać, ale zmienia się z pamięcią, a nie mimo niej. Zespół może ponownie odwiedzić stare decyzje bez konieczności ponownego odkrywania, dlaczego zostały podjęte, co jest zdrowszą i bardziej uczciwą formą zarządzania:

• Małe rejestry zamiast gigantycznych dokumentów
• Przegląd blisko kodu zamiast osobnej teatralnej procedury zatwierdzania
• Kontekst historyczny zamiast wiedzy plemiennej
• Wyraźne kompromisy zamiast ukrytych założeń

Rejestry decyzji i zarządzanie produktem

Praca produktowa również potrzebuje pamięci decyzji, a to jest obszar, w którym wartość rejestrów decyzji jest często niedoceniana. Roadmapa mówi, co może się stać. Zgłoszenie mówi, co zbudować jako następne. Analityka mówi, co zrobili użytkownicy. Żadne z tych w pełni nie wyjaśnia, dlaczego istnieje behawior produktu.

Rejestry Decyzji Produktowych wypełniają tę lukę i są szczególnie przydatne dla decyzji dotyczących cen i pakietów, modeli uprawnień, limitów i kwot, bezpieczeństwa AI i przepływów przeglądu, wyborów onboardingu, definicji ról użytkowników, zasad współpracy, polityk retencji danych oraz granic zakresu funkcji. Po wdrożeniu, decyzje produktowe stają się niewidoczne w kodzie – później ktoś widzi tylko kod i pyta: “Dlaczego to działa w ten sposób?” PDR daje odpowiedź w formie, którą zarówno ludzie, jak i narzędzia AI mogą znaleźć i wykorzystać.

Rejestry decyzji i systemy projektowe

Systemy projektowe często dokumentują komponenty, tokeny i zasady użycia, ale rzadko dokumentują, dlaczego system działa w ten sposób. Rejestry Decyzji Projektowych wypełniają tę lukę. Biblioteka komponentów może mówić “użyj dialogu potwierdzenia dla niszczących akcji”, podczas gdy DDR wyjaśnia uzasadnienie: “Wymagamy potwierdzenia dla niszczących akcji, ponieważ użytkownicy często pracują z danymi zespołu, a przypadkowe usunięcie ma wysoki koszt odzyskania.”

To uzasadnienie ma znaczenie poza konkretnym komponentem. Pomaga przyszłym projektantom, programistom i narzędziom AI stosować zasadę poprawnie w nowych sytuacjach. Bez DDR agent AI może wygenerować szybszą interakcję, która pomija potwierdzenie, ponieważ wydaje się bardziej wydajna. Dzięki DDR agent może rozpoznać, że zachowanie własności bezpieczeństwa jest intencjonalne i bezwarunkowe.

Jak rejestry decyzji wspierają rozwój oparty na specyfikacjach

Rozwój oparty na specyfikacjach wyjaśnia, co system powinien robić. Rejestry decyzji wyjaśniają, dlaczego zespół wybrał ten kierunek, a ta różnica ma duże znaczenie dla pracy asystowanej przez AI.

Specyfikacja funkcji może mówić, że e-maile wygenerowane przez AI muszą być zapisane jako szkice. Rejestr Decyzji Produktowej wyjaśnia, dlaczego automatyczne wysyłanie zostało odrzucone, jakie ryzyko zostało rozważone i które przyszłe zmiany wymagałyby nowej decyzji. Specyfikacja projektowa może opisywać interakcję panelu bocznego, podczas gdy odpowiadający DDR wyjaśnia, dlaczego inline edycje AI zostały wyraźnie odrzucone i dlaczego zachowanie kontroli użytkownika było ważniejsze niż szybkość przepływu pracy. Specyfikacja architekturalna może zdefiniować granicę usługi, a jej ADR wyjaśnia, dlaczego zespół wybrał tę granicę zamiast prostszej lub bardziej rozproszonej alternatywy.

Specyfikacja kieruje wdrożeniem. Rejestr decyzji zachowuje osąd. Razem dają one agentom kodującym AI zarówno instrukcje, jak i kontekst – “co” i “dlaczego” – co czyni tę kombinację tak skuteczną dla złożonych, długotrwałych systemów.

Rejestry decyzji nie są specyfikacjami

Rejestry decyzji są powiązane ze specyfikacjami, ale służą innemu celowi. Specyfikacja mówi “system powinien robić X”, podczas gdy rejestr decyzji mówi “wybraliśmy X zamiast Y ze względu na te ograniczenia i kompromisy”. To “zamiast Y” jest cenną częścią. Narzędzia AI często generują rozwiązania, znajdując plausywalną ścieżkę do żądanego wyniku, ale rejestry decyzji mówią im, które plausywalne ścieżki zostały już zbadane, ocenione i odrzucone – redukując zmienność i poprawiając jakość pracy asystowanej przez AI.

Rejestry decyzji nie są zamiennikiem testów

Testy weryfikują behawior; rejestry decyzji wyjaśniają intencję. Obie są niezbędne i działają razem. Test może wymusić, że e-maile wygenerowane przez AI muszą być zapisane jako szkice, podczas gdy Rejestr Decyzji Produktowej wyjaśnia, że jest to wymagane, ponieważ użytkownicy muszą przeglądać komunikację wygenerowaną przez AI, zanim opuści ona system. Test chroni behawior. Rejestr decyzji chroni znaczenie. Razem sprawiają, że przyszłe zmiany są bezpieczniejsze i bardziej przewidywalne.

Rejestry decyzji nie są zamiennikiem komentarzy w kodzie

Komentarze w kodzie wyjaśniają lokalne szczegóły implementacyjne, podczas gdy rejestry decyzji wyjaśniają szersze decyzje. Używaj komentarzy dla zaskakujących linii, przypadków brzegowych, obejść i funkcji, których nie można uprościć. Używaj rejestrów decyzji dla tego, dlaczego istnieje architektura, dlaczego istnieje behawior produktu, dlaczego istnieje wzorzec interakcji i dlaczego zespół wybrał jeden kierunek zamiast drugiego. Jeśli wyjaśnienie dotyczy tylko kilku linii, komentarz jest odpowiednim narzędziem. Jeśli wpływa na kierunek systemu, rejestr decyzji jest odpowiednim narzędziem.

Częste błędy

Pisanie rejestrów zbyt późno

Rejestr decyzji powinien być napisany, gdy decyzja jest podejmowana, a nie miesiące później, gdy wszyscy zapomnieli o kompromisach. Jest w porządku stworzenie szkicu podczas pull request. Jest jeszcze lepiej stworzyć go przed wdrożeniem, gdy decyzja jest nadal aktywnie omawiana, a alternatywy są świeże.

Robienie rejestrów za długich

Rejestr decyzji nie jest esejem. Powinien być wystarczająco szczegółowy, aby zachować osąd, ale na tyle krótki, aby ludzie go faktycznie czytali. Preferuj klarowność nad kompletnością – zwięzły rejestr, który jest czytany, jest o wiele bardziej wartościowy niż kompleksowy, który jest pomijany.

Rejestrowanie decyzji bez konsekwencji

Sekcja konsekwencji jest sercem rejestru. Decyzja bez stwierdzonych konsekwencji jest często tylko preferencją, a nie rzeczywistą decyzją. Dobre rejestry szczerednie przyznają kompromisy, w tym co staje się trudniejsze lub ryzykowne w wyniku wyboru.

Edytowanie starych rejestrów, jakby historia się zmieniła

Gdy decyzja się zmienia, stwórz nowy rejestr i oznacz stary jako nadpisany. Ciche przepisywanie starej decyzji, aby pasowała do aktualnego stanu, niszczy kontekst historyczny, który sprawia, że rejestry decyzji są wartościowe. Historia jest przydatna właśnie dlatego, że pokazuje, jak ewoluowało myślenie.

Pozwalanie na scalanie rejestrów wygenerowanych przez AI bez przeglądu

AI może wyprodukować wypolerowany, dobrze ustrukturyzowany rejestr, który jest subtelnie błędny. Traktuj rejestry decyzji wygenerowane przez AI dokładnie jak kod wygenerowany przez AI – przeglądaj je ostrożnie, weryfikuj, czy uzasadnienie jest dokładne, i upewnij się, że sekcja konsekwencji odzwierciedla to, co zespół faktycznie zaakceptował.

Ukrywanie rejestrów na zewnątrz repozytorium

Jeśli rejestry decyzji żyją w osobnym wiki lub systemie dokumentacji, są mniej prawdopodobne do aktualizacji wraz ze zmianami kodu i znacznie mniej prawdopodobne do odczytu przez narzędzia kodujące AI ładujące kontekst dla zadania. Trzymanie ich w repozytorium to nie tylko wygoda – to sprawia, że praktyka działa dla rozwoju asystowanego przez AI.

Lekki model operacyjny

Praktyczny proces zespołowy, który dodaje minimalny narzut, wygląda tak:

1. Podczas planowania lub wdrożenia zidentyfikuj, czy podejmowana jest znacząca decyzja.
2. Poproś asystenta AI o stworzenie ADR, PDR lub DDR na podstawie dyskusji.
3. Przeglądaj szkic jako zespół, weryfikując kontekst, alternatywy i konsekwencje.
4. Zacommituj rejestr jako Markdown w repozytorium.
5. Powiąż go z powiązanym zgłoszeniem lub pull request.
6. Instrukuj narzędzia kodujące AI do odczytu istotnych rejestrów przed wprowadzeniem przyszłych zmian w tej dziedzinie.
7. Nadpisuj rejestry, gdy decyzje się zmieniają, zachowując stary rejestr dla historii.

To nie wymaga nowej biurokracji ani dedykowanej roli dokumentacyjnej. Wymaga małego nawyku: zachowywania ważnego osądu w momencie jego tworzenia, blisko kodu, gdzie będzie potrzebny.

Przykładowy ADR

# Decyzja: Użycie PostgreSQL do głównego magazynu aplikacji

Status: Akceptowany
Data: 2026-06-25
Typ: Architektura
Właściciele: Zespół Platformy

## Kontekst

Aplikacja potrzebuje trwałego relacyjnego magazynu dla kont, projektów,
uprawnień i zdarzeń audytowych. Zespół oczekuje częstych zapytań raportowych
i silnych wymagań spójności dla kontroli uprawnień.

## Decyzja

Będziemy używać PostgreSQL jako głównej bazy danych aplikacji.

## Rozważane alternatywy

### DynamoDB

Zalety:
- Skalowalność operacyjna
- Dobre dopasowanie dla przewidywalnych wzorców dostępu klucz-wartość

Wady:
- Bardziej złożone dla zapytań relacyjnych
- Trudniejsze dla raportów ad hoc
- Mniej znane dla obecnego zespołu

### MySQL

Zalety:
- Dojrzała baza danych relacyjna
- Znany model operacyjny

Wady:
- PostgreSQL lepiej pasuje do potrzeb zespołu w zakresie wsparcia JSON,
  opcji indeksowania i istniejącej wiedzy

## Konsekwencje

PostgreSQL staje się kluczową zależnością operacyjną. Zespół musi ostrożnie zarządzać
migracjami i monitorować wydajność zapytań. W zamian aplikacja otrzymuje silne modelowanie relacyjne,
dojrzałe indeksowanie i elastyczne wsparcie raportowe.

## Wytyczne dla AI

Podczas modyfikacji kodu trwałości, preferuj modelowanie relacyjne w PostgreSQL.
Nie wprowadzaj drugiej głównej bazy danych bez nadpisującego ADR.

Przykładowy PDR

# Decyzja: E-maile wygenerowane przez AI muszą pozostać jako szkice

Status: Akceptowany
Data: 2026-06-25
Typ: Produkt
Właściciele: Zespół Produktowy

## Kontekst

Produkt może generować odpowiedzi e-mail przy użyciu AI. Wysyłanie e-maili to
akcja o wysokim zaufaniu, ponieważ błędy mogą dotrzeć do klientów, partnerów lub
wewnętrznych zespołów.

## Decyzja

E-maile wygenerowane przez AI muszą być tworzone jako szkice. Użytkownik ludzki musi
przeglądać i wysyłać je.

## Rozważane alternatywy

### Wysyłanie automatyczne

Zalety:
- Szybszy przepływ pracy
- Mniejszy wysiłek użytkownika

Wady:
- Wyższe ryzyko nieprawidłowych lub nieodpowiednich wiadomości
- Niższe zaufanie użytkowników
- Trudniejsze odzyskiwanie z błędów

### Prośba o potwierdzenie dopiero po generowaniu

Zalety:
- Utrzymuje prosty przepływ pracy
- Zapewnia pewną kontrolę użytkownika

Wady:
- Nadal zachęca do powierzchownego przeglądu
- Nie pasuje tak dobrze do istniejącego zachowania klienta e-mail jak szkice

## Konsekwencje

Przepływ pracy jest nieco wolniejszy, ale bezpieczniejszy i bardziej wiarygodny.
Przyszła automatyzacja może poprawić szybkość przeglądu, ale nie może omijać
zatwierdzenia człowieka bez nadpisującego PDR.

## Wytyczne dla AI

Podczas budowania funkcji generowania e-maili, twórz szkice domyślnie.
Nie dodawaj automatycznego wysyłania, chyba że nowy zaakceptowany PDR wyraźnie to zezwala.

Przykładowy DDR

# Decyzja: Wyświetlanie sugestii pisania AI w panelu bocznym

Status: Akceptowany
Data: 2026-06-25
Typ: Projekt
Właściciele: Zespół Projektowy

## Kontekst

Użytkownicy potrzebują pomocy w poprawianiu treści pisanych, ale muszą też pozostać
w kontroli nad ostatecznym tekstem. Inline edycje AI mogą utrudnić rozróżnienie
treści napisanej przez użytkownika od wygenerowanych sugestii.

## Decyzja

Sugestie pisania AI będą pojawiać się w panelu bocznym. Użytkownicy mogą akceptować,
odrzucać lub kopiować sugestie do głównego edytora.

## Rozważane alternatywy

### Stosowanie sugestii inline

Zalety:
- Szybkie
- Wygląda zintegrowanie

Wady:
- Rozmywa autorstwo
- Utrudnia przegląd
- Może zaskakiwać użytkowników

### Wyświetlanie sugestii w modalu

Zalety:
- Skupione doświadczenie
- Łatwe do wdrożenia

Wady:
- Prerywa przepływ pisania
- Trudniejsze porównanie sugestii i oryginalnego tekstu

## Konsekwencje

Panel boczny zajmuje więcej miejsca na ekranie, szczególnie na małych ekranach.
Jednak zachowuje kontrolę użytkownika i sprawia, że przegląd jest klarowniejszy.

## Wytyczne dla AI

Podczas dodawania funkcji asystencji pisania, zachowuj separację między
tekstem użytkownika a sugestiami AI. Nie stosuj wygenerowanego tekstu bezpośrednio
do dokumentu bez wyraźnej akcji użytkownika.

Sugestia biblioteki promptów

Używaj tych promptów, aby uczynić rejestry decyzji częścią codziennego rozwoju asystowanego przez AI.

Znajdź istotne rejestry przed pracą nad funkcją:

Przeczytaj docs/decisions i zidentyfikuj wszystkie zaakceptowane rejestry decyzji, które mają zastosowanie
do tego zadania. Podsumuj ograniczenia przed zaproponowaniem zmian w kodzie.

Stwórz nowy ADR:

Stwórz Rejestr Decyzji Architektonicznej dla tej decyzji technicznej.
Dołącz kontekst, decyzję, alternatywy, konsekwencje i wytyczne dla AI.
Utrzymaj zwięzłość i specyficzność.

Stwórz nowy PDR:

Stwórz Rejestr Decyzji Produktowej dla tego behawioru produktu.
Dołącz wpływ na użytkownika, zakres, alternatywy, konsekwencje i wytyczne dla AI.

Stwórz nowy DDR:

Stwórz Rejestr Decyzji Projektowej dla tego wzorca interakcji.
Dołącz problem użytkownika, alternatywy, kompromisy, konsekwencje i wytyczne dla AI.

Przeglądaj pull request względem istniejących decyzji:

Przeglądaj ten pull request względem zaakceptowanych rejestrów decyzji w docs/decisions.
Zidentyfikuj wszelkie konflikty, brakujące rejestry decyzji lub decyzje, które powinny
być nadpisane.

Nadpisz decyzję:

Stwórz nowy rejestr decyzji, który nadpisuje istniejący.
Zachowaj historyczne uzasadnienie, wyjaśnij, co się zmieniło, i powiąż oba rejestry.

Powiązane materiały do czytania

• Oryginalny format ADR Michaela Nygarda — foundational post, który rozpoczął ruch ADR
• Organizacja ADR na GitHub — narzędzia, szablony i zasoby społecznościowe do zarządzania rejestrami decyzji
• Czym jest Rozwój Oparty na Specyfikacjach? Specyfikacja jako Źródło Prawdy — kanoniczna definicja SDD wyjaśniająca, jak specyfikacje funkcji uzupełniają rejestry decyzji: obie czynią intencję trwałą, na różnych poziomach systemu
• Rozwój Oparty na Specyfikacjach vs Vibe Coding: Kaskada? — kiedy używać SDD i kiedy pozostać przy szybszych, luźniejszych przepływach pracy
• Architektura Aplikacji w Produkcji: Wzorce Integracyjne, Projekt Kodu i Dostęp do Danych — dom klastra obejmujący integrację, testowanie, dostęp do danych i wzorce dokumentacji oprogramowania
• AI dla Zarządzania Wiedzą: Realne Przepływy Pracy, Które Trzymają Się Razem — praktyczne przepływy pracy zarządzania wiedzą z udziałem AI, które uzupełniają praktykę rejestrów decyzji