Zbuduj swoją pierwszą funkcję wspieraną przez AI

Pierwsza funkcja wspierana przez AI w Cursorze powinna przejść mały, pełny cykl: Plan bada repozytorium i zapisuje kroki, Agent wykonuje je w ograniczonym zakresie, testy dostarczają dowodów, a człowiek zatwierdza diff. Przykładowy rate limiter jest wystarczająco mały do szybkiej nauki, lecz obejmuje kilka warstw kodu i scenariusze błędów.

Ten przewodnik prowadzi przez pierwszą wieloplikową funkcję w Cursorze: od specyfikacji do przechodzących testów z trybami Plan i Agent oraz automatycznym uruchamianiem testów. Orkiestrację całego cyklu w zespole opisuje etap Build.

Efekty budowy funkcji

• Zaimplementujesz wieloplikową funkcję w trybie Agent Cursora od początku do końca.
• Płynnie przełączysz się między trybem Plan i trybem Agent w kluczowych momentach.
• Zweryfikujesz współdziałanie reguł projektu, serwerów MCP i indeksowania kontekstu.
• Wypracujesz powtarzalny proces pracy dla kolejnych zadań programistycznych.

Wybór pierwszej funkcji

Wybierz zadanie początkowe spełniające poniższe kryteria:

Wymóg	Znaczenie
Wieloplikowość (3-8 plików)	Testuje zdolność agenta do koordynowania zmian w architekturze projektu.
Jasne kryteria akceptacji	Daje Tobie i modelowi jednoznaczną definicję ukończenia zadania.
Integracja z istniejącym kodem	Sprawdza, czy reguły projektu i indeksowanie produkują spójny kod.
Brak krytycznego ryzyka	Pozwala na swobodne eksperymentowanie bez ryzyka awarii na produkcji.

Odpowiednimi przykładami są: nowy punkt końcowy API z walidacją danych wejściowych, panel ustawień, moduł obsługi webhooków lub okno preferencji powiadomień. Unikaj pełnej przebudowy uwierzytelniania lub migracji baz produkcyjnych jako pierwszego ćwiczenia.

Kompletny przepływ pracy

W ramach tego przewodnika zbudujemy middleware ogranicznika szybkości (rate limiter) przechowywany w pamięci podręcznej. Zakres obejmuje routing middleware, parsowanie konfiguracji, testy jednostkowe i obsługę błędów.

Faza 1: Plan

Aby rozpocząć planowanie, przełącz się do trybu Plan, naciskając Shift+Tab w oknie wprowadzania agenta lub wybierz Plan z selektora trybów za pomocą Cmd+..

Prompt do zaplanowania funkcji

I need to add rate limiting middleware to our API. Requirements:

- Limit requests by IP address.
- Configurable window (default 15 minutes) and max requests (default 100).
- Return 429 Too Many Requests with a Retry-After header when exceeded.
- Store counters in memory for now (Redis later).
- Skip rate limiting for health check endpoints.
- Include unit tests.

Review our existing middleware patterns and propose an implementation plan.
Ask me clarifying questions before generating the plan.

W trybie Plan Cursor wykonuje następujące operacje:

1. Przeszukuje bazę kodu w poszukiwaniu istniejących wzorców middleware i routingu.
2. Identyfikuje framework aplikacji oraz moduły formatowania błędów.
3. Sprawdza obecność istniejących bibliotek rate limitera lub konfliktujących filtrów.
4. Generuje plan implementacji ze wskazaniem lokalizacji plików, interfejsów i kolejności zadań.

Przejrzyj zaproponowany plan. Jeśli wskazuje niewłaściwy katalog lub narusza konwencje projektu, poinstruuj agenta o konieczności korekty przed generowaniem kodu.

Faza 2: Budowa

Po zaakceptowaniu planu przełącz się do trybu Agent (Shift+Tab lub Cmd+.). Wykonaj plan krok po kroku, stosując poniższą procedurę:

1. Utwórz moduł ogranicznika szybkości

   Implement the rate limiter middleware based on the plan.
   Start with the core logic: the sliding window counter and the
   middleware function. Follow the patterns in our existing middleware.
   @src/middleware/

   Agent tworzy plik middleware zgodnie z konwencjami zdefiniowanymi w .cursor/rules/.

2. Dodaj parametry konfiguracji

   Add configuration for the rate limiter. Read from environment
   variables with sensible defaults. Follow how our other middleware
   reads configuration.

   Agent analizuje istniejącą konfigurację zmiennych środowiskowych i stosuje spójne wzorce.

3. Podłącz moduł do routera aplikacji

   Add the rate limiter middleware to our API route handler. Apply it
   to all routes except /health and /ready.
   @src/app.ts

   Odwołanie @ precyzyjnie wskazuje plik wymagający integracji.

4. Napisz testy jednostkowe i integracyjne

   Write unit tests for the rate limiter middleware. Test:
   - Requests under the limit pass through
   - Requests over the limit get 429
   - The Retry-After header is correct
   - Health check endpoints bypass the limiter
   - The counter resets after the window expires
   
   Run the tests after writing them and fix any failures.

   Z włączonym automatycznym uruchamianiem agent wykonuje testy, analizuje logi błędów, poprawia kod i powtarza proces do pełnego sukcesu.

5. Zweryfikuj pełny build

   Run the full test suite and type check to verify no regressions were introduced.

Faza 3: Przegląd

Po zakończeniu generowania kodu skorzystaj z narzędzi weryfikacji w Cursorze:

1. Kliknij Review w panelu agenta.
2. Kliknij Find Issues, aby przeanalizować wprowadzone modyfikacje za pomocą Bugbota.
3. Przejrzyj uwagi z samooceny modelu i zweryfikuj pokrycie przypadków brzegowych.

Sprawdź diff gita bezpośrednio w edytorze pod kątem:

• Zakodowanych wartości na stałe, które powinny pochodzić ze zmiennych środowiskowych.
• Brakującej obsługi wyjątków przy operacjach na licznikach pamięci.
• Nieobsługiwanych przypadków brzegowych przy jednoczesnych zapytaniach współbieżnych.
• Naruszeń stylu kodu nieujętych dotychczas w regułach projektu.

W przypadku wykrycia nieobsłużonej konwencji zaktualizuj pliki .cursor/rules/, aby kolejne sesje agenta automatycznie przestrzegały nowych wytycznych.

Ślad wykonania w sesji

Poniższy zapis ilustruje typowy przebieg sesji programistycznej:

[Tryb Plan] Agent proponuje umieszczenie modułu w src/lib/.
Twoja odpowiedź: "Zgodnie z naszymi konwencjami middleware umieszczamy w src/middleware/."
Agent aktualizuje plan.

[Tryb Agent] Agent tworzy plik src/middleware/rate-limiter.ts.
Agent stosuje wzorce middleware zdefiniowane w .cursor/rules/.
Agent tworzy plik src/middleware/rate-limiter.test.ts.
Agent uruchamia testy; dwa przypadki nie przechodzą z powodu błędnego mockowania czasu.
Agent poprawia mocki zegara i ponawia próbę; wszystkie asercje przechodzą.

[Tryb Agent] Agent edytuje src/app.ts w celu rejestracji middleware.
Zauważasz, że filtr objął wszystkie trasy łącznie ze sprawdzaniem stanu zdrowia.
Twoja odpowiedź: "Wyklucz endpointy health check zgodnie z zapisami w planie."
Agent dodaje logikę pomijania wyznaczonych tras.

[Tryb Agent] Agent uruchamia pełny pakiet testów; jeden niestabilny test zgłasza błąd.
Agent analizuje ślad stosu i identyfikuje błąd jako istniejący przed rozpoczęciem prac.
Potwierdzasz brak powiązania błędu ze zmianami w rate limiterze.

Wynik: 5 zmodyfikowanych plików, 3 nowe pliki, zielone testy jednostkowe.

Wzorce dla każdej tworzonej funkcji

Kontrola przed rozpoczęciem prac

Przed przystąpieniem do implementacji zweryfikuj:

• Reguły projektu w .cursor/rules/ są zatwierdzone w gicie i aktualne.
• Indeksowanie bazy kodu przez Cursora dobiegło końca (sprawdź wpisując @codebase How is this project structured?).
• Automatyczne uruchamianie terminala (auto-run) jest włączone dla testów i linterów.
• Wybrano właściwy model (Claude Fable 5 lub Opus 5 do złożonej logiki wieloplikowej; Sonnet 5 do standardowej pracy; zobacz przewodnik doboru modeli).

Strategia commitowania

Zatwierdzaj zmiany etapami po zakończeniu każdego kroku:

# Po zaimplementowaniu logiki bazowej
git add src/middleware/rate-limiter.ts
git commit -m "Add rate limiter middleware core logic"

# Po przejściu testów jednostkowych
git add src/middleware/rate-limiter.test.ts
git commit -m "Add rate limiter tests"

# Po integracji z aplikacją
git add src/app.ts
git commit -m "Wire rate limiter into API routes"

Częste commity tworzą przejrzyste punkty przywracania stanu obok migawek (checkpoints) Cursora.

Aktualizacja reguł po zakończeniu prac

Po wdrożeniu funkcji oceń, czy agent popełnił błędy, którym mogłaby zapobiec dedykowana reguła. Jeśli tak, dodaj nową wytyczną do .cursor/rules/:

Prompt do retrospektywy po wdrożeniu

Review the changes we made for the rate limiter feature.
Identify any convention deviations or manual corrections required during the build.
Suggest updates to our rules in .cursor/rules/ to prevent these issues in the future.

Skalowanie dla dużych zadań

Dla funkcji wymagających wielodniowej pracy lub modyfikacji wielu mikrousług podziel zadanie na mniejsze sesje:

Skala zadania	Czas planowania	Długość rozmowy	Częstotliwość commitów
Mała (1-3 pliki)	2 minuty	Pojedyncza rozmowa	Po zakończeniu funkcji
Średnia (5-10 plików)	10 minut	2-3 rozmowy	Po każdym komponencie
Duża (15+ plików)	30+ minut	Wiele dedykowanych sesji	Po każdym podzadaniu

Dla złożonych funkcjonalności zapisuj plan w katalogu .cursor/plans/ i odwołuj się do niego na początku każdej nowej sesji.

Rozwiązywanie typowych problemów

• Agent modyfikuje niewłaściwe pliki: Używaj precyzyjnych odwołań @file w promptach, aby ograniczyć zakres edycji.
• Kod narusza standardy projektu: Dodaj konkretne przykłady kodu do plików .cursor/rules/*.mdc.
• Testy przechodzą, lecz kod działa błędnie: Ręcznie zweryfikuj asercje w testach. Zapytaj agenta: “Do these tests verify the acceptance criteria from the plan?”
• Agent zapętla się w próbach naprawy: Wciśnij Escape, przywróć ostatni stabilny punkt kontrolny i doprecyzuj polecenie.
• Build kończy się błędem po edycjach: Uruchom polecenie kompilacji i wklej wynik: “The build failed with the following error. Resolve the type errors without altering test expectations.”

Weryfikacja działania funkcji

Aby potwierdzić poprawność wdrożonej funkcjonalności:

1. Uruchom pakiet testów jednostkowych:

   npm test -- src/middleware/rate-limiter.test.ts

   Upewnij się, że wszystkie przypadki testowe przechodzą pomyślnie.

2. Wykonaj weryfikację typów i analizę statyczną:

   npm run typecheck && npm run lint

   Upewnij się, że narzędzia nie zwracają błędów.

3. Wykonaj lokalne zapytanie weryfikujące do serwera deweloperskiego:

   curl -i http://localhost:3000/api/test

   Potwierdź obecność nagłówków rate limitera oraz kod 429 po przekroczeniu limitu zapytań.

Kolejne kroki

AI-Native SDLC: Etap 3 - Budowa i wykonanie Opanuj tryb Plan w Composer 2.5, izolację worktree i automatyczną walidację w Cursorze

AI-Native SDLC: Etap 5 - Wdrożenie i przegląd Zintegruj Bugbota i zautomatyzowane bramki weryfikacyjne w procesie wdrażania

Obsługa błędów i przywracanie stanu Poznaj mechanizmy przywracania punktów kontrolnych i debugowania niepoprawnego kodu