Zbuduj swoją pierwszą funkcję wspieraną przez AI

Masz skonfigurowanego Cursora, napisane reguły, działające serwery MCP i ostre umiejętności zarządzania kontekstem. Teoria się skończyła. Teraz nadszedł czas, aby udowodnić, że konfiguracja działa, budując coś prawdziwego. Ten przewodnik przeprowadzi Cię przez kompletną budowę funkcji — od wymagań do przechodzących testów — używając każdego wzorca z poprzednich sekcji. Pod koniec będziesz mieć konkretny model mentalny tego, jak rozwój wspierany przez AI faktycznie wygląda w praktyce.

Co wyniesiecie z tej sekcji

• Kompletną funkcję zbudowaną z trybem Agent Cursora od początku do końca
• Doświadczenie w przełączaniu między trybem Plan a trybem Agent w odpowiednich momentach
• Pewność, że Twoje reguły projektu, serwery MCP i strategie kontekstu działają razem
• Powtarzalny przepływ pracy, który możesz zastosować do każdej funkcji w przyszłości

Wybór Twojej funkcji

Najlepsza pierwsza funkcja ma te cechy:

Wymóg	Dlaczego ma znaczenie
Wieloplikowa (3-8 plików)	Testuje zdolność agenta do koordynowania zmian w całym projekcie
Ma jasne kryteria akceptacji	Daje Tobie i agentowi definicję “ukończone”
Dotyka prawdziwej bazy kodu	Sprawdza, czy Twoje reguły i kontekst produkują poprawny wynik
Nie jest krytyczna dla misji	Możesz eksperymentować bez ryzyka produkcyjnego

Dobre przykłady: nowy endpoint API z walidacją, strona ustawień, obsługa webhooka, interfejs użytkownika preferencji powiadomień. Złe przykłady: pełna przebudowa uwierzytelniania, migracja bazy danych na danych produkcyjnych.

Kompletny przepływ pracy

Zbudujemy middleware ograniczający szybkość dla API Express/Hono/Next.js. Jest to wystarczająco małe, aby ukończyć w 15 minut, ale dotyka wielu warstw: middleware, konfiguracja, testy i obsługa błędów.

Faza 1: Plan (5 minut)

Przełącz się do trybu Plan, naciskając Shift+Tab w polu wejściowym agenta lub wybierz Plan z wyboru trybu za pomocą Cmd+..

Skopiuj i wklej prompt, aby rozpocząć planowanie 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 any clarifying questions before generating the plan.

Agent w trybie Plan będzie:

1. Przeszukiwać bazę kodu w poszukiwaniu istniejących wzorców middleware
2. Pytać o Twój framework (Express, Hono, Next.js, itp.)
3. Sprawdzać, czy masz już ogranicznik szybkości lub podobne middleware
4. Generować plan z lokalizacjami plików, interfejsami i kolejnością implementacji

Przejrzyj plan. Jeśli proponuje tworzenie plików w niewłaściwym katalogu lub używanie wzorca, który nie pasuje do Twojego projektu, powiedz mu. Plan jest tani w zmianie — kod jest drogi do przepisania.

Faza 2: Budowa (8 minut)

Gdy plan wygląda dobrze, przełącz się do trybu Agent (Shift+Tab ponownie lub Cmd+.). Teraz pracuj nad planem zadanie po zadaniu.

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, dopasowując się do konwencji Twojego projektu, ponieważ reguły projektu określają wzorce.

2. Dodaj konfigurację

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

   Agent znajduje istniejące wzorce konfiguracji i podąża za nimi.

3. Podłącz do aplikacji

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

   Odniesienie @ mówi agentowi dokładnie, który plik zmodyfikować.

4. Napisz testy

   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 pisze testy, wykonuje je, widzi niepowodzenia, naprawia implementację i uruchamia ponownie, aż wszystko przechodzi. Obserwujesz widok różnic i interweniujesz tylko wtedy, gdy zbacza z kursu.

5. Zweryfikuj build

   Run the full test suite and type check to make sure we haven't
   broken anything else. Fix any issues.

Faza 3: Przegląd (2 minuty)

Po otrzymaniu odpowiedzi użyj funkcji Agent Review w Cursorze:

1. Kliknij Review w panelu agenta
2. Kliknij Find Issues, aby przeanalizować proponowane zmiany i zasugerować dalsze kroki
3. Agent przegląda własne zmiany i oznacza potencjalne problemy

Również samodzielnie przejrzyj diff. Szukaj:

• Wartości zakodowanych na stałe, które powinny być konfigurowalne
• Brakującej obsługi błędów (co jeśli magazyn liczników rzuci wyjątek?)
• Luk w pokryciu testów (czy przypadki brzegowe są objęte?)
• Naruszeń konwencji (cokolwiek, co Twoje reguły powinny były wychwycić, ale nie zrobiły tego)

Jeśli znajdziesz naruszenie konwencji, to jest sygnał do aktualizacji reguł projektu. Napraw kod i dodaj regułę, aby następna funkcja dostała to poprawnie automatycznie.

Co faktycznie się dzieje podczas budowy

Oto prawdziwy przepływ, łącznie z objazdami:

[Tryb Plan] Agent proponuje umieszczenie ogranicznika szybkości w src/lib/
Mówisz: "Nie, nasze middleware idzie do src/middleware/ zgodnie z naszymi konwencjami"
Agent dostosowuje plan.

[Tryb Agent] Agent tworzy src/middleware/rate-limiter.ts
Używa Twojego istniejącego wzorca middleware z reguł.
Agent tworzy src/middleware/rate-limiter.test.ts
Uruchamia testy -- 2 nie przechodzą, ponieważ mock timera jest zły.
Agent naprawia mock i uruchamia ponownie -- wszystkie przechodzą.

[Tryb Agent] Agent edytuje src/app.ts, aby dodać middleware.
Zauważasz, że zastosował do WSZYSTKICH tras łącznie ze sprawdzaniem zdrowia.
Mówisz: "Sprawdzanie zdrowia powinno być wykluczone, plan to mówił."
Agent dodaje logikę wykluczania.

[Tryb Agent] Agent uruchamia pełny zestaw testów -- jeden niepowiązany test nie przechodzi.
Agent czyta niepowodzenie, widzi, że to niestabilny test, raportuje to.
Potwierdzasz, że to istniejące, nie spowodowane Twoimi zmianami.

Gotowe. 5 plików zmienionych, 3 nowe pliki, wszystkie testy przechodzą.

To jest realistyczne. Agent nie dostaje wszystkiego idealnie za pierwszym razem, szczególnie dla pierwszej funkcji. Ale każda iteracja zajmuje sekundy, nie minuty. A błędy stają się rzadsze, gdy Twoje reguły projektu się poprawiają.

Notatka

Nie oczekuj perfekcji przy pierwszym przejściu. Oczekuj szybkiej iteracji. Wartość rozwoju wspieranego przez AI nie polega na tym, że AI natychmiast ma rację — polega na tym, że cykl od błędu do naprawy jest mierzony w sekundach, a nie godzinach.

Wzorce do zastosowania w każdej funkcji

Kontrola przed startem

Przed rozpoczęciem dowolnej funkcji sprawdź:

• Twoje reguły projektu są zatwierdzone i aktualne
• Agent może zobaczyć Twój projekt (przetestuj z “Jak jest ustrukturyzowany ten projekt?”)
• Automatyczne uruchamianie jest włączone dla testów i buildów
• Wybrałeś odpowiedni model (Fable 5 do najtrudniejszych prac wieloplikowych; Opus 4.8 dla złożonych; Sonnet 4.6 dla prostych — zob. porównanie modeli)

Strategia commitów

Commituj po każdej udanej fazie:

# After the core module is working
git add src/middleware/rate-limiter.ts
git commit -m "Add rate limiter middleware core logic"

# After tests pass
git add src/middleware/rate-limiter.test.ts
git commit -m "Add rate limiter tests"

# After integration
git add src/app.ts
git commit -m "Wire rate limiter into API routes"

To daje Ci punkty wycofania oparte na git oprócz punktów kontrolnych Cursora. Jeśli agent coś zepsuje podczas integracji, możesz cofnąć się do działającego modułu bazowego.

Aktualizacja reguł po funkcji

Po każdej funkcji zadaj sobie pytanie: “Czy agent popełnił jakieś błędy, którym reguła mogłaby zapobiec następnym razem?” Jeśli tak, zaktualizuj .cursor/rules/ i zatwierdź zmianę wraz z kodem funkcji.

Skopiuj i wklej prompt dla retrospektywy po funkcji

Review the changes we just made for the rate limiter feature.
Were there any mistakes or deviations from our project conventions?
If so, suggest updates to our Cursor project rules in .cursor/rules/
that would prevent these in the future.

Skalowanie: co się zmienia dla większych funkcji

Dla funkcji, które zajmują dni zamiast minut, przepływ pracy skaluje się przez dodanie większego planowania i częstsze resetowanie kontekstu:

Rozmiar funkcji	Czas planowania	Długość rozmowy	Częstotliwość commitów
Mała (1-3 pliki)	2 minuty	Pojedyncza rozmowa	Koniec funkcji
Średnia (5-10 plików)	10 minut	2-3 rozmowy	Na komponent
Duża (15+ plików)	30+ minut	Wiele rozmów	Na zadanie

Dla dużych funkcji zapisz swój plan w .cursor/plans/ i odnośnikuj go w każdej nowej rozmowie. Każda rozmowa obsługuje jedno zadanie z planu.

Gdy coś się psuje

Agent ciągle modyfikuje niewłaściwe pliki: Twój prompt jest zbyt niejasny. Użyj odniesień @, aby określić dokładnie, które pliki modyfikować.

Wygenerowany kod nie podąża za Twoimi wzorcami: Twoje reguły projektu są brakujące lub zbyt niejasne. Dodaj konkretne przykłady do swoich reguł.

Testy przechodzą, ale funkcja nie działa: Testy testują niewłaściwą rzecz. Przejrzyj asercje testów ręcznie. Zapytaj agenta: “Czy te testy faktycznie weryfikują wymagania z planu?”

Agent schodzi z kursu i nie może się odzyskać: Naciśnij Escape, przywróć punkt kontrolny, rozpocznij nową rozmowę i daj mu bardziej konkretny prompt.

Build psuje się po zmianach agenta: Uruchom tsc lub polecenie budowania. Powiedz agentowi: “Build się zepsuł po Twoich zmianach. Napraw wszystkie błędy.” Z włączonym automatycznym uruchamianiem będzie iterował, aż build przejdzie.

Co dalej

Obsługa błędów i odzyskiwanie Wzorce debugowania, odzyskiwanie punktów kontrolnych i strategie na wypadek, gdy AI generuje zepsuty kod.