Tutorial 01 · około 12 minut. Scenariusz edukacyjny inspirowany praktyką. Przykład jest modelowy: nie opisuje wdrożenia ani incydentu u konkretnego klienta. Fragmenty odpowiedzi poniżej są przykładami redakcyjnymi, a nie zapisem wywołania konkretnego modelu.

AI wygenerowało HLD. Czy można oddać je do realizacji?

Dokument wygląda przekonująco: są komponenty, kolejka, baza i diagram. To dobry początek rozmowy. Architekt nadal musi ustalić, co pochodzi z briefu, co model założył i gdzie projekt może zawieść. Czytelny rysunek nie dowodzi, że rozwiązanie spełnia wymagania.

1. Zacznij od briefu, który można sprawdzić

Brief do skopiowania:

Projektujemy mały serwis rezerwacji wizyt. Użytkownik wybiera termin przez WWW. Backend zapisuje rezerwację w bazie. Osobny worker wysyła informacyjny e-mail przez zewnętrznego dostawcę. E-mail nie jest warunkiem przyjęcia rezerwacji. Nie obsługujemy płatności. Nie określiliśmy jeszcze skali, czasu odpowiedzi ani zasad logowania. Nie dopisuj tych informacji jako faktów.

Używaj danych modelowych. Nazwy organizacji, dane osobowe, wewnętrzne adresy i poufne dokumenty wymagają zasad ustalonych w Twojej organizacji. Zapisz cel sesji: szkic do przeglądu, nie zatwierdzona architektura.

2. Poproś o pytania przed rozwiązaniem

Oddziel fakty, założenia i niewiadome.
Wskaż pięć pytań, których odpowiedzi najbardziej zmienią projekt.
Przy każdym wyjaśnij wpływ na architekturę.
Nie wybieraj jeszcze dostawców ani produktów.

Sprawdź, czy AI pyta o konflikt dwóch rezerwacji tego samego terminu, identyfikację użytkownika, dane i retencję oraz wymagania dostępności. Pytanie o kolor ekranu może poczekać. Zamiast odpowiadać za biznes, oznacz brakującą decyzję.

3. Wygeneruj szkic i poddaj go kontrprzykładowi

Na podstawie briefu przygotuj krótkie HLD.
Założenia oznacz jawnie. Porównaj wysyłkę synchroniczną i asynchroniczną.
Wyjaśnij zachowanie przy awarii dostawcy e-maila.
Pokaż prosty diagram Mermaid flowchart TB.
Nie twierdź, że kolejka sama gwarantuje dostarczenie.
Przykładowy fragment wymagający przeglądu:

„Po zapisie rezerwacji backend przekazuje wiadomość do kolejki. Dzięki kolejce żadne powiadomienie nie zostanie utracone.”

Tu kryje się luka: proces może zakończyć się po zapisie rezerwacji, a przed wysłaniem do kolejki. Sama kolejka nie rozwiązuje problemu dwóch zapisów. Poproś AI o analizę dokładnie tej przerwy, zamiast ogólnego polecenia „ulepsz HLD”.

Proces kończy się po zatwierdzeniu rezerwacji w bazie,
ale przed przekazaniem wiadomości do kolejki.
Co zostanie zapisane? Co może zginąć? Jak wykryjemy brak?
Zaproponuj mechanizm, jego koszty i test sprawdzający.

4. Popraw mechanizm, nie tylko zdanie

Jedną z możliwości jest transactional outbox: rezerwacja i zadanie powiadomienia trafiają do tej samej transakcji bazy. Osobny proces odczytuje zadania, publikuje je i obsługuje ponowienia. Nie jest to automatycznie najlepsza opcja dla każdego systemu; uzasadnij ją wymaganiem dotyczącym utraty powiadomień.

Ponowienie może dostarczyć duplikat. Określ identyfikator zdarzenia, sposób obsługi ponownego przetworzenia, limit prób oraz ścieżkę ręcznego rozwiązania. Dostawca e-maila może nie udostępniać deduplikacji — nie obiecuj wtedy dokładnie jednej wiadomości.

5. Sprawdź diagram osobno

flowchart TB
  User["Użytkownik"] --> API["API rezerwacji"]
  API --> DB["Baza: rezerwacja i outbox"]
  DB --> Relay["Proces publikujący zadania"]
  Relay --> Queue["Kolejka powiadomień"]
  Queue --> Worker["Worker e-mail"]
  Worker --> Provider["Dostawca e-mail"]

To uproszczony widok przepływu; strzałka od bazy do procesu oznacza odczyt zadań, nie aktywne wywołanie przez bazę. Diagram nie pokazuje granic sieci ani wszystkich zabezpieczeń.

Sprawdź dwie rzeczy oddzielnie: czy składnia renderuje się w używanej wersji Mermaid i czy zależności odpowiadają opisowi. Przy błędzie pobierz Markdown i zachowaj oryginalny blok. Do poprawy przekaż sam diagram i komunikat parsera, bez poufnego briefu. Poproś o zachowanie komponentów i relacji; potem ponownie wyrenderuj. Zmiana modelu nie zastępuje tej kontroli.

6. Zakończ dowodami i decyzją

  • Przerwij proces między zapisem rezerwacji a publikacją. Zadanie powinno pozostać możliwe do odtworzenia.
  • Wyłącz dostawcę e-maila. Rezerwacja pozostaje ważna, a zaległe zadania są widoczne.
  • Przetwórz tę samą wiadomość dwa razy. Sprawdź rzeczywiste zachowanie deduplikacji.
  • Wyślij równolegle dwie rezerwacje tego samego terminu. Zweryfikuj regułę konfliktu.

Zapisz w ADR: wybrany mechanizm, powód, rozważane alternatywy, przyjęte ograniczenia i sposób weryfikacji. Architekt zatwierdza decyzję; AI pomaga ją przygotować i zakwestionować.

Twoje zadanie

W dwóch zdaniach wyjaśnij: dlaczego „mamy kolejkę” nie dowodzi niezawodności i jaki test ujawni lukę między bazą a kolejką. Następnie zmień założenie: e-mail musi potwierdzić rezerwację. Które stany procesu trzeba wtedy doprecyzować?

Wypróbuj generator HLD → · Zapisz decyzję w ADR → · Poznaj wzorce odporności →

Źródła i dalsza weryfikacja

Metoda przeglądu i polecenia są propozycją redakcyjną ArchitectMentor. Materiał przygotowany przy wsparciu AI.