Projektowanie systemów z Claude Code
Twój zespół debatuje, czy podzielić monolit na mikroserwisy. Połowa inżynierów chce iść all-in na architekturę sterowaną zdarzeniami. Druga połowa uważa, że modularny monolit jest lepszy. Jest dwanaście wątków na Slacku, żadnej pisemnej propozycji, a termin podjęcia decyzji to następny tydzień. Tymczasem nikt tak naprawdę nie zmapował zależności obecnego systemu, nie zidentyfikował wąskich gardeł ani nie udokumentował kompromisów. Decyzje architektoniczne podjęte z przeczucia kosztują miesiące przeróbek. Decyzje podjęte na podstawie analizy zajmują godziny.
Co zabierzesz ze sobą
Dział zatytułowany „Co zabierzesz ze sobą”- Przepływ pracy Claude Code do analizy istniejącej architektury systemów, generowania map zależności i tworzenia rekordów decyzji architektonicznych (ADR)
- Prompty gotowe do skopiowania, które tworzą dokumenty projektowe systemów, oceniają kompromisy między podejściami architektonicznymi i generują plany migracji
- Praktyczne podejście do używania trybu plan dla bezpiecznej, tylko-do-odczytu analizy architektonicznej przed wprowadzeniem jakichkolwiek zmian
Analiza twojej obecnej architektury
Dział zatytułowany „Analiza twojej obecnej architektury”Przed podjęciem decyzji architektonicznych musisz zrozumieć, co masz. Claude Code może odczytać całą twoją bazę kodu i stworzyć mapę architektoniczną.
Rozpocznij tę analizę w trybie plan (Shift+Tab dwa razy lub claude --permission-mode plan), aby Claude Code czytał wszystko bez modyfikowania czegokolwiek. Tryb plan jest idealny do analizy architektonicznej, ponieważ chcesz wglądu, nie zmian.
Po analizie, zagłęb się w konkretne obszary:
Skup się na systemie uwierzytelniania i autoryzacji. Prześledzij każdą ścieżkę od logowania przez ochronę tras. Pokaż mi: które middleware wymusza auth, które trasy go omijają, jak tokeny są walidowane, gdzie sesje są przechowywane i co się dzieje, gdy token wygasa w trakcie żądania. Zidentyfikuj wszelkie niespójności.Generowanie rekordów decyzji architektonicznych
Dział zatytułowany „Generowanie rekordów decyzji architektonicznych”ADR-y dokumentują “dlaczego” stojące za decyzjami technicznymi. Claude Code może je generować z rozmowy.
Claude Code bada twoje rzeczywiste wzorce komunikacji usług, aby uziemić ADR w rzeczywistości. Jeśli twoja usługa zamówień wykonuje 5 synchronicznych wywołań HTTP podczas checkout, ADR odnosi się do tych konkretnych wywołań, a nie mówi o ogólnej “komunikacji między-usługowej”.
Ocena kompromisów architektonicznych
Dział zatytułowany „Ocena kompromisów architektonicznych”Gdy wybierasz między podejściami, Claude Code może systematycznie przedstawić kompromisy.
Oceniamy trzy podejścia dla naszej warstwy dostępu do danych: 1) wzorzec Repository z Prismą, 2) CQRS z oddzielnymi modelami odczytu/zapisu, 3) projektowanie sterowane domeną z agregatami. Dla każdego podejścia: przeanalizuj jak wpasowałoby się w naszą obecną bazę kodu (spójrz na nasze istniejące wzorce dostępu do danych), oszacuj wysiłek refaktoryzacji w dniach-developerskich, zidentyfikuj które części naszej aplikacji najbardziej by skorzystały i które by ucierpiały, oraz oceń każde podejście pod względem: testowalności, wydajności, złożoności i trudności wdrożenia dla nowych inżynierów. Przedstaw to jako tabelę porównawczą z rekomendacją.Wartość tutaj nie polega na tym, że Claude Code podejmuje decyzję za ciebie — polega na tym, że Claude Code wykonuje pracę analityczną. Czytanie przez 200 plików, aby zrozumieć obecne wzorce dostępu do danych, liczenie dotkniętych modułów i szacowanie wysiłku zajmuje człowiekowi-inżynierowi dni. Claude Code robi to w minuty.
Projektowanie nowych systemów
Dział zatytułowany „Projektowanie nowych systemów”Gdy rozpoczynasz nową usługę lub funkcję, Claude Code może wygenerować początkową architekturę z wymagań.
Musimy zbudować system powiadomień, który: wysyła email (przez Resend), powiadomienia push (przez Firebase) i powiadomienia w aplikacji (przez WebSocket). Wymagania: 1) użytkownicy mogą skonfigurować, na których kanałach otrzymują powiadomienia dla każdego typu powiadomień, 2) powiadomienia muszą być dostarczane co najmniej raz z ponawianiem, 3) potrzebujemy wspierać szablony powiadomień, 4) wysyłanie nie może blokować odpowiedzi API, 5) potrzebujemy śledzenia dostarczenia (wysłane, dostarczone, nieudane). Zaprojektuj architekturę systemu: modele danych, endpointy API, strukturę zadań w tle oraz przepływ od "wyzwól powiadomienie" do "dostarczone". Następnie wygeneruj początkową strukturę plików z wstępnymi implementacjami.Mapowanie zależności i analiza sprzężenia
Dział zatytułowany „Mapowanie zależności i analiza sprzężenia”Zrozumienie sprzężenia między modułami jest krytyczne dla łatwości utrzymania. Claude Code może je skwantyfikować.
Ta analiza ujawnia strukturalne problemy, które są niewidoczne w codziennym rozwoju. Moduł narzędziowy, od którego zależy połowa bazy kodu, ale który zmienia się co tydzień, to tykająca bomba zegarowa.
Planowanie refaktoryzacji
Dział zatytułowany „Planowanie refaktoryzacji”Gdy wiesz, co musi się zmienić, Claude Code może zaplanować ścieżkę refaktoryzacji.
Musimy wydzielić naszą logikę zarządzania użytkownikami z monolitu do oddzielnej usługi. Obecnie kod związany z użytkownikami jest rozproszony po: src/controllers/user.ts, src/models/user.ts, src/services/auth.ts, src/middleware/auth.ts i jest przywoływany w 34 innych plikach. Zaplanuj ekstrakcję: 1) zidentyfikuj każdy plik, który przeszedłby do nowej usługi, 2) zmapuj granicę API (które funkcje są wywoływane spoza modułu użytkownika), 3) zaprojektuj komunikację między-usługową (REST, gRPC lub zdarzenia dla każdego wywołania), 4) zaplanuj podział bazy danych (które tabele się przenoszą, jak obsłużyć joiny, które przekraczają granice usług), 5) nakreśl fazową migrację, gdzie zarówno stary, jak i nowy kod działają jednocześnie podczas przejścia.Przewaga Claude Code tutaj to wyczerpująca analiza. Znajdzie odniesienie w pomocniku testowym, który ręcznie odpytuje tabelę users, lub skrypt admina, który bezpośrednio importuje funkcję modelu użytkownika. Te przypadki brzegowe są tym, co sprawia, że migracje zawodzą.
Przeglądy projektowania API
Dział zatytułowany „Przeglądy projektowania API”Przed implementacją API, poproś Claude Code o przegląd projektu.
Oto nasz proponowany projekt API dla usługi płatności (wklej specyfikację OpenAPI lub listę tras). Przejrzyj go pod kątem: 1) konsystencji RESTful (konwencje nazewnictwa, metody HTTP, kody statusu), 2) brakujących odpowiedzi błędów (co się dzieje, gdy płatność się nie powiedzie, gdy użytkownik nie zostanie znaleziony, gdy kwota jest ujemna), 3) paginacji dla endpointów list, 4) kluczy idempotentności dla endpointów mutacji, 5) strategii wersjonowania, 6) kompatybilności wstecznej z naszym istniejącym kodem klienta (sprawdź, czego frontend obecnie oczekuje). Zasugeruj ulepszenia i wygeneruj poprawioną specyfikację OpenAPI.Generowanie dokumentacji
Dział zatytułowany „Generowanie dokumentacji”Dokumentacja architektoniczna, która żyje w oddzielnych dokumentach od kodu, zawsze się dezaktualizuje. Claude Code może generować dokumentację bezpośrednio ze źródła.
Wygeneruj dokumentację architektoniczną z naszej bazy kodu. Uwzględnij: 1) przegląd systemu z opisami komponentów, 2) diagram przepływu danych (jako składnia Mermaid) pokazujący, jak żądanie przepływa przez system, 3) diagram schematu bazy danych (jako diagram ER Mermaid) z naszych plików migracji, 4) dokumentację API z naszych handlerów tras, 5) dokumentację zmiennych środowiskowych (każda zmienna środowiskowa przywoływana w kodzie z opisem i wartością domyślną), 6) architekturę wdrożenia (z naszego Dockerfile, manifestów Kubernetes i konfiguracji CI). Zapisz do docs/architecture.md. To powinno być regenerowane okresowo, nie utrzymywane ręcznie.Gdy to nie działa
Dział zatytułowany „Gdy to nie działa”Analiza architektury Claude Code pomija zachowanie runtime. Statyczna analiza kodu pokazuje relacje importów, ale nie dynamiczne wysyłanie, routing sterowany konfiguracją lub wzorce oparte na refleksji. Jeśli twoja aplikacja używa dependency injection lub architektur wtyczek, powiedz Claude Code: “Nasza aplikacja używa kontenera IoC. Rejestracje usług są w src/container.ts. Użyj tego pliku, aby zrozumieć, które konkretne implementacje są używane w runtime.”
Wygenerowany ADR rekomenduje podejście, które nie pasuje do twojego zespołu. Claude Code optymalizuje pod kątem poprawności technicznej, ale nie zna doświadczenia twojego zespołu. Jeśli Claude rekomenduje event sourcing, ale nikt w twoim zespole go nie używał, dodaj to ograniczenie: “Nasz zespół nie ma doświadczenia z event sourcing. Rekomenduj tylko podejścia używające wzorców, które nasza baza kodu już demonstruje.”
Analiza zależności flaguje zbyt wiele problemów. Każda baza kodu ma sprzężenie. Skup się na największych naruszycielu: “Z analizy sprzężenia zidentyfikuj tylko 5 modułów, które stanowią najwyższe ryzyko (kombinacja wysokiej niestabilności i dużej liczby zależnych). Dla każdego daj mi konkretny, wykonalny krok refaktoryzacji, który zajmie mniej niż dzień.”
Plan migracji niedoszacowuje wysiłku. Claude Code szacuje wysiłek na podstawie zmian w kodzie, ale nie może uwzględnić czasu testowania, koordynacji zespołu i nieuniknionych przypadków brzegowych. Pomnóż szacunki Claude przez 2-3x dla celów planowania i dodaj jawne punkty kontrolne “zweryfikuj na staging” do planu migracji.
Wygenerowana dokumentacja jest zbyt długa. Dokumentacja architektoniczna, której nikt nie czyta, jest bezużyteczna. Dodaj ograniczenie długości: “Utrzymaj przegląd na jednej stronie. Używaj punktów, nie paragrafów. Odbiorcy to nowy inżynier dołączający do zespołu — muszą zrozumieć system w 15 minut.”