Zarządzanie kontekstem w Cursorze

Zarządzanie kontekstem w Cursorze to wybór tego, co agent widzi, zanim napisze kod: plików, folderów, zaznaczeń kodu, zindeksowanej dokumentacji, wcześniejszych czatów i reguł, dołączanych wzmiankami @ albo znajdowanych przez samego agenta. Jeden wzorcowy plik zwykle wygrywa z długim opisem, a nadmiar załączników pogarsza wynik, zamiast go poprawiać.

Prosisz agenta o paginację w GET /api/users. Agent pisze od zera nowy helper do paginacji, pomija ten z src/utils/pagination.ts i używa offset/limit, choć projekt kilka miesięcy temu przeszedł na paginację kursorową. Model działa poprawnie. Po prostu nigdy nie zobaczył helpera i nikt mu nie powiedział, który wzorzec obowiązuje.

Ta strona jest dla programisty, który od kilku tygodni pracuje z Cursorem i chce, żeby agent trzymał się istniejących wzorców projektu, zamiast wymyślać nowe. W ścieżce szybkiego startu wypada po konfiguracji MCP w Cursorze, a przed pierwszą funkcją.

Co zyskujesz, zarządzając kontekstem Cursora

• Tabelę rodzajów kontekstu, które przyjmuje agent Cursora, z informacją, kiedy każdy się opłaca.
• Cztery prompty do skopiowania: wzorzec do naśladowania, granice zmiany, aktualna dokumentacja biblioteki i czyste przekazanie pracy między czatami.
• Stałą kolejność dodawania kontekstu, dzięki której dołączasz tylko to, czego brak widać w wyniku.
• Prompt „pokwitowania kontekstu” i trzy sprawdzenia w terminalu, które pokazują, czy agent użył właściwego kodu i nie wyszedł poza granice, bez czytania każdej linii diffu.
• Tabelę trybów awarii z procedurą naprawczą dla każdego objawu.

Jaki kontekst możesz dać agentowi Cursora?

Wpisz @ w polu agenta, żeby otworzyć menu kontekstu, i zawęź listę, pisząc dalej, żeby znaleźć element do dołączenia. Etykiety w menu zmieniały się między wydaniami Cursora, więc ufaj temu, co widzisz na ekranie, a nie zrzutom ekranu. Rodzaje kontekstu poniżej to te, które przenosi protokół agenta Cursora, sprawdzone w @cursor/sdk 1.0.32 w dniu 2026-09-26.

Rodzaj kontekstu	Co dostaje agent	Kiedy po niego sięgnąć
Plik	Wskazany plik	Jeden plik zawiera dokładnie ten wzorzec, który trzeba skopiować, albo to on ma się zmienić
Folder	Katalog, w którym agent pracuje	Agent potrzebuje układu i nazewnictwa obszaru, a nie treści każdego pliku
Zaznaczenie kodu	Wybrana funkcja, klasa lub blok	Liczy się jedna funkcja, a plik jest długi
Dokumentacja	Zindeksowane źródło dokumentacji	Zadanie zależy od biblioteki albo wewnętrznego API, które model zna najwyżej ze starych danych treningowych
Wcześniejszy czat	Poprzednia rozmowa	Wracasz do pracy, której decyzje zapadły w tamtym czacie
Wyjście terminala	Terminal albo zaznaczony fragment	Dowodem jest nieudany przebieg testów albo stack trace
Git i pull requesty	Commity, diffy i pull requesty	Zadanie brzmi „dokończ, przejrzyj albo wyjaśnij tę zmianę”
Reguły	Wybrana reguła	Konwencja ma obowiązywać w tym zapytaniu, choć jej reguła nie ładuje się automatycznie
Obrazy	Wklejony zrzut ekranu lub makieta	Błąd UI albo projekt łatwiej pokazać niż opisać

Reguły dodają kontekst także bez wzmianki: reguła ustawiona na „zawsze” ładuje się przy każdym zapytaniu. Utrzymuj takie reguły krótkie, a resztę przenieś do reguł przypisanych do plików, jak opisują reguły projektu w Cursorze. Każdy załącznik kosztuje tokeny w każdej turze czatu; rachunek omawia zarządzanie tokenami w Cursorze.

Wskaż jeden wzorcowy plik zamiast opisywać wzorzec

Opis konwencji zostawia pole do interpretacji. Plik, który już się ich trzyma, nie zostawia. Porównaj dwa prompty do tego samego zadania:

Weak: Create an orders endpoint. We use Express with auth middleware,
zod for validation and our own error format.

Strong: Create POST /api/orders following @src/routes/users.ts exactly:
same middleware order, same zod validation, same AppError handling,
same response shape.

Mocny prompt daje agentowi coś do skopiowania i coś, z czym można porównać wynik. Konwencje przekrojowe psują się tak samo: poproś o obsługę błędów bez kontekstu, a agent owinie handler w try/catch i zwróci { error: "Something went wrong" }, choć w kodzie jest już klasa AppError, centralne middleware obsługi błędów i format odpowiedzi z kodami błędów. Dołącz middleware i klasę, a agent będzie rzucał AppError jak każda inna trasa.

Wzorzec wybieraj świadomie: najnowszy plik zgodny z obecną konwencją, a nie najstarszy plik w katalogu. Jeśli dwa pliki sobie przeczą, agent może pójść za dowolnym z nich.

Prompt do skopiowania: trzymaj się wzorcowego pliku

Create src/services/notification-service.ts.

Pattern reference: @src/services/email-service.ts
Copy exactly: class structure, constructor dependency injection,
error handling with AppError from src/lib/errors.ts, and the test
file layout in tests/services/email-service.test.ts.
Change only the domain logic: notifications instead of emails.

Before writing code, list the three conventions from the reference
file you will follow. Then write the service and its test file.

Po wklejeniu promptu sprawdź, czy każde odwołanie @ pojawiło się jako dołączony element. Jeśli ścieżka została zwykłym tekstem, usuń ją, wpisz @ jeszcze raz i wybierz plik z menu.

Wzmianka o folderze, gdy agent potrzebuje mapy

Dołącz folder, gdy pytanie brzmi „gdzie to umieścić i jak to nazwać”, a nie „skopiuj tę funkcję”. Na przykład: Look at @src/components/ and add a NotificationBanner component that follows the same file layout, naming and story file as the existing components. Folder jest tańszy niż dołączenie każdego pliku z osobna, a agent sam otworzy te pliki, których potrzebuje.

Zaznaczenie kodu dla jednej funkcji

Dołącz samą funkcję jako zaznaczenie kodu, gdy reszta długiego pliku to szum: Refactor calculateDiscount (attached) to support percentage and fixed-amount discounts. Keep the signature. Dołączenie całego pliku też zadziała, ale kosztuje więcej tokenów i daje agentowi więcej miejsca na błędne odczytanie.

Kiedy dołączać kontekst, a kiedy pozwolić agentowi szukać?

Agent Cursora sam przeszukuje kod, czyta pliki i uruchamia polecenia. Dołączanie kontekstu usuwa zgadywanie, ale nie jest wymagane przy każdym zapytaniu.

Sytuacja	Dołącz sam	Pozwól agentowi szukać
Wiesz, który plik zawiera wzorzec	Tak, jeden plik	—
Wiesz, który plik się zmieni	Tak	—
Nie wiesz, gdzie jest kod	—	Tak, i poproś o raport z tego, co znalazł
Zadanie dotyka każdego wywołania funkcji	Dołącz funkcję	Niech znajdzie wywołania
Decyzja projektowa zapadła we wcześniejszym czacie	Dołącz ten czat albo notatkę przekazania	—
Zadanie jest szerokie i eksploracyjne	—	Tak, najpierw w Plan Mode

W większości prawdziwych zadań najlepiej działa podejście mieszane: dołącz plik do zmiany i regułę, która go dotyczy, a resztę niech agent znajdzie sam. Na przykład: @src/services/billing/subscription.ts Add a three-retry strategy for failed renewal payments. Search the codebase for how we already retry external calls and reuse that helper; tell me which one you picked.

Dodawaj kontekst w stałej kolejności i tylko wtedy, gdy wynik pokazuje brak

Dziesięć plików dołączonych „na wszelki wypadek” sprawia, że agent traktuje nieistotny kod z taką samą wagą jak ten jeden plik, który się liczy. Zacznij od minimum i niech każda błędna odpowiedź pokaże, czego brakowało.

1. Samo zadanie. Opisz zadanie i warunek akceptacji („nowy test przechodzi, npm run typecheck jest czysty”). Pozwól agentowi szukać.

2. Dodaj wzorcowy plik, jeśli wynik używa złego wzorca: jeden plik, dołączony przez @.

3. Dodaj obowiązującą regułę, jeśli agent wciąż pomija konwencję, którą reguła już opisuje, na przykład regułę obsługi błędów.

4. Dodaj folder, jeśli agent umieszcza pliki w złym miejscu albo źle je nazywa.

5. Dodaj dokumentację, jeśli agent wywołuje API, którego nie ma w twojej wersji biblioteki.

6. Zacznij nowy czat, jeśli trzecia poprawka z rzędu nie przynosi efektu. Historia zawiera już błędne próby i konkurują one z twoimi poprawkami.

Gdy któryś krok naprawi wynik na stałe, zapisz ten kontekst w regule albo we wzorcowym pliku, żeby następna osoba nie przechodziła całej drabiny od nowa.

Ogranicz zmianę kontekstem granic

Kontekst pozytywny mówi agentowi, co skopiować. Kontekst granic mówi, czego nie ruszać. Podaj oba i wymień pliki ze ścieżkami, żeby móc potem sprawdzić granice.

Prompt do skopiowania: nowa funkcja w wyznaczonych granicach

Add rate limiting to the /api/users routes in @src/routes/users.ts.

Follow the middleware pattern in @src/middleware/auth.ts.

Boundaries:
- Change only src/routes/users.ts, and add src/middleware/rate-limit.ts
  and tests/middleware/rate-limit.test.ts.
- Do not change middleware order in src/app.ts.
- Do not add dependencies; use what package.json already has.
- Do not add caching, logging or configuration options nobody asked for.

If the task cannot be done inside these boundaries, stop and tell me
which boundary blocks it instead of working around it.

Wykluczenia w rodzaju „bez cache, bez logowania” są równie ważne jak lista plików: niejasne zadanie zachęca agenta do dodawania abstrakcji, które potem musisz przejrzeć i usunąć. Ostatnia linia też ma znaczenie. Bez niej agent, który trafi na granicę, zwykle znajduje pomysłowy sposób, żeby ją obejść, a to zmiana, którą najmniej chcesz odkryć w code review.

Daj agentowi aktualną dokumentację biblioteki

Modele uczą się bibliotek z danych treningowych, które nie nadążają za wersją, której używasz. W Cursorze tę lukę zamykają dwa sposoby.

• Zindeksowana dokumentacja. Kontekst dokumentacji w Cursorze dołącza źródło, które Cursor zindeksował, w tym strony dodane przez ciebie po adresie URL. Zindeksowanymi źródłami zarządzasz w pozycji Docs w ustawieniach Cursora; jej położenie zmieniało się między wydaniami, więc wyszukaj w ustawieniach „Docs”. Używaj tego dla wewnętrznej dokumentacji API i bibliotek, z którymi pracujesz codziennie.
• Serwer MCP Context7. Context7 pobiera na żądanie dokumentację wskazanej biblioteki w konkretnej wersji (npm @upstash/context7-mcp 4.1.1, sprawdzone 2026-09-26). Dodaj zdalny serwer do globalnego ~/.cursor/mcp.json; klucz API jest opcjonalny i należy do pliku globalnego, nigdy do repozytorium. Context7 dla agentów kodujących omawia klucze, przypinanie bibliotek i tryb skilli.

{
  "mcpServers": {
    "context7": { "url": "https://mcp.context7.com/mcp" }
  }
}

Jeśli masz klucz, dodaj go jako nagłówek w tym samym wpisie:

"context7": {
  "url": "https://mcp.context7.com/mcp",
  "headers": { "Authorization": "Bearer YOUR_API_KEY" }
}

Zastąp YOUR_API_KEY swoim kluczem Context7; plik leży w katalogu domowym, więc klucz nie trafia do repozytorium.

Prompt do skopiowania: kod pod wersję biblioteki, której używasz

Check package.json for the installed drizzle-orm version, then use
context7 to fetch the drizzle-orm docs for that version.

Using only APIs that exist in that version, add a notifications table:
id (uuid primary key), user_id (foreign key to users.id), channel
(enum: email, sms, push), status (enum: pending, sent, failed,
delivered), created_at (timestamp, default now), delivered_at
(nullable timestamp). Generate the migration with drizzle-kit, not
raw SQL.

List every drizzle API you used with the doc page it came from.

Odetnij agentowi dostęp do plików przez .cursorignore

Kod generowany, snapshoty, biblioteki vendorowane i duże fixture’y ściągają wyszukiwanie agenta w stronę plików, których nikt nie powinien kopiować. .cursorignore używa składni .gitignore w katalogu głównym repozytorium, a kod agenta Cursora wczytuje zarówno .gitignore, jak i .cursorignore (sprawdzone w @cursor/sdk 1.0.32, 2026-09-26), ale do trzymania plików z dala od agenta służy tylko .cursorignore. Gdy agent przeszukuje ścieżkę zablokowaną w ten sposób, narzędzie zwraca Path '…' is filtered out by .cursorignore (sprawdzone w @cursor/sdk 1.0.32). Zbuduj ten plik na podstawie rzeczywistej liczby plików w repozytorium, jak pokazuje strojenie Cursora pod duże bazy kodu.

Przenoś kontekst między czatami bez całej historii

Każda wiadomość i każdy wynik narzędzia zostają w czacie, więc długi czat niesie stare próby, ślepe zaułki i nieaktualne plany. Gdy czat zapełni okno kontekstu modelu, Cursor go kompaktuje: zastępuje historię streszczeniem, o którego treści decyduje sam. Zacznij nowy czat, gdy kończysz zadanie, przechodzisz do innego obszaru kodu albo widzisz, że agent powtarza błąd, który już poprawiłeś.

Użyteczną część możesz przenieść na dwa sposoby. Odwołanie do wcześniejszego czatu dołącza tamtą rozmowę w całości. Krótka notatka przekazania, którą piszesz sam albo zlecasz agentowi, zawiera tylko to, co wybierzesz, a przejrzysz ją w 30 sekund. Wybieraj notatkę dla wszystkiego, co musi przetrwać: decyzji, ograniczeń i następnego kroku.

Prompt do skopiowania: zamknij czat notatką przekazania

We are ending this chat. Write docs/handoff/notifications.md with:
- Goal: one sentence.
- Decisions: each decision we made and its reason, one line each.
- Done: files changed, with the test that proves each change.
- Open: the next step, and any test that is currently failing.
- Context for the next chat: the files it should attach with @.
Keep it under 40 lines. Do not paste code that is already committed.

Potem otwórz nowy czat i wyślij: Read @docs/handoff/notifications.md and continue with the step under Open. Usuń notatkę, gdy nowy czat przejmie pracę, chyba że zespół chce mieć takie notatki w review; nie dodawaj jej folderu do .cursorignore, bo następny czat musi ją przeczytać. Zarządzanie tokenami w Cursorze pokazuje, jak logować każdą kompakcję hookiem preCompact, żeby widzieć, które czaty trwają za długo.

Jak udowodnić, że agent użył właściwego kontekstu?

Właściwy kontekst widać w wyniku: nowy kod importuje istniejący helper, zmienia tylko pliki w granicach i przechodzi bramki jakości projektu. Wszystkie trzy rzeczy sprawdzisz bez czytania diffu linia po linii.

1. Poproś o pokwitowanie kontekstu przed kodem. Pokwitowanie zamienia niewidoczny wybór w listę, którą porównasz z oczekiwaniami.

Prompt do skopiowania: pokwitowanie kontekstu

Before you change anything, reply with a context receipt:
1. Files you read and why, one line each.
2. The existing helper, type or pattern you will reuse for each part
   of the task, with its path.
3. Anything you expected to find and did not.
4. Files you plan to create or change.
Wait for my OK before editing.

Jeśli pokwitowanie wymienia nowy helper tam, gdzie wiesz, że istnieje już gotowy, dołącz istniejący i zapytaj ponownie. Kosztuje to jedną wiadomość; znalezienie tego w review kosztuje przepisanie.

2. Sprawdź ponowne użycie i zakres w terminalu. Gdy agent skończy, a przed commitem, uruchom sprawdzenia w tym stylu dla przykładu z paginacją. W tym zadaniu granice obejmowały src/routes/users.ts i tests/routes/users.test.ts:

# Every file the agent created or changed, including new files
git status --porcelain -uall

# Files outside the fence you set in the prompt: expect no output
{ git diff --name-only HEAD; git ls-files --others --exclude-standard; } \
  | grep -Ev '^(src/routes/users\.ts|tests/routes/users\.test\.ts)$'

# The route reuses the existing helper: expect one import line
rg -n "utils/pagination" src/routes/users.ts

# No second pagination helper appeared anywhere else: expect no output
rg -n "export (default )?(async )?(function|const) \w*[Pp]aginat" src --glob '!src/utils/pagination.ts'

3. Uruchom bramki, którym projekt już ufa. Testy, sprawdzanie typów i linter dowodzą zachowania; powyższe sprawdzenia dowodzą, że agent budował na właściwym kodzie. Gdy przechodzi jedno i drugie, programista, który prowadził czat, zatwierdza zmianę i wkleja pokwitowanie kontekstu do opisu pull requesta, żeby recenzent sprawdził jedną listę, zamiast odtwarzać ją od zera. Pierwsza funkcja łączy to w pełną pętlę z testami pisanymi najpierw.

Co psuje się w zarządzaniu kontekstem Cursora i jak to naprawić

Objaw	Prawdopodobna przyczyna	Naprawa
Agent pisze nowy helper obok istniejącego	Nigdy nie zobaczył istniejącego	Dołącz plik helpera, poproś o pokwitowanie kontekstu i usuń duplikat, posługując się sprawdzeniem ponownego użycia
Agent stosuje przestarzały wzorzec	Twój wzorcowy plik albo starszy plik, który znalazł, używa starego wzorca	Dołącz najnowszy plik zgodny z obecną konwencją i wskaż stary jako „nie kopiuj”
Pliki lądują w złym katalogu	Agent nie zna układu projektu	Dołącz docelowy folder, a jeśli zdarzy się to dwa razy, dodaj regułę przypisaną do plików
Kod wywołuje API, którego nie ma w twojej wersji	Agent oparł się na danych treningowych	Dodaj zindeksowaną dokumentację albo użyj Context7 i poproś o podanie strony dokumentacji dla każdego API
Kontekst dokumentacji zwraca nieaktualne strony	Zindeksowane źródło jest przestarzałe	Usuń źródło w pozycji Docs w ustawieniach Cursora i dodaj adres URL jeszcze raz
Wynik dodaje cache, logowanie albo warstwy, o które nikt nie prosił	Zadanie nie określało zakresu	Dodaj jawne wykluczenia do granic i poproś o najmniejszą zmianę, która przechodzi test
Agent ignoruje dołączony plik	Plik jest długi, a istotny fragment ginie w środku	Dołącz jedną funkcję jako zaznaczenie kodu i podaj jej nazwę w prompcie
Wyszukiwanie zwraca Path '…' is filtered out by .cursorignore	Ścieżka pasuje do wzorca w .cursorignore	Usuń wzorzec, jeśli agent potrzebuje pliku, albo dołącz nieignorowaną kopię istotnego fragmentu
Reguła i wzorcowy plik sobie przeczą	Dwa źródła prawdy	Popraw to, które jest błędne; do tego czasu napisz w prompcie, które wygrywa
Poprawki przestają działać w długim czacie	Historia pełna starych prób albo kompakcja zgubiła twoją instrukcję	Napisz notatkę przekazania i kontynuuj w nowym czacie
Dziesięć dołączonych plików, gorszy wynik	Agent przykłada wagę do nieistotnego kodu	Ogranicz się do dwóch lub trzech plików, które się liczą, i pozwól agentowi znaleźć resztę

Dokąd dalej po zarządzaniu kontekstem

Zbuduj pierwszą funkcję z pomocą AI Reguły, kontekst, Plan Mode i testy razem na jednej prawdziwej funkcji.

Reguły projektu w Cursorze Zamień kontekst, który ciągle dołączasz, w reguły ładujące się same.

Zarządzanie tokenami w Cursorze Zmierz, ile kosztuje kontekst, i loguj każdą kompakcję.

Szablony promptów dla Cursora Prompty wielokrotnego użytku, które rozwijają wzorce kontekstu z tej strony.

Zarządzanie kontekstem we wszystkich narzędziach Okna kontekstu, dokumentacja jako kontekst i wzorce pamięci w Claude Code, Codeksie i Cursorze.

Używasz też Claude Code albo Codeksa? Te same zasady działają tam z inną mechaniką: zobacz system pamięci Claude Code i wzorce kontekstu w Codeksie.