Analiza architektury i projektowanie systemów z Claude Code

Claude Code wspiera pracę nad architekturą w trybie plan, w którym czyta kod, ale nie może edytować plików, dopóki plan nie zostanie zatwierdzony. Mapuje zależności, porównuje warianty projektu z wzorcami obecnymi już w kodzie, szkicuje rekordy decyzji architektonicznych (ADR) i planuje migracje etapami. Jego wynik to hipoteza, którą potwierdzają narzędzie do analizy zależności i audyt cytowań.

Twój zespół ma tydzień, żeby zdecydować, czy wydzielić obsługę zamówień z monolitu do osobnego serwisu. Jest dwanaście wątków na Slacku, żadnej pisemnej propozycji i nikt nie zmapował, co naprawdę woła co. Ta strona jest dla programisty lub tech leada, który odpowiada za tę decyzję i do piątku potrzebuje rzetelnej propozycji, takiej, której tezy da się sprawdzić bez czytania 400 plików.

Co zyskasz dzięki analizie architektury w Claude Code

Konfigurację sesji (tryb plan, poziom effort, model), dzięki której analiza architektury jest tylko do odczytu i dostatecznie dokładna.
Sześć promptów do skopiowania: mapa systemu, uzgodnienie mapy z narzędziem do analizy zależności, porównanie wariantów, ADR, audyt dowodów i plan migracji.
Tabelę weryfikacji, która mówi, czym udowodnić każdy rodzaj tezy i kto ją zatwierdza.
Sposób na zamianę decyzji w regułę CI, żeby kolejne sesje agentów nie rozmyły jej po cichu.

Jak skonfigurować sesję Claude Code do pracy nad architekturą?

Analiza architektury nie powinna niczego zmieniać, zanim człowiek się z nią nie zgodzi. Tryb plan to wymusza: Claude czyta pliki i uruchamia tylko zatwierdzone polecenia, a edycje są zablokowane, dopóki nie zaakceptujesz planu.

Uruchom sesję w trybie plan z wyższym poziomem effort. W terminalu wpisz:
Okno terminala
```
claude --permission-mode plan --effort high
```
W trwającej sesji naciskaj Shift+Tab, aby przełączać tryby uprawnień, aż włączy się tryb plan, albo wpisz /plan i pytanie. --effort przyjmuje low, medium, high, xhigh i max (sprawdzone w claude --help, v2.1.283).
Zostaw domyślny model i najpierw dostrój effort. Claude Opus 5.5 jest domyślnym modelem Claude Code na każdym płatnym planie od v2.1.280 (kanał wydań latest) i domyślnie działa z effort medium. Do analizy kompromisów podnieś effort poleceniem /effort high lub /effort xhigh, zanim zmienisz model. Na Claude Fable 5.1 (/model fable) przełączaj się tylko przy najdłuższych i najtrudniejszych analizach i tylko wtedy, gdy twoje własne porównanie pokazuje, że Opus na wyższym effort nie wystarcza. Wersje i ceny są w przeglądzie modeli; kompromis związany z poziomem effort wyjaśnia strona o głębokim rozumowaniu i poziomach effort.
Zawęź pytanie. Nazwij katalogi, serwisy lub przepływy, które mają znaczenie. Niezawężone „przeanalizuj naszą architekturę” w dużym repozytorium zapełnia okno kontekstu plikami bez związku z decyzją. W nieznanym kodzie najpierw przejdź przez analizę bazy kodu; ta strona zakłada, że już się w nim orientujesz.
Zanim poprosisz o opinie, zapisz na dysku fakty, które da się sprawdzić narzędziem. Jak to zrobić, pokazuje następna sekcja.

Zmapuj obecną architekturę z dowodami, które da się sprawdzić

Poproś o mapę, w której każda teza wskazuje plik i linię. Dzięki cytowaniom mapę można poddać audytowi: teza bez cytowania to zgadywanie.

Map the architecture of this repository for a decision about extracting order processing into its own service. Stay read-only.

Produce:
1. Modules and their responsibilities, one line each.
2. Every path from an HTTP request that touches orders, down to the database and back, including background jobs and webhooks.
3. External dependencies (databases, caches, queues, third-party APIs) and which modules own them.
4. Shared state and cross-cutting concerns (auth, transactions, logging) that order code relies on.
5. Circular dependencies and modules with too many responsibilities.

Rules: cite path:line for every claim. If you infer something from naming or configuration rather than from a call site, mark it INFERRED. List anything wired at runtime (dependency injection, plugin registries, reflection, config-driven routing) in a separate "Not visible statically" section instead of guessing.

Model językowy słabo liczy importy i nie widzi powiązań dynamicznych, więc część mapy dotyczącą zależności traktuj jak szkic. Narzędzie do analizy statycznej wylicza ten sam graf deterministycznie. W kodzie JavaScript lub TypeScript uruchom w terminalu (sprawdzone 26 września 2026 r. z dependency-cruiser 18.4.0 i madge 8.0.0):

mkdir -p docs/architecture

# Sprzężenie dośrodkowe (Ca), odśrodkowe (Ce) i niestabilność dla modułów i katalogów
npx dependency-cruiser@18.4.0 src --no-config --output-type metrics > docs/architecture/metrics.txt

# Zależności cykliczne
npx madge@8.0.0 --circular src > docs/architecture/cycles.txt

# Cały graf jako schemat blokowy Mermaid
npx dependency-cruiser@18.4.0 src --no-config --output-type mermaid -f docs/architecture/deps.mmd

W Pythonie tę samą rolę pełni import-linter (pip install import-linter, a potem lint-imports z kontraktami z konfiguracji; sprawdzone na wersji 2.15 z PyPI); przewodnik po funkcjach dopasowania ma konfiguracje dla TypeScriptu, Pythona i Javy. Następnie każ Claude’owi uzgodnić mapę z wynikiem narzędzi:

Read docs/architecture/metrics.txt and docs/architecture/cycles.txt. They come from dependency-cruiser and madge and are the source of truth for static imports.

Compare them with the architecture map you produced. List:
1. Every dependency or cycle the tools found that your map missed.
2. Every dependency in your map the tools do not show, and whether it is a runtime-only link (explain the mechanism with path:line) or an error.
3. The five modules that most violate the stable-dependencies principle: the highest Ca combined with the highest I (%). List Ca, Ce and I for each, and what in the order flow depends on it.

Then rewrite the map with the corrections. Do not keep any claim you cannot cite.

Każda rozbieżność to albo powiązanie widoczne dopiero w działaniu, o którym teraz wiesz, albo błąd mapy, który właśnie usunąłeś. Ta lista jest cenniejsza niż każde z dwóch źródeł osobno. Gdy poprawiona mapa się zgadza, zatwierdź jej zapis (albo naciśnij Shift+Tab, żeby wyjść z trybu plan) i poproś Claude’a o zapisanie jej w docs/architecture/current.md; audyt opisany dalej czyta ją z tego pliku.

Porównaj warianty projektu na własnym kodzie

Ogólne porównanie mikroserwisów, modularnego monolitu i architektury sterowanej zdarzeniami znajdziesz wszędzie. Przydatne porównanie mierzy każdy wariant twoim grafem wywołań, twoim zespołem i wzorcami, które kod już stosuje. Podaj Claude’owi ograniczenia, których nie widzi w kodzie.

We are choosing how to separate order processing from the monolith. Evaluate three options:
A) modular monolith: an orders module with an enforced public interface,
B) a separate orders service called over HTTP,
C) a separate service fed by a message queue with an outbox table.

Constraints you cannot see in the code: four backend engineers, none has run a message broker in production; we deploy twice a day; checkout latency must not increase.

Use one Explore subagent per option to find the code each option would change, so the analysis of one option does not crowd out the others.

For each option give: the files and call sites that change (path:line), which transactions currently span orders and other tables and what happens to each, the failure modes it introduces, how reversible it is after one month, and what we would have to learn. End with a table and a recommendation, and state which single fact, if it turned out false, would change the recommendation.

Ostatnie polecenie jest najważniejsze. Fakt, który zmieniłby rekomendację, trzeba sprawdzić przed spotkaniem, a zwykle jest to tańsze niż weryfikacja całej analizy. Explore to jeden z wbudowanych subagentów Claude Code; jeśli chcesz dać subagentowi własne instrukcje lub ograniczyć mu narzędzia, zajrzyj do własnych subagentów.

Nie traktuj szacunków pracochłonności od agenta jak zobowiązań. Agent widzi kod, który się zmienia, ale nie widzi waszej kolejki code review, okien wdrożeniowych ani przypadków brzegowych, które wychodzą na stagingu. Poproś o listę zmian, a wycenę zrób z zespołem.

Zapisz decyzję jako ADR, którego agent będzie przestrzegał

ADR pisany dla ludzi wyjaśnia, dlaczego. ADR, którego przestrzegają agenci, dodatkowo zapisuje regułę w formie sprawdzalnej narzędziem i wskazuje to sprawdzenie. Pisz go po decyzji zespołu, nie przed nią: ADR utrwala decyzję człowieka, a nie ją podejmuje. Kanoniczny format ADR i wzorzec ograniczeń sprawdzalnych maszynowo opisuje strona decyzje architektoniczne, których agenci przestrzegają.

The team decided on option A, a modular orders module with an enforced public interface. Write docs/adr/0007-orders-module-boundary.md, no longer than one page:

- Status: accepted. Date: today.
- Context: the current coupling, citing the reconciled map and docs/architecture/metrics.txt (path:line, not prose).
- Decision: one paragraph.
- Consequences: what gets easier, what gets harder, and what we give up by not choosing B or C.
- Enforcement: a dependency-cruiser rule that forbids any import of src/orders/** from outside src/orders/ except through src/orders/index.ts. Add the rule to .dependency-cruiser.cjs and show the command that fails CI when it is broken.
- Revisit when: the concrete signal that would reopen this decision.

Also add one line to CLAUDE.md under "Architecture" that points to this ADR.

Zanim wyślesz ten prompt, wyjdź z trybu plan albo zatwierdź plan, który Claude zaproponuje, bo prompt zapisuje pliki. Linia w CLAUDE.md wprowadza decyzję do kontekstu każdej przyszłej sesji. Reguła zależności łapie te sesje, które ją zignorują.

Jak zweryfikować analizę bez czytania każdego pliku?

Nikt nie powinien czytać 400 plików, które przeczytał agent. Każdy rodzaj tezy sprawdzasz najtańszym narzędziem, które może ją udowodnić, a decyzję zatwierdza konkretna osoba.

Teza w wyniku	Jak ją sprawdzić	Kto zatwierdza
„Moduł X importuje Y”, cykle, liczby sprzężenia	Wynik dependency-cruiser lub madge, uzgodniony jak wyżej	Programista, który uruchomił narzędzia
„Ten przepływ przechodzi przez plik F w linii L”	Audyt cytowań w nowej sesji (prompt poniżej)	Programista, na podstawie raportu z audytu
Powiązania w działaniu (DI, pluginy, routing z konfiguracji)	Ślad lub test, który przechodzi tę ścieżkę; logi ze stagingu	Właściciel danego podsystemu
„Wariant A łatwiej wycofać niż B”	Ocena zespołu oparta na liście zmian	Tech lead, w review ADR
„Granica trzyma się po zmianie”	Reguła zależności, przez którą CI kończy się błędem przy niedozwolonym imporcie	CI, przy każdym pull requeście

You are auditing docs/architecture/current.md and docs/adr/0007-orders-module-boundary.md. You did not write them. For every path:line citation, open the file and check that the line supports the claim next to it. Report a table: claim, citation, verdict (SUPPORTED / WRONG LINE / NOT SUPPORTED / FILE MISSING), and the correct citation if you find one. Do not fix the documents. At the end, list claims that carry no citation at all.

Uruchom audyt w nowej sesji (claude --permission-mode plan), a nie w tej, która pisała dokumenty. Sesja, która postawiła tezę, ma skłonność do jej potwierdzania. Wszystko z werdyktem NOT SUPPORTED wraca do sesji autorskiej albo wypada z dokumentu. ADR trafia do głównej gałęzi dopiero po zatwierdzeniu przez tech leada w zwykłym code review pull requesta, z dołączonym raportem z audytu. Ogólną praktykę przyjmowania dowodów zamiast czytania diffów opisuje strona dowody zamiast czytania kodu.

Zaplanuj migrację w odwracalnych etapach

Gdy decyzja jest zapisana, poproś o plan, w którym każdy etap da się wdrożyć osobno i ma sprawdzenie dowodzące, że się udał.

Plan the migration to the orders module boundary in docs/adr/0007-orders-module-boundary.md. Stay in plan mode.

Constraints: each phase is one pull request that can ship and be reverted alone; the app works after every phase; no big-bang cutover.

For each phase give: the files it touches (path), what moves or changes, the test or check that proves the phase is done (an existing test, a new test to write first, or a dependency-cruiser rule to tighten), and how to roll it back. Find the hidden callers first: test helpers, admin scripts, migrations and cron jobs that import order code or query order tables directly. List them in phase 1.

Zatwierdzone etapy przekaż do planowania funkcji albo wykonaj je przepływem refaktoryzacji. Żeby reguła zależności zaciskała się w miarę wdrażania kolejnych etapów, użyj wzorca z baseline i --ignore-known z przewodnika po funkcjach dopasowania.

Utrzymuj dokumentację architektury na bieżąco

Dokumenty architektury pisane ręcznie się starzeją. Podziel dokument na dwie części. Część deterministyczną (deps.mmd, metrics.txt, cycles.txt) CI generuje od nowa powyższymi poleceniami po każdym scaleniu (madge 8.0.0 kończy działanie z kodem 1, gdy znajdzie cykl, więc ten krok zatrzymuje build; dopisz || true, jeśli chcesz tylko raport), więc zawsze odpowiada statycznemu grafowi importów. Część opisowa jest krótka, pisze ją Claude na podstawie tych plików, a ponowny audyt robisz tylko wtedy, gdy graf istotnie się zmieni. Żeby odświeżać opis według harmonogramu, Routines w Claude Code mogą otwierać pull request z nowym tekstem do zatwierdzenia przez człowieka.

Minimalny workflow GitHub Actions dla części deterministycznej uruchamia te same przypięte polecenia po każdym scaleniu do main i wysyła trzy pliki jako artefakt builda. Dzięki if: always() pliki trafiają do artefaktu także wtedy, gdy madge przerwie zadanie z powodu cyklu, więc masz raport, który tłumaczy błąd. Jeśli wolisz trzymać pliki w repozytorium, zastąp krok wysyłki krokiem, który commituje docs/architecture/ z powrotem do gałęzi, i podnieś uprawnienia tego zadania do contents: write; uruchamia ono wyłącznie przypięte narzędzia na main, nigdy agenta ani kodu z pull requesta.

name: architecture-docs
on:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  graph:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - name: Regenerate the dependency graph
        run: |
          mkdir -p docs/architecture
          npx dependency-cruiser@18.4.0 src --no-config --output-type metrics > docs/architecture/metrics.txt
          npx dependency-cruiser@18.4.0 src --no-config --output-type mermaid -f docs/architecture/deps.mmd
          npx madge@8.0.0 --circular src > docs/architecture/cycles.txt
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: architecture-docs
          path: docs/architecture/*

Co się psuje, gdy Claude Code analizuje architekturę?

Mapa pomija powiązania widoczne dopiero w działaniu. Statyczny odczyt nie widzi kontenerów wstrzykiwania zależności, rejestrów pluginów ani routingu sterowanego konfiguracją. Jak naprawić: wskaż Claude’owi kod rejestracji („rejestracje serwisów są w src/container.ts; ustal na ich podstawie konkretne implementacje”) i potwierdź krytyczne ścieżki testem lub śladem ze stagingu.

Cytowania wskazują złe linie albo nieistniejące pliki. Jak naprawić: uruchom audyt cytowań w nowej sesji i usuń każdą tezę, która pozostaje niepoparta. Jeśli nie przechodzi więcej niż kilka cytowań, wygeneruj mapę ponownie z węższym zakresem; tak szeroka mapa powstała ze streszczeń, a nie z lektury plików.

Rekomendacja nie pasuje do zespołu. Agent preferuje rozwiązania technicznie czyste i nie wie, że nikt u was nie utrzymywał brokera, którego poleca. Jak naprawić: podaj w prompcie doświadczenie zespołu i ograniczenia operacyjne, i poproś o preferowanie wzorców, które kod już stosuje.

Raport sprzężenia oznacza wszystko. Każdy kod ma sprzężenia. Jak naprawić: poproś o pięć modułów z najgorszym połączeniem niestabilności i liczby zależnych modułów, z jedną zmianą na moduł, którą da się zrobić w jeden dzień.

Kontekst zapełnia się w dużym repozytorium. Odpowiedzi stają się ogólnikowe, a wczesne ustalenia giną. Jak naprawić: podziel analizę na podsystemy, użyj subagentów Explore, żeby każda eksploracja działała we własnym kontekście, i zapisuj ustalenia pośrednie do plików, które czyta następny krok.

Decyzja się rozmywa po scaleniu ADR. Kolejne sesje, ludzkie czy agentowe, importują przez granicę, bo nic ich nie zatrzymuje. Jak naprawić: reguła zależności w CI plus wskazanie w CLAUDE.md. Długoterminowy dryf i progi, przy których warto ograniczyć autonomię agenta, opisuje strona o utrzymaniu w zdrowiu kodu pisanego przez agentów.

Dokąd dalej po analizie architektury

Decyzje architektoniczne, których agenci przestrzegają Kanoniczny format ADR z ograniczeniami sprawdzalnymi maszynowo

Funkcje dopasowania architektury Warstwy, cykle i budżety złożoności egzekwowane w CI, z konfiguracjami dla trzech stosów

Planowanie funkcji z Claude Code Zamień zatwierdzone etapy migracji w plany do wdrożenia

Refaktoryzacja z Claude Code Przeprowadź migrację etap po etapie

Pracujesz w innym narzędziu? Ten sam przepływ w Codeksie opisuje strona projektowanie systemów z Codeksem, a w Cursorze projektowanie systemów z Cursor Agent. Resztę tego etapu znajdziesz w przeglądzie planowania w Claude Code.