Przepływy pracy monorepo z AI

Zmieniłeś nazwę współdzielonego typu w pakiecie core swojego monorepo. Siedem pakietów downstream ma teraz zepsute buildy, dwa z nich mają testy integracyjne, które przechodzą lokalnie, ale padają w CI, bo zależą od pakietu, który nie został jeszcze przebudowany. Narzędzie AI, którego użyłeś, patrzyło tylko na plik, który edytowałeś — nie miało pojęcia o efekcie kaskadowym w całym workspace.

Co wyniesiesz z tego rozdziału

• Strategie promptowania świadome monorepo uwzględniające zależności cross-pakietowe
• Przepływy pracy dla skoordynowanych zmian wielopakietowych z pomocą AI
• Techniki analizy grafów zależności i oceny wpływu sterowane AI
• Zautomatyzowane wzorce koordynacji wydań z wykorzystaniem narzędzi AI
• Strategie dla współdzielonej konfiguracji i egzekwowania konwencji

Wyzwanie kontekstowe monorepo

Monorepo wzmacniają problem kontekstu. Zmiana we współdzielonej utilce może dotknąć 15 pakietów. AI musi rozumieć nie tylko plik, który edytujesz, ale cały łańcuch zależności.

Uczenie narzędzi AI struktury twojego monorepo

Cursor

Ustrukturyzuj swój .cursor/rules, aby zakodować graf monorepo:

# .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 cross-pakietowymi, jawnie odwołuj się do łańcucha zależności: @packages/core/src/types @packages/ui/src/components @apps/web/src/pages

Claude Code

Użyj hierarchii CLAUDE.md do stworzenia kontekstu świadomego monorepo:

# /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 --filter=...affected` after cross-package changes.

# /packages/core/CLAUDE.md
Foundation package. Changes here cascade everywhere.
After ANY modification: run `pnpm turbo build --filter=...dependents`
to verify downstream compatibility.
Exports must be backward-compatible. Use deprecation notices, not breaking changes.

# /packages/ui/CLAUDE.md
React 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.

Sub-agenty Claude Code mogą zrównoleglić analizę w pakietach.

Codex

Zadania chmurowe Codex naturalnie obsługują zakres monorepo:

codex.md

Monorepo with Turborepo + pnpm workspaces.
Before making cross-package changes:
1. Run: pnpm turbo build --dry-run --filter=...affected to preview impact
2. Identify all packages in the dependency chain
3. Make changes starting from the lowest dependency (core) upward
4. Run tests after each package modification

After all changes: pnpm turbo build && pnpm turbo test

Użyj worktrees Codex do pracy na wielu pakietach jednocześnie bez konfliktów Git.

Przepływy pracy refaktoryzacji cross-pakietowej

Wzorzec kaskadowy

Modyfikując współdzielony kod, pracuj od dołu drzewa zależności w górę.

1. Analizuj wpływ

   Zanim dotkniesz jakiegokolwiek kodu, zrozum co się zepsuje.

2. Modyfikuj pakiet źródłowy

   Zmień współdzielony typ, utilkę lub komponent w pakiecie bazowym.

3. Zbuduj pakiet źródłowy

   Zweryfikuj, że pakiet źródłowy kompiluje się poprawnie w izolacji.

4. Aktualizuj bezpośrednich dependentów

   Przesuń się o jeden poziom w górę drzewa zależności. Zaktualizuj każdego bezpośredniego dependenta.

5. Zbuduj i przetestuj każdego dependenta

   Zweryfikuj, że każdy dependent kompiluje się i jego testy przechodzą przed przejściem dalej w górę.

6. Kontynuuj w górę drzewa

   Powtarzaj, aż dotrzesz do aplikacji liściowych.

7. Uruchom pełny pipeline

   Wykonaj kompletny build i pełny zestaw testów, aby wyłapać wszelkie problemy.

Wskazówka

Gotowy prompt do refaktoryzacji cross-pakietowej:

I need to rename the `UserProfile` type to `UserAccount` across our monorepo.
The type is defined in /packages/core/src/types/user.ts.

Follow this exact sequence:
1. Find every file across ALL packages that imports or references UserProfile
2. Show me the complete list before making any changes
3. Update /packages/core first - rename the type and update the barrel export
4. Update /packages/ui - fix all component props and imports
5. Update /packages/api-client - fix all SDK methods and response types
6. Update each app (web, api, admin) one at a time
7. After each package, run its build to verify: pnpm turbo build --filter={package}

Stop after step 2 so I can review the impact before you proceed.

Zarządzanie współdzieloną konfiguracją

Narzędzia AI mogą pomagać utrzymywać spójność w pakietach monorepo.

Wskazówka

Gotowy prompt do audytu spójności monorepo:

Audit our monorepo for configuration drift:
1. Compare tsconfig.json across all packages - flag any that don't extend tsconfig.base.json
2. Check that all packages use the same version of shared dependencies (React, TypeScript, etc.)
3. Verify each package has the required scripts: build, test, lint, type-check
4. Ensure ESLint configs are consistent across packages
5. Check that no package has a direct dependency that should come from the root

Present findings as a table: Package | Issue | Severity | Fix

Analiza grafów zależności

Zrozumienie twojego grafu zależności jest kluczowe dla bezpiecznych zmian. Narzędzia AI mogą generować i analizować te grafy.

Cursor

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 Code

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 dependencies
2. Violation of the layering rule (apps must not depend on other apps)
3. Version mismatches for shared deps
4. Packages that could be merged (similar purpose, small surface)
Output the graph and any issues found."

Codex

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.

Koordynacja wydań

Skoordynowane podbijanie wersji

Gdy zmiana obejmuje wiele pakietów, podbijanie wersji musi podążać za kolejnością zależności.

Wskazówka

Gotowy prompt do koordynacji wydań:

I've made changes to packages/core and packages/ui. Help me prepare a release:
1. Determine the semver bump type for each package based on the changes:
   - Breaking changes to public API = major
   - New features = minor
   - Bug fixes = patch
2. Check which downstream packages need version bumps in their dependencies
3. Generate changelog entries for each affected package from the git commits
4. Create the version bump commands in the correct order
5. List the packages and versions that will be published

Show me the plan before executing anything.

Kiedy coś się psuje

“AI zmodyfikowało współdzielony pakiet bez aktualizacji dependentów.” Twój plik reguł nie koduje grafu zależności. Dodaj jawne łańcuchy zależności i wymagania kolejności budowania do swojego .cursor/rules lub CLAUDE.md.

“Build przechodzi lokalnie, ale pada w CI dla pakietów downstream.” Prawdopodobnie testowałeś z nieaktualnymi buildami zależności. Zawsze uruchamiaj turbo build --filter=...affected (lub odpowiednik), aby przebudować cały dotknięty łańcuch.

“AI stworzyło cykliczne zależności między pakietami.” Dodaj jawne reguły warstw do swojej konfiguracji AI: “packages/core MUST NOT import from packages/ui or any app.” Narzędzia AI dobrze przestrzegają ograniczeń, gdy są jasno sformułowane.

“Podbijanie wersji jest niespójne w pakietach.” Użyj changesets lub podobnego narzędzia do zarządzania wersjami. Naucz AI swojego procesu wersjonowania przez pliki reguł, zamiast polegać na ad-hoc promptowaniu.

Co dalej

Duże bazy kodu Strategie zarządzania kontekstem dla repozytoriów z milionami linii.

Pipeline'y CI/CD Buduj i wdrażaj pakiety monorepo z pipeline'ami CI zoptymalizowanymi pod AI.

Bramki jakości kodu Egzekwuj standardy jakości spójnie we wszystkich pakietach.