Wzorce kontekstu

Prosisz Agenta, aby dodał obsługę błędów do twojej trasy Express. Owija wszystko w try-catch i zwraca { error: "Something went wrong" }. Tymczasem twoja baza kodu ma niestandardową klasę AppError, scentralizowane middleware obsługi błędów i standardowy format odpowiedzi błędów z kodami błędów. Agent nie wiedział o niczym z tego, ponieważ mu nie powiedziałeś, i nie znalazł tego sam.

Jakość wyniku Cursora jest bezpośrednio proporcjonalna do jakości kontekstu, który dostarczasz. Za mało kontekstu i agent zgaduje. Za dużo kontekstu i traci koncentrację na ważnych częściach. Punkt optymalny to precyzyjny, odpowiedni kontekst, który dokładnie mówi agentowi, jakich wzorców ma przestrzegać.

Co wyniesiesz

• Ramy decyzyjne określające, kiedy używać każdego typu wzmianki @
• Strategie efektywnego budowania kontekstu bez przeciążania prompta
• Wzorce wykorzystania reguł do automatycznego dostarczania kontekstu tła
• Techniki debugowania problemów z kontekstem, gdy agent produkuje słabe wyniki

System wzmianek @

Wzmianki @ w Cursorze to twoje podstawowe narzędzie do dostarczania kontekstu. Wpisz @ w polu wprowadzania czatu i wybierz z oficjalnych selektorów — @Files & Folders, @Code, @Docs i @Past Chats:

Typ wzmianki	Co robi	Koszt tokenów	Najlepsze do
@Files & Folders (plik)	Dołącza pełną zawartość określonego pliku	Średni-Wysoki	Pokazywania dokładnych wzorców do naśladowania
@Files & Folders (folder)	Zapewnia przegląd strukturalny katalogu	Niski-Średni	Dawania agentowi mapy twojego projektu
@Code	Dołącza konkretną funkcję lub fragment kodu, który zaznaczysz	Niski	Precyzyjnego wskazania, do czego się odwołać
@Docs	Przeszukuje zindeksowaną dokumentację	Średni	Wskazówek specyficznych dla biblioteki/frameworka
@Past Chats	Odnosi się do poprzedniej konwersacji	Średni	Budowania na wcześniejszej pracy

Pliki i foldery dzielą jeden wspólny selektor (@Files & Folders); poniżej używamy skrótów @file i @folder, aby rozróżnić te dwa zastosowania.

Wzmianki plików: Pokaż, nie mów

Zamiast opisywać swoje wzorce słowami, pokaż agentowi rzeczywisty kod:

# Źle: Opisywanie wzorca (agent może go nie przestrzegać)
"Stwórz endpoint API. Używamy Express z middleware do autentykacji,
Zod do walidacji i zwracamy JSON z kodami statusu."

# Dobrze: Pokazywanie wzorca (agent go replikuje)
"Stwórz endpoint POST /api/orders według dokładnego wzorca
w @src/routes/users.ts -- to samo middleware, walidacja, obsługa
błędów i format odpowiedzi."

Wskazówka

Prompt do skopiowania-wklejenia dla implementacji opartej na wzorcu:

Create [NEW THING] following the exact patterns in @[EXISTING EXAMPLE].

Same structure, same error handling, same response format.
Only change the domain-specific logic.

Zastąp [NEW THING] i [EXISTING EXAMPLE] swoimi szczegółami. Ten dwuliniowy prompt konsekwentnie produkuje wyższej jakości wynik niż 20-liniowy opis tego, czego chcesz.

Wzmianki folderów: Gdy potrzebujesz mapy

Użyj @folder, gdy agent musi zrozumieć strukturę katalogu, ale nie musi czytać każdego pliku:

Look at @src/components/ and create a new NotificationBanner
component that follows the same file organization and naming
conventions as the existing components.

Wzmianki folderów są znacznie tańsze pod względem tokenów niż dołączanie każdego pliku. Agent otrzymuje listę plików i może wybrać, które czytać szczegółowo.

Wzmianki kodu: Precyzja chirurgiczna

Gdy potrzebujesz, aby agent odwołał się do konkretnej funkcji lub klasy bez dołączania całego pliku, zaznacz fragment kodu selektorem @Code zamiast dołączać cały plik:

Refactor the calculateDiscount function (select it with @Code from
src/services/pricing.ts) to support percentage-based and
fixed-amount discounts.

To najbardziej wydajny tokenowo sposób dostarczania kontekstu dla ukierunkowanych edycji. Jeśli wolisz nie szukać dokładnych linii, zwykła wzmianka pliku @src/services/pricing.ts również zadziała — po prostu kosztuje więcej tokenów.

Strategie kontekstu

Strategia 1: Minimalny wykonalny kontekst

Zacznij od najmniejszego możliwego kontekstu i dodawaj więcej tylko wtedy, gdy wynik jest nieprawidłowy:

1. Podaj agentowi tylko opis zadania
2. Jeśli produkuje nieprawidłowe wzorce, dodaj kanoniczny przykładowy plik
3. Jeśli nadal pomija konwencje, dodaj odpowiednią regułę
4. Jeśli tworzy złą strukturę plików, dodaj wzmiankę folderu

To podejście minimalizuje użycie tokenów, zapewniając jednocześnie, że agent otrzyma to, czego potrzebuje.

Strategia 2: Kontekst odniesienia wzorca

Dla zadań, które powinny przestrzegać istniejących wzorców, zawsze dołącz jeden kanoniczny przykład:

Wskazówka

Prompt do skopiowania-wklejenia dla kontekstu odniesienia wzorca:

Create src/services/notification-service.ts.

Pattern reference: @src/services/email-service.ts
- Same class structure
- Same error handling approach
- Same dependency injection pattern
- Same test file organization

Jeden dobry przykładowy plik jest wart więcej niż strona pisemnych instrukcji.

Strategia 3: Kontekst granic

Gdy agent musi wiedzieć, czego NIE dotykać:

Wskazówka

Prompt do skopiowania-wklejenia dla kontekstu granic:

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

Context:
- @src/middleware/auth.ts (existing middleware pattern to follow)
- @src/routes/users.ts (the file to modify)

Boundaries:
- Do NOT modify any other route files
- Do NOT change the middleware loading order in app.ts
- Do NOT install new packages -- use the built-in Node.js APIs

Strategia 4: Kontekst dokumentacji

Użyj @docs, aby dać agentowi wiedzę specyficzną dla frameworka:

@docs Next.js Add server-side data validation using Next.js
Server Actions. Follow the official patterns for form handling
and error states.

Dodaj niestandardowe źródła dokumentacji w Cursor Settings > Indexing & Docs. Jeśli używasz wewnętrznego frameworka lub własnej biblioteki, dodaj URL jej dokumentacji, aby agenci mogli się do niej odwoływać.

Wskazówka

Prompt do skopiowania-wklejenia dla dodawania dokumentacji projektu:

Add the following documentation sources to Cursor for this project:
1. Our API documentation: [your-docs-url]
2. Our design system: [your-design-system-url]
3. Our internal SDK: [your-sdk-docs-url]

Go to Cursor Settings > Indexing & Docs > Add New Doc and paste each URL.

Diagnozowanie problemów z kontekstem

Gdy agent produkuje słabe wyniki, przyczyną jest prawie zawsze jeden z tych problemów z kontekstem:

Agent używa złych wzorców. Nie widział twojego kanonicznego przykładu. Dodaj referencję @file do pliku, który powinien naśladować.

Agent tworzy pliki w złej lokalizacji. Nie zna twojej struktury projektu. Dodaj referencję @folder, aby pokazać, gdzie rzeczy powinny się znajdować.

Agent używa przestarzałych API lub zdeprecjonowanych wzorców. Opiera się na danych treningowych zamiast na twojej bazie kodu. Dodaj @docs dla aktualnej wersji frameworka.

Agent dodaje niepotrzebną złożoność. Twój prompt jest zbyt niejasny. Dodaj wyraźne granice: “NIE dodawaj cachowania. NIE dodawaj logowania. Tylko podstawowa logika.”

Gdy to się psuje

Za dużo kontekstu dezorientuje agenta. Jeśli dołączysz 10+ plików, agent może skupić się na nieistotnych. Zmniejsz do 2-3 najważniejszych plików i pozwól agentowi eksplorować, jeśli potrzebuje więcej.

@docs zwraca przestarzałe informacje. Indeks dokumentacji Cursora może być nieaktualny. Ponownie zindeksuj źródło dokumentacji w Cursor Settings lub dodaj URL ponownie.

Agent nie może znaleźć plików ze wzmiankami @file. Sprawdź, czy ścieżka pliku jest poprawna. Użyj menu autouzupełniania po wpisaniu @, aby przeglądać dostępne pliki.

Reguły i kontekst pliku są sprzeczne. Jeśli reguła mówi “używaj camelCase”, ale plik referencyjny używa snake_case, agent się myli. Upewnij się, że twoje reguły i przykłady są spójne.

Co dalej

• Szablony promptów — Szablony bazujące na tych strategiach kontekstu
• Zarządzanie fragmentami — Fragmenty kodu jako kontekst wielokrotnego użytku
• Zarządzanie tokenami — Strona kosztowa zarządzania kontekstem