Rejestry decyzji w zautomatyzowanym procesie tworzenia oprogramowania

Rejestr decyzji to brakująca warstwa pamięci w wspomaganej sztuczną inteligencją dewelopie oprogramowania. Zapisują nie tylko to, co zostało zbudowane, ale także dlaczego — a ta różnica staje się kluczowa, gdy narzędzia AI piszą Twój kod.

Rejestry decyzji to brakująca warstwa pamięci

Programowanie napędzane przez AI zmienia ekonomię dewelopki oprogramowania, czyniąc kod tańszym w generowaniu, łatwiejszym do refaktoryzacji i szybszym do odrzucenia. To jest przydatne. Jest też niebezpieczne, ponieważ gdy kod staje się łatwiejszy w produkcji, zasobem ograniczającym nie jest już pisanie na klawiaturze — zasobem ograniczającym jest 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 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 i konsekwencje, na które zespół się zgodził. W kodzie wspieranym 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ą przeczytać przed wprowadzeniem przyszłych zmian. Praktyczna zasada operacyjna jest prosta: trzymaj rejestry decyzji jako pliki Markdown w repozytorium, przeglądaj je jak kod i pozwól przyszłym narzędziom AI czytać je przed proponowaniem lub implementowaniem zmian.

Czym są rejestry decyzji?

Rejestr decyzji to zapisany na piśmie dokument znaczącej decyzji, ustrukturyzowany tak, aby odpowiadać na cztery podstawowe pytania: co zdecydowaliśmy, dlaczego to zdecydowaliśmy, jakie alternatywy rozważyliśmy i jakie konsekwencje zaakceptowaliśmy? Najczęstsza forma to Rejestr Decyzji Architektonicznej, skrócony do ADR. ADR-y są szeroko stosowane do dokumentowania decyzji technicznych, a ten sam wzorzec można rozszerzyć poza architekturę na pracę nad produktem i designem.

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 i rozumowanie stojące za doświadczeniem użytkownika. Ta kombinacja ma znaczenie, ponieważ agenci AI mogą czytać kod, ale sam kod nie zawiera wystarczająco kontekstu, aby podejmować dobre decyzje. Rejestry decyzji dają systemom AI zweryfikowane, trwałe, zatwierdzone przez człowieka źródło intencji projektu.

Rejestry Decyzji Architektonicznych

Rejestry Decyzji Architektonicznych 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 modularnego monolitu
• Wprowadzenie kolejki wiadomości
• Wybór REST zamiast GraphQL
• Użycie renderowania po stronie serwera dla aplikacji internetowej
• Wymaganie, aby wszystkie zadania w tle były idempotentne
• Przyjęcie konkretnego modelu uwierzytelniania i autoryzacji

ADR nie jest pełnym dokumentem architektonicznym — jest celowo mały, zapisując jedną ważną decyzję w określonym 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ą proponować technicznie prawdopodobną zmianę, która narusza szersze ograniczenie architektoniczne. ADR daje AI jasną granicę: “Tak ma być ukształtowany ten system.”

Rejestry Decyzji Produktowych

Rejestry Decyzji Produktowych odzwierciedlają zachowanie produktu, zakres i intencje skierowane do użytkownika. Jest to mniej powszechne niż ADR-y, ale często tak samo wartościowe — decyzje produktowe są często rozproszone w zgłoszeniach, narzędziach roadmapy, wątkach czatu, notatkach z spotkań i pamięci ludzi, co czyni je łatwymi do zapomnienia przez ludzi i prawie niemożliwymi do wiarygodnego 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ć w formie draftów do momentu przeglądu przez człowieka
• Użytkownicy warstwy darmowej mogą utworzyć do trzech projektów
• Usunięte przestrzenie robocze są przywracalne przez 30 dni
• Fakturowanie zespołowe jest poza zakresem wersji 1
• Użytkownicy mogą eksportować swoje dane bez kontaktowania się z obsługą
• Podsumowania AI o niskim poziomie zaufania wyświetlają ostrzeżenie zamiast być ukrywane

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

Rejestry Decyzji Designowych

Rejestry Decyzji Designowych odzwierciedlają decyzje dotyczące doświadczenia użytkownika, interakcji, wyglądu i designu treści. Użyj DDR, gdy decyzja wpływa na to, jak użytkownicy interagują z produktem, jak prezentowane są informacje lub jak zasada designowa powinna być stosowana w przyszłej pracy.

Przykłady decyzji designowych 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 postępowego ujawniania dla zaawansowanych ustawień
• Wymaganie potwierdzenia przed niszczącymi działaniami
• Użycie “Draft” i “Opublikowany” zamiast “Nieaktywny” i “Aktywny”
• Pozostawienie głównych akcji widocznych na ekranach mobilnych

Intencja designowa jest łatwa do utraty podczas implementacji. Developer może uproś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 odzwierciedlać: “Wyświetlamy sugestie pisarskie AI obok dokumentu, a nie wewnątrz niego, ponieważ użytkownicy muszą porównać wygenerowany tekst ze swoim własnym draftem przed zaakceptowaniem zmian.” Ten zapis 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 do kodowania 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ą celowe, które przypadkowe, a które już zostały przeanalizowane i rozwiązane. Tworzy to kilka odrębnych ryzyk.

AI może ponownie otworzyć zakończone debaty

Jeśli zespół już zdecydował na użycie modularnego monolitu, agent AI może nadal proponować wyciągnięcie 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 subtelną regresja spójności systemu.

AI może optymalizować lokalnie i uszkodzić globalnie

Wygenerowana refaktoryzacja może uczynić jeden plik czystszym, łamiąc granice systemu. Zmiana UI może zmniejszyć złożoność komponentu, osłabiając zamierzone doświadczenie użytkownika. Zmiana produktu może uprościć implementację, łamiąc założenia dotyczące cen lub zgodności. Rejestry decyzji dają AI szerszy ramy 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 kodzie, ale wzorce nie są tym samym, co zasady. Czasami istniejący kod jest kompromisem. Czasami jest przejściowy. Czasami istnieje ze względu na zewnętrzne ograniczenie, które nie jest widoczne w pliku. Rejestry decyzji wyjaśniają różnicę między “tak to działa” a “dlaczego zostało to zbudowane w ten sposób”.

AI może generować prawdopodobne, ale błędne uzasadnienie

AI może tworzyć rejestry decyzji, ale może też wymyślać brzmiące pewnie wyjaśnienia, które nie pasują do rzeczywistej decyzji. Dlatego przegląd przez człowieka jest niezgodny z warunkami: AI może wygenerować pierwszy draft rejestru, ale człowiek musi zweryfikować, że dokładnie opisuje faktyczną 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 skrzyżowaniu lekkiej governance architektury, dokumentacji jako kodu, przepływów pracy zarządzania wiedzą wspomaganych przez AI, odkrywania produktu, uzasadnienia designu, governance AI i przeglądu kodu. Przydatnym sposobem opisu szerszego procesu jest Dewelopka Skierowana Decyzjami.

Większość przepływów pracy programowania napędzanego przez AI skupia się wąsko na pętli generuj-przeglądaj-commituj:

Ten cykl jest zbyt cienki dla poważnej pracy systemowej. Silniejszy 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 implementacji, intencji i rozumowania — trwałym artefaktem, który gromadzi wartość z każdą podejmowaną 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 Markdownie, przeglądane w pull requestach, wersjonowane z Git, połączone z powiązanymi zgłoszeniami i pull requestami oraz przeszukiwalne przez zarówno ludzi, jak i narzędzia AI. Jest to znacznie bardziej niezawodne niż przechowywanie ważnych decyzji w czatach, stronach wiki, prezentacjach lub notatkach z spotkań — te narzędzia mogą nadal być przydatne do dyskusji, ale zaakceptowana decyzja powinna zawsze żyć blisko kodu. Utrzymywanie Specyfikacji, Testów i Kodu w Synchronizacji w Dewelopce AI rozszerza ten sam nawyk “połącz z powrotem do rejestru” do pełnego modelu śledzenia, który wiąże identyfikatory decyzji wymaganiowych i designowych z testami i pull requestami.

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 płaska struktura działa równie dobrze. 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 kodzie. 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óry 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 wartościową sekcję wytycznych dla AI:

# Decyzja: Krótki tytuł

Status: Proponowany | Akceptowany | Przestarzały | Deprekowany
Data: YYYY-MM-DD
Typ: Architektura | Produkt | Design
Właściciele: Zespół lub imiona

## Kontekst

Opisz problem, ograniczenia, cele, potrzeby użytkowników, fakty techniczne
i 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 trudniejsze i jakie ryzyko
lub pracę nadążną to tworzy.

## Wytyczne dla AI

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

## Linki

- Powiązane zgłoszenia:
- Powiązane pull requesty:
- Powiązane pliki:
- Przestarza:
- Przestarzały przez:

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

Co powinno znaleźć się w rejestrze decyzji?

Nie każdy wybór zasługuje na rejestr, a jeśli każdy mały szczegół implementacji stanie się rejestr decyzji, proces zamieni się w szum. Twó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ę produktu
• Rozwiązują prawdziwą 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 prawdopodobnie źle zrozumieć
• Przyszli współtwórcy mogliby być pokuszeni do przypadkowego odwrócenia

Pogorszymi kandydatami są drobne wybory refaktoryzacji, oczywiste poprawki błędów, tymczasowe eksperymenty, lokalne decyzje dotyczące nazewnictwa i szczegóły implementacyjne bez trwałych konsekwencji. Dobrą zasadą 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 sygnalizować ich aktualny stan. Najprostsze wartości statusu są wystarczające.

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

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

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

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

Wažną zasadą jest, że rejestry decyzji powinny być przyjazne do dodawania. Gdy zespół zmienia kierunek, twórz nowy rejestr i łącz go ze starym, zamiast przepisywać historię, aby przeszłość wyglądała czystszym.

Jak AI powinno generować rejestry decyzji

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

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

Dla pracy nad produktem:

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

Jednak wygenerowany przez AI rejestr nie powinien być automatycznie zaufany. Przegląd przez człowieka powinien zweryfikować, że kontekst jest dokładny, że AI nie wymyśliło uzasadnienia, że wymienione alternatywy są prawdziwe, że konsekwencje są szczere i że wytyczne dla AI pasują do rzeczywistej intencji zespołu. AI jest asystentem w tworzeniu draftów — nie jest właścicielem decyzji.

Jak AI powinno czytać rejestry decyzji

Drugą połową praktyki jest instrukcjonowanie AI do czytania rejestrów przed działaniem. Przed poproszeniem asystenta AI o implementację zmiany, dołącz instrukcję taką jak:

Przed modyfikacją tej funkcji, przeczytaj docs/decisions.
Zidentyfikuj wszystkie Rejestry Decyzji Architektonicznych, Produktowych lub Designowych, które się stosują.
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 zaproponowania nowej decyzji przestarzającej.
Gdy generujesz kod, wyjaśnij, które rejestry decyzji wpłynęły na implementację.

To zmienia rolę AI z “przewidywania prawdopodobnego 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ów, a nie oddzielnym procesem. Prosty wpis na liście kontrolnej PR sprawia, że nawyk jest widoczny:

## Lista kontrolna rejestrów decyzji

- [ ] Ten PR nie wprowadza znaczącej decyzji architektonicznej, produktowej lub designowej.
- [ ] Ten PR wprowadza znaczącą decyzję i zawiera nowy rejestr decyzji.
- [ ] Ten PR zmienia poprzednią decyzję i zawiera rejestr przestarzający.
- [ ] 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 przejrzańe przez człowieka.

Ta lista kontrolna 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ż wychwycenie, gdy zmiana wygenerowana przez AI cicho łamie poprzednią decyzję.

Rejestry decyzji i governance architektury

Tradycyjna governance architektury często zawodzi, ponieważ jest zbyt ciężka, zbyt wolna lub zbyt odłączona od implementacji — centralne rady zatwierdzania, duże wstępne dokumenty i procesy gatekeepingu, które blokują zamiast kierować. Rejestry decyzji oferują lżejszą alternatywę, która integruje się bezpośrednio z przepływem deweloperskim.

Nie wymagają centralnej rady architektury dla każdej zmiany ani nie blokują zespołów od uczenia się i adaptacji. Zamiast tego tworzą ślad decyzji, który można przeglądać, odwoływać się do niego i budować na nim z czasem. To wspiera ewolucyjną architekturę: architektura może się zmieniać, ale zmienia się z pamięcią, a nie pomimo niej. Zespół może ponownie odwiedzić stare decyzje bez konieczności ponownego odkrywania, dlaczego zostały podjęte, co jest zdrowszą i bardziej szczereą formą governance:

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

Rejestry decyzji i zarządzanie produktem

Praca nad produktem również potrzebuje pamięci decyzji, a to obszar, w którym wartość rejestrów decyzji jest często niedoszacowywana. Roadmapa mówi, co może się stać. Zgłoszenie mówi, co zbudować następne. Analityka mówi, co robili użytkownicy. Żadne z tych w pełni nie wyjaśnia, dlaczego istnieje zachowanie 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, przepływów bezpieczeństwa i przeglądu AI, wyborów onboardingowych, definicji ról użytkowników, zasad współpracy, polityk retencji danych i granic zakresu funkcji. Po zaimplementowaniu, 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 użyć.

Rejestry decyzji i systemy designowe

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

To uzasadnienie ma znaczenie poza konkretnym komponentem. Pomaga przyszłym designerom, developerom i narzędziom AI poprawnie zastosować zasadę w nowych sytuacjach. Bez DDR, agent AI może wygenerować szybszą interakcję, która pomija potwierdzenie, ponieważ wydaje się bardziej efektywna. Dzięki DDR, agent może rozpoznać, że zachowanie własności bezpieczeństwa jest celowe i niezgodne z warunkami.

Jak rejestry decyzji wspierają dewelopenkę napędzaną specyfikacjami

Dewelopenka napędzana specyfikacjami wyjaśnia, co system powinien robić. Rejestry decyzji wyjaśniają, dlaczego zespół wybrał ten kierunek, a różnica ma duże znaczenie dla pracy wspomaganej przez AI.

Specyfikacja funkcji może mówić, że e-maile wygenerowane przez AI muszą być zapisane jako drafty. 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 designowa 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 zostało ważniejsze niż szybkość przepływu pracy. Specyfikacja architektoniczna może zdefiniować granicę usługi, a jej ADR wyjaśnia, dlaczego zespół wybrał tę granicę zamiast prostszej lub bardziej rozproszonej alternatywy.

Specyfikacja kieruje implementacją. 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. Gdy przyjąłeś łańcuch narzędzi napędzany specyfikacjami, porównaj, jak każda opcja ujawnia ten kontekst; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows omawia przenośność, bramy przeglądu i osadzenie repozytorium w głównych konfiguracjach. Dla neutralnego narzędziowo pięciopiętrowego procesu, który te narzędzia implementują, zobacz Przepływ Pracy Dewelopki Napędzanej Specyfikacjami Od Wymagań do Kodu.

Rejestry decyzji to nie specyfikacje

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 prawdopodobną ścieżkę do żądanego wyniku, ale rejestry decyzji mówią im, które prawdopodobne ścieżki zostały już przebadane, ocenione i odrzucone — zmniejszając przepływ i poprawiając jakość pracy wspomaganej przez AI.

Rejestry decyzji to nie zamiennik testów

Testy weryfikują zachowanie; rejestry decyzji wyjaśniają intencję. Oba są konieczne i działają razem. Test może wymuszać, że e-maile wygenerowane przez AI muszą być zapisane jako drafty, podczas gdy Rejestr Decyzji Produktowej wyjaśnia, że jest to wymagane, ponieważ użytkownicy muszą przeglądać komunikację wygenerowaną przez AI przed jej wyjściem z systemu. Test chroni zachowanie. Rejestr decyzji chroni znaczenie. Razem czynią przyszłe zmiany bezpieczniejszymi i bardziej przewidywalnymi.

Rejestry decyzji to nie zamiennik komentarzy w kodzie

Komentarze w kodzie wyjaśniają lokalne szczegóły implementacji, 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 uproszczyć. Używaj rejestrów decyzji dla tego, dlaczego istnieje architektura, dlaczego istnieje zachowanie 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 w momencie podjęcia decyzji, a nie miesiące później, gdy wszyscy zapomnieli kompromisy. Jest w porządku, aby stworzyć draft podczas pull request. Jest jeszcze lepiej, aby stworzyć go przed implementacją, podczas gdy decyzja jest nadal aktywnie omawiana, a alternatywy są świeże.

Robienie rejestrów zbyt długich

Rejestr decyzji to nie esej. Powinien być wystarczająco szczegółowy, aby zachować osąd, ale na tyle krótki, aby ludzie go faktycznie czytali. Preferuj jasność nad kompletnością — zwięzły rejestr, który zostaje przeczytany, jest znacznie bardziej wartościowy niż wszechstronny, który zostaje pominięty.

Rejestrowanie decyzji bez konsekwencji

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

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

Gdy decyzja się zmienia, twórz nowy rejestr i oznacz stary jako przestarzały. Ciche przepisywanie starej decyzji, aby pasowała do aktualnego stanu, niszczy kontekst historyczny, który czyni rejestry decyzji wartościowymi. Historia jest przydatna dokładnie dlatego, że pokazuje, jak ewoluowało myślenie. Skompilowane bazy wiedzy napotykają ten sam identyczny problem pod inną nazwą — Konserwacja Wiki LLM: Dryf, Sprzeczności i Przegląd nazywa to dryfem decyzji i stosuje tę samą zasadę zastąpienia zamiast nadpisania do stron wiki.

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

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

Ukrywanie rejestrów poza repozytorium

Jeśli rejestry decyzji żyją w oddzielnej wiki lub systemie dokumentacji, są mniej prawdopodobne do aktualizacji wraz ze zmianami kodu i znacznie mniej prawdopodobne do przeczytania przez narzędzia kodujące AI ładujące kontekst dla zadania. Trzymanie ich w repozytorium to nie tylko wygoda — to czyni praktykę skuteczną dla dewelopki wspomaganej przez AI.

Lekki model operacyjny

Praktyczny proces zespołowy, który dodaje minimalne obciążenie, wygląda tak:

1. Podczas planowania lub implementacji, zidentyfikuj, czy podejmowana jest znacząca decyzja.
2. Poproś asystenta AI o stworzenie draftu ADR, PDR lub DDR na podstawie dyskusji.
3. Przeglądaj draft jako zespół, weryfikując kontekst, alternatywy i konsekwencje.
4. Commituj rejestr jako Markdown w repozytorium.
5. Połącz go z powiązanym zgłoszeniem lub pull request.
6. Instrukcjonuj narzędzia kodujące AI do czytania istotnych rejestrów przed wprowadzeniem przyszłych zmian w tej dziedzinie.
7. Przestarzaj 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ół Platformowy

## 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
- Dobrze pasuje do przewidywalnych wzorców dostępu klucz-wartość

Wady:
- Bardziej złożony dla zapytań relacyjnych
- Trudniejszy dla raportów ad hoc
- Mniej znany obecnemu zespołowi

### MySQL

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

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

## 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 przestarzającego ADR.

Przykładowy PDR

# Decyzja: E-maile wygenerowane przez AI muszą pozostać w formie draftów

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-mail jest
działaniem 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 drafty. Użytkownik ludzki musi
przeglądać i je wysyłać.

## 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żytkownika
- Trudniejsze odzyskiwanie z błędów

### Prośba o potwierdzenie dopiero po generowaniu

Zalety:
- Utrzymuje prostotę przepływu pracy
- Zapewnia pewną kontrolę użytkownika

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

## Konsekwencje

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

## Wytyczne dla AI

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

Przykładowy DDR

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

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

## Kontekst

Użytkownicy potrzebują pomocy w ulepszaniu treści pisanych, ale również muszą pozostać
w kontroli nad końcowym tekstem. Inline edycje AI mogą utrudnić rozróżnienie treści napisanych przez użytkownika od wygenerowanych sugestii.

## Decyzja

Sugestie pisarskie 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:
- Zacieranie autorstwa
- Utrudnia przegląd
- Może zaskakiwać użytkowników

### Wyświetlanie sugestii w modalu

Zalety:
- Skupione doświadczenie
- Łatwe do implementacji

Wady:
- Przerwa w przepływie pisania
- Trudniejsze porównanie sugestii i oryginalnego tekstu

## Konsekwencje

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

## Wytyczne dla AI

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

Sugestowana biblioteka promptów

Używaj tych promptów, aby uczynić rejestry decyzji częścią codziennej dewelopki wspomaganej przez AI.

Znajdź istotne rejestry przed pracą nad funkcją:

Przeczytaj docs/decisions i zidentyfikuj wszystkie akceptowane rejestry decyzji, które stosują się
do tego zadania. Podsumuj ograniczenia przed zaproponowaniem zmian kodu.

Stwórz nowy ADR:

Stwórej Rejestr Decyzji Architektonicznej dla tej decyzji technicznej.
Dołącz kontekst, decyzję, alternatywy, konsekwencje i wytyczne dla AI.
Utrzymaj ją zwięzłą i konkretną.

Stwórz nowy PDR:

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

Stwórz nowy DDR:

Stwórej Rejestr Decyzji Designowej 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 akceptowanych rejestrów decyzji w docs/decisions.
Zidentyfikuj wszelkie konflikty, brakujące rejestry decyzji lub decyzje, które powinny
zostać przestarzałe.

Przestarzaj decyzję:

Stwórej nowy rejestr decyzji, który przestarza istniejący.
Zachowaj historyczne uzasadnienie, wyjaśnij, co się zmieniło, i połącz oba rejestry.

Powiązana lektura

• Oryginalny format ADR Michaela Nygarda — podstawowy 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 Spec-Driven Development? Spec 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
• Dewelopenka Napędzana Specyfikacjami vs Vibe Coding: Kaskada? — kiedy używać SDD i kiedy pozostać przy szybszych, luźniejszych przepływach pracy
• Architektura Aplikacji w Produkcji: Wzorce Integracji, Design Kodu i Dostępu do Danych — dom klastrowy obejmujący integrację, testowanie, dostęp do danych i wzorce dokumentacji oprogramowania
• AI dla Zarządzania Wiedzą: Prawdziwe Przepływy Pracy, Które Trzymają Się — praktyczne przepływy pracy zarządzania wiedzą wspomagane przez AI, które uzupełniają praktykę rejestrów decyzji