Zarządzanie kontekstem

Prosisz agenta o “dodanie paginacji do API.” Generuje on narzędzie paginacji od zera — ignorując to które już istnieje w src/utils/pagination.ts. Tworzy nowy format odpowiedzi który koliduje z twoimi istniejącymi wzorcami API. Używa offset/limit gdy twój projekt ustandaryzował paginację opartą na kursorze dwa miesiące temu. Model nie jest głupi. Po prostu nie miał odpowiedniego kontekstu. Zarządzanie kontekstem to różnica między AI które zna twój projekt a takim które koduje w ciemno.

Co wyniesiesz z tego rozdziału

• Biegłość we wszystkich typach wzmianek @ w Cursor: pliki, foldery, kod, dokumentacja i przeszłe czaty
• Strategia kiedy wyraźnie dostarczać kontekst a kiedy pozwolić agentowi go znaleźć
• Techniki zarządzania kontekstem w długich rozmowach aby zapobiec degradacji
• Przepływ pracy @Docs do integrowania zewnętrznej dokumentacji

System @

Wpisz @ w polu agenta aby otworzyć menu kontekstu. Użyj strzałek aby nawigować po kategoriach, następnie wpisz aby filtrować. Naciśnij Enter aby wybrać.

@Files i Folders

Odwołuj się do konkretnych plików lub całych katalogów aby dać agentowi ukierunkowany kontekst.

@src/utils/pagination.ts Dodaj paginację opartą na kursorze do endpointu /api/users
używając tego samego wzorca co to istniejące narzędzie.

To mówi agentowi dokładnie gdzie szukać istniejącego wzorca. Bez odniesienia @, agent może przeszukać bazę kodu i go znaleźć — albo nie.

Foldery: Odwołaj się do katalogu aby dać agentowi przegląd jego zawartości:

@src/api/ Utwórz nowy endpoint dla powiadomień użytkownika który podąża za
wzorcami używanymi w istniejących endpointach w tym katalogu.

Po wybraniu folderu, wpisz / aby nawigować głębiej do podkatalogów.

Notatka

Duże pliki i foldery są automatycznie kondensowane aby zmieścić się w limitach kontekstu. To zwykle jest w porządku, ale dla bardzo dużych plików możesz chcieć odnieść się do konkretnych sekcji kodu zamiast tego.

@Code

Dla bardziej precyzyjnego kontekstu niż całe pliki, użyj @Code aby odnieść się do konkretnych funkcji, klas lub bloków kodu:

@Code UserService.createUser Refaktoryzuj tę metodę aby dodać weryfikację email.
Zachowaj ten sam interfejs ale dodaj krok który wysyła email weryfikacyjny
przed zwróceniem obiektu użytkownika.

To jest bardziej efektywne niż odnoszenie się do całego pliku gdy potrzebujesz tylko aby agent skupił się na jednej funkcji.

@Docs

Cursor utrzymuje bibliotekę dokumentacji dla popularnych frameworków i bibliotek. Możesz także dodać własne.

Używanie wbudowanych dokumentów:

@Docs Next.js Jak implementuję middleware które sprawdza uwierzytelnianie
na wszystkich trasach /api/* w App Router?

Dodawanie niestandardowej dokumentacji:

1. Wpisz @Docs w czacie
2. Wybierz Add new doc
3. Wklej URL strony dokumentacji (np. twoje wewnętrzne dokumenty API)
4. Cursor indeksuje i kataloguje dokumentację

Po dodaniu, dokumentacja jest dostępna we wszystkich rozmowach. Możesz zarządzać swoimi dokumentami w Ustawieniach Cursor następnie Indeksowanie i dokumentacja.

Prompt do skopiowania dla kodowania świadomego dokumentacji

@Docs Drizzle ORM Utwórz migrację która dodaje tabelę powiadomień z:
- id (uuid, klucz główny)
- user_id (klucz obcy do users)
- channel (enum: email, sms, push)
- status (enum: pending, sent, failed, delivered)
- created_at (timestamp z domyślną wartością)
- delivered_at (nullable timestamp)

Użyj wzorców migracji Drizzle z dokumentów, nie surowego SQL.

@Past Chats

Odwołuj się do poprzednich rozmów aby przenieść kontekst z wcześniejszych sesji do bieżącej.

@Past Chats [planowanie systemu powiadomień] Zdecydowaliśmy o podejściu
śledzenia dostawy opartym na webhookach w naszej wcześniejszej rozmowie. Teraz
zaimplementuj endpoint webhooka używając tego projektu.

To jest znacznie lepsze niż kopiowanie-wklejanie ze starej rozmowy. Agent dostaje pełny kontekst przywoływanego czatu, włączając zmiany kodu i wyniki narzędzi.

Kiedy dostarczać kontekst a kiedy pozwolić agentowi szukać

Agent ma wbudowane narzędzia wyszukiwania. Może przeszukać twoją bazę kodu, czytać pliki i eksplorować katalogi. Więc kiedy powinieneś wyraźnie dostarczyć kontekst z @, a kiedy pozwolić mu samemu się zorientować?

Dostarczaj wyraźny kontekst gdy:

• Wiesz dokładnie które pliki są istotne
• Wzorzec który chcesz naśladować jest w konkretnym pliku
• Zadanie obejmuje modyfikację istniejącego kodu (odnieś się do pliku który ma być zmodyfikowany)
• Miałeś poprzednią rozmowę która informuje tę pracę

Pozwól agentowi szukać gdy:

• Nie wiesz gdzie jest istotny kod
• Chcesz aby agent odkrył jak twoja baza kodu jest ustrukturyzowana
• Zadanie jest szerokie i wiele plików może być istotnych
• Chcesz aby agent znalazł wszystkie wystąpienia wzorca

Uwaga

Częstym błędem jest nadmierne dostarczanie kontekstu. Dołączenie 10 nieistotnych plików myli agenta co do tego co jest ważne. Jeśli znasz dwa pliki które się liczą, odnieś się tylko do tych dwóch. Jeśli nie wiesz co się liczy, pozwól agentowi szukać.

Podejście hybrydowe

Dla złożonych zadań, łącz wyraźny i odkryty kontekst:

@src/services/billing/subscription.ts Logika odnowienia subskrypcji wymaga
obsługi nieudanych płatności ze strategią 3 prób. Sprawdź jak obsługujemy
próby ponowne gdzie indziej w bazie kodu i użyj tego samego wzorca.

Wskazałeś konkretny plik do zmodyfikowania, ale poprosiłeś agenta aby sam znalazł wzorzec prób ponownych.

Zarządzanie kontekstem w długich rozmowach

Każda wiadomość w rozmowie dodaje się do okna kontekstu. Po 20-30 wymianach, skumulowany kontekst może powodować problemy:

• Agent zaczyna zapominać instrukcje z początku rozmowy
• Jakość odpowiedzi pogarsza się gdy model żongluje zbyt dużą ilością informacji
• Koszt rośnie ponieważ każda nowa wiadomość zawiera cały poprzedni kontekst

Kiedy zacząć od nowa

Zacznij nową rozmowę gdy:

• Przechodzisz do innego zadania lub funkcji
• Agent wciąż popełnia ten sam błąd mimo poprawek
• Ukończyłeś jedną logiczną jednostkę pracy
• Rozmowa przekroczyła 15-20 wymian

Jak przenosić kontekst dalej

Rozpoczynając nową rozmowę, nie tracisz swojej poprzedniej pracy:

1. @Past Chats — odwołaj się do starej rozmowy dla jej kontekstu
2. @Files — odwołaj się do plików które zostały zmodyfikowane w poprzedniej sesji
3. Zapisane plany — odwołaj się do plików .cursor/plans/ dla kontekstu implementacji

Prompt do skopiowania dla rozpoczęcia świeżej rozmowy z kontekstem

Kontynuuję pracę nad systemem powiadomień. W poprzedniej sesji:
- Utworzyliśmy schemat bazy danych (migracje są ukończone)
- Zaimplementowaliśmy API preferencji (/api/users/:id/preferences)
- Zaczęliśmy ale nie ukończyliśmy workera email

@src/services/notifications/email-worker.ts
@.cursor/plans/notification-system.md

Podejmijmy od miejsca gdzie skończyliśmy. Worker email potrzebuje logiki
prób ponownych i integracji SendGrid.

Zaawansowane techniki kontekstu

Przeciąganie i upuszczanie plików

Możesz przeciągać pliki bezpośrednio z paska bocznego eksploratora plików do czatu agenta. To najszybszy sposób aby dodać kontekst pliku bez wpisywania @.

Obrazy jako kontekst

Wklej zrzuty ekranu bezpośrednio do czatu. To działa ze wszystkimi modelami, ale Gemini 3 Pro ma najsilniejsze zrozumienie obrazów. Użyj tego do:

• Zrzutów ekranu błędów UI (“napraw ten problem layoutu”)
• Makiet projektowych (“zaimplementuj ten projekt”)
• Zrzutów ekranu błędów (“Widzę ten błąd w konsoli przeglądarki”)

Wskaźnik kontekstu

Najedź na wskaźnik kontekstu w polu promptu aby zobaczyć:

• Jak dużo okna kontekstu jest użyte
• Które zasady są obecnie aktywne
• Które pliki i narzędzia są załadowane

Jeśli jesteś blisko limitu, zacznij nową rozmowę lub usuń niepotrzebny kontekst.

Zmiany kontekstu w Cursor 2.0

Cursor 2.0 uprościł system wzmianek @. Kilka wyraźnych typów kontekstu zostało usuniętych ponieważ agent teraz zbiera je automatycznie:

• @Web — usunięto, agent może przeglądać sieć przez MCP lub wbudowane narzędzia
• @Git — usunięto, pytaj agenta bezpośrednio o historię git
• @Linter Errors — usunięto, agent czyta output lintera automatycznie
• @Recent Changes — usunięto, agent może zapytać git diff sam

Pozostałe typy @ (@Files, @Folders, @Code, @Docs, @Past Chats) to te gdzie wyraźne ludzkie kierowanie dodaje wartość nad automatyczne odkrywanie.

Kiedy to nie działa

Agent ignoruje pliki do których się odniosłeś: To zwykle oznacza że pliki są zbyt duże i zostały skondensowane. Spróbuj odnieść się do konkretnej funkcji z @Code zamiast całego pliku.

@Docs zwraca przestarzałe informacje: Dokumentacja jest w cache. Przejdź do Ustawień Cursor następnie Indeksowanie i dokumentacja i przeindeksuj źródło dokumentacji.

Odniesienie do przeszłego czatu nie zawiera odpowiedniego kontekstu: Agent dostaje pełną rozmowę, ale bardzo długie przeszłe czaty mogą być podsumowane. Dla krytycznego kontekstu, zapisz go do pliku planu i odnieś się do tego zamiast.

Okno kontekstu pełne: Skumulowałeś zbyt dużo kontekstu. Zacznij nową rozmowę. Odnieś się tylko do konkretnych plików i planów potrzebnych dla bieżącego zadania.

Agent halucynuje mimo dobrego kontekstu: Czasami model się myli nawet z prawidłowym kontekstem. Zacznij nową rozmowę, dostarcz ten sam kontekst i przeformułuj pytanie. Świeży start często rozwiązuje halucynacje.

Co dalej

Zbuduj swoją pierwszą funkcję Połóż wszystko razem -- zasady, kontekst, tryb Plan i tryb Agent -- aby zbudować prawdziwą funkcję od podstaw.