Praca z wieloma repozytoriami

Twój zespół ma bramkę API, trzy serwisy backendowe, bibliotekę współdzieloną i dwie aplikacje frontendowe — każde w osobnym repozytorium. Musisz dodać nowe pole do profilu użytkownika. Oznacza to aktualizację biblioteki typów współdzielonych, API serwisu użytkowników, schematu bramki i obu aplikacji frontendowych. Otwierasz Cursora w repozytorium serwisu użytkowników, a agent nie ma wglądu w bibliotekę współdzieloną ani bramkę. Każdy prompt wymaga ręcznego wyjaśniania, co istnieje w innych repozytoriach.

Praca z wieloma repozytoriami przy użyciu narzędzi AI wymaga konkretnych strategii, aby wypełnić lukę między repozytoriami, których agent nie może widzieć jednocześnie.

Czego się nauczysz

• Techniki przekazywania Cursorowi kontekstu o kodzie znajdującym się w innych repozytoriach
• Podejście oparte na regułach do kodyfikowania zależności i kontraktów między repozytoriami
• Wzorce workflow do koordynowania zmian w wielu serwisach
• Strategie dla monorepo versus polyrepo w programowaniu wspomaganym AI

Problem kontekstu między repozytoriami

Cursor indeksuje i przeszukuje repozytorium, które jest aktualnie otwarte. Nie ma natywnej świadomości siostrzanych repozytoriów. Gdy kontrakt API jest zdefiniowany w jednym repozytorium i konsumowany w innym, agent pracujący w repozytorium konsumenta nie widzi definicji kontraktu.

Istnieje kilka praktycznych podejść do rozwiązania tego problemu.

Strategia 1: Workspace z wieloma folderami głównymi

VS Code (i Cursor) wspiera workspace z wieloma folderami głównymi, gdzie otwierasz kilka folderów jako jeden workspace. Daje to agentowi wgląd we wszystkie uwzględnione repozytoria:

{
  "folders": [
    { "path": "./api-gateway" },
    { "path": "./user-service" },
    { "path": "./shared-types" },
    { "path": "./frontend-app" }
  ],
  "settings": {
    "search.exclude": {
      "**/node_modules": true,
      "**/dist": true
    }
  }
}

Zapisz to jako project.code-workspace w katalogu głównym projektu. Otwórz za pomocą File > Open Workspace from File.

Uwaga

Workspace z wieloma folderami głównymi zwiększają powierzchnię indeksowania. Jeśli masz cztery duże repozytoria, czas indeksowania i zużycie pamięci się mnożą. Używaj .cursorignore agresywnie w każdym repozytorium, aby wykluczyć artefakty budowania, wygenerowany kod i fixtury testowe.

Strategia 2: Reguły dokumentujące kontrakty między repozytoriami

Gdy workspace z wieloma folderami nie są praktyczne (zbyt wiele repozytoriów, zbyt dużo szumu), zakoduj informacje o kontraktach w regułach:

---
description: Cross-repo API contracts
alwaysApply: true
---

This service consumes the User API from the user-service repo.

User API contract (source of truth: user-service/src/routes/users.ts):
- GET /api/users/:id returns { id, email, firstName, lastName, role, createdAt }
- PATCH /api/users/:id accepts { firstName?, lastName?, email? }
- POST /api/users accepts { email, firstName, lastName, password }

Shared types (source of truth: shared-types/src/user.ts):
- UserResponse: { id: string, email: string, firstName: string, lastName: string, role: 'admin' | 'user', createdAt: string }
- CreateUserRequest: { email: string, firstName: string, lastName: string, password: string }
- UpdateUserRequest: Partial<Omit<CreateUserRequest, 'password'>>

When making changes that affect these contracts, flag it -- the corresponding services will need updates too.

Wskazówka

Reguła do skopiowania — dokumentacja kontraktów API:

Utwórz .cursor/rules/api-contracts.mdc:

---
description: External API dependencies this service consumes
alwaysApply: false
---

Payment Service API (payment-service repo):
- POST /api/payments/charge { amount: number, currency: string, customerId: string } -> { paymentId, status }
- GET /api/payments/:id -> { paymentId, amount, currency, status, createdAt }
- POST /api/payments/:id/refund { reason: string } -> { refundId, status }

Notification Service API (notification-service repo):
- POST /api/notifications/send { userId: string, type: 'email' | 'push', template: string, data: Record<string, string> } -> { notificationId }

When implementing features that call these APIs, use the httpClient from @src/lib/http-client.ts and handle timeout, retry, and circuit-breaker patterns as shown in @src/services/payment-client.ts.

Strategia 3: Kopiowanie plików kontraktów

Dla kluczowych typów współdzielonych utrzymuj lokalną kopię lub dowiązanie symboliczne w każdym repozytorium konsumenckim:

# In your consuming repo
mkdir -p .cursor/contracts
cp ../shared-types/src/user.ts .cursor/contracts/user-types.ts
cp ../api-gateway/schema.graphql .cursor/contracts/gateway-schema.graphql

Odwołuj się do nich w promptach za pomocą @.cursor/contracts/user-types.ts, aby dać agentowi dokładne informacje o typach z repozytorium źródłowego.

Koordynowanie zmian między repozytoriami

Workflow “kontrakt przede wszystkim”

Gdy zmiana obejmuje wiele repozytoriów, zacznij od wspólnego kontraktu:

1. Zaktualizuj definicję typów współdzielonych / kontraktu API w repozytorium źródłowym
2. Zatwierdź zmianę i (jeśli dotyczy) opublikuj zaktualizowany pakiet typów
3. W każdym repozytorium konsumenckim zaktualizuj zależność i dostosuj kod do nowego kontraktu
4. Uruchom testy w każdym repozytorium, aby zweryfikować kompatybilność

Wskazówka

Prompt do skopiowania — migracja między repozytoriami:

We are adding a `phoneNumber` field to the User type.

The shared types have already been updated (UserResponse now includes phoneNumber: string | null).

Update this service to:
1. Add a phone_number column to the users table (nullable, migration in src/db/migrations/)
2. Include phoneNumber in the GET /api/users/:id response
3. Accept phoneNumber in PATCH /api/users/:id
4. Update all tests to include the new field
5. Ensure backward compatibility -- existing clients that do not send phoneNumber should still work

Follow existing patterns in @src/routes/users.ts and @src/db/migrations/.

Wzorzec równoległego rozwoju

Dla dużych funkcji obejmujących wiele repozytoriów używaj osobnych okien Cursora dla każdego repozytorium. Zaplanuj zmianę w jednym oknie, a następnie wykonuj w każdym:

1. Okno planowania (dowolne repozytorium): Użyj trybu Ask do zaprojektowania zmiany przekrojowej
2. Okno serwisu A: Zaimplementuj zmiany po stronie serwisu
3. Okno serwisu B: Zaimplementuj zmiany po stronie konsumenta
4. Testy integracyjne: Uruchom testy end-to-end między serwisami

Kwestie monorepo

Jeśli używasz monorepo (Turborepo, Nx, pnpm workspaces), Cursor ma natywny wgląd we wszystkie pakiety. Upraszcza to pracę wieloserwisową, ale wprowadza szum. Używaj reguł o zakresie folderowym, aby utrzymać skupienie agenta:

---
globs: "packages/api/**/*.ts"
---

This is the API package. It depends on:
- packages/shared-types for TypeScript interfaces
- packages/db for database queries via Drizzle ORM

API routes are in packages/api/src/routes/. Follow the pattern in users.ts for new routes.
Do not modify packages outside of packages/api/ unless explicitly asked.

Kiedy coś nie działa

Agent sugeruje zmiany w złym repozytorium w workspace z wieloma folderami. Dodaj reguły ograniczające granice każdego serwisu. Powiedz agentowi wyraźnie, które katalogi powinien modyfikować.

Dokumentacja kontraktów w regułach staje się przestarzała. Zautomatyzuj kopiowanie plików kontraktów jako część CI lub hooka pre-commit. Lub użyj schematów OpenAPI/GraphQL jako źródła prawdy i odwołuj się do nich bezpośrednio.

Agent nie rozumie granic serwisów. Twoje reguły muszą wyjaśniać architekturę. Krótki opis tego, który serwis jest właścicielem której domeny i jak komunikują się między sobą, robi ogromną różnicę.

Co dalej

• Strategie dla dużych baz kodu — Indeksowanie i wydajność specyficzne dla monorepo
• Współpraca zespołowa — Udostępnianie reguł między repozytoriami w zespole
• Niestandardowe reguły i szablony — Budowanie reguł dokumentacji kontraktów