Strategie dla dużych baz kodu w Cursorze

Poziom 2 Poradnik Zaktualizowano 2026-10-12

Strategia dla dużej bazy kodu w Cursorze zawęża to, co widzi agent, do wycinka, którego dotyczy zadanie: otwiera się pakiet zamiast korzenia monorepo, .cursorignore odcina śledzony szum, konwencje ładują się przez reguły z globami, a zmiany między pakietami dzieli się na zaplanowane kroki. Każdy krok kończy kontrola zakresu, licznik pozostałości starego wzorca i testy pakietów zależnych.

Ta strona jest dla deweloperów i tech leadów pracujących w repozytorium powyżej mniej więcej 100 000 linii, zwykle w monorepo w TypeScripcie. Prosisz agenta o endpoint preferencji powiadomień, a on pisze nowy serwis od zera, zamiast użyć tego, który leży trzy katalogi niżej. Kopiuje wzorzec z packages/legacy-billing/, którego nikt nie ruszał od dwóch lat. W połowie zmiany nazwy zapomina, które pakiety już skończył. To nie jest błąd Cursora. Agent czyta wycinek repozytorium, a w dużym repozytorium domyślny wycinek jest zły.

Co zyskujesz, zawężając Cursora do dużej bazy kodu

Sposób otwierania dużego repozytorium, dzięki któremu wyszukiwanie agenta zaczyna się we właściwym pakiecie.
.cursorignore wymierzony w pliki, których .gitignore jeszcze nie obejmuje.
Regułę-mapę w korzeniu, reguły pakietów z globami i streszczenia modułów, które mówią agentowi to, czego nie pokazuje kod.
Cztery prompty do skopiowania: mapa obszaru, plan zmiany między pakietami, wykonanie jednego kroku i audyt nieaktualnych reguł.
Bramkę verify-change.sh, która sprawdza, czy zmiana nie wyszła poza zakres, czy jest kompletna i czy pakiety zależne nadal działają, bez czytania zmiany linia po linii.

Dlaczego agent Cursora działa gorzej, gdy repozytorium rośnie?

Agent odpowiada na podstawie tego, co przeczytał, a czyta ułamek repozytorium. W dużej bazie kodu psują się trzy rzeczy i każda ma własne lekarstwo.

Objaw	Przyczyna	Lekarstwo na tej stronie
Kopiuje wycofany moduł, cytuje kod generowany	Wyszukiwanie najpierw trafia na złe pliki	Otwórz pakiet i odfiltruj śledzony szum
Pisze nową funkcję pomocniczą zamiast użyć twojej	Konwencje żyją w głowach ludzi, nie w kodzie	Reguły z zakresem i streszczenia modułów
Zapomina wcześniejsze decyzje, powtarza pracę	Jeden czat niesie za dużo historii	Zaplanowane kroki, każdy w osobnym czacie

Większe okno kontekstu nie usuwa żadnej z tych przyczyn. Więcej miejsca pozwala agentowi zmieścić więcej złych plików. To, które pliki dołączać, a kiedy pozwolić agentowi szukać samemu, opisuje zarządzanie kontekstem w Cursorze; ta strona przenosi te nawyki na repozytoria, które nie mieszczą się w żadnym oknie kontekstu.

Otwieraj pakiet, w którym pracujesz, nie korzeń monorepo

To, gdzie otworzysz Cursora, decyduje, gdzie zaczyna się wyszukiwanie agenta i które reguły się ładują. Mechanizm ładowania reguł w @cursor/sdk 1.0.32 zawsze czyta .cursor/rules/ w otwartym katalogu i w każdym katalogu nad nim. Otwarcie packages/api/ ładuje więc reguły samego pakietu API i reguły z korzenia repozytorium, a wyszukiwanie startuje wśród plików API.

Przy pracy w jednym pakiecie otwórz jako folder katalog tego pakietu.
Przy pracy obejmującej dwa lub trzy pakiety utwórz w korzeniu repozytorium plik workspace’u wielofolderowego i otwórz go zamiast folderu głównego. Cursor jako fork VS Code otwiera wielofolderowe pliki .code-workspace z VS Code; potwierdź to w swojej wersji:
```
// api-web.code-workspace
{
  "folders": [
    { "path": "packages/api", "name": "api" },
    { "path": "packages/web", "name": "web" },
    { "path": "packages/shared", "name": "shared" }
  ]
}
```
Commituj pliki workspace’ów, których zespół używa wielokrotnie, po jednym na częste zestawienie, i nazywaj je od zadania (api-web.code-workspace, nie workspace2.code-workspace).
Cały korzeń otwieraj tylko przy zadaniach z natury przekrojowych, jak zmiana nazwy w całym repozytorium, i łącz je z planem z sekcji Wprowadzaj zmianę między pakietami w zaplanowanych krokach.

Przy osobnych repozytoriach, a nie pakietach jednego repo, ta sama idea rozszerza się na reguły kontraktów i przepływ „najpierw kontrakt”; zobacz pracę z wieloma repozytoriami w Cursorze.

Odetnij śledzony szum od wyszukiwania agenta przez `.cursorignore`

Agent Cursora, przechodząc po workspace’ie, czyta zarówno .gitignore, jak i .cursorignore, a oba pliki mają tę samą składnię (sprawdzone w @cursor/sdk 1.0.32). Wszystko, co już jest w .gitignore, na przykład node_modules/ czy dist/, jest wykluczone bez drugiego wpisu. .cursorignore służy plikom, które są zacommitowane, ale których agent nigdy nie powinien kopiować:

# .cursorignore: zacommitowane pliki, których agent nie może czytać ani naśladować

# Kod generowany trzymany w repozytorium
packages/api/src/generated/
packages/web/src/__generated__/
*.generated.ts

# Wycofane moduły, trzymane tylko do końca migracji
packages/legacy-billing/

# Kod zewnętrzny wkopiowany do repo i duże fixture'y
vendor/
packages/api/test/fixtures/large/

# Lockfile'y i zminifikowane bundle
pnpm-lock.yaml
*.min.js

Dwie zasady utrzymują ten plik w dobrej formie. Nigdy nie wykluczaj żywego kodu, testów ani konfiguracji, bo agent potrzebuje ich, żeby trzymać się twoich wzorców. Wpis dla wycofanego modułu traktuj jako tymczasowy: usuń go, gdy moduł zniknie, bo inaczej agent nie pomoże w migracji, która go usuwa. Ścieżka zablokowana w ten sposób kończy się błędem wskazującym .cursorignore, gdy agent próbuje ją przeczytać, więc błędny wpis łatwo zauważyć.

Jak zmierzyć wpływ zmiany w pliku ignorowania na indeksowanie i szybkość wyszukiwania, z liczbami przed i po, pokazuje strojenie Cursora pod duże repozytoria. Zastosowanie tego samego pliku do bezpieczeństwa opisuje strona o prywatności i bezpieczeństwie Cursora w zespole.

Zapisz w regułach to, czego nie pokazuje kod

Nowa osoba w zespole potrzebuje mapy i kilku zasad obowiązujących w zespole, zanim dotknie repozytorium na 300 000 linii. Agent też. Reguły projektu to pliki .mdc w .cursor/rules/. Zwykły plik .md w tym katalogu mechanizm ładowania reguł pomija (sprawdzone w @cursor/sdk 1.0.32), więc nic nie sygnalizuje błędu; dokumentacja Cursora mówi to samo (sprawdzone 2026-10-12). Dużą bazę kodu pokrywają trzy warstwy.

1. Jedna krótka, zawsze aktywna mapa w korzeniu. Tylko to, czego potrzebuje każde zadanie: gdzie co leży, co jest wycofane i jakie są polecenia bramek.

---
description: Repository map and gates for the acme monorepo
alwaysApply: true
---

- pnpm monorepo. Live packages: packages/api (Fastify), packages/web (Next.js),
  packages/shared (types only, no runtime code).
- packages/legacy-billing is deprecated. Never import from it or copy its patterns;
  the replacement is packages/api/src/billing.
- Before reporting a task done, run for each package you touched:
  pnpm --filter <package> run typecheck && pnpm --filter <package> test

2. Reguły pakietów z globami. Reguła z globs ładuje się, gdy w kontekście jest pasujący plik, więc konwencje API nigdy nie trafiają do pracy nad frontendem. Umieść ją w pakiecie, którego dotyczy, na przykład packages/api/.cursor/rules/api-conventions.mdc, a glob zapisz względem korzenia pakietu, czyli folderu, który otwierasz. Sprawdź, czy pasuje, procedurą próbną z poradnika o własnych regułach:

---
description: HTTP handler conventions for packages/api
globs: src/**/*.ts
alwaysApply: false
---

- Handlers call services; services call repositories. No SQL in handlers.
- Validate input with the Zod schemas in packages/api/src/schemas/.
- Errors use AppError from packages/api/src/errors.ts, never a bare throw.
- Canonical example: packages/api/src/routes/users/index.ts

3. Plik streszczenia dla każdego dużego modułu. Dla modułu zbyt dużego, żeby go dołączyć, jednostronicowy ARCHITECTURE.md daje agentowi mapę za ułamek tokenów. Odwołaj się do niego w regule modułu, żeby agent przeczytał go przed otwieraniem pojedynczych plików:

# Payments
- service.ts: checkout and refunds (Stripe). repository.ts: Drizzle queries.
- webhook.ts: verifies the signature, then updates status via repository.ts.
- Invariants: amounts are integer cents; every Stripe call sends an idempotency key.

Gdy zamiast pakietu otworzysz korzeń monorepo, mechanizm ładowania sięga po reguły zagnieżdżone w packages/*/.cursor/rules/ tylko przy włączonym wykrywaniu reguł zagnieżdżonych (w @cursor/sdk 1.0.32 jest ono domyślnie włączone), a glob liczony od korzenia pakietu może nie pasować z korzenia repozytorium. To, które reguły się ładują, sprawdź procedurą próbną z poradnika o regułach, zamiast zakładać. Tryby ładowania, szablony i test CI, który zawodzi, gdy glob nie pasuje do żadnego pliku, opisuje strona własne reguły i szablony w Cursorze. Jeśli piszesz pierwszą regułę, zacznij od reguł projektu.

AGENTS.md i CLAUDE.md w monorepo. Dokumentacja Cursora (sprawdzone 2026-10-12) podaje, że Cursor obsługuje AGENTS.md w korzeniu projektu i w podkatalogach. Pliki zagnieżdżone są łączone z plikami z katalogów nadrzędnych, a pierwszeństwo mają instrukcje bardziej szczegółowe, więc AGENTS.md w packages/api/ uzupełnia plik z korzenia repozytorium i wygrywa tam, gdzie oba się różnią. Według pomocy Cursora Cursor czyta pliki CLAUDE.md tak samo jak AGENTS.md i stosuje je zawsze, w każdej rozmowie, niezależnie od ustawienia alwaysApply we frontmatterze (sprawdzone 2026-10-12). W Cursorze 3.21 (2026-09-17) reguły zespołu ze wzorcami plików obowiązują tylko dla pasujących plików.

Zmapuj nieznany obszar, zanim go zmienisz

Przed pierwszą edycją w kodzie, którego nie pisałeś, poproś o mapę tylko do odczytu, ze ścieżkami plików. Mapa staje się kontekstem następnego czatu, a jej lista plików staje się zakresem, z którym porównasz zmianę.

Read-only task: do not edit any file.

Map how POST /api/orders is handled in packages/api. Start at the route
registration and follow the call chain through middleware, handler,
service, repository and any queue or webhook it triggers.

Reply with:
1. A numbered call chain, one line per step: file path, function, what it does.
2. Error paths: what happens on validation failure, database error, and
   payment provider rejection, with the file that handles each.
3. Anything resolved indirectly (string-registered routes, dependency
   injection, event names) that a text search would miss.
4. Files under packages/legacy-billing/ that are still on the live path.
   Say "none" if there are none.

Sprawdź odpowiedź w kodzie dwiema lub trzema próbkami: otwórz wskazane pliki we wskazanych liniach. Mapa z błędną ścieżką pliku oznacza, że agent zgadywał, a lekarstwem jest węższe pytanie, nie dłuższe.

Wprowadzaj zmianę między pakietami w zaplanowanych krokach

Zmiana obejmująca kilka pakietów zawodzi, gdy jeden czat próbuje zrobić wszystko naraz. Zaplanuj ją raz, zapisz plan do pliku i wykonuj po jednym pakiecie na czat, z bramką po każdym kroku.

Przełącz agenta w Plan Mode, który tworzy plan implementacji przed napisaniem kodu, i poproś o plik planu. Przeglądasz plan, nie kod: lista wywołań i kolejność kroków to miejsca, gdzie błędy kosztują najmniej.

Plan, do not implement. Goal: add organizationId (string, required) to
the User type and carry it through the API and the web user form.

Write the plan to docs/plans/user-organization-id.md with:
- Every file to change, grouped by package, in dependency order:
  packages/shared first, then packages/api, then packages/web.
- Every caller of the User type outside those files, found with a
  text search and the language server, and whether it needs a change.
- The database migration, and how existing rows get a value.
- For each step: the command that proves it, using
  pnpm --filter <package> run typecheck and pnpm --filter <package> test.
- Files you will not touch, including anything in packages/legacy-billing/.

Wykonuj jeden krok na czat. Nowy czat dla każdego pakietu trzyma wcześniejsze próby poza kontekstem, a plik planu przenosi decyzje dalej.

Read @docs/plans/user-organization-id.md. Execute only the first step
that is not marked done.

Change only the files that step lists. If you need to change any other
file, stop and tell me which file and why.

When the edits are finished, run the step's gate commands and show their
output. If a gate fails, fix it within the same files. Then mark the step
done in the plan file with the commit-ready summary: files changed and
the gate result.

Commituj po każdym zielonym kroku. Mały commit to jednostka, którą możesz cofnąć, a następny czat startuje ze sprawdzonego stanu drzewa.
Przy długich migracjach obejmujących wiele pakietów uruchamiaj niezależne kroki równolegle w osobnych worktree albo przekaż je agentom w chmurze (Cloud Agents); zobacz Cloud Agents i automatyzacje.

To, czy agent uruchamia polecenia bramek bez pytania, zależy od trybu uruchamiania (run mode). Skonfiguruj tryby uruchamiania i sandbox tak, jak opisuje strona o prywatności i bezpieczeństwie Cursora w zespole, zamiast zatwierdzać każde polecenie ręcznie.

Jak zweryfikować zmianę w dużej bazie kodu bez czytania każdego diffa?

Udowodnij mechanicznie trzy rzeczy, a uwagę człowieka przeznacz na plan i na to, co wskażą kontrole.

Pytanie	Kontrola	Zaliczona, gdy…
Czy zmiana została w zakresie?	`git diff --name-only` porównany z listą plików z planu	Każdy zmieniony plik jest w planie albo ma podany powód
Czy jest kompletna?	Licznik starego wzorca z `rg`	Licznik wynosi 0
Czy każdy konsument nadal działa?	Typecheck i testy zmienionych pakietów i pakietów od nich zależnych	Wszystkie na zielono

#!/usr/bin/env bash
# verify-change.sh: uruchom w terminalu w korzeniu repozytorium po ostatnim kroku
set -euo pipefail
base=origin/main

echo "== Files changed (compare with docs/plans/user-organization-id.md)"
git diff --name-only "$base"...HEAD

echo "== Files changed outside the allowed packages (must be empty)"
outside=$(git diff --name-only "$base"...HEAD \
  | grep -v -E '^(packages/(shared|api|web)/|docs/plans/)' || true)
echo "$outside"
test -z "$outside"

echo "== Imports from the deprecated module (must be 0)"
count=$( { rg -n "from ['\"].*legacy-billing" packages/ --type ts --glob '!packages/legacy-billing/**' || true; } | wc -l)
echo "$count"
test "$count" -eq 0

echo "== Typecheck and test every changed package and its dependents"
pnpm --filter "...[$base]" run typecheck
pnpm --filter "...[$base]" test

Filtr ...[origin/main] wybiera pakiety zmienione od origin/main oraz każdy pakiet, który od nich zależy, bo właśnie tam psuje się zmiana współdzielonego typu. Nx (nx affected -t typecheck test) i Turborepo (turbo run typecheck test --filter=...[origin/main]) robią to samo w swoich repozytoriach. Wzorzec w rg zamień na to, co zmiana usuwa: starą nazwę funkcji, pozycyjny styl wywołań, wycofany import.

Uruchamiaj ten sam skrypt w CI, żeby bramka nie zależała od czyjejś pamięci. Potem niech Bugbot przejrzy pull request pod kątem poprawności, a CODEOWNERS skieruje go do właścicieli pakietów, żeby każdy zatwierdził swój wycinek. Właściciel czyta plan i wynik bramek dla swojego pakietu, nie każdą linię. Szerszą konfigurację przeglądu opisuje code review z Cursorem.

Jak utrzymać celność długich sesji w dużym repozytorium

Jedno zadanie na czat. Zacznij nowy czat, gdy krok jest zacommitowany, gdy przechodzisz do innego pakietu albo gdy agent powtarza błąd, który już poprawiłeś. Stan przenoś w pliku planu albo w krótkiej notatce przekazania, jak w zarządzaniu kontekstem w Cursorze.
Dołączaj jeden kanoniczny przykład, nie folder. @packages/api/src/routes/users/index.ts kosztuje kilka tysięcy tokenów; wzmianka o całym packages/api/src/ może zapełnić okno, zanim agent zacznie pracę. Jak zmierzyć różnicę, pokazuje zarządzanie tokenami w Cursorze.
Trzymaj reguły w zgodzie z kodem. Reguła opisująca zeszłoroczną architekturę wprowadza agenta w błąd w każdym czacie, do którego się załaduje. Audytuj reguły po dużych refaktoryzacjach.

Read-only task: do not edit any file.

For each .mdc file under .cursor/rules/ and packages/*/.cursor/rules/:
1. List every file path, function or package it names, and whether that
   still exists.
2. Quote each instruction that the current code contradicts, and name the
   file that contradicts it.
3. Flag any glob that matches no file in the repository.
Propose a corrected line for each problem. Output a table.

Co psuje się w dużej bazie kodu w Cursorze i jak z tego wyjść

Agent kopiuje wycofany albo generowany moduł

Wyszukiwanie najpierw trafiło na stary moduł. Jak naprawić: przywróć checkpoint sprzed edycji (zobacz checkpointy i rozgałęzianie), dodaj ścieżkę do .cursorignore albo oznacz ją jako wycofaną w regule w korzeniu i powtórz krok w nowym czacie.

Agent pisze nową funkcję pomocniczą zamiast użyć istniejącej

Konwencja istnieje tylko w głowach ludzi. Jak naprawić: dodaj kanoniczny plik do reguły pakietu z globem i powtórz krok z tym plikiem dołączonym. Jeśli zdarzy się to dwa razy przy tej samej funkcji pomocniczej, dodaj regułę lintera zakazującą duplikatu; linter zatrzymuje CI, reguła tylko prosi.

Agent edytuje plik o podobnej nazwie w innym pakiecie

packages/web/src/user.ts i packages/api/src/user.ts wyglądają dla wyszukiwania tak samo. Jak naprawić: otwieraj pakiet albo jego workspace zamiast korzenia, pisz w prompcie pełne ścieżki i pozwól, żeby kontrola zakresu w verify-change.sh wyłapała zabłąkany plik.

Indeksowanie się nie kończy albo wyszukiwanie jest wolne

W śledzonym katalogu leży duży plik generowany lub binarny. Jak naprawić: znajdź go poleceniem git ls-files -z | xargs -0 du -k | sort -rn | head -20, dodaj do .cursorignore i przejdź kroki pomiaru ze strojenia Cursora pod duże repozytoria.

Reguła pakietu nigdy się nie ładuje

Plik zapisano jako .md zamiast .mdc albo jego glob nie pasuje do niczego. Jak naprawić: zmień rozszerzenie, przetestuj glob na wyniku git ls-files i dodaj test CI z własnych reguł i szablonów w Cursorze.

Agent gubi wątek w połowie zmiany

Czat niesie zbyt wiele prób. Jak naprawić: zatrzymaj się, upewnij, że plik planu oznacza wykonane kroki, zacommituj to, co przeszło bramkę, i kontynuuj od pierwszego niedokończonego kroku w nowym czacie.

Jak z dużymi repozytoriami radzą sobie Claude Code i Codex

Zasady zawężania są wspólne dla narzędzi, konfiguracja już nie. Claude Code zawęża pracę katalogiem startowym, zagnieżdżonymi plikami CLAUDE.md i regułami odmowy; opisuje to strona duże bazy kodu i monorepo w Claude Code. Codex utrzymuje długie sesje na kursie dzięki plikom AGENTS.md i plikom przekazania; opisuje to zarządzanie kontekstem we wszystkich interfejsach Codeksa. Strategię wspólną dla narzędzi znajdziesz w strategiach dla baz kodu z milionami linii i w pracy z monorepo z asystentami AI.

Dokąd dalej z dużymi bazami kodu w Cursorze

Przed tą stroną: zarządzanie kontekstem w Cursorze, czyli nawyki „dołączyć czy pozwolić szukać”, na których opiera się ta strona.
Dalej: strategie refaktoryzacji w Cursorze dla zmian nazw i przebudowy, w której każdy krok jest weryfikowany przed następnym, oraz refaktoryzacja kodu legacy dla kodu bez testów.
Między repozytoriami: praca z wieloma repozytoriami w Cursorze.
Wybór modelu do długiej pracy między pakietami: wybór modelu w Cursorze.