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

Muszę dodać middleware ograniczający szybkość do naszego API. Wymagania:

- Ograniczenie żądań według adresu IP
- Konfigurowalne okno (domyślnie 15 minut) i maksymalna liczba żądań (domyślnie 100)
- Zwracanie 429 Too Many Requests z nagłówkiem Retry-After po przekroczeniu
- Przechowywanie liczników w pamięci na razie (Redis później)
- Pominięcie ograniczenia szybkości dla endpointów sprawdzania zdrowia
- Uwzględnienie testów jednostkowych

Przejrzyj nasze istniejące wzorce middleware i zaproponuj plan implementacji.
Zadaj mi pytania wyjaśniające przed wygenerowaniem planu.

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

   Zaimplementuj middleware ogranicznika szybkości na podstawie planu.
   Zacznij od logiki bazowej: licznika przesuwnego okna i
   funkcji middleware. Postępuj zgodnie ze wzorcami w naszym istniejącym middleware.
   @src/middleware/

   Agent tworzy plik middleware, dopasowując się do konwencji Twojego projektu, ponieważ reguły projektu określają wzorce.

2. Dodaj konfigurację

   Dodaj konfigurację dla ogranicznika szybkości. Powinien czytać ze zmiennych
   środowiskowych z rozsądnymi wartościami domyślnymi. Postępuj zgodnie z tym,
   jak nasze inne middleware czyta konfigurację.

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

3. Podłącz do aplikacji

   Dodaj middleware ogranicznika szybkości do naszego handlera trasy API. Zastosuj go
   do wszystkich tras oprócz /health i /ready.
   @src/app.ts

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

4. Napisz testy

   Napisz testy jednostkowe dla middleware ogranicznika szybkości. Przetestuj:
   - Żądania poniżej limitu przechodzą
   - Żądania powyżej limitu otrzymują 429
   - Nagłówek Retry-After jest poprawny
   - Endpointy sprawdzania zdrowia omijają ogranicznik
   - Licznik resetuje się po upływie okna
   
   Uruchom testy po ich napisaniu i napraw wszelkie niepowodzenia.

   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

   Uruchom pełny zestaw testów i sprawdzenie typów, aby upewnić się, że niczego
   innego nie zepsułeś. Napraw wszelkie problemy.

Faza 3: Przegląd (2 minuty)

Po zakończeniu przez agenta użyj funkcji przeglądu Cursora:

1. Kliknij Review w panelu agenta
2. Wybierz Find Issues, aby uruchomić dedykowany przegląd
3. Agent analizuje 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 (Opus 4.6 dla złożonych, Sonnet 4.5 dla prostych)

Strategia commitów

Commituj po każdej udanej fazie:

# Po tym, jak moduł bazowy działa
git add src/middleware/rate-limiter.ts
git commit -m "Dodaj bazową logikę middleware ogranicznika szybkości"

# Po przejściu testów
git add src/middleware/rate-limiter.test.ts
git commit -m "Dodaj testy ogranicznika szybkości"

# Po integracji
git add src/app.ts
git commit -m "Podłącz ogranicznik szybkości do tras API"

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

Przejrzyj zmiany, które właśnie zrobiliśmy dla funkcji ogranicznika szybkości.
Czy były jakieś błędy lub odstępstwa od naszych konwencji projektu?
Jeśli tak, zaproponuj aktualizacje naszych reguł projektu Cursora w .cursor/rules/,
które zapobiegłyby tym w przyszłości.

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.