Rozwój systemów rozproszonych z AI

Zmieniasz jedno pole w API serwisu Order, a trzy inne serwisy zaczynają zwracać błędy 500 na środowisku staging. Ślad jest niekompletny, bo dwa serwisy nigdy nie przekazały kontekstu śladu, saga przetwarzająca płatności po cichu pominęła krok kompensacji, a twój dashboard dyżurny świeci na zielono, podczas gdy klienci nie mogą sfinalizować zakupu. Systemy rozproszone psują się w lukach między serwisami — i to dokładnie tam asystenci AI są najbardziej przydatni i najbardziej niebezpieczni: szybko generują wiarygodny szkielet wielu serwisów, ale wklejenie „wygeneruj cały system produkcyjny” daje ci kod, którego nie jesteś w stanie zweryfikować.

Ten przewodnik pokazuje, jak używać Cursora, Claude Code i Codeksa do tych części, w których AI jest naprawdę dobre — szkicowania zrębów serwisów, przekazywania kontekstu śladu, pisania nudnej logiki kompensacji — przy jednoczesnym utrzymaniu pętli weryfikacji na tyle ciasnej, że bez wahania wdrożysz wynik.

Co z tego wyniesiesz

• Przepływ koordynowania pojedynczej funkcji w wielu repozytoriach serwisów w każdym z trzech narzędzi
• Gotowe prompty do projektowania granic serwisów, napisania kroku sagi wraz z jego kompensacją i testem, który najpierw nie przechodzi, oraz instrumentowania OpenTelemetry przyrostowo
• Realne, zweryfikowane serwery MCP do monitorowania (Sentry, Grafana, Dynatrace) i infrastruktury (Docker, Kubernetes, AWS) — wraz z dokładnymi poleceniami instalacji
• Sekcja „Gdy to się psuje” obejmująca tryby awarii, które naprawdę dają się we znaki: zerwany kontekst śladu, brakująca kompensacja w sadze i błędy uwierzytelniania MCP

Serwery MCP, które naprawdę istnieją

Połowa wartości AI w systemach rozproszonych polega na tym, że pozwalasz mu odpytywać żywą infrastrukturę, zamiast zgadywać. Ale ekosystem jest pełen łudząco podobnych paczek npm — sentry-mcp to mało popularna zaślepka, a nie serwer Sentry. Korzystaj z tych zweryfikowanych serwerów. Konfiguracja MCP jest identyczna w Cursorze, Claude Code i Codeksie: wszystkie trzy czytają te same definicje serwerów (.mcp.json dla Claude Code, .cursor/mcp.json dla Cursora, ~/.codex/config.toml dla Codeksa), więc poniższe polecenia działają niezależnie od tego, którego narzędzia używasz.

Monitorowanie i obserwowalność

1. Sentry (błędy, ślady, wydania) — użyj oficjalnego, hostowanego serwera z OAuth, bez tokena do zarządzania:

   claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

   Dla samodzielnie hostowanego Sentry oficjalną paczką npm jest @sentry/mcp-server:

   claude mcp add sentry -- npx -y @sentry/mcp-server@latest --access-token=YOUR_TOKEN

2. Grafana (dashboardy, zapytania Loki/Prometheus, incydenty) — oficjalny serwer to grafana/mcp-grafana, binarka Go dystrybuowana przez Dockera (nie ma paczki npm mcp-grafana):

   claude mcp add grafana -- docker run --rm -i \
     -e GRAFANA_URL=http://localhost:3000 \
     -e GRAFANA_SERVICE_ACCOUNT_TOKEN=YOUR_TOKEN \
     grafana/mcp-grafana -t stdio

3. Dynatrace (APM, wykrywanie anomalii przez AI) — oficjalna paczka jest publikowana przez organizację Dynatrace OSS i wymaga Node 22.10+:

   DT_ENVIRONMENT=https://YOUR.apps.dynatrace.com \
     claude mcp add dynatrace -- npx -y @dynatrace-oss/dynatrace-mcp-server@latest

Uwaga

Zanim dodasz jakikolwiek serwer MCP do monitorowania, uruchom npm view <package> version i potwierdź wydawcę. sentry-mcp, dynatrace-mcp, greptimedb-mcp i @leval/mcp-grafana są nieoficjalne lub nie istnieją. Oficjalne paczki mają przestrzeń nazw (@sentry/mcp-server, @dynatrace-oss/dynatrace-mcp-server) albo są dystrybuowane poza npm (binarka Go Grafany).

Kontenery i infrastruktura

1. Docker — oficjalny MCP jest dostarczany z MCP Toolkit w Docker Desktop; uruchamiasz bramę zamiast paczki npm:

   claude mcp add docker -- docker mcp gateway run

   W Cursorze dodaj serwer typu polecenie w Settings → MCP, wskazując na to samo docker mcp gateway run.

2. Kubernetes — kubernetes-mcp-server to prawdziwa paczka; używa twojego bieżącego kontekstu kubeconfig:

   claude mcp add k8s -- npx -y kubernetes-mcp-server@latest

3. AWS — AWS Labs publikuje serwery o konkretnym przeznaczeniu (nie jeden monolityczny obraz). Wybierz ten, którego potrzebujesz, i polegaj na standardowym łańcuchu poświadczeń AWS, zamiast wpisywać klucze na sztywno:

   claude mcp add aws-api -- uvx awslabs.aws-api-mcp-server@latest

   Przejrzyj pełny katalog na awslabs.github.io/mcp. Dla Google Cloud wdróż własny serwer MCP na Cloud Run — zobacz cloud.google.com/run/docs.

Projektowanie granic serwisów

AI szybko szkicuje propozycje ograniczonych kontekstów, ale granice to decyzja biznesowa — traktuj wynik jako pierwszą wersję do dyskusji, a nie wyrok. Zacznij wąsko: poproś o granice wraz z uzasadnieniem, abyś mógł wychwycić, gdzie model pomylił warstwę techniczną z domeną.

Wskazówka

Gotowy prompt do proponowania granic serwisów:

I have an e-commerce monolith with these features: user management, product catalog, inventory tracking, order processing, payments, shipping, notifications. Propose microservice boundaries using domain-driven design. For each proposed service, give me: (1) the bounded context and the single team that would own it, (2) the data it owns exclusively, (3) which other services it talks to and whether that’s sync or async. Flag any place where two contexts share a database or a write path—those are coupling risks I need to resolve before splitting.

Gdy uzgodnisz już granice, projektuj po jednym serwisie naraz. Oprzyj się pokusie „wygeneruj wszystkie serwisy” — nie da się zrecenzować zrzutu siedmiu serwisów, a to właśnie w kontraktach między nimi kryją się błędy.

Wskazówka

Gotowy prompt na kontrakt jednego serwisu:

For the Order Processing context, design the service contract only (not the implementation yet): the REST endpoints with request/response schemas, the domain events it publishes (OrderCreated, OrderConfirmed, OrderCancelled) with their payloads, and the events it consumes from Payment and Inventory. Output the OpenAPI spec and the event schemas as separate files. Do not generate business logic—I want to review the contract first.

Wzorce saga, które naprawdę da się zweryfikować

Wzorzec saga to miejsce, gdzie wygenerowany przez AI kod rozproszony najczęściej wygląda dobrze, a jest błędny. Tryb awarii jest zawsze taki sam: ścieżka szczęśliwa działa, ale krok kompensacji nie jest idempotentny albo brakuje budżetu czasowego (timeout). Lekarstwem jest budowanie po jednym kroku naraz, każdego wraz z jego kompensacją i najpierw testem, który nie przechodzi, a potem obserwowanie, jak zmienia się na zielony.

Cursor

Otwórz repozytorium serwisu Order i przełącz się w tryb Agent. Poproś o jeden krok sagi wraz z testem, który nie przechodzi, uruchom test w terminalu Cursora i zaakceptuj diff dopiero, gdy zmieni się na zielony. Użyj punktu kontrolnego (checkpoint) przed każdym krokiem, abyś mógł cofnąć złą kompensację bez utraty poprzednich kroków. Widok inline diff w Cursorze ułatwia wychwycenie, gdy model „naprawił” test, osłabiając asercję zamiast kodu.

Claude Code

Steruj nim z terminala, aby uruchomienie testu było częścią pętli. Claude Code potrafi uruchomić test, odczytać błąd i iterować bez kopiowania i wklejania danych wyjściowych przez ciebie:

claude "Implement step 3 of the order saga (process payment) plus its
compensation (refund). Write a failing test that asserts the refund fires
when step 4 throws, then make it pass. Run the test with `npm test -- saga`
and show me the diff before committing."

Dodaj hook w .claude/settings.json, który uruchamia zestaw testów sagi przy każdej edycji w saga/, aby regresja we wcześniejszym kroku natychmiast wychodziła na jaw.

Codex

Użyj worktree Codeksa, aby praca nad sagą była odizolowana we własnym lokalnym checkoucie, a następnie pozwól Codeksowi uruchamiać zestaw testów po każdym kroku. Ponieważ Codex obejmuje CLI, IDE i Cloud, możesz wystartować krok z CLI i zrecenzować powstały diff w IDE:

codex --ask-for-approval on-request "Implement the payment step of the order
saga with an idempotent compensation. Add a test that injects a failure at
the inventory step and asserts payment is refunded exactly once on retry.
Run the suite and stop for my review before applying."

Wskazówka

Gotowy prompt na jeden krok sagi + kompensację + test, który nie przechodzi:

Implement one step of the orchestrator-based order saga: “reserve inventory.” Requirements: (1) the step is idempotent—calling it twice with the same order ID reserves once; (2) it has a compensation that releases the reservation; (3) a 30s timeout budget, after which the orchestrator triggers compensation. Write the failing test first: simulate the payment step (the next step) throwing, and assert the inventory reservation is released exactly once. Then implement until the test passes. Show me the test and the diff—do not add the remaining saga steps yet.

Powiąż każdy krok z obserwowalnym sprawdzeniem: gdy model twierdzi, że krok działa, uruchom ten jeden test, który dowodzi, że kompensacja się odpala. Jeśli nie potrafisz wyrazić testu, nie możesz ufać kodowi.

Komunikacja między serwisami i kontekst śladu

Konfiguracje service mesh i bramy są dla AI bardzo opłacalne — ale znów, przyrostowo. Zacznij od najmniejszej konfiguracji, którą da się zweryfikować jednym poleceniem (curl, istioctl analyze), a potem nakładaj wagi canary i wyłączniki obwodu.

Wskazówka

Gotowy prompt na przyrostowy rollout Istio:

Generate the minimal Istio config to enforce mTLS between the order and payment services: one PeerAuthentication in STRICT mode plus the DestinationRule. Give me the exact istioctl analyze and curl commands to confirm mTLS is active and that plaintext calls are rejected. Once that’s verified, I’ll ask you to add a 90/10 canary VirtualService—don’t add traffic splitting or circuit breakers yet.

W przepływach sterowanych zdarzeniami nawracający błąd produkcyjny to zerwany ślad: serwis konsumuje wiadomość Kafki, ale nigdy nie wyodrębnia i ponownie nie wstrzykuje kontekstu śladu, więc ślad urywa się w ślepym zaułku. Gdy prosisz AI o podłączenie konsumentów, uczyń propagację kontekstu jawnym, przetestowanym wymaganiem — a nie kwestią dodaną na końcu.

Wskazówka

Gotowy prompt na konsumentów Kafki bezpiecznych dla kontekstu śladu:

Generate a Node.js Kafka consumer template for the Order domain using KafkaJS and OpenTelemetry. The critical requirement: extract the trace context from incoming message headers and make it the active context for the handler span, then inject the current context into headers of any message it produces. Include a test that publishes a message with a known traceId and asserts the downstream produced message carries the same traceId. Handle poison messages with a dead-letter topic.

Obserwowalność: instrumentuj przyrostowo

Nowoczesna obserwowalność wykroczyła poza dashboardy ku wykrywaniu anomalii sterowanemu AI i analizie podstawowych przyczyn świadomej topologii — ale wciąż zdobywasz ją po jednym serwisie naraz. Podejście „zinstrumentuj 8 serwisów i 3 bazy danych w jednym promcie” daje konfigurację, której nie da się zwalidować. Zinstrumentuj jeden serwis od początku do końca, potwierdź, że span pojawia się w Jaegerze, a potem zrób z tego szablon.

Wskazówka

Gotowy prompt na OpenTelemetry w jednym serwisie:

Add OpenTelemetry auto-instrumentation to the Order service (Node.js/Express). Auto-instrument the HTTP server and the Postgres client, add one custom span around the order-creation business logic, and export traces to a local Jaeger via OTLP. Give me the exact steps to send one request and confirm the trace appears in Jaeger at localhost:16686, including the custom span. Once I confirm, I’ll ask you to extract this into a shared instrumentation module the other services import.

Z podłączonymi serwerami MCP Grafany i Sentry możesz domknąć pętlę bez opuszczania edytora: poproś AI, by wyciągnęło faktyczny wskaźnik błędów albo najwolniejszy ślad dla serwisu i przeanalizowało go, zamiast robić zrzut ekranu dashboardu.

Wskazówka

Gotowy prompt na triage incydentu w oparciu o MCP:

Using the Sentry MCP, find the top 3 unresolved issues for the payment-service project in the last 6 hours, ranked by event count. For the most frequent one, pull the stack trace and the linked trace, identify which downstream call failed, and propose a fix as a diff. Don’t apply it—explain the root cause first so I can confirm.

Koordynowanie zmian w wielu repozytoriach

Funkcja taka jak „punkty lojalnościowe” dotyka serwisów Customer, Order, Payment i Notification. To problem koordynacji — a nie kod poszczególnych serwisów — czyni to trudnym, a trzy narzędzia podchodzą do tego naprawdę odmiennie.

Cursor

Otwórz wszystkie cztery repozytoria serwisów w jednym wieloźródłowym workspace, aby agent widział każdy kontrakt naraz. Zaprojektuj najpierw kontrakty OpenAPI/zdarzeń, a potem użyj agenta w tle do zaimplementowania każdego serwisu w kolejności zależności, recenzując diffy per repozytorium. Punkty kontrolne na poziomie pliku w Cursorze pozwalają cofnąć zmiany jednego serwisu bez rozplątywania pozostałych. Najlepsze, gdy chcesz wizualnie obserwować i sterować diffem każdego serwisu.

Claude Code

Oskryptuj koordynację. Claude Code działa bezgłowo (headless), więc możesz sterować każdym repozytorium nieinteraktywnie i bramkować na testach kontraktów:

for svc in customer order payment notification; do
  (cd "../$svc" && claude -p "Implement the loyalty-points changes per
    ../contracts/loyalty.openapi.yaml. Add Pact contract tests against the
    services you call. Stop if any contract test fails." \
    --allowedTools Read Edit Bash)
done

Pod-agenci i bezgłowy tryb -p czynią Claude Code najlepszym wyborem, gdy zmiana jest mechaniczna w wielu repozytoriach i chcesz mieć ją audytowalną w CI.

Codex

Użyj Codex Cloud — jedno zadanie na serwis, każde we własnym środowisku chmurowym — aby zmiany były odizolowane i recenzowalne jako odrębne jednostki, a następnie pozwól Codeksowi otworzyć PR-y. Jego integracje z GitHubem i Linearem oznaczają, że możesz sterować całą funkcją z poziomu zgłoszenia: podlinkuj ticket Linear, a Codex śledzi pracę między repozytoriami i raportuje status z powrotem. Najlepsze, gdy koordynacja powinna żyć w twoim trackerze zgłoszeń, a nie w skrypcie powłoki.

Wskazówka

Gotowy prompt na zmianę między serwisami w podejściu kontrakt-najpierw:

We’re adding Customer Loyalty Points across Customer, Order, Payment, and Notification services. Step 1 only: design the API contracts and event schemas (OpenAPI + event payloads) and a dependency-ordered implementation plan that says which service to change first and why. Add the contract tests (Pact) that must pass between each pair before we deploy. Do not implement any service yet—I want to review the contracts and the sequence.

Gdy to się psuje

Systemy rozproszone psują się w sposób, którego nie wychwytuje sposób myślenia o pojedynczym serwisie. Oto tryby awarii, które naprawdę wychodzą na jaw przy pracy wspomaganej AI, i sposoby na wyjście z nich.

1. Kontekst śladu urywa się na granicy asynchronicznej. Żądanie pojawia się w Jaegerze przez dwa skoki, a potem znika. Konsument nie wyodrębnił kontekstu śladu z nagłówków wiadomości. Przeszukaj konsumenta pod kątem wyodrębniania kontekstu; jeśli go brak, poproś AI o dodanie propagacji opartej na nagłówkach oraz testu, który potwierdza, że znany traceId przetrwa skok (zobacz prompt dla Kafki powyżej). Nie ufaj „dodałem śledzenie” — zweryfikuj traceId od początku do końca.

2. Saga zostawia osierocony stan. Płatność się powiodła, ale zapasy nigdy nie zostały zwolnione po awarii w dół strumienia. Kompensacja jest brakująca lub nieidempotentna. Odtwórz problem, wstrzykując awarię na kroku po tym, który podejrzewasz, i potwierdź, że kompensacja odpala się dokładnie raz. Przebuduj ten krok z promptem „najpierw test, który nie przechodzi”; nigdy nie akceptuj logiki kompensacji bez testu, który ją wyzwala.

3. Uwierzytelnianie serwera MCP zawodzi lub nic nie zwraca. Narzędzie się łączy, ale każde zapytanie kończy się błędem albo zwraca pustkę. Zwykle to brakujący/wygasły token lub błędna zmienna środowiskowa (GRAFANA_SERVICE_ACCOUNT_TOKEN, DT_ENVIRONMENT, nieukończony OAuth Sentry). Uruchom claude mcp list, aby potwierdzić, że serwer jest połączony, sprawdź ponownie zmienne środowiskowe względem poleceń instalacji powyżej, a dla hostowanego serwera Sentry ponownie przejdź przepływ OAuth. Jeśli npm view <pkg> pokazuje podejrzanie niską liczbę pobrań, zainstalowałeś podróbkę — przeinstaluj oficjalną paczkę z przestrzenią nazw.

4. AI wygenerowało „rozproszony monolit”. Serwisy, które muszą być wdrażane razem, albo dwa serwisy zapisujące do tej samej tabeli. To wada projektowa, której model sam z siebie nie zgłosi. Poproś go o audyt: „Wypisz każde miejsce, gdzie dwa serwisy współdzielą bazę danych, ścieżkę zapisu lub muszą być wdrażane w blokadzie”. Rozwiąż te przypadki, zanim podzielisz dalej — współdzielone ścieżki zapisu niweczą sens mikrousług.

5. Automatyczne cofnięcie canary nigdy się nie odpala. Wdrożenie poszło źle, ale pozostało na 100%. Próg cofnięcia odwołuje się do metryki, która nie jest emitowana, albo nazwa metryki jest błędna. Potwierdź, że metryki golden signals istnieją w Prometheus/Grafanie (użyj MCP Grafany, aby je odpytać), zanim zaczniesz polegać na automatycznym cofaniu, i przetestuj ścieżkę cofnięcia na staging z celowo wadliwym buildem.

Co dalej

• Monitorowanie i obserwowalność — wejdź głębiej w OpenTelemetry, dashboardy Grafany i pętlę debugowania z MCP Sentry
• Automatyzacja potoków z AI — buildy świadome zmian i bezpieczne wdrożenia progresywne dla serwisów, które właśnie wydzieliłeś
• Infrastruktura jako kod z asystentami AI — Terraform, Pulumi i serwery MCP dostawców, które osadzają AI w realnym stanie
• Wzorce testów integracyjnych — testowanie kontraktów i weryfikacja granic serwisów bez kruchych atrap
• Niezbędne serwery MCP dla każdego dewelopera — fundamentalne serwery stojące za każdym z powyższych przepływów