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 wzmiankek @

Wzmianki @ w Cursorze to twoje podstawowe narzędzie do dostarczania kontekstu. Wpisz @ w polu wprowadzania czatu i wybierz spośród:

Typ wzmianki	Co robi	Koszt tokenów	Najlepsze do
@file	Dołącza pełną zawartość określonego pliku	Średni-Wysoki	Pokazywania dokładnych wzorców do naśladowania
@folder	Zapewnia przegląd strukturalny katalogu	Niski-Średni	Dawania agentowi mapy twojego projektu
@code	Dołącza konkretną funkcję lub klasę	Niski	Precyzyjnego wskazania, co należy odwoływać się
@docs	Przeszukuje zindeksowaną dokumentację	Średni	Wskazówek specyficznych dla biblioteki/frameworka
@past-chats	Odnosi się do poprzedniej konwersacji	Średni	Budowania na wcześniejszej pracy

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:

Stwórz [NOWĄ RZECZ] według dokładnych wzorców w @[ISTNIEJĄCY PRZYKŁAD].

Ta sama struktura, ta sama obsługa błędów, ten sam format odpowiedzi.
Zmień tylko logikę domenową.

Zastąp [NOWĄ RZECZ] i [ISTNIEJĄCY PRZYKŁAD] 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:

Spójrz na @src/components/ i stwórz nowy komponent NotificationBanner,
który przestrzega tej samej organizacji plików i konwencji nazewnictwa
co istniejące komponenty.

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:

Zrefaktoryzuj funkcję calculateDiscount w @Code:src/services/pricing.ts:calculateDiscount,
aby obsługiwała rabaty procentowe i kwotowe.

To najbardziej wydajny tokenowo sposób dostarczania kontekstu dla ukierunkowanych edycji.

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:

Stwórz src/services/notification-service.ts.

Odniesienie wzorca: @src/services/email-service.ts
- Ta sama struktura klasy
- To samo podejście do obsługi błędów
- Ten sam wzorzec wstrzykiwania zależności
- Ta sama organizacja plików testowych

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

Strategia 3: Kontekst granic

Gdy agent musi wiedzieć, czego NIE dotykać:

Dodaj ograniczanie szybkości do tras /api/users w @src/routes/users.ts.

Kontekst:
- @src/middleware/auth.ts (istniejący wzorzec middleware do naśladowania)
- @src/routes/users.ts (plik do modyfikacji)

Granice:
- NIE modyfikuj żadnych innych plików tras
- NIE zmieniaj kolejności ładowania middleware w app.ts
- NIE instaluj nowych pakietów -- użyj wbudowanych API Node.js

Strategia 4: Kontekst dokumentacji

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

@docs Next.js Dodaj walidację danych po stronie serwera używając Next.js 14
Server Actions. Przestrzegaj oficjalnych wzorców dla obsługi formularzy
i stanów błędów.

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:

Dodaj następujące źródła dokumentacji do Cursora dla tego projektu:
1. Nasza dokumentacja API: [twój-url-docs]
2. Nasz system projektowania: [twój-url-system-projektowania]
3. Nasze wewnętrzne SDK: [twój-url-docs-sdk]

Przejdź do Cursor Settings > Indexing & Docs > Add New Doc i wklej każdy 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 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