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.
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.
nx.json/turbo.json w konkretne zyski z równoległościuvx, niewstający serwer MCPSerwer 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:
{ "mcpServers": { "nx": { "command": "npx", "args": ["-y", "nx-mcp"] } }}Potwierdź to w Cursor Settings → MCP — powinieneś zobaczyć nx na liście z zieloną kropką.
Dodaj go jako serwer stdio z katalogu głównego repozytorium. Użyj --scope project, aby konfiguracja trafiła do współdzielonego .mcp.json, a nie do domyślnego zakresu local (który mieszka w ~/.claude.json pod ścieżką twojego projektu i jest prywatny). Flaga --scope musi pojawić się przed nazwą serwera i przed --:
claude mcp add nx --scope project -- npx -y nx-mcpSprawdź, że się zarejestrował i jest osiągalny:
claude mcp listZ --scope project konfiguracja ląduje w .mcp.json. Zatwierdź ten plik w repozytorium, żeby cały zespół miał tę samą konfigurację świadomą grafu.
Zarejestruj ten sam serwer stdio. Codex przechowuje go w ~/.codex/config.toml:
codex mcp add nx -- npx -y nx-mcpcodex mcp listW przypadku większych workspace daj serwerowi więcej zapasu na start w ~/.codex/config.toml:
[mcp_servers.nx]command = "npx"args = ["-y", "nx-mcp"]startup_timeout_sec = 30Dwa 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.
{ "mcpServers": { "git": { "command": "uvx", "args": ["mcp-server-git", "--repository", "/path/to/monorepo"] }, "fs": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/monorepo"] } }}claude mcp add git -- uvx mcp-server-git --repository /path/to/monorepoclaude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem /path/to/monorepocodex mcp add git -- uvx mcp-server-git --repository /path/to/monorepocodex mcp add fs -- npx -y @modelcontextprotocol/server-filesystem /path/to/monorepoOgraniczenie 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.jsonPracują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
Użyj hierarchii CLAUDE.md, żeby każdy pakiet niósł własne reguły:
# /CLAUDE.md (root)pnpm monorepo with Turborepo. Run `pnpm turbo build` to build all packages.Run `pnpm turbo test` to test all packages.Package dependency graph: core → ui, api-client → web, api, admin.Always run `pnpm turbo build --affected` after cross-package changes.
# /packages/core/CLAUDE.mdFoundation package. Changes here cascade everywhere.After ANY modification: run `pnpm turbo build --filter='core...'`to rebuild every package that depends on core and verify compatibility.Exports must be backward-compatible. Use deprecation notices, not breaking changes.
# /packages/ui/CLAUDE.mdReact component library. Storybook for development: `pnpm storybook`.Components must be exported from /src/index.ts barrel.Every component needs a .stories.tsx and .test.tsx file.Pod-agenci mogą wtedy zrównoleglić analizę pakiet po pakiecie, bez wyprowadzania układu od nowa przez każdego z nich.
Codex czyta pliki AGENTS.md przed rozpoczęciem jakiejkolwiek pracy, więc zakoduj tam przepływ pracy monorepo (Codex nie czyta pliku o nazwie codex.md, chyba że dodasz go do project_doc_fallback_filenames):
Monorepo with Turborepo + pnpm workspaces.Before making cross-package changes:1. Run: pnpm turbo build --affected --dry-run to preview the affected chain2. Identify all packages in the dependency chain3. Make changes starting from the lowest dependency (core) upward4. Run tests after each package modification
After all changes: pnpm turbo build && pnpm turbo testUżyj osobnych git worktree do równoległych zadań Codeksa; ChatGPT desktop może tworzyć opcjonalne zarządzane worktree, a zadania CLI/IDE używają worktree utworzonych lub wybranych przez ciebie.
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ę:
Useris imported by 8 packages. Addingstatusas 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.
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.
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.
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:
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.
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.
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.claude "Analyze our monorepo's package dependency graph.Read every package.json in /packages/ and /apps/.Build the complete dependency graph and check for:1. Circular dependencies2. Violation of the layering rule (apps must not depend on other apps)3. Version mismatches for shared deps4. Packages that could be merged (similar purpose, small surface)Output the graph and any issues found."Perform a full dependency analysis of this monorepo.For each package, document:- Direct dependencies (internal)- Transitive dependencies (internal)- External dependency versions- Build time and test coverage
Create a dependency graph visualization in /docs/dependency-graph.md.Flag any architectural violations or optimization opportunities.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:builddeclares a dependency onmobile-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, yourtesttarget’sinputsinclude**/*.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:
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”.@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.nx.json. Jeśli model mówi „no Nx workspace detected”, uruchom go ponownie z katalogu głównego repozytorium.npx nx reset, aby wyczyścić cache Nx, a potem poproś model o ponowne odczytanie grafu, zanim zaufasz nowemu raportowi wpływu..cursor/rules / CLAUDE.md / AGENTS.md — serwer grafu dostarcza krawędzi, plik reguł dostarcza zobowiązania.turbo build --affected (lub --filter=...[origin/main]), a nie tylko ten jeden pakiet, który edytowałeś.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:
# Browse or run cloud tasks from the terminalcodex cloud
# Apply a completed cloud task's diff to your local treecodex applyPozwala 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.
Mikroserwisy
Koordynuj zmiany przez granice usług z tym samym nastawieniem opartym na grafie. Zobacz Przepływy pracy w mikroserwisach.
Jakość kodu na dużą skalę
Utrzymuj spójność lintingu, typów i testów w każdym pakiecie. Zobacz Przepływy pracy dla jakości kodu.
Pipeline'y CI/CD
Buduj i wdrażaj pakiety monorepo z pipeline’ami zoptymalizowanymi pod AI. Zobacz Automatyzację potoków z AI.
Ekosystem MCP
Wejdź głębiej w konfigurowanie i łączenie serwerów MCP we wszystkich trzech narzędziach. Zobacz przewodniki po ekosystemie MCP.