Szablony promptów dla agenta Cursora

Szablon prompta dla Cursora to sprawdzony prompt wielokrotnego użytku, który od razu przekazuje agentowi pięć rzeczy: zadanie, wzorcowy plik do naśladowania, granice, kontrole do uruchomienia i dowody do zaraportowania. Najważniejszy jest blok weryfikacji, bo wynik oceniają wtedy testy i kontrola typów, a nie czytanie diffu linijka po linijce.

Prosisz agenta Cursora o „endpoint POST do tworzenia zamówień”. Agent pomija walidację, wymyśla własny format błędów i ignoruje wzorzec tras, którego używa twój zespół. Po pięciu poprawkach wpisałeś więcej tekstu, niż zajęłoby samodzielne napisanie endpointu, a nadal nie wiesz, czy działa.

Ta strona jest dla programistów, którzy codziennie pracują z agentem Cursora. Tech leadzi, którzy chcą jednej wspólnej biblioteki dla zespołu, powinni przeczytać sekcję o przechowywaniu: szablon trzymany w repozytorium przechodzi review i ewoluuje tak jak kod.

Co obejmuje ta biblioteka promptów dla Cursora

Siedem gotowych szablonów do zadań, które powtarzasz najczęściej: endpoint, komponent, migracja, diagnoza błędu, refaktoryzacja, zestaw testów i przegląd przed PR.
Pięcioczęściową budowę własnych szablonów z blokiem weryfikacji, który zmusza agenta do udowodnienia wyniku.
Tabelę decyzyjną: kiedy szablon powinien być Agent Skillem, a kiedy regułą projektu.
Typowe awarie bibliotek szablonów i sposób wyjścia z każdej z nich.

Co musi zawierać szablon prompta, żeby Cursor trafił za pierwszym razem?

Każdy szablon na tej stronie ma te same pięć części. Gdy szablon zawodzi, zwykle brakuje jednej z nich.

Część	Co zawiera	Co się psuje bez niej
Zadanie	Jeden wynik opisany jako zachowanie: „zwraca 201 z utworzonym zamówieniem”	Agent rozwiązuje sąsiedni problem
Wzorzec	Odwołanie `@` do pliku w repozytorium, który robi to dobrze	Agent wymyśla nowy wzorzec
Granice	Pliki i zachowania, których nie wolno ruszać, w formie „Do NOT…”	Rozlewanie się zmian na niezwiązane moduły, poprawione testy
Weryfikacja	Dokładne komendy: testy, kontrola typów, lint	Weryfikujesz, czytając diff
Raport	Format końcowej wiadomości: zmienione pliki, wynik komend, otwarte pytania	„Gotowe” bez żadnych dowodów

Wzorzec robi więcej niż jakikolwiek przymiotnik. „Follow the pattern in @src/routes/users.ts” przenosi walidację, obsługę błędów, logowanie i kształt odpowiedzi w jednym odwołaniu. Jak odwołania @ dodają pliki do kontekstu, opisuje strona zarządzanie kontekstem w Cursorze. Ogólną technikę stojącą za tymi pięcioma częściami znajdziesz w skutecznych technikach promptowania.

Którego szablonu użyć do jakiego zadania?

Przebudowę zaczynaj w Plan Mode, który według Cursora tworzy „szczegółowe plany implementacji przed napisaniem jakiegokolwiek kodu”, a potem przełącz się na Agenta. Diagnozy prowadź w Agencie, bo muszą uruchamiać kod: szablon błędu pisze i uruchamia padający test, a szablon wydajności uruchamia benchmark. Same prompty zakazują edycji kodu źródłowego i zatrzymują się przed poprawką. Zamiast diffu sprawdzasz bramkę weryfikacji.

Zadanie	Szablon	Zacznij w	Bramka, którą sprawdzasz
Nowy endpoint	Nowy endpoint API	Agent	Nowe testy przechodzą, cały zestaw zielony, typy czyste
Nowy komponent UI	Nowy komponent React	Agent	Testy komponentu dla stanów ładowania, błędu i sukcesu
Zmiana schematu	Migracja bazy danych	Agent	Migracja wchodzi i cofa się na lokalnej bazie
Nieznany błąd	Diagnoza błędu	Agent, zatrzymuje się przed poprawką	Padający test, który odtwarza błąd
Wolna ścieżka	Diagnoza wydajności	Agent, zatrzymuje się przed poprawką	Liczby przed i po z tego samego pomiaru
Przebudowa	Refaktoryzacja	Plan Mode, potem Agent	Niezmieniony zestaw testów wciąż zielony, publiczne eksporty bez zmian
Brak pokrycia	Zestaw testów	Agent	Każdy test pada, gdy zepsujesz zachowanie, które sprawdza
Przed PR	Przegląd przed PR	Agent, bez edycji	Tabela uwag do triażu

Szablony funkcji: endpointy, komponenty i migracje

Szablony funkcji zaczynają od kryteriów akceptacji i każą napisać testy przed implementacją. Dzięki temu testy opisują zachowanie, o które prosiłeś, a nie kod, który agent akurat napisał. Pełną technikę opisuje strona wykonywalne kryteria akceptacji.

Add a POST /api/orders endpoint.

Acceptance criteria:
- A valid body returns 201 with the created order.
- An invalid body returns 400 in the error format from @src/lib/errors.ts.
- A request without a session returns 401 (use the withAuth middleware).

Anchor: follow @src/routes/users.ts exactly for route structure, Zod validation,
error handling and response shape. Validate with a Zod schema in src/schemas/order.ts.
Call the existing service in @src/services/order-service.ts.

Order of work:
1. Write the tests for the three criteria first in src/routes/__tests__/orders.test.ts,
   following @src/routes/__tests__/users.test.ts. Run them and confirm they fail.
2. Implement the endpoint and register it in @src/app.ts.

Do NOT modify existing endpoints, existing tests or the error helpers.

Verify: run `npx vitest run src/routes`, then `npx tsc --noEmit`, then `npm run lint`.
Report: files changed, the last 20 lines of each command's output, and any
assumption you made about the order payload.

Create UserNotificationPreferences in src/components/UserNotificationPreferences.tsx.

Behaviour:
- Props: { userId: string; onSave: (prefs: NotificationPrefs) => void }
- Loads preferences from GET /api/users/:userId/notification-preferences.
- Shows switches for email, push, sms and weekly digest.
- Save sends PATCH to the same URL, then calls onSave with the saved value.
- Renders distinct loading, error and saved states.

Anchor: follow @src/components/UserProfile.tsx for data fetching and state handling.
Use only Button, Switch and Card from @src/components/ui/.

Do NOT create or change API endpoints; they already exist.

Verify: add src/components/__tests__/UserNotificationPreferences.test.tsx covering
the loading, error, and save paths with fetch mocked, then run
`npx vitest run src/components` and `npx tsc --noEmit`.
Report: files changed and the test output.

Szablon migracji potrzebuje jednej dodatkowej granicy: działa wyłącznie na lokalnej bazie i musi mieć drogę powrotu. Narzędzie drizzle-kit nie generuje migracji odwrotnych, więc szablon każe agentowi napisać ją ręcznie i podaje komendy, którymi ją zastosować.

Add an orders table with Drizzle.

Columns: id uuid primary key default gen_random_uuid(); user_id uuid not null
references users.id; status enum ('pending','confirmed','shipped','delivered',
'cancelled') default 'pending'; total_amount numeric(10,2) not null;
created_at and updated_at timestamptz default now().
Add one index on (user_id, status).

Anchor: define the table in @src/db/schema.ts in the same style as the users table,
and generate the migration with `npx drizzle-kit generate` into the existing
migrations folder.

Do NOT edit earlier migrations. Do NOT run anything against a remote or
production database; use the local DATABASE_URL from .env.local only.

Verify, with DATABASE_URL loaded from .env.local:
1. Apply the migration with `npx drizzle-kit migrate`.
2. drizzle-kit does not generate down migrations, so write the reverse by hand
   as orders_down.sql next to the generated file (DROP the index, the table and
   the enum type). Apply it with `psql "$DATABASE_URL" -f <path>/orders_down.sql`
   and show with `psql "$DATABASE_URL" -c '\d orders'` that the table is gone.
3. Apply the generated forward SQL again with `psql "$DATABASE_URL" -f <generated file>`.
Report: the generated SQL, the reverse SQL, and the output of each command.

Szablony debugowania: najpierw odtwórz, potem napraw

Szablon debugowania zabrania edycji, dopóki przyczyna nie zostanie udowodniona. Dowodem jest padający test, a nie wyjaśnienie, bo wiarygodne wyjaśnienie złej przyczyny brzmi dokładnie tak samo jak trafne. Pełny proces debugowania opisuje strona polowanie na błędy w Cursorze.

Bug: [PASTE THE ERROR AND STACK TRACE]
Trigger: [THE STEPS OR REQUEST THAT CAUSES IT]
Expected: [WHAT SHOULD HAPPEN]

Phase 1, no source edits:
- Read the stack trace and the files it names. List up to three candidate causes,
  each with the evidence for and against it.
- Write one failing test that reproduces the bug, next to the existing tests for
  that module. Run it and show that it fails for the reason you expect.

Stop after phase 1 and wait for my go-ahead.

Phase 2, after I approve:
- Make the smallest fix that turns the new test green.
- Run the whole test suite and `npx tsc --noEmit`.
Report: the root cause in two sentences, the diff summary, and both test runs.

Uzupełnij trzy pola w nawiasach kwadratowych prawdziwym błędem, krokami i oczekiwanym wynikiem. Test z pierwszej fazy zostaje w zestawie jako ochrona przed regresją.

GET /api/orders?userId=... takes about 3 s; the target is under 300 ms.

No source edits yet. Measure first:
1. Run the existing benchmark in scripts/bench-orders.ts (or write one that calls
   the handler 50 times against the local database) and record the median.
2. Read the handler and everything it calls. Look for N+1 queries, sequential awaits
   that could run in parallel, over-fetching, and missing indexes.

For each finding, give the file and line, the expected effect, and the fix.
Rank them by expected effect. Stop and wait for me to pick which to apply.
After each fix I approve, rerun the same benchmark and report the new median.

Szablony refaktoryzacji i zestawu testów

Refaktoryzacja jest bezpieczna tylko wtedy, gdy zachowanie jest przypięte testami przed pierwszym ruchem. Dlatego szablon refaktoryzacji zabrania edycji testów: dowodem jest niezmieniony zestaw, który pozostaje zielony. Większe przebudowy opisuje strona strategie refaktoryzacji w Cursorze.

Split @src/services/user-service.ts into:
- src/services/user/authentication.ts (login, logout, token refresh)
- src/services/user/profile.ts (get, update, delete account)
- src/services/user/preferences.ts (notification and privacy settings)
Re-export every public function from src/services/user/index.ts.

Rules:
- Every exported name and signature stays identical.
- Update imports across the codebase to the new paths.
- Do NOT edit any test file. If a test fails, stop and tell me why.

Start this prompt in Plan Mode: list every file whose imports will change and stop.
After I approve the plan, I switch to Agent and you implement it.

Verify: `npx tsc --noEmit`, `npx vitest run`, `npm run lint`, and
`git diff --stat main -- '*.test.ts'`, which must print nothing.
Report: the output of all four commands.

Wygenerowany zestaw testów ma konkretną słabość: testy pisane na podstawie kodu sprawdzają, co kod robi, łącznie z jego błędami. Szablon każe agentowi udowodnić, że każdy test potrafi się wywrócić. Głębszą strategię testów znajdziesz na stronie wzorce testowania w Cursorze.

Write tests for @src/services/order-service.ts in
src/services/__tests__/order-service.test.ts.

Anchor: follow @src/services/__tests__/user-service.test.ts for structure,
mocks and factory functions.

Cover: the happy path, validation errors, permission errors, database errors,
and empty and boundary inputs. Mock the database layer and the payment and email
clients. Name each test "should <behaviour> when <condition>".

Do NOT change order-service.ts.

Verify:
1. Run `npx vitest run src/services/__tests__/order-service.test.ts`; all pass.
2. For three tests of your choice, break the behaviour each one covers in
   order-service.ts, rerun, confirm that test fails, then restore the file.
Report: the test list, both runs, and `git diff --stat` showing order-service.ts
unchanged at the end.

Szablon przeglądu przed pull requestem

Szablon przeglądu działa bez edycji i zwraca tabelę, którą przejrzysz w kilka minut. To pierwsze przejście przed przeglądem ludzkim lub automatycznym, a nie zamiennik żadnego z nich. Przegląd kodu w Cursorze, łącznie z Bugbotem na pull requeście, opisuje strona code review w Cursorze.

Review the changes on this branch: run `git diff main...HEAD`.
Do not edit any file.

Check, in this order:
1. Security: injection, missing auth checks, secrets in code or logs.
2. Correctness: unhandled promise rejections, error paths that swallow errors.
3. Tests: new code paths without a test; tests that were weakened or deleted.
4. Consistency with the patterns in the files each change touches.
5. Dependencies: imports of packages missing from package.json.

Output one table: severity (high, medium, low), file:line, problem, proposed fix.
List high-severity items first. If you find nothing in a category, say so.

Jak sprawdzić wynik szablonu bez czytania każdej linijki?

Sprawdzasz dowody, które szablon wymusił na agencie, a kod czytasz tylko tam, gdzie dowody są słabe.

Czytaj raport, nie diff. Każdy szablon kończy się raportem z wynikiem komend. Jeśli wyniku brakuje albo jest ucięty, zadanie nie jest skończone; uruchom komendę sam.
Upewnij się, że agent nie zmienił testów. Uruchom git diff --stat main -- '*.test.ts', które porównuje z gałęzią bazową zarówno zatwierdzone, jak i niezatwierdzone zmiany. Zmieniony test w zadaniu, które mówiło „Do NOT edit tests”, to czerwona flaga bez względu na powód. Ochrona wyroczni pokazuje, jak zrobić z tego mechanizm i co Cursor potrafi, a czego nie potrafi wymusić.
Pozwól CI powtórzyć bramki. Kontrola typów, lint i testy uruchamiają się ponownie w CI na pull requeście, poza sesją agenta, więc deklarowany zielony wynik zostaje niezależnie potwierdzony.
Czytaj tylko części wysokiego ryzyka. Kontrole autoryzacji, migracje i wszystko, co dotyka pieniędzy, nadal czyta człowiek. Resztę oceniasz po testach i bramkach.

Zatwierdzasz kryteria akceptacji przed pracą i dowody po niej. Pakiet dowodów określa, co musi zawierać pull request od agenta, żeby recenzent mógł zrobić to samo.

Gdzie trzymać szablony promptów Cursora: skill czy reguła?

Szablon wklejany z notatnika z czasem się rozjeżdża. Trzymaj każdy w repozytorium, w miejscu dopasowanym do tego, jak go używasz.

Zastosowanie	Miejsce	Jak się uruchamia	Współdzielony z innymi narzędziami
Zadanie, które zaczynasz ręcznie, np. „nowy endpoint”	Agent Skill (`SKILL.md`)	Podajesz nazwę skilla w prompcie	CLI `skills` instaluje ten sam folder dla Claude Code i Codeksu
Procedura, którą agent ma podjąć sam, bez proszenia	Agent Skill z precyzyjnym `description`	Agent dopasowuje opis do zadania	Tak samo
Ograniczenie przy każdej edycji określonych plików	Reguła projektu w `.cursor/rules/`	Automatycznie, według wzorca plików lub zawsze	Tylko Cursor

Przydatny podział: ograniczenia, które się nie zmieniają, np. „w trasach używaj AppError”, trafiają do reguły. Dzięki temu każdy szablon zostaje krótki i dotyczy tylko zadania.

Spakuj szablon jako Agent Skill

Agent Skill to folder z plikiem SKILL.md, którego frontmatter zawiera name i description. Agent czyta opis w każdej sesji, a treść ładuje dopiero wtedy, gdy zadanie do niego pasuje albo gdy wskażesz skill z nazwy. Trzymaj źródło w jednym folderze repozytorium, na przykład skills/api-endpoint/SKILL.md:

---
name: api-endpoint
description: Add a REST endpoint to this service with tests first, the users.ts route pattern and the standard verification commands. Use when asked to add or change an API route.
---

1. Restate the acceptance criteria as tests in src/routes/__tests__/ and run them to see them fail.
2. Implement following src/routes/users.ts and src/lib/errors.ts.
3. Never edit existing tests or existing endpoints.
4. Run `npx vitest run src/routes`, `npx tsc --noEmit` and `npm run lint`.
5. Report files changed and the output of each command.

Potem zainstaluj go dla wszystkich agentów przez CLI skills (1.7.0, sprawdzone 2026-09-26):

npx skills add ./skills --skill api-endpoint -a cursor -a claude-code -a codex -y

Flaga -y pomija pytania o potwierdzenie. CLI kopiuje skill do .agents/skills/, skąd czytają go Cursor i Codex, a .claude/skills/ dowiązuje do tej kopii dla Claude Code (skills 1.7.0, sprawdzone 2026-09-26). Kopia nie śledzi późniejszych zmian w skills/: po każdej zmianie uruchom ponownie to samo polecenie npx skills add albo trzymaj źródło w .agents/skills/api-endpoint/ i edytuj je tam. Żeby współdzielić skill między repozytoriami, opublikuj folder na GitHubie i zainstaluj go przez npx skills add OWNER/REPO --skill api-endpoint -y z tymi samymi flagami -a. Strukturę, testowanie i publikowanie skilli opisuje strona budowanie własnych skilli.

Żeby uruchomić szablon ręcznie, podaj nazwę skilla razem z zadaniem: Use the api-endpoint skill: POST /api/orders returns 201 with the created order and 400 on an invalid body.

Niektóre zespoły trzymają ręcznie uruchamiane szablony jako komendy slash w .cursor/commands/. Pluginy Cursora też mogą zawierać komendy: według dokumentacji pluginy „package rules, skills, agents, commands, MCP servers, and hooks”. Szablon, który mieszka w twoim repozytorium, zapisz jednak jako skill, żeby jeden plik obsłużył wszystkich trzech agentów.

Zamień powtarzające się ograniczenie w regułę projektu

Reguła działa bez proszenia. Utwórz w .cursor/rules/ regułę z konwencjami tras API i zawęź ją do src/routes/**/*.ts, żeby działała tylko wtedy, gdy agent edytuje pliki tras. Jej treść to krótka lista ograniczeń:

- Validate every request body with a Zod schema from src/schemas/.
- Wrap handlers in withAuth unless the route is listed as public in src/routes/public.ts.
- Return errors only through AppError from src/lib/errors.ts.

Typy reguł, zawężanie wzorcem plików i format pliku opisuje strona reguły projektu w Cursorze, a zespołową bibliotekę reguł — własne reguły i szablony.

Kiedy szablony promptów przestają działać

Wynik ignoruje twoje konwencje. Plik wzorcowy zmienił nazwę, zniknął albo nie pokazuje już aktualnego wzorca. Otwórz każde odwołanie @ w szablonie i wskaż plik, który dziś pokazałbyś nowej osobie w zespole.

Agent wykonuje pierwszą połowę szablonu i gubi resztę. Szablon niesie zbyt wiele stałych ograniczeń. Przenieś te, które dotyczą każdego zadania, do reguły, a w szablonie zostaw zadanie, wzorzec, granice, weryfikację i raport.

Raport mówi „all tests pass”, a CI jest czerwone. Agent podsumował zamiast uruchomić komendę albo uruchomił węższą komendę niż ta, którą podałeś. Wymagaj w raporcie dosłownych ostatnich linii wyniku i traktuj CI jako rozstrzygające uruchomienie.

Testy zmieniły się, żeby zadanie przeszło. Granica mówiła „Do NOT edit tests”, a agent i tak je poprawił, zwykle pod własną implementację. Odrzuć zmianę, przywróć testy przez git checkout main -- <ścieżki testów> i uruchom je ponownie. Potem zablokuj ścieżki testów zgodnie z opisem w ochronie wyroczni.

Ten sam szablon istnieje jako skill, plik w .cursor/commands/ i wklejana notatka, a wersje się różnią. Trzymaj jeden folder źródłowy, po każdej zmianie instaluj go ponownie przez npx skills add … -y (albo edytuj bezpośrednio .agents/skills/), usuń pozostałe i przeglądaj zmiany szablonów w pull requestach jak każdy inny kod.

Szablon jest zbyt sztywny do bieżącego zadania. Usuń części, które nie pasują, i dopisz to, czego zadanie potrzebuje. Jeśli tę samą poprawkę robisz trzeci raz, zaktualizuj sam szablon.

Co dalej z szablonami promptów w Cursorze

Zarządzanie kontekstem w Cursorze: wybór odwołań @, które kotwiczą szablon.
Reguły projektu w Cursorze: stałe ograniczenia, dzięki którym szablony są krótkie.
Wykonywalne kryteria akceptacji: kryteria, od których zaczyna się każdy szablon funkcji.
Ochrona wyroczni: jak sprawić, żeby „nie edytuj testów” dało się wymusić.
Ta sama biblioteka dla innych narzędzi: prompt engineering w Claude Code i prompt engineering w Codeksie.