Przejdź do głównej zawartości

Przepływy pracy w monorepozytoriach z asystentami AI

Przepływy pracy w monorepozytoriach z asystentami AI opierają się na serwerze MCP z grafem projektu, najczęściej Nx Console, który podaje Cursorowi, Claude Code i Codeksowi graf zależności i cache zadań jako ustrukturyzowany kontekst. W parze z plikiem reguł opisującym kolejność budowania i ograniczenia warstw analiza wpływu, refaktoryzacja kaskadowa i kolejność wydań stają się zapytaniami, a nie ręcznymi audytami.

Pojawia się ostrzeżenie bezpieczeństwa dla twojej biblioteki uwierzytelniania. Mieszka ona w @company/core, a importują ją 23 usługi w monorepozytorium liczącym 47 pakietów. Musisz wiedzieć dokładnie, które pakiety przestaną działać, w jakiej kolejności się przebudują i które zespoły zawiadomić. Otwórz najpierw niewłaściwy plik, a stracisz całe popołudnie na tropienie przechodnich importów, na które graf projektu odpowiedziałby w kilka sekund. Ta sama luka gryzie w spokojny wtorek: zmieniasz nazwę współdzielonego typu i psuje się siedem pakietów niżej w łańcuchu, w tym dwa z testami integracyjnymi, które przechodzą lokalnie, a padają w CI, bo zależność nigdy nie została przebudowana.

Domyślnie asystenci AI traktują twoje monorepozytorium jak stos plików. Nie mają pojęcia, że web-app zależy od @company/ui, które zależy od @company/core. Rozwiązaniem jest serwer MCP z grafem projektu (Nx Console jest najdojrzalszy), który podaje modelowi graf zależności, schematy generatorów i cache zadań jako ustrukturyzowany kontekst. Gdy już to skonfigurujesz, pytanie „co się zepsuje, jeśli to zmienię?” staje się zapytaniem, a nie ręcznym audytem.

  • Działającą konfigurację Nx MCP w Cursorze, Claude Code i Codeksie, dzięki której model może czytać twój graf projektu
  • Pliki reguł kodujące kolejność budowania, ograniczenia warstw i konwencje poszczególnych pakietów — politykę, której sam graf nie niesie
  • Wielokrotnego użytku prompt do analizy wpływu, który zwraca dotknięte pakiety w kolejności zależności, zanim dotkniesz kodu
  • Dwa prompty do refaktoryzacji między pakietami: jeden napędzany grafem Nx, drugi działający w zwykłym workspace pnpm/Turborepo bez serwera grafu
  • Audyt dryfu konfiguracji i audyt architektury grafu, które wyłapują zależności cykliczne i naruszenia warstw
  • Prompt do optymalizacji budowania, który zamienia grafy zadań z nx.json/turbo.json w konkretne zyski z równoległości
  • Planowanie wydań respektujące kolejność publikacji oraz polecenia podbicia wersji, którymi je wykonasz
  • Kroki naprawcze dla trybów awarii, które naprawdę cię spotkają: nieaktualne grafy, brakujący uvx, niewstający serwer MCP

Serwer Nx MCP (nx-mcp) to dziś najbardziej zaawansowana integracja monorepozytoriów. Udostępnia twój graf projektu, schematy generatorów i dokumentację Nx jako narzędzia, które model może wywoływać. Konfiguracja jest niemal identyczna we wszystkich trzech narzędziach — jedyną realną różnicą jest uruchamiane polecenie.

Zainstaluj rozszerzenie Nx Console. W workspace Nx Cursor (0.46+) wykrywa je automatycznie i pokazuje powiadomienie z propozycją włączenia serwera Nx MCP. Zaakceptuj je, a Nx Console zapisze za ciebie wpis w .cursor/mcp.json.

Aby skonfigurować to ręcznie, uruchom nx.configureMcpServer z palety poleceń (Cmd/Ctrl+Shift+P) albo dodaj wpis samodzielnie:

.cursor/mcp.json
{
"mcpServers": {
"nx": { "command": "npx", "args": ["-y", "nx-mcp"] }
}
}

Potwierdź to w Cursor Settings → MCP — powinieneś zobaczyć nx na liście z zieloną kropką.

Dwa kolejne serwery dopełniają konfigurację monorepozytorium. Zwróć uwagę, że uruchamiane są inaczej: oficjalny serwer systemu plików to pakiet Node uruchamiany przez npx, natomiast serwer git działa wyłącznie w Pythonie i uruchamiany jest przez uvx (najpierw zainstaluj uv). W npm nie ma pakietu @modelcontextprotocol/server-git — taki pakiet nie istnieje.

.cursor/mcp.json
{
"mcpServers": {
"git": {
"command": "uvx",
"args": ["mcp-server-git", "--repository", "/path/to/monorepo"]
},
"fs": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/monorepo"]
}
}
}

Ograniczenie serwera systemu plików do katalogu głównego monorepozytorium utrzymuje operacje masowe wewnątrz twojego workspace, a nie na reszcie dysku.

Graf mówi modelowi, co od czego zależy. Nie mówi mu, co jest dozwolone: że aplikacje nigdy nie mogą importować z innych aplikacji, że core nie ma zewnętrznych zależności, że eksporty pozostają wstecznie zgodne. Ta polityka należy do pliku reguł i to ona powstrzymuje model przed rozwiązaniem cyklicznego importu przez dodanie krawędzi, którą odrzuciłbyś w przeglądzie. Jest też planem awaryjnym, gdy nie ma serwera grafu — workspace na Turborepo dostaje większość korzyści z samego pliku reguł.

Ustrukturyzuj swój .cursor/rules, aby zakodować graf i ograniczenia razem:

# .cursor/rules (root)
This is a Turborepo monorepo managed with pnpm workspaces.
Package structure:
- /packages/core - Shared types, utilities, base classes (NO external deps)
- /packages/ui - React component library (depends on: core)
- /packages/api-client - API SDK (depends on: core)
- /apps/web - Next.js frontend (depends on: core, ui, api-client)
- /apps/api - Express backend (depends on: core)
- /apps/admin - Admin dashboard (depends on: core, ui, api-client)
Build order: core → ui, api-client → web, api, admin
CRITICAL RULES:
- Changes to /packages/core affect ALL other packages. Always check downstream.
- Never import from /apps/* into /packages/*
- Shared types go in /packages/core/src/types/
- Each package has its own tsconfig.json that extends /tsconfig.base.json

Pracując nad zmianami między pakietami, jawnie odwołuj się do łańcucha zależności: @packages/core/src/types @packages/ui/src/components @apps/web/src/pages

Najcenniejszym ruchem w monorepozytorium jest zapytanie modelu, co się zepsuje, zanim zaczniesz edytować. Z aktywnym Nx MCP model wywołuje nx_workspace i nx_project_details zamiast zgadywać z instrukcji import.

Mając realny kontekst grafu, dostajesz coś, na czym możesz działać, a nie zgadywankę:

User is imported by 8 packages. Adding status as optional is non-breaking at the type level. The packages that render user data and should be updated to show status: UserCard (web-app), UserProfile (mobile-app), UserList (admin-dashboard). Rebuild order: @company/core@company/ui → web-app, mobile-app, admin-dashboard.

Ta lista kontrolna to różnica między kontrolowaną zmianą a popołudniem spędzonym na grep. Model przeczytał twój prawdziwy graf, więc kolejność przebudowy i ocena „opcjonalne znaczy bez łamania kodu” są oparte na faktach, a nie zmyślone.

Gdy zaufasz analizie wpływu, ta sama świadomość grafu napędza skoordynowane zmiany. Pracuj od dołu drzewa zależności w górę, warstwa po warstwie, tak by awarie integracyjne wychodziły na jaw, póki diff jest jeszcze mały. Przepływ jest identyczny we wszystkich trzech narzędziach — model proponuje plan, ty go zatwierdzasz, a następnie wykonuje go pakiet po pakiecie — więc różnica tkwi tylko w tym, jak sterujesz każdym narzędziem. Tryb agenta w Cursorze nanosi zmiany w miejscu, z punktami kontrolnymi; Claude Code działa w terminalu i może wpinać się w hooki lub CI; Codex może rozdzielić pracę między opcjonalne lokalne worktree w ChatGPT desktop albo osobne hostowane zadania Cloud.

  1. Najpierw zdobądź plan. Uruchom powyższy prompt do analizy wpływu, żeby mieć listę dotkniętych pakietów w kolejności zależności, i zweryfikuj ją z własnym zrozumieniem, zanim cokolwiek zostanie wyedytowane.

  2. Zmodyfikuj pakiet źródłowy i zbuduj go w izolacji. Zmień współdzielony typ, narzędzie lub komponent w pakiecie bazowym i sprawdź, że kompiluje się samodzielnie — pnpm turbo build --filter=core — zanim zobaczy go którykolwiek pakiet zależny.

  3. Refaktoryzuj o jedną warstwę wyżej naraz. Poproś model, żeby pracował w kolejności zależności, tak aby każdy pakiet kompilował się, zanim zmienią się jego pakiety zależne:

  4. Zbuduj i przetestuj każdy pakiet zależny, zanim ruszysz dalej. Nie wspinaj się na kolejną warstwę, dopóki bieżąca nie jest zielona — to właśnie powstrzymuje awarię CI przed pojawieniem się pięć pakietów później, bez oczywistej przyczyny.

  5. Weryfikuj grafem budowania. Uruchom tylko to, co się zmieniło — npx nx affected -t build test lint albo pnpm turbo build --affected w workspace na Turborepo — i przekaż modelowi każdy błąd wraz z nazwą pakietu i treścią błędu.

  6. Na końcu uruchom pełny pipeline raz. Przebieg na grafie dotkniętych pakietów to twoja szybka pętla; kompletny build i pełny zestaw testów to coś, czemu ufasz przed scaleniem.

Bez serwera grafu model nie wyprowadzi kolejności sam — więc podajesz mu ją ty. Poniższy prompt to ta sama kaskada rozpisana ręcznie, po którą sięgasz w zwykłym workspace pnpm/Turborepo, a jego twardy przystanek po kroku z listowaniem jest tym zabezpieczeniem, które wersja z Nx dostaje od grafu:

Analiza wpływu odpowiada na pytanie „czego dotyka ta zmiana?”. Inne pytanie — „czy ten graf ma kształt, jaki zamierzaliśmy?” — wymaga własnego przebiegu i to ono wyłapuje zależności cykliczne oraz naruszenia warstw, zanim zdążą stwardnieć.

Analyze the import statements across our entire monorepo and build a dependency graph.
Flag any:
- Circular dependencies between packages
- Apps importing from other apps (forbidden)
- Packages importing from apps (forbidden)
- Unused packages (no dependents)
- Packages with suspiciously deep dependency chains (> 3 levels)
Visualize the graph as a text-based tree structure.

Konfiguracja dryfuje tak samo jak graf, tylko ciszej: jeden pakiet na innej wersji TypeScriptu, jeden bez skryptu type-check, jeden, którego tsconfig.json przestał rozszerzać bazowy. Uruchamiaj ten audyt cyklicznie, a nie dopiero wtedy, gdy coś pęknie.

Wolne CI to zwykle problem grafu zadań, a nie sprzętu. Nx MCP pozwala modelowi przeczytać twój rzeczywisty nx.json i konfiguracje projektów, zamiast udzielać ogólnikowych rad.

Model świadomy grafu daje ci konkrety, które możesz wkleić do PR-a:

Your web-app:build declares a dependency on mobile-app:build, but nothing in web-app imports mobile-app. Removing that edge lets the two apps build in parallel — roughly 40% off the critical path. Separately, your test target’s inputs include **/*.md, so doc edits bust the test cache. Narrow it to ["default", "^default"].

W przypadku Turborepo ten sam wzorzec dotyczy turbo.json — poproś model o audyt inputs, outputs i dependsOn — ale dopóki nie pojawi się oficjalny serwer, będziesz podawać mu zawartość pliku bezpośrednio, a nie przez narzędzie MCP.

Wielopakietowe wydania to miejsce, gdzie kolejność zależności gryzie najmocniej: wydaj @company/payments przed @company/core, od którego zależy, a opublikujesz zepsutą wersję. Połącz dla tego serwer git MCP (historia commitów) z Nx MCP (kolejność zależności).

Tamten prompt planuje wydanie na podstawie historii. Kolejny wykonuje je dla zmiany, którą właśnie skończyłeś: wychodzi od pakietów, których dotknąłeś, a nie od tagu, i kończy się faktycznymi poleceniami podbicia wersji we właściwej kolejności.

Narzędzia świadome grafu zawodzą na kilka przewidywalnych sposobów. Rozpoznawaj je szybko:

  • Serwer MCP nie wstaje. Uruchom claude mcp list (lub codex mcp list) — serwer utknięty w stanie „failed” zwykle oznacza brakujący plik wykonywalny launchera. Dla nx-mcp i serwera systemu plików potrzebujesz Node/npx w PATH; dla serwera git potrzebujesz uv/uvx. Zainstaluj uv, jeśli uvx zgłasza „command not found”.
  • Użyłeś @modelcontextprotocol/server-git i dostałeś 404. Tego pakietu nie ma w npm — serwer git jest wyłącznie w Pythonie. Zamiast tego użyj uvx mcp-server-git --repository /path.
  • Model nie znajduje twoich projektów. Nx MCP musi działać z (albo być wskazany na) katalogu głównego workspace, gdzie mieszka nx.json. Jeśli model mówi „no Nx workspace detected”, uruchom go ponownie z katalogu głównego repozytorium.
  • Analiza wpływu jest nieaktualna. Graf projektu jest cache’owany. Po dodaniu lub przeniesieniu pakietów uruchom npx nx reset, aby wyczyścić cache Nx, a potem poproś model o ponowne odczytanie grafu, zanim zaufasz nowemu raportowi wpływu.
  • Model zmienił współdzielony pakiet i zostawił pakiety zależne w spokoju. Nic mu nie powiedziało, że zmiana kaskaduje. Dodaj jawny łańcuch zależności i wymóg kolejności budowania do .cursor/rules / CLAUDE.md / AGENTS.md — serwer grafu dostarcza krawędzi, plik reguł dostarcza zobowiązania.
  • Build przechodzi lokalnie, ale pada w CI dla pakietów niżej w łańcuchu. Testowałeś na nieaktualnych buildach zależności. Przebuduj cały dotknięty łańcuch przez turbo build --affected (lub --filter=...[origin/main]), a nie tylko ten jeden pakiet, który edytowałeś.
  • Model wprowadził zależność cykliczną. Sformułuj regułę warstw jako zakaz, a nie opis: “packages/core MUST NOT import from packages/ui or any app.” Modele dobrze przestrzegają ograniczeń, gdy są ujęte jako ograniczenia.
  • Podbicia wersji wychodzą niespójnie. Promptowanie ad hoc nie utrzyma polityki wersjonowania. Przyjmij changesets lub odpowiednik i naucz narzędzie tego procesu w pliku reguł, żeby każde wydanie szło tą samą ścieżką.
  • Duże prompty przekraczają limit czasu lub halucynują eksporty. W dużych workspace ładunek grafu może przekroczyć okno kontekstu. Zawęź żądanie do jednego pakietu lub jednego wycinka (nx affected --base=main) i podbij startup_timeout_sec serwera, jeśli przekracza limit czasu przy pierwszym wywołaniu.

Migracje monorepozytoriów są wolne i podatne na zrównoleglenie, co czyni je dobrym dopasowaniem do wielopowierzchniowego modelu Codeksa. W ChatGPT desktop lokalne zadanie może używać opcjonalnego zarządzanego worktree gita; zadanie Codex Cloud działa natomiast w osobnym hostowanym środowisku. Użyj jednego izolowanego zadania na grupę pakietów, a następnie zastosuj wyniki Cloud lokalnie:

Okno terminala
# Browse or run cloud tasks from the terminal
codex cloud
# Apply a completed cloud task's diff to your local tree
codex apply

Pozwala to rozesłać zadanie „migrate package group A to the new API” do chmury, podczas gdy ty dalej edytujesz lokalnie, a następnie przejrzeć każdy diff za pomocą codex apply, zanim trafi do drzewa.

Duże bazy kodu

Strategie kontekstu dla repozytoriów zbyt dużych, by zmieścić je w oknie — niezbędna umiejętność do każdego monorepozytorium. Zobacz Praca z dużymi bazami kodu.

Ekosystem MCP

Wejdź głębiej w konfigurowanie i łączenie serwerów MCP we wszystkich trzech narzędziach. Zobacz przewodniki po ekosystemie MCP.