Podstawowa konfiguracja Cursora do pracy z agentem

Podstawowa konfiguracja Cursora to zestaw ustawień repozytorium i konta, dzięki którym agent Cursora uruchamia kontrole projektu bez pytania o każdą z nich, a polecenia destrukcyjne i sekrety pozostają za zgodą człowieka. Składa się z pięciu części: jednego polecenia weryfikującego, trybu uruchamiania, reguł projektu, hooka stop ponawiającego bramkę oraz .cursorignore z Privacy Mode.

Otwierasz w Cursorze prawdziwe repozytorium, prosisz agenta o naprawę czerwonego testu, a on pyta o zgodę przed npm test, potem przed tsc, potem przed eslint. Po dziesiątym zatwierdzeniu albo się poddajesz, albo każesz mu uruchamiać wszystko, i tak właśnie agent dochodzi do git push albo czytania .env. Żadna z tych dróg nie jest konfiguracją. Obie kończą się czytaniem każdej linii diffu, żeby sprawdzić, czy zmiana działa.

Ta strona jest dla dewelopera, który w pierwszej godzinie konfiguruje Cursora na działającym repozytorium, oraz dla tech leada, który commituje wynik, żeby cały zespół dostał tę samą konfigurację. Zakłada, że Cursor jest już zainstalowany (instalacja i konfiguracja platformy).

Co sprawdziliśmy

Na 2026-10-12 dokumentacja i pomoc Cursora potwierdzają opisane tutaj tryby uruchamiania, klasyfikator Auto-review, format reguł .mdc z kluczami frontmattera oraz obsługę AGENTS.md i CLAUDE.md przez Cursora. Strony cursor.com nie dało się pobrać 26 września 2026, więc resztę zachowania ustawień (hooki, .cursorignore, chronione pliki konfiguracyjne) sprawdziliśmy w środowisku uruchomieniowym agenta, które Cursor dostarcza we własnym pakiecie @cursor/sdk 1.0.32 w npm (aktualnym wydaniu z 26 września 2026; @cursor/sdk w npm i cursor-sdk w PyPI mają 2026-10-07 wersję 1.0.37), a nazwy funkcji w dokumentacji Cursora pobranej 28 sierpnia 2026. Tego pozostałego zachowania nie sprawdzaliśmy ponownie 2026-10-12. Etykiety w menu zmieniają się między wydaniami, więc ta strona nazywa ustawienia po tym, co robią, a nie po ich dokładnym miejscu w interfejsie.

Co daje działająca konfiguracja Cursora

• Jedno polecenie npm run verify, które dowodzi poprawności zmiany i które uruchamiają agent, hook stop oraz CI.
• Tryb uruchamiania, w którym agent uruchamia to polecenie bez nadzoru, a git push, rm -rf i wszystko z sudo nadal czekają na ciebie.
• Zacommitowaną regułę projektu, która mówi agentowi o stosie, poleceniach i granicach.
• Hook stop, który ponownie uruchamia bramkę, gdy agent twierdzi, że skończył, i odsyła go do pracy, jeśli bramka nie przechodzi.
• Pięciominutowy test dymny, który dowodzi, że konfiguracja działa, zanim powierzysz jej prawdziwe zadanie.

W jakiej kolejności konfigurować Cursora?

Konfiguruj od środka na zewnątrz. Najpierw polecenie weryfikujące, bo każda kolejna warstwa na nie wskazuje. Prywatność na poziomie konta ustaw, zanim otworzysz zastrzeżony kod, bo danych, które już wyszły, nie da się cofnąć.

Warstwa	Gdzie jest	W gicie?	Właściciel
Polecenie weryfikujące	package.json (albo Makefile, pyproject.toml)	Tak	Deweloper
Tryb uruchamiania i allowlista	Cursor Settings > Agents > Approvals & Execution	Nie: per użytkownik; administrator może dodać allowlistę poleceń dla całego zespołu	Deweloper, potem tech lead
Reguły projektu	.cursor/rules/*.mdc	Tak	Tech lead
Hook stop	.cursor/hooks.json i .cursor/hooks/	Tak	Tech lead
Wykluczenia sekretów	.cursorignore	Tak	Tech lead z działem bezpieczeństwa
Privacy Mode	Twoje konto Cursora albo panel administratora zespołu	Nie	Właściciel konta lub administrator
Ustawienia edytora	.vscode/settings.json	Tak	Tech lead

Daj agentowi jedno polecenie, które dowodzi poprawności

Agent, który musi zgadywać, jak testować projekt, w każdej sesji zgaduje inaczej: dziś npx jest, jutro npm test -- --watch, które się zawiesza. Jeden skrypt usuwa zgadywanie i daje allowliście, hookowi i CI to samo polecenie do wywołania.

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "test": "vitest run",
    "verify": "npm run typecheck && npm run lint && npm run test"
  }
}

Skrypt musi kończyć się kodem różnym od zera przy każdym błędzie i nigdy nie może uruchamiać trybu watch. Jeśli projekt ma już workflow CI, verify wykonuje te same kroki co CI, więc zielona bramka lokalnie zapowiada zielony pipeline.

Prompt do skopiowania: zbuduj polecenie verify

Read package.json, any Makefile, and every workflow under .github/workflows/.
List each check that CI runs (type check, lint, unit tests, format check) and
the exact command it uses.

Then add a single "verify" script to package.json that runs those same checks
in order, fails on the first error, and never starts a watch mode. Do not
change any existing script. Run `npm run verify` once and report: the exit code,
how long it took, and every check that failed with its first error line.
Do not fix failures yet.

Czerwone verify na nietkniętym checkoucie to cenna informacja: to punkt odniesienia. Napraw go albo zapisz w regule projektu, zanim poprosisz agenta o cokolwiek innego. W przeciwnym razie agent dziedziczy błędy, których nie spowodował, i „naprawia” je w sposób, o który nie prosiłeś.

Wybierz tryb uruchamiania, w którym agent odpali bramkę

Cursor grupuje kontrolę nad terminalem w trybach uruchamiania (run modes, zob. stronę run modes w dokumentacji Cursora). Środowisko uruchomieniowe obsługuje trzy mechanizmy, które się łączą:

• Allowlistę: polecenia, które zawsze uruchamiają się bez pytania.
• Sandbox dla poleceń powłoki, który ogranicza, co polecenie może zapisać i z czym połączyć się przez sieć.
• Auto-review, które wysyła wywołania narzędzi spoza allowlisty i niedające się uruchomić w sandboksie do klasyfikatora, a ten decyduje, czy je wykonać, czy zapytać ciebie.

Dokumentacja Cursora wymienia trzy tryby uruchamiania (sprawdzone 2026-10-12), ustawiane w Settings > Agents > Approvals & Execution:

• Auto-review to zalecany tryb domyślny od Cursora 3.6 i, jak pisze Cursor, „the safest useful setup for most people”. Wywołania z allowlisty uruchamiają się od razu, pozostałe polecenia powłoki działają w sandboksie, gdy to możliwe, a wywołania niekorzystające z sandboksu trafiają do klasyfikatora Auto-review.
• Allowlist: „Actions in your allowlist run without approval.”
• Run Everything: „Every tool call runs automatically.” W CLI przełącza go /run-everything [on|off|status], a /auto-run jest aliasem.

Klasyfikator sam jest modelem. Dokumentacja Cursora mówi: „Today it uses Gemini 3.5 Flash Lite, with Claude 4.5 Haiku as the fallback”, a zablokowanie Claude 4.5 Haiku „can disable Auto-review”. Pisze też: „Auto-review is not a security boundary” i „The classifier can make mistakes”, więc w każdym trybie trzymaj polecenia nieodwracalne poza allowlistą. Cursor 3.24 dodał „Auto-review stops risky deletes for your approval”, a CLI v2026.10.08 uczyniło Auto-review ostrzejszym wobec ryzykownych usunięć.

Samouczki nadal używają starszych nazw. YOLO mode i Auto-Run to dawne nazwy, a obecnym terminem jest „run modes”. Cursor 3.5 wycofał Ask Every Time (to samo zachowanie da Allowlist z pustą allowlistą) i włączył Run in Sandbox do Allowlist z włączonym sandboksem.

Tryby uruchamiania dotyczą tylko agentów lokalnych; dokumentacja Cursora mówi: „Cloud Agents run inside their own dedicated machine, so the agent never asks you to approve an action”. Ta sama strona dokumentacji wymienia ~/.cursor/permissions.json i <project>/.cursor/permissions.json (scalane) jako pliki konfiguracyjne oraz sandbox.json dla sandboksu; poniższe kroki korzystają z ekranu ustawień.

Na planie zespołowym administrator może ustawić allowlistę poleceń dla całego zespołu, która nadpisuje twoją, więc sprawdź, co już ustawił, zanim cokolwiek zmienisz.

1. Otwórz Cursor Settings i przejdź do Agents > Approvals & Execution, gdzie są tryby uruchamiania.

2. Zostaw tryb, który wysyła wszystko spoza allowlisty do przeglądu (Auto-review) albo do sandboksu (Allowlist z włączonym sandboksem), a nie Run Everything.

3. Dodaj do allowlisty polecenia, których agent potrzebuje do weryfikacji własnej pracy. Zestaw startowy dla projektu w TypeScripcie:

   npm run verify, npm test, npm run lint, npm run typecheck, npx vitest run,
   tsc, eslint, prettier --check, git status, git diff, git log

   Dla Pythona dodaj pytest, ruff check, mypy. Dla Rusta cargo test, cargo clippy.

4. Nie dodawaj niczego nieodwracalnego: git push, git commit, git reset --hard, rm -rf, sudo, npm publish, docker rm, curl, ssh ani żadnego skryptu deploy czy migracji bazy danych.

Nie uruchamiaj wszystkiego bez przeglądu na swoim laptopie

Cursor oferuje też tryb Run Everything, który wykonuje każde polecenie bez pytania. Używaj go wyłącznie w jednorazowym środowisku z ograniczoną siecią, nigdy na maszynie z poświadczeniami, kluczami SSH czy produkcyjnym kubeconfigiem. Allowlista plus przegląd wszystkiego innego daje tę samą szybkość tam, gdzie ma ona znaczenie. Kompromisy dla wszystkich trzech agentów opisuje strona uprawnienia i sandboksy.

Prompt do skopiowania: zaproponuj allowlistę na podstawie repozytorium

List every command an agent would need to verify a change in this repository:
the scripts in package.json, the tools CI calls, and the git read commands.

Sort them into two tables:
1. Safe to run unattended: read-only, or writes only inside the working tree
   and is undone by `git restore .`.
2. Must ask first: pushes, publishes, deletes outside the working tree,
   touches the network, a database or a cloud account, or needs sudo.

For every row say why. Do not run any command in table 2. Print table 1 as a
single comma-separated line I can paste into Cursor's allowlist.

Przekaż agentowi konwencje w regule projektu

Reguły projektu to instrukcje, które agent ładuje przy każdym żądaniu. Środowisko uruchomieniowe czyta reguły z .cursor/rules/**/*.mdc, a reguła z alwaysApply: true we frontmatterze ładuje się w każdej sesji. Na start wystarczy jedna taka reguła; reguły zawężone do wzorców plików i pełny format opisuje strona reguły projektu w Cursorze. Dokumentacja Cursora mówi też, że Cursor obsługuje AGENTS.md w katalogu głównym projektu i w podkatalogach oraz że pliki CLAUDE.md czyta tak samo (sprawdzone 2026-10-12).

Reguła startowa do skopiowania: .cursor/rules/project.mdc

---
description: Stack, commands and boundaries for this repository
alwaysApply: true
---

Stack: Next.js App Router, TypeScript strict, Tailwind CSS, Drizzle ORM on
PostgreSQL, Vitest. Package manager: npm (never pnpm or yarn).

Before you say a task is done, run `npm run verify` and paste the last lines
of its output. A task is not done while verify fails.

Never edit or delete an existing test to make it pass. If a test looks wrong,
stop and explain why instead.

Use named exports. Validate all external input with zod. Handle errors from
every async call; never swallow them.

Ask before adding a dependency, changing a migration, or touching anything
under .github/ or .cursor/.

Reguła kształtuje to, co agent pisze. Nie zatrzymuje polecenia, więc nigdy nie polegaj na regule tam, gdzie granicy powinien pilnować tryb uruchamiania, hook albo .cursorignore. Pomoc Cursora nazywa plik .cursorrules w katalogu głównym „legacy and will be deprecated” (sprawdzone 2026-10-12), a środowisko SDK 1.0.32 nadal ładuje go jako regułę stosowaną zawsze, obok nowych. Przenieś jego treść do .cursor/rules/ i usuń go, bo inaczej agent czyta dwa zestawy instrukcji, które z czasem się rozjadą.

Każ Cursorowi ponowić bramkę, zanim powie „gotowe”

Reguła prosi agenta o uruchomienie verify. Hook to wymusza. Hooki Cursora to procesy, które komunikują się przez stdio w formacie JSON i mogą obserwować, blokować lub modyfikować zachowanie agenta (dokumentacja hooków Cursora, sprawdzone 28 sierpnia 2026). Hook stop uruchamia się, gdy agent kończy turę. W środowisku SDK 1.0.32 dostaje status tury i loop_count, a jeśli wypisze followup_message, agent otrzymuje tę wiadomość i pracuje dalej.

{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "node .cursor/hooks/verify-on-stop.mjs", "loop_limit": 3, "timeout": 900 }]
  }
}

// .cursor/hooks/verify-on-stop.mjs: send the agent back if the gate fails
import { readFileSync } from 'node:fs';
import { spawnSync } from 'node:child_process';

const input = JSON.parse(readFileSync(0, 'utf8'));
const done = () => { process.stdout.write('{}'); process.exit(0); };

// Only check turns the agent finished on its own, not ones you stopped.
if (input.status !== 'completed') done();

const run = spawnSync('npm run verify', { shell: true, encoding: 'utf8' });
if (run.status === 0) done();

const tail = `${run.stdout}\n${run.stderr}`.trim().split('\n').slice(-40).join('\n');
process.stdout.write(JSON.stringify({
  followup_message:
    'npm run verify failed after your last change. Fix the cause. Do not edit, ' +
    'skip or delete tests to make it pass. Output:\n' + tail,
}));

loop_limit ogranicza, ile razy hook może odesłać agenta w jednym zadaniu. Trzy wystarczą, żeby dopisać brakujący import; czwarta porażka zwykle oznacza, że podejście jest złe, i chcesz to zobaczyć. Bez loop_limit środowisko zatrzymuje się po 5 pętlach (SDK 1.0.32). Hooki przekraczają limit czasu po 60 sekundach, chyba że ustawisz timeout (w sekundach; SDK 1.0.32), a hook, który przekroczył limit, pozwala agentowi zakończyć pracę. Ustaw więc wartość wyższą niż czas najwolniejszego uruchomienia verify.

Zacommituj oba pliki. Środowisko uruchomieniowe traktuje pliki JSON w .cursor/ jako chronioną konfigurację, więc edycja hooks.json czy mcp.json przez agenta wymaga twojej zgody, zamiast dziać się po cichu. Ochrona obejmuje tylko pliki JSON: skrypt hooka verify-on-stop.mjs i skrypt verify w package.json nie są plikami chronionymi i agent może je zmienić bez pytania. Agent, który skróci verify albo rozbroi hook, dostanie zieloną bramkę, choć praca nie jest poprawna, dlatego sprawdzenie diffu opisane w sekcji gdy konfiguracja Cursora zawodzi obejmuje także te pliki. Uzupełniający strażnik, który hookami beforeShellExecution i beforeReadFile blokuje czytanie sekretów i polecenia sieciowe, opisuje strona prywatność i bezpieczeństwo w Cursorze.

Trzymaj sekrety i zastrzeżony kod poza zasięgiem agenta

O tym, co opuszcza twoją maszynę, decydują dwa ustawienia, i każde jest w innym miejscu.

• .cursorignore, commitowany w katalogu głównym repozytorium, w składni .gitignore. Narzędzia plikowe agenta odmawiają czytania pasujących ścieżek. Zacznij od .env, .env.*, *.pem, *.key, secrets/ i każdego zrzutu bazy danych.
• Privacy Mode, ustawienie na poziomie konta po stronie Cursora. Repozytorium nie może go ustawić. Na planie zespołowym potwierdź poziom w panelu administratora; na koncie prywatnym sprawdź go we własnych ustawieniach, zanim otworzysz zastrzeżony kod.

To, co gwarantuje każdy poziom, zależy od planu i umowy, więc potwierdź to na aktualnych stronach Cursora o prywatności, a nie we wpisie na blogu. Pełną konfigurację, razem z testem w CI dowodzącym, że strażnik nadal blokuje, opisuje strona prywatność i bezpieczeństwo w Cursorze.

Ustawienia edytora, dzięki którym zmiany agenta da się przejrzeć

Cursor jest zbudowany na VS Code, więc ustawienia przestrzeni roboczej w .vscode/settings.json działają i można je zacommitować dla zespołu.

{
  "files.autoSave": "afterDelay",
  "editor.formatOnSave": true,
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/.next": true,
    "**/coverage": true
  }
}

Autozapis utrzymuje pliki na dysku w zgodzie z tym, co widzisz, więc polecenia agenta nigdy nie działają na nieaktualnym buforze. Formatowanie przy zapisie obejmuje pliki, które edytujesz ty. Nie gwarantuje, że pliki zapisane przez agenta będą sformatowane, więc trzymaj prettier --check (albo tryb sprawdzania twojego formatera) w verify i niech wyłapie to bramka.

W monorepo otwieraj pakiety, nad którymi pracujesz, a nie cały katalog główny, albo zgrupuj je w pliku przestrzeni roboczej z wieloma katalogami:

{
  "folders": [
    { "path": "apps/web", "name": "Web (Next.js)" },
    { "path": "services/api", "name": "API (Express)" },
    { "path": "packages/shared", "name": "Shared types" }
  ]
}

Zapisz go jako myproject.code-workspace i otwórz przez File > Open Workspace from File. Agent może wtedy edytować wszystkie trzy katalogi w jednej rozmowie. Strategie dla większych drzew opisują strony strategie dla dużych baz kodu i praca z wieloma repozytoriami.

Jak udowodnić, że konfiguracja działa?

Nie ufaj konfiguracji, której nie widziałeś w działaniu. Najpierw zacommituj czysty stan (git status nic nie pokazuje), a potem daj agentowi małe zadanie, które przechodzi przez każdą warstwę.

Prompt do skopiowania: test dymny konfiguracji Cursora

This is a configuration test. Do the following in order and report each result.

1. Add a function `slugify(title: string): string` to src/lib/slugify.ts that
   lowercases, trims, replaces runs of non-alphanumerics with "-", and strips
   leading and trailing "-". Add three Vitest cases in src/lib/slugify.test.ts,
   including an empty string.
2. Run `npm run verify` and paste the last 10 lines of output.
3. Try to run `git push --dry-run`. Report whether you were asked for approval.
4. Try to read .env with your file tool and then with the terminal. Report
   exactly what happened each time.
5. List every command you ran and whether it needed my approval.

Konfiguracja przechodzi test, gdy wszystkie poniższe warunki są spełnione, a żaden z nich nie wymaga czytania nowego kodu:

Kontrola	Gdzie to widać	Wynik pozytywny
verify uruchomiło się bez pytania o zgodę	Lista poleceń agenta	Tak, bez pytania
Wynik bramki jest prawdziwy	Uruchom npm run verify samodzielnie	Kod wyjścia 0
git push został zatrzymany	Prośba o zgodę (albo komunikat odmowy z hooka strażnika, jeśli masz strażnika ze strony prywatność i bezpieczeństwo w Cursorze)	Pytanie lub blokada
.env nie został odczytany	Raport agenta	Odmowa przez .cursorignore (narzędzie plikowe) lub zatrzymanie z prośbą o zgodę (terminal); odczyt przez terminal bez pytania oznacza porażkę
Zmieniły się tylko oczekiwane pliki	git diff --stat	Dwa pliki
Pliki bramki bez zmian	git diff --stat -- package.json .cursor/	Brak linii
Hook stop działa	Zepsuj test ręcznie, poproś agenta, żeby „dokończył”	Agent wraca z błędem

Potem otwórz pull request z .cursor/, .cursorignore, .vscode/settings.json i skryptem verify. Tech lead przegląda ten PR z konfiguracją raz, a CI uruchamia to samo npm run verify przy każdym kolejnym PR. Od tej chwili zmianę ocenia się po wyniku bramki i krótkim podsumowaniu diffu, a nie po lekturze każdej linii; metodę opisuje strona dowody zamiast czytania kodu.

Gdy konfiguracja Cursora zawodzi

Agent nadal pyta przed każdym uruchomieniem testów. Polecenie, które uruchamia, nie pasuje do wpisu na allowliście: npx vitest to nie npm test. Dopisz do reguły projektu linię „run tests only with npm run verify” i dodaj na allowlistę dokładnie ten ciąg.

Agent uruchomił coś destrukcyjnego. Zatrzymaj agenta. Uruchom git status i git diff --stat, żeby zobaczyć szkody, potem git restore . (pliki śledzone) oraz git clean -n, a po sprawdzeniu listy git clean -f (pliki nieśledzone). Usuń polecenie z allowlisty albo zablokuj je w strażniku beforeShellExecution ze strony prywatność i bezpieczeństwo w Cursorze. Właśnie dlatego czysty stan w gicie jest przed pierwszym zadaniem. Wycofywanie zmian w edytorze opisuje strona checkpointy i gałęzie.

Hook stop nigdy się nie uruchamia albo się zapętla. Sprawdź, czy .cursor/hooks.json to poprawny JSON i czy ścieżka polecenia działa z katalogu głównego projektu. Jeśli agent wraca wciąż z tym samym błędem, loop_limit robi swoje: przeczytaj błąd sam, bo zły jest plan, a nie kod.

Hook stop przechodzi, a verify jest czerwone. Hook przekroczył limit czasu, a taki hook pozwala agentowi zakończyć pracę. Podnieś timeout w .cursor/hooks.json powyżej czasu najwolniejszego npm run verify.

Agent osłabia test albo bramkę, żeby dostać zielone światło. Po każdym zadaniu uruchom git diff --stat -- '*.test.*' '*.spec.*' package.json .cursor/ .cursorignore. Każda zmiana istniejącego testu, o którą nie prosiłeś, oznacza odrzucenie, niezależnie od wyniku bramki. To samo dotyczy skryptu hooka (.mjs) i package.json: nie są plikami chronionymi, więc każda ich zmiana, o którą nie prosiłeś, oznacza odrzucenie. Linia w regule „Never edit or delete an existing test” ogranicza to zjawisko; sprawdzenie diffu wyłapuje resztę.

Agent ignoruje regułę projektu. Upewnij się, że plik leży w .cursor/rules/, ma rozszerzenie .mdc i alwaysApply: true w poprawnym frontmatterze. Usuń pozostawiony w katalogu głównym .cursorrules, jeśli jej przeczy, i sprawdź, czy nie przeczy jej też żaden AGENTS.md ani CLAUDE.md, bo Cursor czyta oba. Więcej diagnostyki na stronie reguły projektu w Cursorze.

Członkowie zespołu dostają różne zachowanie. Wszystko, co jest w gicie, jest wspólne; tryb uruchamiania i Privacy Mode nie są. Poproś administratora o ustawienie allowlisty poleceń dla całego zespołu i dodaj .cursor/ oraz .cursorignore do CODEOWNERS, żeby zmiana konfiguracji zawsze miała recenzenta.

Co dalej po konfiguracji Cursora

Wybór modelu Jakiego modelu używać w Cursorze i kiedy go zmienić.

Reguły projektu w Cursorze Reguły zawężone, typy reguł i sprawdzanie, czy się ładują.

Konfiguracja MCP Podłącz agenta do trackera zadań, bazy danych i przeglądarki.

Twoja pierwsza funkcja Użyj konfiguracji przy prawdziwej zmianie.

Używasz więcej niż jednego agenta? Te same warstwy dla pozostałych narzędzi opisują strony konfiguracja Claude Code i konfiguracja Codeksa. Ceny i domyślne modele znajdziesz w przeglądzie modeli.