Przepływy pracy w monorepozytoriach z asystentami AI

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.

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.

Co z tego wyniesiesz

• Działającą konfigurację Nx MCP w Cursorze, Claude Code i Codeksie, dzięki której model może czytać twój graf projektu
• Wielokrotnego użytku prompt do analizy wpływu, który zwraca dotknięte pakiety w kolejności zależności, zanim dotkniesz kodu
• Prompt do optymalizacji budowania, który zamienia grafy zadań z nx.json/turbo.json w konkretne zyski z równoległości
• Przepływ refaktoryzacji między pakietami, który utrzymuje spójność importów i typów w dziesiątkach pakietów
• Kroki naprawcze dla trybów awarii, które naprawdę cię spotkają: nieaktualne grafy, brakujący uvx, niewstający serwer MCP

Konfiguracja serwerów MCP z grafem projektu

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.

Uwaga

Nowsze wersje nx-mcp domyślnie działają w trybie „minimal”, który ukrywa narzędzia do analizy workspace, na których opierają się poniższe prompty — w tym nx_workspace, nx_project_details, nx_generators i nx_generator_schema — ponieważ Nx dostarcza teraz tę funkcjonalność jako umiejętności agenta. Jeśli twój agent korzysta z tych umiejętności, domyślny tryb jest w porządku. Jeśli chcesz, żeby model wywoływał narzędzia grafu bezpośrednio (jak zakładają tu prompty do analizy wpływu i refaktoryzacji), dodaj --no-minimal do polecenia — na przykład npx -y nx-mcp --no-minimal.

Cursor

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ą.

Claude Code

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-mcp

Sprawdź, że się zarejestrował i jest osiągalny:

claude mcp list

Z --scope project konfiguracja ląduje w .mcp.json. Zatwierdź ten plik w repozytorium, żeby cały zespół miał tę samą konfigurację świadomą grafu.

Codex

Zarejestruj ten sam serwer stdio. Codex przechowuje go w ~/.codex/config.toml:

codex mcp add nx -- npx -y nx-mcp
codex mcp list

W 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 = 30

Notatka

Użytkownicy Turborepo i Bazel: Nie ma jeszcze oficjalnego serwera MCP dla Turborepo — to wciąż otwarta dyskusja w Vercel (turborepo#10130), a nie wydanie. Tymczasem i tak zainstaluj Nx Console: jego narzędzia do grafu projektu działają z dowolnym workspace, gdy tylko wskażesz im swoje pakiety, a możesz połączyć je z serwerem git do koordynacji zmian. W przypadku Bazel oprzyj się na serwerze plików oraz wynikach bazel query wklejonych do kontekstu.

Dodawanie kontekstu Git i systemu plików

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

.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"]
    }
  }
}

Claude Code

claude mcp add git -- uvx mcp-server-git --repository /path/to/monorepo
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem /path/to/monorepo

Codex

codex mcp add git -- uvx mcp-server-git --repository /path/to/monorepo
codex mcp add fs -- npx -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.

Analiza wpływu, zanim dotkniesz kodu

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.

Wskazówka

Prompt do skopiowania — analiza wpływu zmiany:

Using the Nx project graph, I’m adding an optional status: 'active' | 'suspended' field to the User interface exported from @company/core. Tell me:

1. Every package that imports User (direct and transitive), in rebuild order.
2. Which of those will break at compile time vs. which are safe because the field is optional.
3. The specific components that render user data and should surface the new field. Output a checklist grouped by package. Do not edit anything yet — I want the plan first.

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.

Refaktoryzacja między pakietami

Gdy zaufasz analizie wpływu, ta sama świadomość grafu napędza skoordynowane zmiany. Przepływ jest taki sam 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ę na tła w worktreech albo do chmury.

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.

2. Refaktoryzuj w kolejności grafu. Poproś model, żeby pracował od dołu do góry, tak aby każdy pakiet kompilował się, zanim zmienią się jego pakiety zależne:

   Wskazówka

   Prompt do skopiowania — skoordynowana zmiana nazwy:

   We’re renaming getUser(id) to fetchUserById(id) across the monorepo. Using the Nx graph, refactor in dependency order: update the definition in @company/core first, then every consumer. For each package, change call sites, update mocks in test files, and keep TypeScript types in sync. Add a deprecated getUser alias that re-exports fetchUserById so nothing breaks mid-migration. Show me the diff per package and stop before committing.

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

Uwaga

Powstrzymaj się od jednego wielkiego promptu „zrefaktoryzuj wszystko”. Duże zmiany w monorepozytorium dryfują: model traci orientację, w którym pakiecie jest, i zaczyna zmyślać eksporty. Trzymaj każdą turę zawężoną do jednego pakietu lub jednego wycinka grafu, weryfikuj przez nx affected, a potem przechodź dalej. Sztuczka z przestarzałym aliasem utrzymuje drzewo na zielono między krokami.

Optymalizacja budowania

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.

Wskazówka

Prompt do skopiowania — optymalizacja budowania:

Read our nx.json and project configurations through the Nx MCP. Our CI build step takes ~9 minutes. Identify:

1. Tasks declared as dependencies that aren’t real (e.g. apps depending on each other’s build output unnecessarily).
2. Cache misses caused by overly broad inputs globs.
3. Targets that could run with parallel but currently don’t. For each finding, give me the exact config change and an estimated time saved. Cite the file and line.

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.

Koordynacja release’ów

Wielopakietowe release’y 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).

Wskazówka

Prompt do skopiowania — planowanie release’u:

Using the git MCP for commit history and the Nx graph for dependencies, plan the next release. Since the last tag:

1. Group commits by affected package.
2. Classify each as patch, minor, or major using Conventional Commits.
3. Flag any breaking change that forces a major bump in a dependent package too.
4. Produce a publish order that respects the dependency graph.
5. Draft changelog entries per package, linking the relevant commits. Output a release table: package, current version, proposed version, publish order.

Kiedy to się psuje

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.
• 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.

Worktreey w tle w Codeksie do długich migracji

Migracje monorepozytoriów są wolne i podatne na zrównoleglenie, co czyni je dobrym dopasowaniem do wielopowierzchniowego modelu Codeksa. Codex uruchamia zadania w tle w dedykowanych worktreech gita, więc długa refaktoryzacja nie blokuje twojego drzewa roboczego. Odpal zadanie w chmurze dla każdej grupy pakietów, a potem ściągnij wyniki lokalnie:

# 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.

Co dalej

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.

Ekosystem MCP

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