Nasze standardy na front-endzie
Jak utrzymać wysoką jakość kodu w dobie AI, gdy nad naszymi produktami pracują developerzy o bardzo różnym doświadczeniu? Pokazujemy standardy frontendowe GI: konwencje, narzędzia i pracę z AI.

W Generacji Innowacji nad naszymi produktami pracują developerzy z bardzo różnym doświadczeniem. Część z nich na co dzień rozwija projekty komercyjne, inni dopiero zaczynają swoją przygodę z programowaniem w ramach wolontariatu lub programu praktyk.
Do tego dochodzi AI, które pozwala nam pisać coraz więcej kodu w coraz krótszym czasie.
I tutaj pojawia się pytanie: jak przy tak różnorodnym zespole i coraz szybszym tempie developmentu utrzymać wysoką jakość kodu?
Jednym ze sposobów, w jaki podchodzimy do tego problemu w GI, jest wprowadzenie wspólnych standardów technologicznych. Dzięki nim każdy developer ma dostęp do tych samych zasad i nie musi za każdym razem zastanawiać się, jak powinien wyglądać komponent, gdzie umieścić logikę biznesową albo jakie narzędzie wykorzystać.
Standardy technologiczne - Frontend
Dzisiaj chciałbym skupić się na standardach frontendowych, które opracowaliśmy na podstawie doświadczeń naszych developerów, zarówno z projektów komercyjnych, jak i tych rozwijanych w fundacji.
Możemy podzielić je na trzy główne obszary.
1. Konwencje
Definiujemy zasady dotyczące struktury projektów, organizacji komponentów, nazewnictwa plików oraz pisania testów.
Jednym z najważniejszych założeń jest oddzielenie kodu specyficznego dla danej domeny od kodu współdzielonego. Przykładowo, komponent wykorzystywany tylko w widoku użytkowników powinien znajdować się w katalogu tej domeny, a nie od razu w katalogu komponentów globalnych.
Podobnie podchodzimy do organizacji samych komponentów. Opieramy się na trzech zasadach:
Encapsulation - typy, stałe i funkcje pomocnicze wykorzystywane wyłącznie przez jeden komponent pozostają w jego katalogu.
Minimization - nie tworzymy dodatkowych plików i katalogów, jeżeli nie są potrzebne.
Mirroring - struktura katalogów odzwierciedla strukturę komponentów i ich zależności.
Dzięki temu kod staje się bardziej przewidywalny, łatwiej go przeglądać i nie musimy przeszukiwać całego projektu, żeby znaleźć funkcję pomocniczą wykorzystywaną przez jeden komponent.
Chcemy, żeby przejście z jednego projektu GI do drugiego nie oznaczało konieczności uczenia się całej architektury od zera.
Mamy również określone zasady nazewnictwa oraz pisania testów w podejściu BDD (Behavior-Driven Development), wykorzystując strukturę Given-When-Then.

Przykład testu w strukturze Given-When-Then z dokumentu Testing convention w repozytorium gi-tech-standards.
2. Narzędzia
Sama struktura projektu to oczywiście nie wszystko. Równie ważne jest określenie zestawu technologii i zasad ich stosowania.
W naszych standardach frontendowych stawiamy na React, TypeScript, Vite, React Router i Tailwind CSS. Do dokumentowania komponentów przewidzieliśmy również Storybook.
Ale ciekawsza od samej listy bibliotek jest dla mnie kwestia tego, kiedy powinniśmy z nich korzystać i jakie problemy chcemy nimi rozwiązywać.
Dobrym przykładem jest zarządzanie stanem aplikacji.
Nie zakładamy, że każdy projekt od początku potrzebuje dodatkowej biblioteki do globalnego stanu. W pierwszej kolejności korzystamy z natywnych mechanizmów Reacta, takich jak useState i useContext.
Dopiero kiedy stan staje się bardziej złożony, wymaga persystencji, dodatkowego middleware lub pojawiają się problemy z wydajnością, rozważamy Zustand.
Podobnie podchodzimy do komunikacji z API.
Wykorzystujemy Axios do wykonywania zapytań HTTP oraz Zod do walidacji otrzymywanych danych.
Dlaczego oba narzędzia?
Ponieważ TypeScript pozwala sprawdzić poprawność typów podczas developmentu, ale nie gwarantuje, że dane otrzymane z backendu rzeczywiście odpowiadają naszym interfejsom.
Zod pozwala zweryfikować ich strukturę w runtime, zanim zaczniemy wykorzystywać je w aplikacji.
Oprócz tego mamy ustalone zasady automatycznej kontroli jakości kodu:
Biome - linting i formatowanie.
Vitest - testy jednostkowe.
Playwright - testowanie pełnych przepływów użytkownika.
TypeScript - statyczna weryfikacja typów.
CI/CD - automatyczne kontrole builda, lintingu i testów.
Stosujemy też podejście oparte na piramidzie testów. Większość przypadków, szczególnie logikę i edge case’y, chcemy weryfikować na poziomie testów jednostkowych, natomiast E2E mają obejmować przede wszystkim kluczowe scenariusze użytkownika.
W dokumentacji przyjęliśmy ambitny cel 95-100% pokrycia testami jednostkowymi. Sam procent pokrycia nie jest jednak gwarancją jakości - równie istotne jest to, co właściwie sprawdzają nasze testy.
3. Praca z AI
Tutaj podchodzimy do tematu z dwóch stron.
Z jednej strony mamy techniczne zasady, które określają, jak powinien wyglądać kod generowany przy pomocy AI. Z drugiej - promujemy świadome wykorzystywanie takich narzędzi.
Samo napisanie w prompcie „follow best practices” nie gwarantuje przecież, że agent zastosuje się do architektury konkretnego projektu.
Dlatego przygotowaliśmy plik CLAUDE.md, który zawiera nasze standardy frontendowe w formie możliwej do wykorzystania jako kontekst przez agentów AI.
Znajdują się w nim m.in. informacje o dozwolonym stacku technologicznym, strukturze katalogów, zasadach zarządzania stanem, komunikacji z API oraz Definition of Done.
Dzięki temu agent może otrzymać konkretne wymagania zamiast samodzielnie decydować, czy powinien wykorzystać nową bibliotekę, gdzie umieścić logikę albo jak zorganizować testy.
Ale sama zgodność z instrukcjami nie wystarczy.
W GI promujemy podejście Reflective use of AI, czyli świadome i krytyczne korzystanie z AI.
Nie chcemy, żeby AI podejmowało wszystkie decyzje za developera. Wręcz przeciwnie - powinno pomagać w rozwiązywaniu problemów, ale to człowiek musi rozumieć, weryfikować i brać odpowiedzialność za rezultat.
Jest to szczególnie ważne w przypadku osób rozpoczynających naukę programowania, ponieważ samo wygenerowanie działającego kodu nie oznacza jeszcze zrozumienia problemu, który rozwiązujemy.
Jak to działa w praktyce?
Wszystkie standardy opisaliśmy w publicznym repozytorium na GitHubie. Dokumentacja jest podzielona na mniejsze części, dzięki czemu łatwiej znaleźć konkretną zasadę.

Spis standardów frontendowych (docs/frontend/INDEX.md) w repozytorium gi-tech-standards.
Żeby lepiej pokazać, jak przekładają się one na codzienną pracę, przygotowaliśmy trzy przykłady - od organizacji kodu, przez dobór narzędzi i weryfikację jakości, aż po pracę z agentami AI.
Co na tym zyskujemy?
Przede wszystkim ułatwiamy przekazywanie wiedzy naszym praktykantom i wolontariuszom.
Zależy nam na tym, żeby osoby rozpoczynające u nas swoją przygodę z programowaniem poznawały nie tylko konkretne technologie, ale również dobre praktyki stosowane podczas pracy nad prawdziwymi produktami.
Nie chodzi wyłącznie o nauczenie kogoś Reacta czy TypeScriptu.
Równie ważna jest umiejętność podjęcia decyzji, kiedy warto wydzielić komponent, jak poprawnie walidować dane z API, jakie przypadki powinny zostać pokryte testami oraz jak zweryfikować rozwiązanie wygenerowane przez AI.
To właśnie takie umiejętności przydają się później podczas pracy w większych zespołach i projektach komercyjnych.
Druga korzyść to łatwiejsze rozwijanie i utrzymywanie naszych produktów.
Kiedy wszyscy korzystają ze wspólnych zasad, łatwiej jest zrozumieć kod napisany przez inną osobę, przeprowadzić review czy wdrożyć nowego developera do projektu.
Wspólne standardy zmniejszają również ryzyko sytuacji, w której każdy kolejny developer wprowadza zupełnie inne rozwiązania dla tych samych problemów.
Nie oznacza to oczywiście, że nasze podejście jest idealne i nigdy nie będzie wymagało zmian. Technologie się rozwijają, pojawiają się nowe narzędzia i lepsze sposoby rozwiązywania problemów.
Dlatego standardy traktujemy jako dokumentację, którą chcemy aktualizować razem z rozwojem naszych produktów i doświadczeniem zespołu.
Na koniec
Wprowadzenie standardów technologicznych nie sprawi, że wszystkie problemy z jakością kodu nagle znikną.
Ale pozwala nam ograniczyć liczbę powtarzalnych decyzji, szybciej wdrażać nowe osoby do projektów i przede wszystkim przekazywać wiedzę, którą nasi developerzy zdobywali przez lata.
I właśnie na tym najbardziej nam zależy.
Nasze standardy są publiczne, więc jeśli interesuje Cię, jak organizujemy pracę frontendową w Generacji Innowacji, możesz zajrzeć do repozytorium:
Zachęcamy też do zgłaszania sugestii i dzielenia się doświadczeniami. Być może niektóre z naszych rozwiązań przydadzą się również w Twoich projektach.
Czytaj dalej











































