Dokumentacja decyzji w rozwoju oprogramowania opartym na AI

Rekordy decyzji to brakująca warstwa pamięci w rozwoju oprogramowania wspieranym przez AI. Łączą one nie tylko to, co zostało zbudowane, ale i dlaczego — a ta różnica staje się kluczowa, gdy to narzędzia AI piszą Twój kod.

Rekordy decyzji to brakująca warstwa pamięci

Programowanie napędzane przez AI zmienia ekonomię rozwoju oprogramowania, czyniąc kod tańszym w generowaniu, łatwiejszym w refaktoryzacji i szybszym w porzucaniu. To jest przydatne. Jest jednak też niebezpieczne, ponieważ gdy kod staje się łatwiejszy do wytworzenia, zasobem rzadkim przestaje być samo pisanie — zasobem rzadkim staje się są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 bocznym panelu, zamiast stosować je bezpośrednio? Dlaczego prostsze podejście zostało odrzucone sześć miesięcy temu? Kod może pokazywać to, co istnieje, ale rzadko wyjaśnia, dlaczego to istnieje.

Rekordy decyzji rozwiązują ten problem, zapewniając krótki, wersjonowany dokument, który odnotowuje ważny wybór, kontekst stojący za nim, rozważone alternatywy oraz konsekwencje, które zespół zaakceptował. W bazie kodu wspieranej przez AI te rekordy 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 dokonywaniem przyszłych zmian. Praktyczna zasada operacyjna jest prosta: trzymaj rekordy decyzji jako pliki Markdown w repozytorium, przeglądaj je tak jak kod i pozwalaj przyszłym narzędziom AI odczytywać je przed proponowaniem lub wdrażaniem zmian.

Czym są rekordy decyzji?

Rekord decyzji to spisany dokument istotnej decyzji, ustrukturyzowany tak, aby odpowiadać 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 Architekturany Rekord Decyzji (ADR). ADR-y są szeroko stosowane do dokumentowania decyzji technicznych, a ten sam wzorzec można rozszerzyć poza architekturę na pracę produktową i projektową.

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 również intencję produktu i rozumowanie stojące za doświadczeniem użytkownika. To połączenie jest istotne, ponieważ agenci AI mogą odczytywać kod, ale sam kod nie zawiera wystarczającego kontekstu, aby podejmować dobre decyzje. Rekordy decyzji dostarczają systemom AI zweryfikowanego, trwałego i zatwierdzonego przez człowieka źródła intencji projektu.

Architecture Decision Records (ADR)

Architecture Decision Records (Rekordy Decyzji Architektonicznych) odnotowują decyzje techniczne i strukturalne. Używaj ADR, gdy decyzja wpływa na kształt systemu — jego granice, zależności, model operacyjny lub długoterminową utrzymywalność.

Przykłady decyzji warte odnotowania jako ADR obejmują:

• Wybór PostgreSQL jako głównej bazy danych
• Użycie architektury zorientowanej na zdarzenia do przetwarzania w tle
• Utrzymanie aplikacji jako modułowego monolitu
• Wprowadzenie kolejki wiadomości
• Wybór REST zamiast GraphQL
• Użycie renderowania po stronie serwera dla aplikacji webowej
• Wymaganie, aby wszystkie zadania w tle były idempotentne
• Przyjęcie określonego modelu uwierzytelniania i autoryzacji

ADR nie jest pełnym dokumentem architektonicznym — jest celowo mały, odnotowując jedną ważną decyzję w określonym momencie w czasie. Dobre ADR zapobiega amnezji architektonicznej: bez niego przyszli współtwórcy mogą na nowo odkrywać te same kompromisy, otwierać stare debaty lub przypadkowo odwracać ważne ograniczenia.

W programowaniu napędzanym przez AI ADR-y niosą na sobie nawet większą wagę. Narzędzia AI są często biegłe w optymalizacji lokalnej i mogą proponować zmianę technicznie prawdopodobną, która łamie szersze ograniczenie architektoniczne. ADR daje AI jasną granicę: „Tak ma być ukształtowany ten system.”

Product Decision Records (PDR)

Product Decision Records (Rekordy Decyzji Produktowych) odnotowują zachowanie produktu, zakres i intencję skierowaną do użytkownika. Jest to mniej powszechne niż ADR, ale często równie wartościowe — decyzje produktowe są często rozproszone po biletach, narzędziach do mapowania trasy (roadmap), wątkach czatu, notatkach z posiedzeń i pamięci ludzi, co sprawia, że ludzie łatwo je zapominają, a dla narzędzi AI są one niemal niemożliwe do wiarygodnego wywnioskowania.

Używaj 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, dopóki nie zostaną sprawdzone przez człowieka
• Użytkownicy warstwy darmowej mogą tworzyć do trzech projektów
• Usunięte przestrzenie robocze są odzyskiwalne przez 30 dni
• Fakturowanie zespołowe znajduje się poza zakresem wersji 1
• Użytkownicy mogą wyeksportować swoje dane bez kontaktu z pomocą techniczną
• Podsumowania AI o niskim stopniu pewności wyświetlają ostrzeżenie, zamiast być ukryte

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 potraktować tę liczbę jako magiczną stałą i zasugerować jej zmianę. Z PDR, AI może widzieć, że limit jest powiązany ze strategią cenową, kosztem onboardingu lub obciążeniem wsparcia — i że jego zmiana wymaga świadomej decyzji produktowej, a nie szybkiej edycji.

Design Decision Records (DDR)

Design Decision Records (Rekordy Decyzji Projektowych) odnotowują decyzje dotyczące doświadczenia użytkownika, interakcji, wizualizacji i projektowania treści. Używaj DDR, gdy decyzja wpływa na to, jak użytkownicy interagują z produktem, jak prezentowane są informacje lub jak zasada projektowa powinna być stosowana w przyszłych pracach.

Przykłady decyzji projektowych wartych odnotowania obejmują:

• Używanie walidacji inline zamiast walidacji tylko przy wysyłaniu
• Umieszczanie sugestii AI w bocznym panelu, a nie bezpośrednio w edytorze
• Używanie progresywnego ujawniania (progressive disclosure) dla zaawansowanych ustawień
• Wymaganie potwierdzenia przed niszczącymi akcjami
• Używanie „Szkic” i „Opublikowany” zamiast „Nieaktywny” i „Aktywny”
• Utrzymywanie widocznych akcji głównych na ekranach mobilnych

Intencja projektowa jest łatwa do utraty podczas implementacji. Programista 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 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 zaakceptowaniem zmian.” Ten rekord daje przyszłym współtwórcom zasadę do zachowania, a nie tylko układ do skopiowania.

Dlaczego rekordy decyzji mają większe znaczenie z AI

Narzędzia do kodowania AI są potężne, ale często są bezstanowe lub mają tylko częściową świadomość historii projektu. Mogą inspekcjonować pliki, wnioskować wzorce i generować zmiany — ale nie wiedzą automatycznie, które decyzje są zamierzone, które przypadkowe, a które były już przedyskutowane i rozwiązane. Stwarza to kilka odrębnych ryzyk.

AI może ponownie otwierać zakończone debaty

Jeśli zespół już zdecydował się na użycie 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 zmarnowany wysiłek lub subtelny regres spójności systemu.

AI może optymalizować lokalnie i szkodzić globalnie

Wygenerowana refaktoryzacja może sprawić, że jeden plik stanie się czystszy, łamiąc jednocześnie granice systemu. Zmiana interfejsu może zmniejszyć złożoność komponentu, osłabiając zamierzone doświadczenie użytkownika. Zmiana produktowa może uprościć implementację, łamiąc założenia dotyczące cen lub zgodności z przepisami. Rekordy decyzji dają AI szerszą ramę odniesienia, zanim zacznie działać na wąsko zakresowanych sygnałach.

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

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

AI może wygenerować prawdopodobny, ale błędny uzasadnienie

AI może szkicować rekordy decyzji, ale może też wymyślać pewne brzmieniem wyjaśnienia, które nie odpowiadają rzeczywistej decyzji. Dlatego przegląd przez człowieka jest niezbywalny: AI może wygenerować pierwszy szkic rekordu, ale człowiek musi zweryfikować, że dokładnie opisuje on faktyczną decyzję, alternatywy i konsekwencje, zanim rekord zostanie scalony.

Rekordy decyzji jako część szerszej metodyki

Rekordy decyzji to nie tylko dokumentacja — są częścią szerszego sposobu pracy, który znajduje się na przecięciu lekkiego zarządzania architekturą, dokumentacji jako kodu, workflowów zarządzania wiedzą rozszerzonych przez AI, odkrywania produktu, uzasadnienia projektowego, zarządzania AI i przeglądu kodu. Przydatnym sposobem na opisanie większego procesu jest Rozwój Orientowany na Decyzje.

Większość workflowów programowania napędzanego przez AI koncentruje się wąsko na pętli generowanie-przegląd-zatwierdzenie:

Ten cykl jest zbyt cienki dla poważnej pracy systemowej. Silniejszy workflow traktuje repozytorium jako składowisko zarówno kodu, jak i intencji — diagramy tutaj używają Mermaid, lekkiego formatu, który dobrze działa również wewnątrz rekordów decyzji Markdown:

Ten proces zmienia repozytorium w coś więcej niż składowisko kodu. Staje się źródłem prawdy dla implementacji, intencji i rozumowania — trwałym artefaktem, który gromadzi wartość przy każdej podejmowanej decyzji.

Rekordy decyzji i dokumentacja jako kod

Rekordy decyzji działają najlepiej, gdy podążają za zasadami dokumentacji-jako-kodu (docs-as-code), co oznacza, że powinny być przechowywane w tym samym repozytorium co kod, pisane w czystym Markdown, przeglądane w pull requestach, wersjonowane przez Git, łączone z powiązanymi problemami i pull requestami oraz wyszukiwalne zarówno przez ludzi, jak i narzędzia AI. Jest to znacznie bardziej niezawodne niż przechowywanie ważnych decyzji w czacie, stronach wiki, prezentacjach slajdowych lub notatkach z posiedzeń — te narzędzia mogą nadal być przydatne do dyskusji, ale zaakceptowana decyzja powinna zawsze znajdować się blisko kodu. Utrzymywanie spójności specyfikacji, testów i kodu w rozwoju AI rozszerza ten sam nawyk „połącz to z powrotem z rekordem” na pełny model śledzenia, wiążący identyfikatory wymagań i decyzji projektowych z testami i pull requestami.

Dobrze zorganizowana struktura repozytorium dla rekordó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 dobrze sprawdzi się również płaska struktura. Dokładna organizacja folderów jest mniej ważna niż spójność — rekordy muszą być łatwe do znalezienia, łatwe do przeglądu i łatwe dla narzędzi AI do załadowania jako kontekst przed działaniem na bazie kodu. Dla zespołów Go, ta struktura docs/decisions/ naturalnie mieści się obok układu cmd/, internal/ i api/ opisanego w Struktura projektu Go: Praktyki i wzorce, który rekomenduje docs/ jako miejsce dla decyzji architektonicznych i referencji API.

Praktyczny szablon rekordu decyzji

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

# Decyzja: Krótki tytuł

Status: Propozycja | Akceptowany | Przekroczone | Odrzucone
Data: YYYY-MM-DD
Typ: Architektura | Produkt | Projekt
Właściciele: Zespół lub nazwiska

## Kontekst

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

## Decyzja

Sformułuj decyzję jasno.

## Rozważone alternatywy

### Opcja 1

Zalety:
- ...

Wady:
- ...

## Konsekwencje

Opisz, co stanie się łatwiejsze, co stanie się trudniejsze i jakie ryzyka
lub prace następcze to tworzy.

## Wytyczne dla AI

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

## Linki

- Powiązane problemy:
- Powiązane pull requesty:
- Powiązane pliki:
- Przekroczone przez:
- Przekroczone przez:

Sekcja „Wytyczne dla AI” jest opcjonalna, ale w programowaniu napędzanym przez AI jest niezwykle cenna — zamienia rekord decyzji w trwałą instrukcję dla przyszłych agentów pracujących w tym samym obszarze bazy kodu.

Co powinno znajdować się w rekordzie decyzji?

Nie każda zasługuje na rekord, a jeśli każdy mały detal implementacyjny stanie się rekordem decyzji, proces przejdzie w szum. Utwórz rekord decyzji, gdy wybór jest istotny i prawdopodobnie będzie miał znaczenie później.

Dobrymi kandydatami są decyzje, które:

• Wpływają na wiele części systemu
• Kodują obietnicę produktową
• Rozstrzygają realną debatę
• Wprowadzają długoterminowy trade-off
• Zależą od ograniczeń biznesowych, compliance lub operacyjnych
• Byłyby kosztowne do ponownego odkrycia
• Przyszłe narzędzia AI mogłyby prawdopodobnie źle odczytać
• Przyszli współtwórcy mogą być skuszeni do casualowego odwrócenia

Słabymi kandydatami są drobne wybory refaktoryzacji, oczywiste poprawki błędów, tymczasowe eksperymenty, lokalne decyzje nazewnicze i detale implementacyjne bez trwałej konsekwencji. Dobrą zasadą jest prosta: jeśli odwrócenie decyzji wymagałoby dyskusji, odnotuj tę decyzję.

Wartości statusu i cykl życia

Rekordy decyzji powinny mieć cykl życia, aby sygnalizować ich bieżący status. Najprostsze wartości statusu są wystarczające.

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

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

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

Odrzucony — 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 bazie kodu obok nowych podejść.

Ważną zasadą jest to, że rekordy decyzji powinny być przyjazne dla dopisywania (append-friendly). Gdy zespół zmienia kierunek, utwórz nowy rekord i połóż stary, zamiast przepisywać historię, aby przeszłość wyglądała na czystszą.

Jak AI powinno generować rekordy decyzji

AI może pomóc w tworzeniu rekordów decyzji, a to jest jednym z lepszych zastosowań AI w rozwoju oprogramowania — jest szybkie w szkicowaniu ustrukturyzowanych dokumentów z kontekstu. Po dyskusji, przeglądzie architektonicznym lub pull requestu, możesz poprosić asystenta AI o szkic rekordu:

Szkicuj Architecture Decision Record (ADR) dla decyzji w tym pull request.
Włącz kontekst, alternatywy, konsekwencje i wytyczne dla AI.
Zapisz jako Markdown pod docs/decisions/architecture.

Dla pracy produktowej:

Szkicuj Product Decision Record (PDR) wyjaśniający, dlaczego wiadomości wygenerowane przez AI
muszą pozostać jako szkice, dopóki nie zostaną sprawdzone przez użytkownika.
Włącz wpływ na użytkownika, zachowanie poza zakresem, trade-offy i wytyczne dla AI.

Rekord wygenerowany przez AI nie powinien być jednak automatycznie zaufany. Przegląd przez człowieka powinien zweryfikować, czy kontekst jest dokładny, czy AI nie wymyśliło uzasadnienia, czy wymienione alternatywy są realne, czy konsekwencje są uczciwe i czy wytyczne dla AI odpowiadają faktycznej intencji zespołu. AI jest asystentem szkicującym — nie jest właścicielem decyzji.

Jak AI powinno odczytywać rekordy decyzji

Drugą połową praktyki jest instruowanie AI do odczytu rekordów przed działaniem. Zanim poprosisz asystenta AI o implementację zmiany, włącz instrukcję taką jak ta:

Zanim zmodyfikujesz tę funkcję, przeczytaj docs/decisions.
Zidentyfikuj wszelkie Architecture, Product lub Design Decision Records, które mają zastosowanie.
Podążaj za zaakceptowanymi decyzjami. Jeśli Twoja proponowana zmiana koliduje z rekordem
decyzji, wyjaśnij kolizję, zanim zmienisz kod.

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

Użyj rekordów decyzji jako pamięci projektu.
Nie odwracaj zaakceptowanych decyzji bez zaproponowania nowej decyzji je przekraczającej.
Gdy generujesz kod, wyjaśnij, które rekordy decyzji wpłynęły na implementację.

Zmienia to rolę AI z „przewidywanie prawdopodobnego kodu” na „działanie wewnątrz udokumentowanego systemu ograniczeń” — znaczną poprawę niezawodności dla złożonych lub długoterminowych projektów.

Rekordy decyzji w pull requestach

Rekordy decyzji powinny być częścią normalnego przeglądu pull requestów, a nie oddzielnego procesu. Prosta pozycja checklisty PR czyni nawyk widocznym:

## Checklisty rekordów decyzji

- [ ] Ten PR nie wprowadza istotnej decyzji architektonicznej, produktowej lub projektowej.
- [ ] Ten PR wprowadza istotną decyzję i zawiera nowy rekord decyzji.
- [ ] Ten PR zmienia poprzednią decyzję i zawiera rekord przekraczający.
- [ ] Rozważono istniejące, powiązane rekordy decyzji.
- [ ] Kod wygenerowany przez AI podąża za zaakceptowanymi rekordami decyzji.
- [ ] Rekordy decyzji wygenerowane przez AI zostały przejrzyte przez człowieka.

Ta lista kontrolna jest prosta, ale zmienia zachowanie, przypominając zespołowi, że kod to nie jedyny artefakt, który ma znaczenie w pull request. Umożliwia też naturalne wychwycenie, gdy zmiana wygenerowana przez AI cicho łamie wcześniejszą decyzję.

Rekordy decyzji i zarządzanie architekturą

Tradycyjne zarządzanie architekturą często zawodzi, ponieważ jest zbyt ciężkie, zbyt wolne lub zbyt odcięte od implementacji — centralne komitety akceptacyjne, duże wstępne dokumenty i procesy gatekeepingowe, które blokują, zamiast kierować. Rekordy decyzji oferują lżejszą alternatywę, która integruje się bezpośrednio z workflowem rozwoju.

Nie wymagają centralnego komitetu architektonicznego dla każdej zmiany, ani nie blokują zespołów przed nauką i adaptacją. Zamiast tego tworzą szlak decyzji, które mogą być przeglądane, referencjonowane i rozwijane w czasie. To wspiera ewolucyjną architekturę: architektura może się zmieniać, ale zmienia się z pamięcią, a nie pomimo niej. Zespół może ponownie rozważyć stare decyzje, nie musząc ponownie odkrywać, dlaczego zostały podjęte, co jest zdrowszą i uczciwszą formą zarządzania:

• Małe rekordy zamiast gigantycznych dokumentów
• Przegląd blisko kodu zamiast oddzielnej teatralnej akceptacji
• Kontekst historyczny zamiast wiedzy plemiennej
• Jawne trade-offy zamiast ukrytych założeń

Rekordy decyzji i zarządzanie produktem

Praca produktowa również potrzebuje pamięci decyzji, a jest to obszar, w którym wartość rekordów decyzji jest często niedoszacowana. Mapa drogowa mówi, co może się wydarzyć. Bilet mówi, co budować jako następne. Analityka mówi, co zrobili użytkownicy. Żadne z tych nie w pełni wyjaśnia, dlaczego zachowanie produktu istnieje.

Rekordy Decyzji Produktowych wypełniają tę lukę i są szczególnie przydatne dla decyzji o cennikach i pakowaniu, modeli uprawnień, limitów i kwot, bezpieczeństwa AI i przepływów przeglądania, wyborów onboardingu, definicji ról użytkowników, zasad współpracy, polityk retencji danych i granic zakresu funkcji. Po wdrożeniu decyzje produktowe stają się niewidoczne w kodzie — później ktoś widzi tylko kod i pyta: „Dlaczego to tak działa?” PDR daje odpowiedź w formie, którą zarówno ludzie, jak i narzędzia AI mogą znaleźć i użyć.

Rekordy 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. Rekordy Decyzji Projektowych wypełniają tę lukę. Biblioteka komponentów może mówić „użyj dialogu potwierdzenia dla akcji niszczących”, podczas gdy DDR wyjaśnia uzasadnienie: „Wymagamy potwierdzenia dla akcji niszczących, ponieważ użytkownicy często pracują z danymi współdzielonymi przez zespół, a przypadkowe usunięcie ma wysokie koszty odzyskania.”

To uzasadnienie ma znaczenie poza konkretnym komponentem. Pomaga przyszłym projektantom, deweloperom i narzędziom AI prawidłowo stosować zasadę w nowych sytuacjach. Bez DDR, agent AI może wygenerować szybszą interakcję, która pomija potwierdzenie, ponieważ wydaje się bardziej efektywna. Z DDR, agent może rozpoznać, że zachowanie właściwości bezpieczeństwa jest zamierzone i niezbywalne.

Jak rekordy decyzji wspierają rozwój oparty o specyfikacje

Rozwój oparty o specyfikacje wyjaśnia, co system powinien robić. Rekordy decyzji wyjaśniają, dlaczego zespół wybrał ten kierunek, a ta różnica ma znaczącą wagę dla pracy wspieranej przez AI.

Specyfikacja funkcji może mówić, że e-maile wygenerowane przez AI muszą być zapisywane jako szkice. Produktowy Rekord Decyzji wyjaśnia, dlaczego automatyczne wysyłanie zostało odrzucone, jakie ryzyka były rozważane i które przyszłe zmiany wymagałyby nowej decyzji. Specyfikacja projektowa może opisywać interakcję panelu bocznego, podczas gdy odpowiadający jej DDR wyjaśnia, dlaczego edycje AI inline zostały wyraźnie odrzucone i dlaczego zachowanie kontroli użytkownika zostało ocenione jako ważniejsze niż szybkość workflowu. 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ą. Rekord decyzji zachowuje sąd. Razem dają agentom kodującym AI zarówno instrukcje, jak i kontekst — „co” i „dlaczego” — co sprawia, że połączenie to jest tak skuteczne dla złożonych, długoterminowych systemów. Gdy przyjmujesz narzędziopis SDD, porównaj, jak każda opcja ujawnia ten kontekst; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows omawia przenośność, bramki przeglądania i zakorzenienie w repozytorium w głównych konfiguracjach. Dla narzędziowo-neutralnego pięciofazowego procesu, który te narzędzia implementują, zobacz Spec-Driven Development Workflow From Requirements to Code. Większość narzędzi SDD obsługuje tylko „wysłaną” połowę tej pętli czysto; [OpenSpec Rejected Proposals: A Decision Memory Convention](https://www.glukhov.org/pl/ai-devtools/openspec/handling-rejected-proposals/ “OpenSpec Odrzucone Propozycje: Konwencja Pamięci Decyzji”) obejmuje drugą połowę — trwałe odnotowanie odrzuconej decyzji, aby agent sprawdził ją przed ponownym zaproponowaniem tego samego pomysłu.

Rekordy decyzji nie są specyfikacjami

Rekordy decyzji są powiązane ze specyfikacjami, ale służą innemu celowi. Specyfikacja mówi „system ma wykonywać X”, podczas gdy rekord decyzji mówi „wybraliśmy X zamiast Y z powodu tych ograniczeń i trade-offów.” To „zamiast Y” jest cenną częścią. Narzędzia AI często generują rozwiązania, znajdując prawdopodobną ścieżkę do żądanego rezultatu, ale rekordy decyzji mówią im, które prawdopodobne ścieżki zostały już przebadane, ocenione i odrzucone — zmniejszając churn (prace ponawiane) i poprawiając jakość pracy wspieranej przez AI.

Rekordy decyzji nie są zamiennikiem testów

Testy weryfikują zachowanie; rekordy decyzji wyjaśniają intencję. Obie są konieczne i działają razem. Test może wymusić, że e-maile wygenerowane przez AI muszą być zapisywane jako szkice, podczas gdy Produktowy Rekord Decyzji wyjaśnia, że jest to wymagane, ponieważ użytkownicy muszą przeglądać komunikację wygenerowaną przez AI, zanim opuści system. Test chroni zachowanie. Rekord decyzji chroni znaczenie. Razem czynią przyszłe zmiany bezpieczniejszymi i bardziej przewidywalnymi.

Rekordy decyzji nie są zamiennikiem komentarzy w kodzie

Komentarze w kodzie wyjaśniają lokalne detale implementacji, podczas gdy rekordy 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 rekordó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 wpływa tylko na kilka linii, komentarz jest właściwym narzędziem. Jeśli wpływa na kierunek systemu, rekordem decyzji jest właściwym narzędziem.

Częste błędy

Pisanie rekordów zbyt późno

Rekord decyzji powinien być pisany, gdy decyzja jest podejmowana, a nie miesiące później, gdy wszyscy zapomnieli o trade-offach. Jest w porządku szkicować jeden podczas pull requestu. Jeszcze lepiej jest szkicować go przed implementacją, gdy decyzja jest wciąż aktywnie omawiana, a alternatywy są świeże.

Robienie rekordów zbyt długimi

Rekord decyzji to nie esej. Powinien być wystarczająco szczegółowy, aby zachować sąd, ale wystarczająco krótki, aby ludzie faktycznie go przeczytali. Preferuj jasność nad kompletnością — zwięzły rekord, który jest czytany, jest znacznie wartościowszy niż obszerny, który jest pomijany.

Odnotowywanie decyzji bez konsekwencji

Sekcja konsekwencji jest sercem rekordu. Decyzja bez podanych konsekwencji to często tylko preferencja, a nie prawdziwa decyzja. Dobre rekordy uczciwie przyznają trade-offy, w tym to, co staje się trudniejsze lub bardziej ryzykowne w wyniku wyboru.

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

Gdy decyzja się zmienia, utwórz nowy rekord i oznacz stary jako przekroczony. Ciche przepisywanie starej decyzji, aby pasowała do bieżącego stanu, niszczy kontekst historyczny, który czyni rekordy decyzji wartościowymi. Historia jest użyteczna właśnie dlatego, że pokazuje, jak myślenie ewoluowało. Kompilowane bazy wiedzy stykają się z identycznym problemem pod inną nazwą — [LLM Wiki Maintenance: Drift, Contradictions and Review](https://www.glukhov.org/pl/knowledge-management/knowledge-systems-architectures/compiled-knowledge/llm-wiki-maintenance-knowledge-drift/ “Konserwacja Wiki LLM: Dryf, Sprzeczności i Przegląd”) nazywa to dryfem decyzyjnym i stosuje tę samą zasadę przekraczania zamiast nadpisywania do stron wiki.

Pozwalanie, aby rekordy wygenerowane przez AI zostały scalone bez przeglądu

AI może wyprodukować dopracowany, dobrze ustrukturyzowany rekord, który jest subtelnie błędny. Traktuj rekordy decyzji wygenerowane przez AI dokładnie tak 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 rekordów poza repozytorium

Jeśli rekordy decyzji znajdują się w oddzielnej 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 to, co czyni tę praktykę działającą dla rozwoju wspieranego przez AI.

Lekki model operacyjny

Praktyczny proces zespołu, który dodaje minimalny overhead, wygląda tak:

1. Podczas planowania lub implementacji zidentyfikuj, czy podejmowana jest istotna decyzja.
2. Poproś asystenta AI o szkic ADR, PDR lub DDR na podstawie dyskusji.
3. Przeglądaj szkic jako zespół, weryfikując kontekst, alternatywy i konsekwencje.
4. Zatwierdź rekord jako Markdown w repozytorium.
5. Połącz go z powiązanym problemem lub pull requestem.
6. Instrukcjonuj narzędzia kodujące AI do odczytu powiązanych rekordów przed dokonywaniem przyszłych zmian w obszarze.
7. Przekraczaj rekordy, gdy decyzje się zmieniają, zachowując stary rekord dla historii.

Nie wymaga to nowej biurokracji ani dedykowanej roli dokumentacyjnej. Wymaga małego nawyku: zachowywania ważnego sądu w momencie, gdy jest tworzony, blisko kodu, gdzie będzie potrzebny.

Przykład ADR

# Decyzja: Użycie PostgreSQL dla głównego przechowywania aplikacji

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

## Kontekst

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

## Decyzja

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

## Rozważone alternatywy

### DynamoDB

Zalety:
- Skalowalne operacyjnie
- Dobre dopasowanie do 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 relacyjnych
- Znajomy model operacyjny

Wady:
- PostgreSQL lepiej odpowiada potrzebom zespołu w zakresie obsługi JSON,
opcji indeksowania i istniejącej ekspertyzy

## Konsekwencje

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

## Wytyczne dla AI

Gdy modyfikujesz kod persystencji, preferuj modelowanie relacyjne w PostgreSQL.
Nie wprowadzaj drugiej głównej bazy danych bez przekraczającego ADR.

Przykład 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 na e-maile używając AI. Wysyłanie e-maili to
akcja o wysokim zaufaniu, ponieważ błędy mogą dotrzeć do klientów, partnerów lub
zespołów wewnętrznych.

## Decyzja

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

## Rozważone alternatywy

### Automatyczne wysyłanie

Zalety:
- Szybszy workflow
- Mniej wysiłku użytkownika

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

### Poproszenie o potwierdzenie tylko po wygenerowaniu

Zalety:
- Utrzymuje prosty workflow
- Daje pewną kontrolę użytkownika

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

## Konsekwencje

Workflow jest nieco wolniejszy, ale bezpieczniejszy i bardziej godny zaufania.
Przyszła automatyzacja może poprawić szybkość przeglądu, ale nie może omijać
zatwierdzenia przez człowieka bez przekraczającego PDR.

## Wytyczne dla AI

Gdy budujesz funkcje generowania e-maili, twórz szkice domyślnie.
Nie dodawaj automatycznego wysyłania, chyba że nowy zaakceptowany PDR wprost na to pozwala.

Przykład DDR

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

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

## Kontekst

Użytkownicy potrzebują pomocy w ulepszaniu treści pisanych, ale potrzebują też pozostać
w kontroli końcowego tekstu. Edycje AI inline mogą sprawić, że trudno jest odróżnić
treść napisaną przez użytkownika od wygenerowanych sugestii.

## Decyzja

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

## Rozważone alternatywy

### Stosowanie sugestii inline

Zalety:
- Szybkie
- Czuje się zintegrowane

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

### Wyświetlanie sugestii w modale

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

Wady:
- Przerywa przepływ pisania
- Trudniejsze do porównania sugestii i oryginalnego tekstu

## Konsekwencje

Boczny panel zajmuje więcej miejsca na ekranie, szczególnie na małych ekranach.
Jednak zachowuje kontrolę użytkownika i czyni przegląd jaśniejszym.

## Wytyczne dla AI

Gdy dodajesz funkcje wspierania pisania, zachowaj separację między
tekstem użytkownika a sugestiami AI. Nie stosuj wygenerowanego tekstu bezpośrednio
do dokumentu bez jawnego działania użytkownika.

Sugerowana biblioteka promptów

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

Znajdź powiązane rekordy przed pracą nad funkcją:

Przeczytaj docs/decisions i zidentyfikuj wszelkie zaakceptowane rekordy decyzji, które mają
zastosowanie do tego zadania. Zestaw ograniczenia przed proponowaniem zmian kodu.

Szkicuj nowy ADR:

Szkicuj Architecture Decision Record (ADR) dla tej decyzji technicznej.
Włącz kontekst, decyzję, alternatywy, konsekwencje i wytyczne dla AI.
Zachowaj zwięzłość i konkretność.

Szkicuj nowy PDR:

Szkicuj Product Decision Record (PDR) dla tego zachowania produktu.
Włącz wpływ na użytkownika, zakres, alternatywy, konsekwencje i wytyczne dla AI.

Szkicuj nowy DDR:

Szkicuj Design Decision Record (DDR) dla tego wzorca interakcji.
Włącz problem użytkownika, alternatywy, trade-offy, konsekwencje i wytyczne dla AI.

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

Przeglądaj ten pull request względem zaakceptowanych rekordów decyzji w docs/decisions.
Zidentyfikuj wszelkie kolizje, brakujące rekordy decyzji lub decyzje, które powinny
być przekroczone.

Przekraczaj decyzję:

Utwórz nowy rekord decyzji, który przekracza istniejący.
Zachowaj historyczne uzasadnienie, wyjaśnij, co się zmieniło, i połóż oba rekordy.

Powiązana lektura

• Oryginalny format ADR Michaela Nygarda — podstawowy wpis, który uruchomił ruch ADR
• Organizacja GitHub ADR — narzędzia, szablony i zasoby społeczności do zarządzania rekordami decyzji
• [Czym jest Spec-Driven Development? Specyfikacja jako Źródło Prawdy](https://www.glukhov.org/pl/app-architecture/documentation/what-is-spec-driven-development/ “Czym jest Spec-Driven Development? Specyfikacja jako Źródło Prawdy”) — kanoniczna definicja SDD wyjaśniająca, jak specyfikacje funkcji uzupełniają rekordy decyzji: oba czynią intencję trwałą, na różnych poziomach systemu
• [Spec-Driven Development vs Vibe Coding: Czy to tylko powrót Wodospadu?](https://www.glukhov.org/pl/ai-devtools/vibe-coding/spec-driven-development-vs-vibe-coding/ “Spec-Driven Development vs Vibe Coding — Czy to tylko powrót Wodospadu?”) — kiedy używać SDD, a kiedy pozostać przy szybszych, luźniejszych workflowach
• [Architektura aplikacji w produkcji: Wzorce integracji, projektowanie kodu i dostęp do danych](https://www.glukhov.org/pl/app-architecture/ “Architektura aplikacji w produkcji: Wzorce integracji, projektowanie kodu i dostęp do danych”) — dom dla klastra obejmującego integrację, testy, dostęp do danych i wzorce dokumentacji oprogramowania
• [OpenSpec Rejected Proposals: A Decision Memory Convention](https://www.glukhov.org/pl/ai-devtools/openspec/handling-rejected-proposals/ “OpenSpec Odrzucone Propozycje: Konwencja Pamięci Decyzji”) — stosowanie tego wzorca rekordu decyzji konkretnie w archiwum zmian OpenSpec
• [AI dla Zarządzania Wiedzą: Rzeczywiste Workflowy, Które Dają Radę](https://www.glukhov.org/pl/knowledge-management/ai-augmented-knowledge/ai-for-knowledge-management-workflows/ “AI dla Zarządzania Wiedzą: Rzeczywiste Workflowy, Które Dają Radę”) — praktyczne workflowy zarządzania wiedzą rozszerzone przez AI, które uzupełniają praktykę rekordów decyzji