Przepływy pracy w monorepozytoriach z asystentami AI

Praca agentów AI w monorepozytorium zależy od grafu projektu, którego Claude Code, Codex i Cursor domyślnie nie mają. Dostarcza go serwer MCP Nx, skille Nx albo wynik turbo ls; plik reguł dodaje politykę warstw, a bramki build, lint i granic modułów uruchamiane tylko dla pakietów, których dotyczy zmiana (affected), weryfikują każdą zmianę zamiast człowieka czytającego cały diff.

Ta strona jest dla programistów i tech leadów, którzy utrzymują workspace pnpm, Nx albo Turborepo z więcej niż kilkoma pakietami. Zmieniasz nazwę typu w @company/core, agent poprawia trzy wywołania znalezione grep-em, a CI pada w dwóch pakietach, których nigdy nie otwierałeś, bo importują ten typ przez @company/ui. Albo poprawka bezpieczeństwa trafia do współdzielonego pakietu uwierzytelniania i nie umiesz powiedzieć, które z 23 usług trzeba przebudować, w jakiej kolejności i którym zespołom dać znać. Oba problemy to pytania o graf, a agent bez grafu odpowiada na nie zgadywaniem.

Jeśli twoje repozytorium jest duże, ale nie jest podzielone na pakiety, zacznij od pracy z dużymi bazami kodu; ta strona zakłada, że masz już strategię zarządzania kontekstem.

Co daje ci ten przewodnik po monorepo

• Sprawdzony sposób przekazania grafu projektu do Claude Code, Codeksa i Cursora, osobno dla Nx i dla Turborepo
• Plik reguł z kolejnością budowania i zakazanymi importami, żeby agent nie „naprawiał” cyklu, dodając krawędź, którą odrzuciłbyś w review
• Prompty do skopiowania: analiza wpływu, zmiana nazwy sterowana grafem, zmiana nazwy bez serwera grafu, przegląd różnicy grafu i audyt dryfu
• Sekwencję bramek, która dowodzi poprawności zmiany między pakietami bez czytania każdej linii: build zbioru affected, lint granic modułów i porównanie grafu przed i po
• Kroki naprawcze dla awarii, które naprawdę się zdarzają: nieaktualny graf, ukryte narzędzia MCP, serwer, który nie startuje, i pakiety zależne, których nikt nie przebudował

Jak przekazać agentowi AI graf projektu monorepo?

Agent czyta pliki. Nie wie, że apps/web zależy od @company/ui, a to od @company/core, dopóki ktoś mu tego nie powie. W workspace Nx robi to sam Nx. W Turborepo i zwykłych workspace’ach pnpm dostarczasz graf z wiersza poleceń.

Workspace Nx: niech Nx sam zapisze konfigurację agentów

Nx 23 ma polecenie, które jednym ruchem konfiguruje serwer MCP, skille i pliki instrukcji dla każdego agenta. Uruchom je w katalogu głównym workspace’u:

1. Uruchom konfigurator dla agentów, których używa twój zespół:

   npx nx configure-ai-agents --agents claude codex cursor

   Jeśli npx nx configure-ai-agents --help kończy się błędem, twoja wersja Nx jest starsza niż to polecenie. Najpierw przeprowadź migrację i przejrzyj ją jako osobny pull request, zanim dołożysz na nią konfigurację agentów; migracja Nx do nowej wersji głównej przepisuje konfigurację w całym workspace:

   npx nx migrate latest
   npm install                        # or pnpm install / yarn
   npx nx migrate --run-migrations

2. Przeczytaj diff, zanim go zacommitujesz. W próbnym uruchomieniu na Nx 23.2.1 polecenie dopisało zarządzany blok do CLAUDE.md i AGENTS.md, utworzyło siedem skilli w .agents/skills/ (m.in. nx-workspace, nx-run-tasks i nx-generate), subagenta ci-monitor-subagent dla Codeksa w .codex/agents/, wpis nx-mcp w .codex/config.toml uruchamiający npx nx mcp oraz .claude/settings.json, który włącza plugin nx z marketplace’u nrwl/nx-ai-agents-config. Ustawiło też multi_agent = true dla Codeksa i dodało wyjątki sandboxa dla ~/.nx i /tmp/.nx. Zostaw to, czego chcesz; usuń to, na co nie pozwala twoja polityka bezpieczeństwa.

3. Po aktualizacjach sprawdzaj stan konfiguracji:

   npx nx configure-ai-agents --check=all

Krok dla Cursora wymaga polecenia cursor w PATH; bez niego konfigurator pomija Cursora i odsyła do rozszerzenia Nx Console. Ręczne wpisy z następnej sekcji działają w każdym przypadku.

Serwer MCP Nx domyślnie ukrywa narzędzia grafu

nx-mcp 0.25.0 startuje z --minimal ustawionym na true, co ukrywa nx_workspace, nx_project_details, nx_generators, nx_generator_schema, nx_available_plugins i nx_workspace_path (sprawdzone przez nx-mcp --help, 2026-09-26). Nx zakłada, że tę pracę wykonają skille z poprzedniej sekcji. Jeśli uruchamiasz serwer MCP bez skilli Nx i chcesz, żeby agent wywoływał narzędzia grafu bezpośrednio, dodaj --no-minimal.

Skonfiguruj serwer MCP ręcznie

Użyj tej ścieżki, gdy nie korzystasz z konfiguratora albo chcesz przypiętej wersji. Przypinaj ją: w sierpniu 2025 roku na npm trafiły złośliwe wersje nx, które przeszukiwały system plików w poszukiwaniu danych uwierzytelniających (advisory bezpieczeństwa Nx GHSA-cxm3-wv7p-598c, 2025-08-27), a npx -y bez wersji uruchamia najnowsze wydanie, jakiekolwiek ono jest.

Claude Code

Dodaj serwer w zakresie projektu, żeby wpis trafił do współdzielonego .mcp.json, który commitujesz, a nie do domyślnego zakresu local w twoim ~/.claude.json:

claude mcp add nx --scope project -- npx -y nx-mcp@0.25.0 --no-minimal
claude mcp list

Opcje (--scope, -e, --transport) podajesz przed nazwą serwera; wszystko po -- to polecenie uruchamiające.

Codex

codex mcp add nx -- npx -y nx-mcp@0.25.0 --no-minimal
codex mcp list

Wpis trafia do ~/.codex/config.toml, który widzisz tylko ty. Żeby udostępnić go zespołowi, umieść ten sam blok [mcp_servers.nx] w pliku .codex/config.toml workspace’u i zacommituj go; Codex wczytuje konfigurację projektu tylko w zaufanych projektach (zobacz punkt o AGENTS.md w sekcji rozwiązywania problemów).

Codex 0.157.1 czeka na start serwera 30 sekund (zmierzone 2026-09-30 na serwerze, który nigdy nie odpowiada). W dużym workspace pierwsze wyliczenie grafu może trwać dłużej, więc ustaw limit powyżej domyślnego:

[mcp_servers.nx]
command = "npx"
args = ["-y", "nx-mcp@0.25.0", "--no-minimal"]
startup_timeout_sec = 60

Cursor

Dodaj serwer do .cursor/mcp.json w katalogu głównym workspace’u i zacommituj plik:

{
  "mcpServers": {
    "nx": { "command": "npx", "args": ["-y", "nx-mcp@0.25.0", "--no-minimal"] }
  }
}

W sekcji MCP ustawień Cursora sprawdź, czy nx jest na liście i jest włączony.

Szerszy obraz MCP (bezpieczeństwo, koszt tokenów, inne serwery) znajdziesz w przewodnikach po ekosystemie MCP.

Workspace Turborepo i pnpm: podawaj graf z CLI

Turborepo 2.11 nie ma własnego serwera MCP, ale jego CLI odpowiada na te same pytania, a każdy agent może je uruchomić:

npx turbo ls --output json                 # every package, as JSON (--output is experimental)
npx turbo ls --filter=...@company/core     # a package plus everything that depends on it
npx turbo ls --affected                    # packages changed since `main`, plus their dependents
npx turbo run build --affected --dry-run   # the task graph turbo would run, without running it

--affected porównuje stan z main, więc ma co zgłosić dopiero wtedy, gdy pliki już się zmieniły. Do zaplanowania zmiany przed edycją użyj formy --filter=...<pakiet>. Wpisz te polecenia do pliku reguł (następna sekcja), żeby agent uruchamiał je przed planowaniem, zamiast odtwarzać graf z instrukcji import.

Co musi zawierać plik reguł, czego nie ma w grafie?

Graf zapisuje, co od czego zależy. Nie zapisuje, co jest dozwolone: że aplikacje nigdy nie importują z innych aplikacji, że core nie ma zewnętrznych zależności, że eksportowane typy zmieniają się tylko przez okres deprecjacji. Bez tej polityki agent rozwiązuje cykliczny import, dodając właśnie tę krawędź, która go tworzy.

Claude Code

Politykę umieść w głównym CLAUDE.md, a reguły konkretnych pakietów w ich własnych plikach CLAUDE.md, które Claude Code wczytuje, gdy pracuje w danym katalogu:

# CLAUDE.md (root)
pnpm + Turborepo monorepo. Layers, lowest first:
  packages/core -> packages/ui, packages/api-client -> apps/web, apps/api, apps/admin
Hard rules:
- packages/* MUST NOT import from apps/*. apps/* MUST NOT import from each other.
- packages/core MUST NOT gain external runtime dependencies.
- Exported types change only by adding a deprecated alias first.
Before planning a cross-package change: run `npx turbo ls --filter=...<changed package> --output json` to list the package and its dependents.
After changing a package: `npx turbo run build test --filter=...@company/core`
(the leading `...` selects the package and everything that depends on it).

Codex

Codex czyta pliki AGENTS.md, zanim zacznie jakąkolwiek pracę. Użyj tej samej polityki, zapisanej jako kolejność kroków, którą Codex ma wykonać:

AGENTS.md

Layers, lowest first: core -> ui, api-client -> web, api, admin.
packages/* MUST NOT import from apps/*; apps MUST NOT import from each other.
For any cross-package change:
1. Run `npx turbo ls --filter=...<changed package> --output json` to list the package and its dependents, in layer order.
2. Change the lowest layer first; build and test it before touching dependents.
3. Finish with `npx turbo run build test lint --affected`.

Cursor

Dodaj regułę projektu w .cursor/rules/, która obowiązuje zawsze, i daj jej tę samą treść co w zakładce Codex. Jak ograniczyć konwencje pakietu do jego katalogu, opisuje dokumentacja reguł Cursora.

Reguły warstw formułuj jako zakazy („MUST NOT import”), a nie opisy („aplikacje zwykle korzystają z pakietów”). Potem wymuś tę samą regułę lintem (zobacz, jak udowodnić zmianę między pakietami), bo plik reguł to rada, a reguła lintera to bramka.

Zrób analizę wpływu, zanim agent cokolwiek zmieni

Najcenniejszy prompt w monorepo pyta, co się zepsuje, zanim zmieni się jakikolwiek plik. Z dostępem do grafu agent zwraca pakiety w kolejności przebudowy, a nie listę trafień grep.

Prompt do skopiowania: analiza wpływu zmiany

Do not edit any files yet. I want to add an optional field
`status: 'active' | 'suspended'` to the `User` interface exported from
@company/core.

Use the Nx project graph (nx-workspace skill or Nx MCP tools) or, if this
is not an Nx workspace, `npx turbo ls --filter=...@company/core --output json`
(the package and everything that depends on it).
Report:
1. Every package that imports `User`, directly or transitively, in
   rebuild order (lowest layer first).
2. For each, whether it breaks at compile time or is safe because the
   field is optional. Name the file and symbol for every break.
3. The components that render user data and should show the new field.
4. The exact command that builds and tests exactly this set.

Output a checklist grouped by package. Mark any claim you did not confirm
from the graph or a file read as "unverified".

Odpowiedź sprawdzisz tanio. Przed edycją, w workspace Turborepo lub pnpm, lista pakietów musi się zgadzać z npx turbo ls --filter=...@company/core. Po zmianie musi się zgadzać z npx nx show projects --affected albo npx turbo ls --affected. Jeśli agent wymienia pakiet, którego narzędzie nie pokazuje, albo jakiś pomija, źle odczytał graf. Zatrzymaj się i popraw kontekst, zanim agent pójdzie dalej.

Refaktoryzuj między pakietami od dołu grafu

Zmiana obejmująca wiele pakietów pozostaje mała tylko wtedy, gdy każda warstwa kompiluje się, zanim zmieni się następna. Kolejność jest taka sama we wszystkich trzech narzędziach; różni się tylko sposób równoległego prowadzenia warstw.

1. Zdobądź plan. Uruchom prompt analizy wpływu i porównaj jego listę pakietów z listą pakietów zależnych z samego narzędzia (npx turbo ls --filter=...<pakiet> albo graf projektu Nx).

2. Zmień najniższy pakiet i zbuduj go osobno — na przykład npx nx build @company/core albo npx turbo run build --filter=@company/core — zanim zobaczy to którykolwiek pakiet zależny.

3. Dodaj warstwę zgodności. Zostaw starą nazwę jako przestarzały alias, żeby każda wyższa warstwa kompilowała się w trakcie migracji.

4. Migruj po jednej warstwie. Zbuduj i przetestuj każdą warstwę, zanim agent pójdzie wyżej. Błąd wskazuje wtedy jeden pakiet, a nie pięć.

5. Uruchom bramkę affected (następna sekcja), a potem usuń alias w osobnej, małej zmianie.

Prompt do skopiowania: zmiana nazwy w kolejności zależności z grafem Nx

Rename `getUser(id)` to `fetchUserById(id)` across the monorepo.

1. From the Nx project graph, list every project that calls `getUser`,
   in dependency order. Stop and show me the list.
2. After I confirm: change the definition in @company/core and export a
   deprecated `getUser` alias that calls `fetchUserById`. Run
   `npx nx build @company/core` and stop if it fails.
3. Then migrate one layer at a time: call sites, test mocks and types.
   After each layer run `npx nx affected -t build test --base=origin/main`
   and fix failures before moving on.
4. Do not remove the alias. Do not commit. End with a per-package summary
   and the final affected run's result.

Bez serwera grafu to ty podajesz agentowi kolejność. Twarde zatrzymanie po kroku z listą zastępuje kontrolę, którą wykonałby graf:

Prompt do skopiowania: zmiana nazwy w workspace pnpm lub Turborepo

Rename the type `UserProfile` to `UserAccount`. It is defined in
packages/core/src/types/user.ts.

1. Run `npx turbo ls --filter=...@company/core --output json` to list
   the packages that depend on core, then search only those packages
   for imports of or references to UserProfile. Show me the list
   grouped by package and STOP.
2. After I confirm: in packages/core, rename the type, export
   `/** @deprecated */ export type UserProfile = UserAccount;`, and run
   `npx turbo run build --filter=@company/core`.
3. Update packages/ui, then packages/api-client, then each app, one
   package per step. After each package run
   `npx turbo run build test --filter=<that package>`.
4. Finish with `npx turbo run build test lint --affected`. Report the
   result and do not commit.

Warstwy równolegle. Gdy najniższa warstwa jest już zmergowana, te pakiety z kolejnej warstwy, które nie zależą od siebie nawzajem, mogą pracować każdy we własnym worktree. Najpierw to sprawdź: npx turbo ls <pakiet> wypisuje zależności pakietu, a graf Nx pokazuje to samo. Jeśli w kolejności warstw z pliku reguł powyżej ui importuje typy z api-client, te dwa pakiety idą po kolei, a nie równolegle. Dla każdego niezależnego pakietu uruchom osobny worktree: claude --worktree ui-migration w Claude Code, codex --worktree w Codeksie albo Worktrees w Cursorze. Nigdy nie zrównoleglaj między warstwami; pakiet zależny zbudowany na niezmergowanej zależności niczego nie dowodzi. Jak orkiestrować wiele agentów, opisuje przewodnik po agentach równoległych.

Uwaga

Unikaj jednego promptu „zrefaktoryzuj wszystko”. W dużym workspace agent gubi się w tym, w którym pakiecie jest, i zaczyna wymyślać eksporty. Ogranicz każdą turę do jednego pakietu albo jednej warstwy i pozwól bramce affected zdecydować, kiedy praca jest skończona.

Jak udowodnić zmianę między pakietami bez czytania każdego diffu?

Zmiana nazwy w 40 pakietach daje diff, którego nikt nie czyta linia po linii i nikt nie powinien musieć. Dowód niosą cztery kontrole; części wymagające człowieka zatwierdzają właściciele pakietów.

Kontrola	Polecenie lub mechanizm	Czego dowodzi	Kto reaguje na błąd
Build, testy i lint zbioru affected	npx nx affected -t build test lint --base=origin/main albo npx turbo run build test lint --affected	Każdy pakiet zależny kompiluje się i przechodzi testy z nowym kodem	Agent poprawia, ty uruchamiasz ponownie
Granice modułów	Nx: reguła @nx/enforce-module-boundaries z @nx/eslint-plugin z tagami projektów. Inne workspace’y: kontrola reguł zależności, np. dependency-cruiser (npm install --save-dev dependency-cruiser, potem npx depcruise --init), uruchamiana jako funkcja dopasowania	Nie dodano zakazanego importu, żeby coś się skompilowało	Agent poprawia; nowy wyjątek wymaga tech leada
Różnica grafu	Nx: npx nx graph --file=before.json na gałęzi bazowej i --file=after.json na zmianie. Turborepo: polecenie turbo query poniżej, przekierowane do before.json i after.json	Które krawędzie zależności dodano lub usunięto	Właściciel każdego pakietu, który zyskał krawędź, ją zatwierdza (CODEOWNERS)
Pełny pipeline	Zwykły przebieg CI na merge requeście	Nic poza zbiorem affected się nie zepsuło	Zespół odpowiedzialny za CI

W workspace Turborepo turbo ls --output json bez nazw pakietów wypisuje tylko nazwy i ścieżki, bez krawędzi. Krawędzie zwraca turbo query (sprawdzone na turbo 2.11.5, 2026-09-30):

npx turbo query '{ packages { items { name directDependencies { items { name } } } } }' > before.json

To różnica grafu zastępuje czytanie. Zmiana nazwy nie powinna dodać żadnej krawędzi. Jeśli apps/admin zależy teraz od apps/web, różnica pokaże to w jednej linii, niezależnie od wielkości zmiany w kodzie. Reguły granic zamień w bramki CI za pomocą architektonicznych funkcji dopasowania, a cztery wyniki dołącz do pull requesta jako pakiet dowodów.

Prompt do skopiowania: przegląd różnicy grafu zależności

Compare before.json and after.json. They come from the same tool:
either `nx graph --file=...` (edges under graph.dependencies) or
`turbo query` (edges as each package's directDependencies).
List every dependency edge that was added or removed, as
"source -> target". For each added edge:
- quote the import statement that created it (file and line),
- say whether it breaks a rule in CLAUDE.md / AGENTS.md,
- say whether the change could avoid it (for example by moving the
  shared code down into packages/core).
If no edges changed, say exactly "No dependency edges changed."
Do not edit any files.

Audytuj dryf konfiguracji i graf zadań według harmonogramu

Monorepo dryfuje po cichu: jeden pakiet na innej wersji TypeScriptu, jeden tsconfig.json, który przestał rozszerzać bazowy, jeden target test, którego wejścia obejmują Markdown, więc każda zmiana w dokumentacji unieważnia cache. Uruchamiaj audyt co miesiąc albo w zaplanowanym zadaniu agenta, a nie dopiero po incydencie.

Prompt do skopiowania: audyt dryfu konfiguracji i grafu zadań

Audit this monorepo for drift. Read files only; do not edit.
1. tsconfig.json in every package: flag any that does not extend
   tsconfig.base.json.
2. Shared dependencies (typescript, react, eslint, vitest): flag every
   package whose version differs from the root.
3. Scripts: flag packages missing build, test, lint or typecheck.
4. Task graph (nx.json and project.json, or turbo.json): flag dependsOn
   edges between projects that do not import each other, and inputs
   globs that include docs or other files the task does not read.
5. Imports: flag any cycle between packages and any app importing
   another app.
Output one table: package | finding | evidence (file:line) | severity |
proposed fix. Do not estimate time savings; I will measure them.

Każdą poprawkę grafu zadań zmierz, zanim ją przyjmiesz: porównaj czas tego samego builda zbioru affected przed i po, na tym samym runnerze CI. Szacunek zaoszczędzonego czasu podany przez agenta to zgadywanie.

Planuj wydania w kolejności zależności

Opublikowanie @company/payments przed wersją @company/core, której potrzebuje, to wydanie zepsutego pakietu. Mechanikę wersjonowania oddaj Changesets, a agenta użyj do napisania changesetów i sprawdzenia kolejności.

Prompt do skopiowania: szkic planu wydania

Plan the next release. Do not publish or tag anything.
1. Run `git log <last-release-tag>..HEAD --name-only` and group the
   commits by package.
2. Classify each package's change as patch, minor or major (Conventional
   Commits; any removed or changed export is major).
3. Using the project graph, list the dependents that need a version bump
   because of a major change below them.
4. Write one .changeset/*.md file per logical change.
5. Run `npx changeset status` and show me its output next to your table:
   package | current version | proposed bump | reason.

Potem człowiek uruchamia npx changeset version i npx changeset publish z CI. Publikację trzymaj poza zasięgiem agenta; to jedyny krok, którego nie cofniesz przez git revert.

Co się psuje, gdy agenci pracują w monorepo?

• Serwer MCP nie startuje. Uruchom claude mcp list albo codex mcp list. Serwer w stanie błędu zwykle oznacza, że w PATH dziedziczonym przez agenta brakuje npx albo że skończył się czas podczas wyliczania grafu. Popraw PATH albo podnieś w Codeksie startup_timeout_sec powyżej domyślnych 30 sekund, np. do 60.
• Agent twierdzi, że nie ma narzędzi grafu. Serwer działa w domyślnym trybie minimalnym. Zainstaluj skille Nx przez nx configure-ai-agents albo dodaj --no-minimal.
• Agent zgłasza „no Nx workspace”. Serwer wystartował poza katalogiem głównym workspace’u. Uruchom agenta z katalogu, w którym leży nx.json, albo podaj ścieżkę workspace’u jako pierwszy argument: npx nx-mcp@0.25.0 /path/to/workspace.
• Analiza wpływu wymienia pakiety, których już nie ma. Graf jest w cache. Uruchom npx nx reset, które czyści cache i zatrzymuje demona Nx (wystartuje przy następnym poleceniu), a potem poproś agenta, żeby ponownie odczytał graf.
• Zmienił się współdzielony pakiet, a zależne nie. Nic nie powiedziało agentowi, że zmiana ma skutki kaskadowe. Dodaj do pliku reguł zasadę kolejności budowania i filtr ...@company/core, a bramkę affected ustaw jako wymagany check w CI.
• Testy przechodzą lokalnie, a padają w CI w pakietach zależnych. Pakiety zależne testowano na nieaktualnych buildach ich zależności. Przebuduj cały zbiór affected (nx affected albo turbo run --affected), a nie tylko edytowany pakiet.
• Agent dodał cykliczną zależność, żeby coś się skompilowało. Reguła była opisem, a nie zakazem, i lint jej nie wymuszał. Przepisz regułę jako „MUST NOT”, dodaj regułę lintera dla granic i odrzuć zmianę.
• Codex ignoruje AGENTS.md. Od Codex CLI 0.150.0 niezaufane projekty nie dostarczają instrukcji z projektowego AGENTS.md. Oznacz workspace jako zaufany, gdy Codex o to zapyta, i zacznij nową sesję.
• Agent wymyśla eksporty przy bardzo dużej zmianie. Graf razem z zadaniem przepełnił jego kontekst. Podziel pracę na jedną warstwę na turę i zawęź nx affected przez --base.
• nx configure-ai-agents zmieniło więcej, niż się spodziewałeś. Potrafi włączyć marketplace pluginów Claude Code, tryb wieloagentowy Codeksa i wyjątki sandboxa. Przejrzyj .claude/settings.json i .codex/config.toml w diffie tak jak każdą inną zmianę zależności.

Dokąd dalej z pracą w monorepo

Duże bazy kodu

Strategie kontekstu dla repozytoriów zbyt dużych na jedno okno. Zobacz pracę z dużymi bazami kodu.

Funkcje dopasowania

Zamień reguły warstw w kontrole CI, z którymi agent nie wygra dyskusji. Zobacz architektoniczne funkcje dopasowania.

Mikrousługi

To samo podejście oparte na grafie na granicach usług. Zobacz przepływy pracy z mikrousługami.

Pipeline’y CI/CD

Podłącz bramkę affected i krok wydania do CI. Zobacz automatyzację pipeline’ów z AI.

Repozytorium gotowe dla agentów

Pliki reguł, polecenia i kontrole, które ułatwiają agentom pracę w każdym repozytorium. Zobacz, jak przygotować repozytorium dla agentów.