Jak AI godzi wydajność, czytelność i prostotę w kodzie

Co oznacza pogodzenie wydajności, czytelności i prostoty\n\nZanim ocenisz, czy AI coś „zbalansowało”, warto nazwać, o jaki rodzaj kodu chodzi.\n\nLogika aplikacji to kod wyrażający reguły i przepływy produktu: sprawdzenia uprawnień, decyzje cenowe, przejścia stanów zamówień, uprawnienia i „co się dzieje dalej”. To część najbardziej powiązana z zachowaniem biznesowym i najczęściej podlegająca zmianom.\n\nKod infrastruktury to instalacja: połączenia z bazą, serwery HTTP, kolejki wiadomości, konfiguracja wdrożenia, pipeline’y logowania i integracje. Jest ważny, ale zwykle nie to w nim kodujesz jako główne reguły aplikacji.\n\n### Trzy cele — i co one w praktyce znaczą\n\nWydajność oznacza, że kod wykonuje zadanie używając rozsądnego czasu i zasobów (CPU, pamięć, wywołania sieciowe, zapytania do BD). W logice aplikacji problemy wydajnościowe często wynikają z dodatkowego I/O (za dużo zapytań, powtarzające się wywołania API) bardziej niż z wolnych pętli.\n\nCzytelność oznacza, że współpracownik może dokładnie zrozumieć, co kod robi, dlaczego to robi i gdzie wprowadzić zmianę — bez „debugowania w myślach” przez godzinę.\n\nProstota oznacza mniejszą liczbę poruszających się elementów: mniej abstrakcji, mniej wyjątkowych przypadków i mniej ukrytych efektów ubocznych. Prosty kod łatwiej testować i bezpieczniej modyfikować.\n\n### Dlaczego te cele się ścierają w rzeczywistych projektach\n\nPoprawa jednego celu zwykle obciąża pozostałe.\n\nCache może przyspieszyć, ale dodaje reguły unieważniania. Silna abstrakcja usuwa duplikację, ale utrudnia śledzenie przepływu. Mikrooptymalizacje zmniejszają czas działania, jednocześnie zaciemniając intencję.\n\nAI też potrafi „przesadzić”: może zaproponować uogólnione wzorce (factory, strategy, rozbudowane helpery), gdy prostsza funkcja była jaśniejsza.\n\n### Jak wygląda „wystarczająco dobre”\n\nDla większości zespołów „wystarczająco dobre” to:\n\n- Jasny przepływ sterowania i nazewnictwo, z minimalną abstrakcją\n- Wydajność spełniająca aktualne SLA, z uniknięciem oczywistych wąskich gardeł (zwłaszcza dodatkowych zapytań do BD/API)\n- Proste miejsca do testowania, tak aby zmiany można było wprowadzać bezpiecznie\n\nBalans zwykle oznacza wypuszczenie kodu łatwego do utrzymania najpierw, a dopiero potem komplikowanie go, gdy pomiary (lub incydenty) to uzasadnią.\n\n## Jak AI zwykle wybiera strukturę kodu\n\nAI nie „decyduje” o strukturze tak jak inżynier. Przewiduje następne najbardziej prawdopodobne tokeny na podstawie promptu i wzorców, które widziało. To oznacza, że kształt kodu zależy w dużej mierze od tego, o co prosisz i co pokazujesz.\n\n### Optymalizuje to, o co prosisz (i jakie przykłady dasz)\n\nJeśli poprosisz o „najszybsze rozwiązanie”, często dostaniesz dodatkowe cache, wczesne wyjścia i struktury danych upraszczające dostęp — nawet gdy zysk jest marginalny. Jeśli poprosisz o „czystość i czytelność”, zwykle otrzymasz bardziej opisowe nazwy, krótsze funkcje i jaśniejszy przepływ sterowania.\n\nPodanie przykładu lub istniejącego stylu kodu działa jeszcze silniej niż przymiotniki. Model będzie odtwarzał:\n\n- konwencje nazewnictwa i granice funkcji\n- wzorce obsługi błędów (wyjątki vs. wartości zwracane)\n- preferowane abstrakcje (helpery, serwisy, repozytoria)\n\n### Typowe tryby awarii, na które warto uważać\n\nPonieważ AI dobrze składa wzorce, może zbaczać w „przemyślane” rozwiązania, które wyglądają imponująco, ale trudniej je utrzymać:\n\n- Nadmierne zaprojektowanie: niepotrzebne warstwy, factory, interfejsy lub uogólnione helpery dla prostego zadania\n- Skomplikowany kod: gęste jednowierszówki, zawiłe comprehensions lub intensywne łańcuchowanie funkcyjne, które ukrywa intencję\n- Przedwczesna optymalizacja: mikrooptymalizacje (ręczne cache, własne sortowania) przed wykonaniem pomiarów\n\n### Dane treningowe kształtują styl i domyślne zachowania\n\nAI uczy się z mieszanki kodu: czystych bibliotek, pośpiesznie napisanego kodu aplikacji, rozwiązań z rozmów kwalifikacyjnych i przykładów frameworków. Ta różnorodność tłumaczy, dlaczego widzisz niespójne wybory struktury — czasem idiomatyczne, czasem nadmiernie abstrakcyjne, czasem niepotrzebnie rozwlekłe.\n\n### Ludzie wciąż odpowiadają za finałowy kompromis\n\nModel może zaproponować opcje, ale nie zna wszystkich Twoich ograniczeń: poziomu zespołu, konwencji bazy kodu, obciążenia produkcji, terminów i kosztu utrzymania w długiej perspektywie. Traktuj wyjście AI jako szkic. Twoim zadaniem jest wybrać kompromis, którego naprawdę chcesz — i upraszczać, aż intencja będzie oczywista.\n\n## Trójkąt kompromisów w codziennej logice aplikacji\n\nCodzienna logika aplikacji żyje wewnątrz trójkąta: wydajność, czytelność i prostota. Kod generowany przez AI często wygląda „rozsądnie”, bo próbuje pogodzić wszystkie trzy — ale rzeczywiste projekty zmuszają do wyboru, który wierzchołek jest najważniejszy dla konkretnej części systemu.\n\n### Kompromisy, które rozpoznasz od razu\n\nKlasycznym przykładem jest cache vs. przejrzystość. Dodanie cache przyspiesza wolne żądanie, ale pojawiają się pytania: kiedy cache wygasa? Co się dzieje po aktualizacji? Jeśli reguły cache nie są oczywiste, przyszli czytelnicy będą go źle używać lub „naprawiać” nieprawidłowo.\n\nInne napięcie to abstrakcje vs. kod bezpośredni. AI może wydzielać helpery, wprowadzać ogólne narzędzia czy dodawać warstwy („service”, „repository”, „factory”), by wyglądać estetycznie. Czasem to poprawia czytelność; czasem ukrywa regułę biznesową za pośrednictwem i utrudnia proste zmiany.\n\n### Kiedy mikrooptymalizacje szkodzą zrozumieniu\n\nDrobne modyfikacje — prealokacja tablic, zgrabne jednowierszówki, unikanie zmiennej tymczasowej — mogą zaoszczędzić milisekundy, a kosztować minuty ludzkiej uwagi. Jeśli kod jest w ścieżce niekrytycznej, takie mikrooptymalizacje zwykle się nie opłacają. Wygrywa jasne nazewnictwo i prosty przepływ.\n\n### Kiedy „proste” staje się wolne przy skali\n\nZ drugiej strony, najprostsze podejście może się zawalić pod obciążeniem: zapytania w pętli, ponowne obliczanie tej samej wartości, pobieranie zbyt wielu danych. Co wygląda dobrze dla 100 użytkowników, przy 100 000 może być kosztowne.\n\n### Praktyczna zasada\n\nZacznij od najbardziej czytelnej wersji, która jest poprawna. Optymalizuj tylko tam, gdzie masz dowody (logi, profilowanie, rzeczywiste metryki opóźnień), że kod jest wąskim gardłem. Dzięki temu utrzymasz zrozumiałość wyjścia AI, a jednocześnie poprawisz tam, gdzie to ma znaczenie.\n\n## Jak promptować AI, by wygenerować właściwą logikę\n\nAI zwykle robi dokładnie to, o co prosisz — dosłownie. Jeśli prompt jest nieprecyzyjny (np. „przyspiesz to”), może wynaleźć złożoność, której nie potrzebujesz, albo zoptymalizować niewłaściwy fragment. Najlepszym sposobem sterowania wynikiem jest opisanie jak wygląda dobre rozwiązanie i czego nie chcesz.\n\n### Zacznij od kryteriów akceptacji (i non-goals)\n\nNapisz 3–6 konkretnych kryteriów akceptacji, które da się szybko sprawdzić. Dodaj non-goals, żeby zapobiec „pomocnym” dygresjom.\n\nPrzykład:\n\n- Kryteria akceptacji: „Musí zwracać wyniki w <200ms dla 10k rekordów; błędy przyjazne użytkownikowi; funkcje poniżej ~40 linii.”\n- Non-goals: „Brak warstwy cache; brak nowych zależności; brak zmian schematu BD.”\n\n### Określ ograniczenia, których model nie odgadnie\n\nWydajność i prostota zależą od kontekstu, więc podaj znane ograniczenia:\n\n- cele latencji (p95, p99 jeśli są)\n- rozmiar danych i oczekiwany wzrost\n- współbieżność (pojedynczy użytkownik vs wiele równoległych żądań)\n- limity pamięci (serverless, urządzenia mobilne itp.)\n\nNawet przybliżone liczby są lepsze niż brak.\n\n### Poproś o „najpierw prostą wersję” oraz „wersję zoptymalizowaną”\n\nZamów dwie wersje jasno. Pierwsza powinna priorytetyzować czytelność i prosty przepływ. Druga może dodać rozważne optymalizacje — ale tylko takie, które pozostają wytłumaczalne.\n\ntext\nWrite application logic for X.\nAcceptance criteria: ...\nNon-goals: ...\nConstraints: latency ..., data size ..., concurrency ..., memory ...\nDeliver:\n1) Simple version (most readable)\n2) Optimized version (explain the trade-offs)\nAlso: explain time/space complexity in plain English and note any edge cases.\n\n\n### Wymagaj wyjaśnień i złożoności prostym językiem\n\nPoproś model o uzasadnienie kluczowych wyborów („dlaczego ta struktura danych”, „dlaczego taki porządek rozgałęzień”) i oszacowanie złożoności bez żargonu. Ułatwia to przegląd, testowanie i podjęcie decyzji, czy optymalizacja jest warta dodanej złożoności.\n\n## Wzorce, które utrzymują czytelność generowanej przez AI logiki\n\nCzytelna logika aplikacji rzadko zależy od wymyślnej składni. Chodzi o to, by następna osoba (często przyszłe ja) zrozumiała, co kod robi na pierwszy rzut oka. Gdy używasz AI do generowania logiki, kilka powtarzalnych wzorców daje najlepsze rezultaty.\n\n### Trzymaj funkcje małe i jednozadaniowe\n\nAI ma skłonność do „pomocnego” łączenia walidacji, transformacji, persystencji i logowania w jednej dużej funkcji. Naciskaj na mniejsze jednostki: jedna funkcja waliduje wejście, druga oblicza wynik, trzecia zapisuje.\n\nPrzydatna zasada: jeśli nie potrafisz opisać zadania funkcji w jednym krótkim zdaniu bez „i”, prawdopodobnie robi za dużo.\n\n### Preferuj prosty przepływ sterowania\n\nCzytelna logika faworyzuje oczywiste rozgałęzienia zamiast sprytnego zagęszczania. Jeśli warunek jest ważny, zapisz go jako czytelny blok if, a nie jako zagnieżdżony ternary lub łańcuch trików boolean.\n\nGdy widzisz wyjście AI typu „rób wszystko w jednym wyrażeniu”, poproś o „early returns” i „guard clauses”. To często redukuje zagnieżdżenia i uwidacznia ścieżkę szczęścia.\n\n### Nazwy jakimi posłuży się współpracownik\n\nZnaczące nazwy biją „uniwersalne helpery”. Zamiast processData() lub handleThing() używaj nazw, które zakodują intencję:\n\n- calculateInvoiceTotal()\n- isPaymentMethodSupported()\n- buildCustomerSummary()\n\nUważaj też na zbyt ogólne narzędzia (np. mapAndFilterAndSort()): mogą ukrywać reguły biznesowe i utrudniać debugowanie.\n\n### Komentarze o intencji, nie o mechanice\n\nAI potrafi generować obszerne komentarze, które powtarzają kod. Zachowuj komentarze tylko tam, gdzie intencja nie jest oczywista: dlaczego dana reguła istnieje, jakiego przypadku brzegowego chronisz, jakich założeń trzeba przestrzegać.\n\nJeśli kod potrzebuje wielu komentarzy, potraktuj to jako sygnał do uproszczenia struktury lub poprawy nazewnictwa — nie jako zachętę do dopisywania słów.\n\n## Wybory projektowe sprzyjające prostocie\n\nProstota rzadko oznacza „mniej kodu za wszelką cenę”. Chodzi o pisanie kodu, który współpracownik może pewnie zmienić za tydzień. AI może tu pomóc — jeśli poprowadzisz je ku wyborom utrzymującym prostotę rozwiązania.\n\n### Zacznij od najprostszej struktury danych, która działa\n\nAI często przeskakuje do sprytnych struktur (mapy map, klasy, zagnieżdżone generyki), bo wyglądają „zorganizowanie”. Sprzeciwiaj się temu. Dla większości logiki aplikacji proste listy/obiekty są łatwiejsze do rozumienia.\n\nJeśli masz mały zbiór elementów, lista z czytelnym filter/find często jest bardziej czytelna niż budowanie indeksu przedwcześnie. Wprowadź mapę/słownik dopiero, gdy wyszukiwania staną się istotne i powtarzalne.\n\n### Ogranicz warstwy abstrakcji, dopóki nie ma powtarzalnej potrzeby\n\nAbstrakcje wyglądają ładnie, ale ich nadmiar ukrywa zachowanie. Przy zamawianiu kodu od AI preferuj „jedną warstwę pośredniczącą”: małą funkcję, jasny moduł i bezpośrednie wywołania.\n\nPrzydatna zasada: nie twórz interfejsu, factory i systemu pluginów, żeby rozwiązać pojedynczy przypadek. Poczekaj na drugi lub trzeci wariant, a potem refaktoryzuj z pewnością.\n\n### Kompozycja zamiast głębokich drzew dziedziczenia\n\nDrzewka dziedziczenia utrudniają odpowiedź na pytanie: „Skąd pochodzi to zachowanie?” Kompozycja utrzymuje zależności widoczne. Zamiast class A extends B extends C wolisz małe komponenty, które jawnie łączysz.\n\nW promptach możesz napisać: „Unikaj dziedziczenia, chyba że jest stabilny kontrakt; preferuj przekazywanie helperów/usług jako parametrów.”\n\n### Używaj znanych wzorców, które zespół już rozumie\n\nAI może zaproponować wzorce technicznie poprawne, ale kulturowo obce. Znajomość jest funkcją. Poproś o rozwiązania pasujące do Twojego stacku i konwencji (nazewnictwo, struktura folderów, obsługa błędów), żeby wynik naturalnie wszedł do przeglądu i utrzymania.\n\n## Wydajność bez utraty czytelności\n\nPrace nad wydajnością idą źle, gdy optymalizujesz niewłaściwą rzecz. Najlepszy „szybki” kod to często po prostu odpowiedni algorytm zastosowany do realnego problemu.\n\n### Wybierz właściwy algorytm przed strojeniem\n\nZanim poprawisz pętle czy jednowierszówki, upewnij się, że używasz sensownego podejścia: mapa skrótu zamiast powtarzanych wyszukiwań liniowych, set do sprawdzeń przynależności, jedno przejście zamiast kilku skanów. Przy zamówieniu pomocy AI bądź konkretny w ograniczeniach: oczekiwany rozmiar wejścia, czy dane są posortowane i co oznacza „wystarczająco szybkie”.\n\nProsta zasada: jeśli złożoność jest nieodpowiednia (np. O(n²) na dużych listach), żadna mikrooptymalizacja tego nie uratuje.\n\n### Mierz najpierw (na realnych danych)\n\nNie zgaduj. Użyj podstawowego profilowania, lekkich benchmarków i — co najważniejsze — realistycznych wolumenów danych. Kod generowany przez AI może wyglądać efektywnie, a ukrywać kosztowne operacje (powtarzane parsowanie, dodatkowe zapytania).\n\nUdokumentuj, co zmierzyłeś i dlaczego to ma znaczenie. Krótki komentarz typu „optymalizowano pod 50k elementów; poprzednia wersja kończyła się w ~2s” pomaga przyszłym programistom nie cofać optymalizacji.\n\n### Optymalizuj tylko gorące ścieżki\n\nPozwól większości kodu być nudnym i czytelnym. Skoncentruj wysiłek wydajnościowy tam, gdzie rzeczywiście spędza się czas: ciasne pętle, serializacja, wywołania do BD, granice sieciowe. W innych miejscach preferuj czytelność ponad sprytem, nawet jeśli to kilka milisekund wolniej.\n\n### Ostrożnie stosuj cache, batching i indeksowanie\n\nTechniki te dają duże korzyści, ale zwiększają koszt mentalny.\n\n- Cache: zapisz reguły unieważniania i TTL w komentarzu przy kodzie.\n- Batching: wyjaśnij rozmiar batcha i obsługę błędów.\n- Indeksy: zanotuj, które zapytania korzystają i jaki jest koszt zapisu.

Jeśli AI sugeruje któreś z tych narzędzi, poproś o „dlaczego”, kompromisy i krótki opis, kiedy usunąć optymalizację.\n\n## Testowanie jako siatka bezpieczeństwa dla logiki generowanej przez AI\n\nAI potrafi szybko wygenerować „rozsądną” logikę aplikacji, ale nie wyczuje kosztu subtelnego błędu w produkcji ani nie odczuje zamieszania wynikającego z niejasnego wymogu. Testy są buforem między pomocnym szkicem a niezawodnym kodem — szczególnie gdy później refaktoryzujesz dla wydajności lub upraszczasz zagraconą funkcję.\n\n### Proś o testy razem z kodem\n\nKiedy prosisz o implementację, poproś również o testy. Otrzymasz klarowniejsze założenia i lepiej zdefiniowane interfejsy, ponieważ model musi udowodnić zachowanie, a nie tylko je opisać.\n\nPraktyczny podział:\n\n- dla czystych reguł biznesowych (cennik, sprawdzenia uprawnień, walidacja)\n- dla logiki „klejącej” (zapytania BD, kolejki, klienci HTTP), z użyciem fake’ów lub kontenerów testowych\n\n### Pokryj przypadki brzegowe, które AI często pomija\n\nAI ma tendencję pisać ścieżkę „happy path” jako pierwszą. Uczyń przypadki brzegowe jawne w planie testów, aby później nie polegać na pamięci czy wiedzy plemiennej. Typowe: \n- Puste wejścia, brakujące pola, / \n- Nieoczekiwane typy lub źle sformatowane dane\n- Timeouts, retry, częściowe błędy (szczególnie przy wywołaniach sieciowych)\n- Idempotencja (bezpieczne ponowne uruchomienia) i duplikaty zdarzeń\n\n### Używaj testów tabelarycznych lub property-based dla reguł biznesowych\n\nLogika biznesowa często ma wiele drobnych wariantów („jeśli użytkownik jest X i zamówienie jest Y, to Z”). utrzymują to czytelne, listując wejścia i oczekiwane wyjścia w kompaktowej macierzy.\n\nJeśli reguła ma inwarianty („suma nie może być ujemna”, „rabat nigdy nie przekracza podsumowania”), mogą eksplorować więcej przypadków niż ręcznie napisane testy.\n\n### Testy chronią refaktory i optymalizacje\n\nGdy masz dobre pokrycie, możesz bezpiecznie:\n\n- Zastępować zagnieżdżone warunki jaśniejszą strukturą\n- Dodać cache lub batching dla wydajności\n- Wydzielać helpery bez zmiany zachowania\n\nTraktuj przechodzące testy jako kontrakt: jeśli poprawisz czytelność lub szybkość, a testy nadal przechodzą, najpewniej zachowałeś poprawność.\n\n## Lista kontrolna podczas code review logiki napisanej przez AI\n\nAI może wygenerować „prawdopodobny” kod, który wygląda czysto na pierwszy rzut oka. Dobry przegląd skupia się mniej na tym, czy było to napisać, a bardziej na tym, czy to właściwa logika dla Twojej aplikacji.\n\n### Szybka lista kontrolna\n\nUżyj tego jako szybkiego pierwszego przeglądu przed debatą o stylu czy mikrooptymalizacjach:\n\n- Czy odpowiada wymaganiu i przypadkom brzegowym (puste wejścia, null, duplikaty, strefy czasowe, zaokrąglenia)? Czy błędy są obsłużone celowo?\n- Czy współpracownik po jednym przeczytaniu potrafi wyjaśnić przepływ? Czy nazwy są specyficzne ( vs )?\n- Czy logika jest bardziej skomplikowana niż konieczne (zagnieżdżone warunki, gęste jednowierszówki, przedwczesne abstrakcje)?\n- Czy AI powtórzyło logikę w wielu gałęziach zamiast ją scentralizować?\n\n### Uważaj na ukrytą złożoność\n\nAI często „rozwiązuje” problem, grzebiąc złożoność w szczegółach, które łatwo przeoczyć:\n\n- Zamień na stałe lub enumy i dodaj komentarz tylko wtedy, gdy powód nie jest oczywisty.\n- Uważaj na kod mutujący współdzielone obiekty, aktualizujący zmienne w wielu gałęziach lub polegający na implicytnych wartościach domyślnych.\n- Sprawdź, czy helpery „czyste” nie wykonują logowania, wywołań sieciowych, zapisów do BD lub zmian globalnej konfiguracji.\n\n### Spójność ważniejsza niż spryt\n\nUpewnij się, że wynik przestrzega konwencji projektu (lint, struktura plików, typy błędów). Jeśli nie, popraw to teraz — niespójności stylu spowalniają refaktory i utrudniają przeglądy.\n\n### Postanów, co zatrzymać, a co przepisać ręcznie\n\nZachowaj kod AI, gdy jest . Przepisz, gdy widzisz:\n\n- niejasną intencję (musiałbyś dodać komentarze, by zrozumieć)\n- skomplikowany przepływ sterowania (flagi, wczesne wyjścia wszędzie, głębokie zagnieżdżenia)\n- «uniwersalne» abstrakcje, które nie pasują do domeny\n\nJeśli robisz takie przeglądy regularnie, szybko rozpoznasz, które prompty dają przeglądalny kod — potem dostroisz prompt zanim wygenerujesz kolejny raz.\n\n## Bezpieczeństwo i niezawodność\n\nGdy AI generuje logikę aplikacji, często optymalizuje „ścieżkę szczęścia”. To może pozostawić luki tam, gdzie żyją bezpieczeństwo i niezawodność: przypadki brzegowe, tryby awaryjne i domyślne wartości wygodne, ale niebezpieczne.\n\n### Nie ujawniaj sekretów (w promptach ani logach)\n\nTraktuj prompt jak komentarz w publicznym repozytorium. Nigdy nie wklejaj kluczy API, tokenów produkcyjnych, danych klientów ani wewnętrznych URL-i. Pilnuj też outputu: AI może zasugerować logowanie całych requestów, nagłówków lub obiektów wyjątków zawierających poświadczenia.\n\nProsta zasada: loguj identyfikatory, nie całe payloady. Jeśli musisz logować payloady do debugowania, domyślnie je redaguj i dołącz gate za flagą środowiskową.\n\n### Waliduj wejścia i zwracaj przewidywalne błędy\n\nKod z AI czasem zakłada dobrze sformatowane wejścia. Uczyń walidację explicite na granicach (handlery HTTP, konsumenci wiadomości, CLI). Konwertuj nieoczekiwane wejścia na spójne błędy (np. 400 vs 500) i projektuj retry, aby były bezpieczne, stawiając na idempotencję.\n\nNiezawodność to także czas: dodaj timeouts, obsłuż null-e i zwracaj strukturalne błędy zamiast niejasnych stringów.\n\n### Uważaj na niebezpieczne domyślne ustawienia\n\nGenerowany kod może zawierać skróty wygodne, ale ryzykowne:\n\n- Szerokie uprawnienia (wildcard IAM, zakresy „admin”)\n- Słabe szyfrowanie (własne hashowanie, przestarzałe algorytmy, brak soli)\n- Brak sprawdzeń autoryzacji (ufanie przesłanym przez klienta identyfikatorom użytkownika)\n\nProś o konfiguracje w trybie least-privilege i umieszczaj sprawdzenia autoryzacji blisko dostępu do danych, które mają chronić.\n\n### Wymagaj założeń bezpieczeństwa i trybów awarii\n\nPraktyczny wzorzec promptu: „Wyjaśnij założenia bezpieczeństwa, model zagrożeń i co się dzieje, gdy zależności zawiodą.” Chcesz, żeby AI stwierdziło np.: , itp.\n\nJeśli te założenia nie zgadzają się z rzeczywistością, kod jest błędny — nawet jeśli jest szybki i czytelny.\n\n## Utrzymywalność w czasie: kiedy refaktoryzować, a kiedy przestać\n\nAI szybko generuje czystą logikę, ale utrzymywalność zdobywa się przez miesiące: zmiany wymagań, nowi członkowie zespołu i rosnący nierównomiernie ruch. Celem nie jest bezkończyste „udoskonalanie” kodu — chodzi o utrzymanie go zrozumiałym, dopóki spełnia realne potrzeby.\n\n### Refaktoryzuj, gdy frikcja jest mierzalna\n\nRefaktoryzacja ma sens, gdy potrafisz wskazać konkretny koszt:\n\n- Wprowadzenie nowej funkcji zajmuje zauważalnie dłużej, bo logika jest splątana lub zdublowana.\n- Błędy skupiają się wokół tego samego modułu, bo odpowiedzialności są niejasne.\n- Prace nad wydajnością są zablokowane, bo kod ukrywa, gdzie spędza się czas.\n\nJeśli nic z tego nie występuje, powstrzymaj się od „sprzątania dla samego sprzątania”. Czasem duplikacja kosztuje mniej niż wprowadzenie abstrakcji, które mają sens tylko w Twojej głowie.\n\n### Dokumentuj „dlaczego”, nie tylko „co”\n\nKod wygenerowany przez AI często wygląda rozsądnie, ale przyszłe ja potrzebuje kontekstu. Dodaj krótkie notatki wyjaśniające kluczowe decyzje:\n\n- dlaczego dana sekcja była zoptymalizowana (co było wolne)\n- dlaczego coś zostało uogólnione (co się powtarzało)\n- dlaczego zachowano prostsze podejście (złożoność nie się opłacała)\n\nTrzymaj to blisko kodu (docstring, README lub krótka notatka w /docs) i powiąż z ticketami, jeśli je masz.\n\n### Dodaj lekkie diagramy dla krytycznych przepływów\n\nDla kilku kluczowych ścieżek, mały diagram zapobiega nieporozumieniom i zmniejsza ryzyko przypadkowych przepisów:\n\n\n\nSą szybkie w utrzymaniu i pomagają recenzentom zobaczyć, gdzie umieścić nową logikę.\n\n### Zapisz „znane limity” i plany refaktora\n\nSpisz oczekiwania operacyjne: progi skalowalności, spodziewane wąskie gardła i kolejne kroki. Przykład: „Działa do ~50 requestów/sec na jednej instancji; wąskie gardło to ewaluacja reguł; następny krok to cache.”\n\nTo zamienia refaktoryzację w zaplanowaną odpowiedź na wzrost użycia, zamiast na domysły, i zapobiega przedwczesnym optymalizacjom, które szkodzą czytelności.\n\n## Praktyczny workflow, żeby utrzymać wyjście AI szybkie i zrozumiałe\n\nDobry workflow traktuje wyjście AI jako pierwszy szkic, nie gotową funkcję. Celem jest szybko uzyskać coś poprawnego i czytelnego, a potem poprawiać wydajność tylko tam, gdzie naprawdę ma to znaczenie.\n\nTu też narzędzia mają znaczenie. Jeśli używasz platformy typu vibe-coding, jak (chat-to-app z trybem planowania, eksportem źródła i snapshotami/rollback), stosujesz te same zasady: najpierw prosty, czytelny kod logiki aplikacji, potem iterujesz małymi, przeglądalnymi zmianami. Platforma przyspiesza szkicowanie i szkielety, ale zespół wciąż odpowiada za kompromisy.\n\n### Standardy zespołowe (ustal je przed promptowaniem)\n\nSporządź kilka domyślnych reguł, aby każde AI-generated change zaczynało z tych samych oczekiwań:\n\n- preferuj funkcje poniżej ~40–60 linii; unikaj głębokiego zagnieżdżenia; trzymaj niską złożoność cyklomatyczną (np. „żadna funkcja powyżej 10 bez uzasadnienia”).\n- terminy domenowe zamiast technicznych (np. , nie ); brak jednoznacznych liter poza krótkimi pętlami.\n- minimalne oczekiwania (np. „nowa logika musi zawierać testy jednostkowe dla happy path + kluczowych brzegów”).\n- optymalizuj tylko przy dowodach (wolne endpointy, gorąca pętla, zmierzone regresje).\n\n### Generuj → recenzuj → mierz → doskonal\n\n1) (wejścia, wyjścia, niezmienniki, przypadki błędów).\n\n2) wraz z testami.\n\n3) Jeśli trudno to streścić w kilku zdaniach, prawdopodobnie jest zbyt skomplikowane.\n\n4) Uruchom szybki benchmark lub dodaj lekkie timingi wokół podejrzanych wąskich gardeł.\n\n5) Zamiast „przyspiesz”, poproś „zmniejsz alokacje w tej pętli, zachowując strukturę funkcji”.\n\n### Co robić, a czego unikać\n\n- proś o małe, kompozycyjne funkcje z jasnymi nazwami.\n- wymagaj przykładów wejść/wyjść i testów w tej samej odpowiedzi.\n- proś o komentarze tylko tam, gdzie „dlaczego” nie jest oczywiste.\n- akceptuj mikrooptymalizacje bez pomiaru.\n- pozwól na „magiczne” helpery lub abstrakcje, które nie są używane gdzie indziej.\n- merguj kod AI, którego nikt w zespole nie potrafi swobodnie modyfikować.\n\n### Szablon promptu do ponownego użycia (kopiuj/wklej)\n\n\n\nJeśli utrzymasz tę pętlę — generuj, recenzuj, mierz, dopracowuj — otrzymasz kod, który pozostanie zrozumiały, a jednocześnie spełni oczekiwania wydajnościowe.