Nowy projekt z agentem Cursora

Poziom 4 Poradnik Zaktualizowano 2026-10-12

Nowy projekt z agentem Cursora to siedem kroków: zamiana briefu na PRD w Plan Mode, reguły projektu przed jakimkolwiek kodem, szkielet frameworka, narzędzia z jednym poleceniem verify, dowód, że każda bramka potrafi zawieść, punkt wyjścia jako wymagane sprawdzenie w CI (required status check) i pierwsza funkcja pisana od testów. Pracę agenta potwierdzają wtedy bramki, a nie twoja lektura kodu.

Ta strona jest dla programisty, który od pustego katalogu odpowiada za nowy kod, i dla tech leada, który chce, żeby każde nowe repozytorium w zespole startowało z tego samego, sprawdzalnego punktu. Sytuacja: product manager pisze „potrzebujemy czegoś jak Trello, tylko prostszego, do codziennych standupów, prototyp na czwartek”. Nie ma specyfikacji ani makiet. Jeśli od razu każesz agentowi budować funkcje, w czwartek masz demo, a w piątek kod, którego nikt nie potrafi bezpiecznie zmienić.

Linia Cursor 3.x; aktualne wydanie na 2026-10-12 to Cursor 3.24 (2026-10-09, informacje o wydaniu Cursora). Dokumentacja Cursora wymienia cztery tryby agenta: Agent, Ask, Plan i Debug, a Shift+Tab przełącza je po kolei; Cmd+I (Ctrl+I w Windows i Linuksie) otwiera panel Agenta. Tryby uruchamiania to Auto-review, Allowlist i Run Everything, a Cursor nie wskazuje jednego domyślnego modelu (wszystko sprawdzone 2026-10-12). Plan Mode i Rules zweryfikowano w dokumentacji Cursora po raz pierwszy 28 sierpnia 2026. Wzorzec plików reguł, który wczytuje agent z SDK Cursora, odczytano z @cursor/sdk 1.0.32. Wersje pakietów sprawdzono przez npm view 26 września 2026: create-next-app 16.3.6, drizzle-orm 0.45.3, drizzle-kit 0.31.11, better-sqlite3 13.0.3, zod 4.6.5, vitest 5.0.2, @playwright/test 1.63.0.

Co daje ci start projektu w Cursorze

PRD w docs/prd.md, w którym kryteria akceptacji mają postać Given/When/Then i przekładają się na testy
Dwie reguły projektu w .cursor/rules/, napisane, zanim agent napisze choćby linię kodu, które każdemu kolejnemu czatowi mówią, jaki jest stos i jakie polecenie oznacza „gotowe”
Szkielet z samymi narzędziami i jedno polecenie npm run verify, które uruchamia lint, sprawdzenie typów, testy jednostkowe i testy end-to-end
Tabelę pokazującą, że każda bramka robi się czerwona po celowym zepsuciu; to dowód, że późniejsze zielone przebiegi coś znaczą
Pięć promptów do skopiowania, po jednym na każdy krok z udziałem agenta, oraz sposoby wyjścia z typowych awarii

Wymagania: zainstalowany i zalogowany Cursor oraz Node.js i Git w PATH. Jeśli Cursor jest dla ciebie nowy, zacznij od szybkiego startu z Cursorem. Jeśli to funkcja w istniejącym kodzie, a nie nowy projekt, skorzystaj z workflow PRD w Cursorze.

Jak krok po kroku postawić nowy projekt w Cursorze?

Kolejność jest tu najważniejsza. Każdy krok zostawia na dysku plik, który czyta następny czat, więc żaden krok nie zależy od tego, czy przetrwa długa rozmowa. Każdy krok zaczynaj w nowym czacie.

Zamień brief na PRD w Plan Mode. Plan Mode „tworzy szczegółowe plany implementacji, zanim powstanie jakikolwiek kod” (dokumentacja Cursora, sprawdzone 28 sierpnia 2026), więc agent może dopytać o brief, nie ruszając plików. Utwórz pusty folder, otwórz go w Cursorze, otwórz nowy czat, przełącz go na Plan Mode i wklej poniższy prompt, podmieniając cytowany brief na wiadomość od PM-a.

Brief from the product manager: "Something like Trello but simpler, focused on
daily standups, for one team of 8-12 people. Prototype by Thursday."

Act as the senior engineer who has to ship this in two days. Do not write code.
1. Ask me up to five questions whose answers change the scope or the data model.
   Wait for my answers before continuing.
2. Then produce a PRD for docs/prd.md, under 600 words, with these sections:
   - Problem (2-3 sentences) and the single user workflow the MVP must support
   - MVP features, at most five, each with 2-4 acceptance criteria written as
     Given/When/Then. Every criterion must be checkable by an automated test.
   - Out of scope: what we explicitly cut to hit Thursday
   - Stack: Next.js App Router with TypeScript, SQLite through Drizzle ORM,
     Zod for input validation, Vitest for unit tests, Playwright for end-to-end
     tests. Justify any change you would make to this stack in one line.
   - Data model: tables, columns and relationships
   - Risks: the two unknowns to resolve first, and how we will know they are resolved
Be opinionated. Give me decisions, not option lists.

Odpowiedz na pytania, potem wyjdź z Plan Mode i poproś agenta o zapisanie PRD w docs/prd.md. Ten plik przeczytaj uważnie: to jedyny dokument, który przeglądasz linijka po linijce, bo wszystko później jest sprawdzane właśnie względem niego.

Napisz reguły projektu, zanim powstanie kod. Reguły zapisuj jako pliki .mdc w .cursor/rules/; taki wzorzec wczytuje agent z SDK Cursora (@cursor/sdk 1.0.32) i odczytuje z nich klucze frontmattera alwaysApply, globs i description: alwaysApply: true stosuje regułę do każdego zapytania, globs stosuje ją, gdy w grze są pasujące pliki, a description pozwala agentowi samemu zdecydować. Dokumentacja Cursora mówi to samo: „Project rules live in .cursor/rules as .mdc files”, z kluczami frontmattera description, globs i alwaysApply (sprawdzone 2026-10-12). Wklej ten prompt w nowym czacie:

Read @docs/prd.md. Do not create any application code.
Create two Cursor project rules:

1. .cursor/rules/project.mdc with frontmatter `alwaysApply: true`. Under 40 lines:
   - The stack from the PRD, with major versions
   - Folder layout: src/app for routes, src/db for schema and queries,
     src/lib for domain logic, tests/e2e for Playwright specs,
     unit tests next to the source as *.test.ts
   - "Done" means `npm run verify` exits 0. Never report a task as done otherwise.
   - Never edit an existing test to make it pass; stop and explain instead.
   - Validate every request body with Zod at the route boundary.
   - Secrets go in .env.local, which is gitignored; document names in .env.example.

2. .cursor/rules/database.mdc with frontmatter `globs: src/db/**` and a one-line
   `description`. Under 25 lines: every schema change goes through a generated
   Drizzle migration, never an edit to an applied migration; foreign keys are
   declared explicitly; every query function has a unit test against a
   throwaway SQLite file.

Write concrete rules a reviewer could check, not style advice.

Polecenie verify jeszcze nie istnieje; reguła nazywa je już teraz, żeby krok 4 miał ustalony cel. Pełna składnia reguł i więcej szablonów: reguły projektu w Cursorze.

Wygeneruj szkielet frameworka sam, w terminalu. Uruchom generator z podanymi wszystkimi opcjami, żeby o nic nie pytał:
Okno terminala
```
# W folderze projektu, w terminalu Cursora albo własnym
npx create-next-app@16.3.6 . --ts --tailwind --eslint --app --src-dir --use-npm --yes
```
Generator akceptuje folder, w którym są już docs/ i .cursor/. Domyślnie zapisuje też AGENTS.md ze wskazówkami dla Next.js i inicjuje repozytorium Git (każde z nich wyłączysz przez --no-agents-md albo --disable-git). Cursor obsługuje AGENTS.md w katalogu głównym projektu i w podkatalogach, więc agent czyta także ten plik (dokumentacja Cursora, sprawdzone 2026-10-12). Gdy uruchamiasz generator sam, a nie przez agenta, krok pobierający szablon zostaje poza czatem, a wynik jest znanym szablonem, a nie wygenerowanym kodem.

Dodaj narzędzia i jedno polecenie verify, bez żadnych funkcji. Teraz agent instaluje resztę stosu i podłącza bramki. Funkcje zostaw na później: szkielet, w którym jest już pół tablicy, trudniej sprawdzić.

Read @docs/prd.md and follow the project rules.
Add the tooling for this stack. Do not build any feature from the PRD.

1. Install drizzle-orm, better-sqlite3 and zod; install drizzle-kit, vitest,
   @playwright/test and @types/better-sqlite3 as dev dependencies.
2. Create src/db/schema.ts with the PRD's tables, a drizzle.config.ts that uses
   SQLite at ./data/dev.db, and generate the first migration. Add ./data/ to .gitignore.
3. Add package.json scripts: db:generate, db:migrate, lint (eslint --max-warnings=0),
   typecheck (tsc --noEmit), test (vitest run), test:e2e (playwright test), and
   verify = lint + typecheck + test + test:e2e, in that order, failing on the first error.
   Run `npx playwright install chromium` once.
4. Add one unit test that inserts and reads a row through Drizzle against a
   temporary SQLite file, and one Playwright test that loads / and checks the
   page title. Configure Playwright to start the dev server itself.
5. Run `npm run verify` and paste the last 30 lines of its output.
Stop and show me the error if any command fails. Do not work around a failing
check by skipping or deleting it.

Zatwierdzaj każde polecenie terminala zaproponowane przez agenta, chyba że twój tryb uruchamiania pozwala mu uruchamiać polecenia bez pytania. Tryby uruchamiania w Cursorze to Auto-review (zalecany tryb domyślny od Cursora 3.6: wywołania z allowlisty uruchamiają się od razu, a pozostałe polecenia powłoki, gdy się da, w sandboksie), Allowlist (akcje z twojej allowlisty uruchamiają się bez zatwierdzenia) i Run Everything (każde wywołanie narzędzia uruchamia się automatycznie). Wybierasz jeden w Settings > Agents > Approvals & Execution, a dokumentacja Cursora opisuje je na stronie Run modes w sekcji Agent security (sprawdzone 2026-10-12).

Gdy verify przechodzi, zacommituj wszystko, co już masz. Krok 5 cofa swoje próby właśnie do tego commita, a git restore działa tylko na plikach, które Git już śledzi:

git add -A
git commit -m "Baseline: PRD, project rules, tooling and verify gate"

Udowodnij, że każda bramka potrafi zawieść. Zielony verify pierwszego dnia niczego nie dowodzi, dopóki nie zobaczysz, jak każda bramka robi się czerwona. To ten krok pozwala później ufać pracy agenta bez czytania jej w całości.

I want evidence that each check in `npm run verify` can fail. For each gate:
1. Make the smallest change that should break only that gate:
   - lint: add an unused variable in src/app/page.tsx
   - typecheck: add `export const typecheckProbe: string = 1;` to src/db/schema.ts
   - test: change the expected value in the Drizzle unit test
   - test:e2e: change the expected page title in the Playwright test
2. Run `npm run verify` and report which gate failed and its exit code.
3. Revert with `git restore <file>` and confirm `git status --short` shows no
   changes to tracked files.
Finish with a table: gate, breaking change, failed as expected (yes/no), exit code.
If a gate did not fail, stop and explain why instead of fixing it.

Odpowiedź „no” w kolumnie „failed as expected” to najcenniejszy wynik całego startu projektu. Napraw tę bramkę i uruchom prompt jeszcze raz.

Ustaw punkt wyjścia jako wymagane sprawdzenie w CI. Jeśli w kroku 5 musiałeś naprawić którąś bramkę, zacommituj tę poprawkę teraz, żeby punktem wyjścia była wersja, której bramki widziałeś czerwone. Potem dodaj w CI job, który przy każdym pull requeście uruchamia npm ci, npx playwright install --with-deps chromium i npm run verify. Instaluje tylko Chromium, tę samą przeglądarkę co lokalnie, więc CI i twój komputer testują to samo:
.github/workflows/verify.yml
```
name: verify
on: [pull_request]
permissions:
  contents: read
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: lts/*
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run verify
```
Wypchnij plik, a potem w regułach ochrony gałęzi main ustaw job verify jako wymagane sprawdzenie. Lokalny przebieg agenta to podgląd; bramką jest CI. Działa to tylko dopóki pull request agenta nie może przepisać bramki: przy pull_request GitHub uruchamia verify.yml z samego pull requesta, a npm run verify pochodzi z jego package.json. Obejmij /.github/ i package.json wpisem w CODEOWNERS z wymaganą akceptacją właściciela kodu, a każdą zmianę w nich w pull requeście z funkcją traktuj jako znalezisko. Jak uruchomić agenta Cursora wewnątrz takiego workflow, pokazuje strona Cursor w CI/CD. Commity w Gicie to punkty przywracania, nad którymi masz kontrolę; jak łączą się z checkpointami Cursora, opisuje checkpointy i gałęzie.

Zbuduj pierwszą funkcję z PRD, zaczynając od testów. Najpierw utwórz gałąź: git switch -c feat/move-card. Funkcja trafia do main przez pull request, który blokuje wymagane sprawdzenie. Otwórz nowy czat w Plan Mode i wybierz jedną funkcję MVP. Plan nazywa jej testy, zanim agent napisze kod, a każdy kamień milowy kończy się przebiegiem verify.

Read @docs/prd.md and @src/db/schema.ts. Plan the "move a card between columns"
feature. Do not edit files yet.

The plan must contain:
1. For each acceptance criterion of this feature in the PRD, the name and file
   of the test that proves it: Vitest for domain logic, Playwright for the
   drag-and-drop flow. Each test must fail before the change.
2. Files to create or change, and files you must not touch (existing tests,
   applied migrations).
3. Milestones small enough to revert on their own; each ends with
   `npm run verify` passing.
4. The simplest approach that meets the criteria for 12 users: no WebSockets
   unless a criterion requires live updates, no new services.
End with open questions instead of guessing.

Oceniaj plan względem PRD, nie własnego gustu: każde kryterium akceptacji musi mieć nazwany test. Potem go zbuduj. Najpierw napisz testy i sprawdź, że nie przechodzą, a dopiero potem implementuj. Wypchnij gałąź i otwórz pull request. Każda kolejna funkcja, łącznie z logowaniem, przechodzi przez ten sam krok.

Jak sprawdzić szkielet bez czytania każdego wygenerowanego pliku?

Linijka po linijce czytasz dwie rzeczy: PRD i dwie reguły, bo są krótkie, a wszystko inne jest sprawdzane względem nich. Resztę potwierdzają dowody:

Co chcesz wiedzieć	Dowód	Skąd się bierze
Bramki potrafią złapać błąd	Tabela bramek z kroku 5 z wartością „yes” w każdym wierszu	Prompt sprawdzający bramki
Agent stosuje reguły	W nowym czacie zapytaj: „Which command proves a change is done here, and which files may you not edit?”. Odpowiedź cytuje `npm run verify` i regułę o testach	`.cursor/rules/project.mdc`
Funkcja robi to, co mówi PRD	Każde kryterium akceptacji ma test, który przed zmianą nie przechodził, a po zmianie przechodzi	Plan z kroku 7 i przebieg testów
Zmiana nie wyszła poza zakres	`git diff --stat main...HEAD` pokazuje tylko pliki wymienione w planie	Git
Nic się nie zepsuło	Wymagane sprawdzenie w CI jest zielone na pull requeście	CI uruchamiające `npm run verify`

Akceptacja dzieli się tak samo. Programista, który odpowiada za projekt, zatwierdza PRD i reguły; gdy repozytorium ma być szablonem zespołu, zatwierdza je tech lead. Potem recenzenci czytają plan, nazwy testów i wynik CI, a do diffa zaglądają tylko tam, gdzie ten pakiet dowodów jest słaby. Jak pisać kryteria, które da się sprawdzić testem, opisuje wykonywalne kryteria akceptacji, a dlaczego przegląda się dowody zamiast diffów, wyjaśnia dowody zamiast diffów.

Co się psuje, gdy zaczynasz nowy projekt w Cursorze?

Agent sięga po przestarzałe API. Modele uczą się na latach starszego kodu, więc podsuwają wzorce Pages Routera albo starsze API biblioteki uwierzytelniania. Na przykład tag latest pakietu next-auth to 4.24.15, a wersja 5 jest pod tagiem beta (sprawdzone 26 września 2026), więc agent, który pisze kod pod wersję 5, a instaluje latest, dostaje błędy typów. Wyjście: przypnij główne wersje w project.mdc, a przy dodawaniu biblioteki podaj agentowi wersję, którą zwraca npm view <package> version.

Reguły jakby nie działały. Plik leży poza .cursor/rules/, ma inne rozszerzenie albo uszkodzony frontmatter. Loader SDK (@cursor/sdk 1.0.32) czyta .cursor/rules/**/*.mdc, więc używaj .mdc, a regułę wczyta i IDE, i SDK. Dokumentacja Cursora dodaje, że zwykły plik .md w .cursor/rules jest ignorowany przez system reguł (sprawdzone 2026-10-12). Wyjście: sprawdź, czy plik ma rozszerzenie .mdc i blok frontmattera na samej górze, a potem w nowym czacie zadaj pytanie kontrolne z tabeli powyżej. Jeśli odpowiedź nie cytuje npm run verify, reguła nie jest wczytywana.

Generator zatrzymuje się z komunikatem „contains files that could conflict”. create-next-app 16.3.6 toleruje docs/, .cursor/, .git i kilka innych plików, ale już nie na przykład package.json czy README.md, które napisałeś wcześniej. Wyjście: przenieś dodatkowy plik gdzie indziej, uruchom generator i przenieś plik z powrotem.

verify jest zielony, ale niczego nie testuje. Runner testów bez pasujących plików albo konfiguracja Playwrighta wskazująca zły port potrafią po cichu przejść lub pominąć testy, a ostrzeżenia ESLinta nie zmieniają kodu wyjścia, dlatego skrypt lint używa --max-warnings=0. Wyjście: właśnie to wyłapuje krok 5. Nie zaczynaj kroku 7, dopóki każdy wiersz tabeli bramek nie ma „yes”.

Agent zmienia test, żeby przeszedł. To dla agenta najtańsza droga do zielonego wyniku. Wyjście: linia „never edit an existing test” w project.mdc plus kontrola zakresu: jeśli git diff --stat pokazuje zmieniony plik testu, którego plan nie wymienia, odrzuć zmianę.

Architektura rośnie ponad brief. Poproszony o plan tablicy agent proponuje WebSockety, kolejkę i cache dla 12 użytkowników. Wyjście: podaj skalę w prompcie („12 users, two days, one SQLite file”) i odrzuć każdy punkt planu, którego nie wymaga żadne kryterium akceptacji. Decyzje, które zaważą na projekcie na lata, podejmuj według przewodnika projektowanie architektury z Cursorem.

Kolejne czaty przeczą wcześniejszym decyzjom. Decyzje podjęte w jednej rozmowie znikają w następnej. Wyjście: zapisuj każdą decyzję w PRD albo w regule, nie w czacie, i każdy krok zaczynaj w nowym czacie, który odwołuje się do tych plików.

Dokąd dalej po wdrożeniu pierwszej funkcji

Projektowanie schematu bazy danych z Cursorem Rozwijaj model danych z testami ograniczeń i odwracalnymi migracjami.

Test-driven development w Cursorze Zrób z nawyku „najpierw czerwony test” z kroku 7 domyślny sposób pracy nad każdą funkcją.

Spec-driven development Niech to specyfikacja, a nie kod, będzie tym, co ludzie przeglądają, w Cursorze, Claude Code i Codeksie.

Planowanie z Cursorem Pozostałe przewodniki z tej sekcji i wspólna sesja w Plan Mode.

Ten sam start projektu w innych narzędziach: nowy projekt z Codeksem oraz inicjalizacja projektu w Claude Code.