AI-assisted engineering w praktyce: case study OpenMercato #EN370

Poniższe notatki pochodzą z 40-minutowego tutorialu wideo Piotra Karwatki pokazującego rzeczywisty proces AI-assisted development w projekcie OpenMercato. Wszystkie przedstawione przemyślenia, obserwacje i wnioski należą do autora materiału, z wyjątkiem checklisty, biblioteki promptów i kluczowego insightu, które stanowią interpretację informacji zawartych w nagraniu.

TL;DR

• Spec-driven development z AI wymaga szczegółowej specyfikacji PRZED kodowaniem – stanowi to fundament efektywnej pracy
• AgentsMD to standard guardrails dla agent coding (konwencje, architektura, extensibility contract)
• Realna efektywność AI-assisted engineering wynosi 3–4-krotny wzrost, nie mityczne 10-krotne zwiększenie – komunikacja i przegląd kodu pozostają kluczowe
• Monorepository drastycznie upraszcza pracę AI poprzez scentralizowany kontekst (vs rozproszony microservices)
• Kod powstaje automatycznie, jednak ludzie nadal odpowiadają za: specs, komunikację, przegląd i decyzje architektoniczne
• Narzędzia: Codex 5.2, Claude Opus 4.5, GitHub Copilot, Cursor – wszystkie działają na podobnym poziomie jakości
• Częste zatwierdzanie zmian to zabezpieczenie – zawsze można wrócić, jeśli AI pójdzie w złym kierunku

Wprowadzenie: implementacja realnej funkcjonalności z GitHub

Piotr Karwatka przedstawia praktyczny proces dodawania funkcji do OpenMercato Core z wykorzystaniem AI assistant engineering. Punktem wyjścia jest zgłoszenie #210 z GitHub dotyczące order status history. Zamiast teoretycznych rozważań, materiał przedstawia rzeczywisty przepływ pracy od wybrania zadania przez przygotowanie specyfikacji po żądanie scalenia.

Jak wyjaśnia prelegent, cel jest podwójny. Po pierwsze – pokazanie jak codziennie pracuje zespół główny OpenMercato. Po drugie – rozwikłanie mitów o AI-assisted development i podzielenie się realnymi obserwacjami po miesiącach pracy tym modelem. OpenMercato służy tu jako pole treningowe i przestrzeń nauki do praktycznego wykorzystania assistant engineering.

Przygotowanie: wybór funkcji i konfiguracja środowiska

Wybrana funkcja jest świadomie niedookreślona w zgłoszeniu GitHub. Według prelegenta, to doskonała okazja do pokazania spec-driven development. W OpenMercato zmiany statusu zamówienia są zapisywane, mimo to historia tych zmian nie jest wyświetlana w UI. System ma już zaimplementowany comment pattern – każda zmiana (np. adresu rozliczeniowego) generuje wpis w action log z możliwością cofnięcia operacji.

Dane w action log są szyfrowane w bazie danych. Zawierają migawkę danych przed i po zmianie, co umożliwia funkcję cofania.

Praca zawsze odbywa się na gałęzi develop. Autor podkreśla wagę częstego zatwierdzania zmian – stanowi to zabezpieczenie na wypadek gdy AI pójdzie w złym kierunku. Możliwość szybkiego powrotu do wcześniejszego stanu eliminuje ryzyko. Dla osób spoza zespołu głównego OpenMercato zaleca fork do własnego konta GitHub i pracę na nim z późniejszym tworzeniem żądań scalenia.

AgentsMD: guardrails dla AI coding

AgentsMD to plik standardu dla agent coding, zawierający guardrails i konwencje projektowe. Jak wyjaśnia autor, każda framework-wide feature, konwencja czy guardrail którą deweloperzy powinni pamiętać, trafia do AgentsMD. To gwarantuje, że narzędzia agent coding automatycznie zastosują te zasady.

Według prezentacji, AgentsMD zawiera:

• Konwencje nazewnictwa plików i encji bazy danych
• Extensibility contract (OCP – Open for extensions, Closed for modifications)
• Strukturę modułową – moduły są niezależne od siebie
• Specyfikacje API endpoints – kompletna dokumentacja integracji
• Zasady OpenAPI – sposób dokumentowania API

LLM czyta AgentsMD przed rozpoczęciem pracy nad kodem. Dzięki temu decyzje architektoniczne i konwencje kodowania są stosowane konsekwentnie bez konieczności przypominania w każdym poleceniu. Nawet jeśli specyfikacja pominie jakiś element (np. szyfrowanie), AgentsMD jest na tyle jasny, że zostanie użyty automatycznie.

Spec-driven development: specyfikacja przed kodem

Pierwszy krok – zawsze specs

Autor tworzy specyfikację przed rozpoczęciem kodowania. Używa do tego Codex 5,2, jednak – jak podkreśla – równie dobrze sprawdzają się Claude Opus 4.5, GitHub Copilot czy Cursor. Polecenie jest proste: „Specify requirements and design architecture for ticket #210”.

Codex ma integrację z GitHub, więc automatycznie pobiera opis zgłoszenia. W rezultacie generuje specyfikację zapisywaną do pliku markdown w folderze AI-specs. Alternatywnie można publikować specs bezpośrednio jako zgłoszenie GitHub.

Kluczowa obserwacja o tworzeniu poleceń

Według autora, kluczową rzeczą jest po prostu mieć to dobrze i być pewnym zanim LLM zacznie pracować, że rozwinie dokładnie to czego potrzebujemy. Jego obserwacja: LLM świetnie pracują z przykładami i user stories. Im bardziej szczegółowe polecenie, tym lepiej. Można definiować jakie przyciski, co się dzieje po kliknięciu, każdy szczegół interakcji.

Iteracyjne dopracowywanie

Specyfikacja nie powstaje jednorazowo. Autor pokazuje przepływ pracy z różnymi modelami:

• Codex 5,2 generuje pierwszą wersję specs
• Claude Opus 4.5 w Cursor dostaje polecenie „challenge the specification”
• Opus zauważa brakujące elementy (np. konfiguracja indeksera dla API route, funkcje pomocnicze do szyfrowania)
• Specyfikacja jest aktualizowana przed rozpoczęciem implementacji

Praktyczny wskazówka od autora: pozytywny ton w poleceniach faktycznie wpływa na jakość rezultatów.

W większych zespołach specyfikacja to punkt wyjścia do dyskusji. W OpenMercato deweloperzy tworzą możliwie szczegółowe specs, następnie dyskutują w zgłoszeniach GitHub i na Discordzie. Dopiero po osiągnięciu konsensusu rozpoczyna się kodowanie.

Wygenerowana specyfikacja zawiera: cel i opis problemu (co i dlaczego), historie użytkownika (szczegółowe opisy funkcjonalności), projekt UI (nawet próbę makiety), obserwacje o istniejącym kodzie (np. action log z modułu outdelocs), punkty końcowe API i struktury danych, oraz notatki o lokalizacji.

Makiety UI: obrazek wart tysiąca słów

Autor przygotowuje ręcznie narysowany szkic UI i wkleja go jako PNG do Visual Studio Code. Jak wyjaśnia, bez makiety agent sam określa interfejs, ale rezultat nie zawsze jest przyjazny użytkownikowi. Łatwiej przygotować prosty rysunek niż później naprawiać kod.

OpenMercato używa shadcn dla React jako system projektowy, co zapewnia spójność komponentów. Mimo to, nawet przy systemie projektowym, konkretna makieta pomaga AI zrozumieć intencję. Plugin Visual Studio Code pozwala na wklejanie obrazków bezpośrednio do polecenia.

Implementacja: od specs do działającego kodu

Po zatwierdzeniu specs, autor podaje polecenie: „That’s cool, let’s implement the feature based on specs from AI-specs/order-status-history” z załączoną makietą PNG. Codex rozpoczyna implementację. Według materiału, zadania mogą trwać od kilku minut do nawet 8 godzin (przykład: szeroka refaktoryzacja używająca jednej funkcji pomocniczej w całym OpenMercato).

W trakcie implementacji AI automatycznie:

• Tworzy walidatory używając Zod
• Dodaje funkcje filtrowania dla action log (po typie zasobu i ID zasobu)
• Aktualizuje miejsca gdzie brakuje logów zmian
• Definiuje struktury danych zgodnie ze specs
• Tworzy funkcje pomocnicze zamiast klas (łatwiejsze utrzymanie)
• Generuje punkty końcowe API zgodnie z OpenAPI specifications
• Buduje UI z lazy compilation
• Aktualizuje pliki lokalizacji dla wszystkich obsługiwanych języków

Funkcje pomocnicze zamiast klas – kluczowa decyzja

OpenMercato używa programowania funkcyjnego. Jak pokazuje autor, zamiast klas definiowane są funkcje pomocnicze. To znacznie ułatwia utrzymanie kodu. Ścieżki API są proste dzięki gotowym pomocnikom jak CRUD helper (tworzenie, odczyt, aktualizacja, usuwanie) i funkcje pomocnicze OpenAPI. W rezultacie LLM używa tych funkcji zamiast duplikować kod, co zapobiega bałaganowi w projekcie.

Podczas gdy jedno zadanie kodowania działa, można równolegle uruchomić: napraw błędy kompilacji. Agent wykona krok budowania i naprawi błędy. Autor zaleca to przed utworzeniem żądania scalenia, ponieważ kompilacja sprawdza się automatycznie na GitHub Actions. Podobnie działa yarn test dla testów jednostkowych, choć ostrzeżenie: zmienianie kodu testów tylko po to, by przeszły, bez zrozumienia dlaczego nie działają, to zła praktyka.

Monorepository: architektura ułatwiająca AI

Autor odpowiada na częste pytanie: czemu OpenMercato nie jest headless? Może być wdrożone headless (wspierane w 100%), jednak struktura projektu ma znaczenie dla AI assistant engineering. Projekty rozproszone (wiele mikroserwisów, różne języki jak Python vs TypeScript) komplikują zarządzanie kontekstem. W związku z tym AI używa skanowania kodu do określania specyfikacji i aplikowania zmian. Gdy projekt jest rozproszony, dodawanie kontekstu (specyfikacje markdown, symlinkowanie folderów) robi się złożone.

Monorepository drastycznie upraszcza pracę. Konfiguracja lokalnej instancji OpenMercato trwa około 10–12 minut (może nawet 7 minut według autora). Po tym czasie można od razu kodować. Jak podkreśla autor, biorąc pod uwagę rozmiar OpenMercato, to świetny wynik.

Drugi cel architektury modułowej: dodawanie funkcji jest łatwiejsze. Nowy moduł zawiera wszystko potrzebne do działania funkcjonalności. Dlatego moduły nie są połączone między sobą. To najprostszy sposób osiągnięcia rezultatu.

Praktyczny zysk: oszczędność tokenów

Dodatkowa korzyść z monorepository: OpenMercato generuje specyfikację markdown całego API, którą można wkleić do LLM. Jak zauważa autor, to oszczędza mnóstwo tokenów podczas integracji czy pracy z API. Cała dokumentacja z autoryzacją, punktami końcowymi, wszystko w jednym miejscu.

Przegląd kodu: co się NIE zmieniło

Autor pokazuje żądanie scalenia z 48 zmienionymi plikami. Przegląd kodu zajmuje czas, ale jest niezbędny. Dlaczego? Po pierwsze – znajdowanie niezgodności z zasadami frameworka i projektowymi. Po drugie – identyfikacja sposobów na ulepszenie guardrails (AgentsMD, sprawdzenia GitHub Actions). Po trzecie – krzywa uczenia dla deweloperów, zrozumienie jak działa OpenMercato.

Kluczowy proces: gdy ktoś zatwierdza żądanie scalenia z oczywistym problemem, zespół główny najpierw sprawdza jak można temu zapobiec w AgentsMD lub innych guardrails, może jakimiś sprawdzeniami GitHub Actions. To proaktywne podejście do kontroli jakości – zamiast tylko naprawiać, budować systemy zapobiegające.

Według prezentacji, im więcej podstawowych funkcji dostarcza deweloper, tym więcej problemów powstaje z przeglądu kodu. Stanowi to proces uczenia się.

Komunikacja ważniejsza niż kiedyś

Jak podkreśla autor: co się NIE zmienia z agent encoding i assisted engineering to właściwie komunikacja. Co więcej – gdy tylko zaczęli pracować z większym zespołem nad OpenMercato, komunikacja stała się jeszcze ważniejsza.

Paradoks AI-assisted development: deweloperzy piszą mniej kodu, ale komunikacja stała się ważniejsza. W zespole głównym OpenMercato (ponad 100 inżynierów na Discordzie – wszyscy to inżynierowie, nie przypadkowi ludzie) dyskusje są intensywne. Zmiana polega na tym, że deweloperzy prawdopodobnie nie czytają już kodu sami, ponieważ używają agentów. W rezultacie specyfikacje i dokumentacja są bardziej krytyczne.

Dokumentacja i testowanie: co się zmieniło

Jak zauważa autor, przed erą AI obszerna dokumentacja dla żądań scalenia i specs praktycznie nie istniała. Ludzie nienawidzą tego typu żmudnej roboty. Teraz dostaje się to za darmo przez AI, więc nie ma wymówek żeby tego nie robić. W efekcie powstaje repozytorium zapisów decyzji architektonicznych (ADR). Można zawsze sprawdzić dlaczego coś się zmieniło i jak, nawet bez wchodzenia w zmiany kodu.

Emocjonalne reakcje to przeszłość

W kontekście testowania – przed AI-assisted development, gdy ktoś znajdował błąd i zgłaszał problem, czasami generowało to emocjonalne reakcje. Niektórzy ludzie byli wkurzeni – nie każdy przyjmuje informację zwrotną w ten sam sposób.

Teraz jest bardzo łatwo, ponieważ koszt kodowania dąży do zera. Gdy pojawia się zgłoszenie ze zrzutami ekranu (jak przykład Patricka, który znalazł problemy UX), deweloper po prostu pyta coding agent o naprawę. Autor pokazuje konkretny przykład: Patrick zgłosił problem ze zrzutami ekranu, deweloper zadał kilka poleceń i miał to naprawione natychmiast. Można nawet dać zrzut ekranu bezpośrednio do AI.

Automatyczne scenariusze testowe

W OpenMercato trwa praca nad scenariuszami QA generowanymi przez AI na podstawie rzeczywistego kodu i specs. 126 przypadków testowych – przed AI byłoby to 2 tygodnie pracy dla testera, może więcej. Następnie aktualizowanie to koszmar. Teraz tworzy się automatycznie. MCP dla Playwright (wbudowana przeglądarka którą AI może użyć) pozwala na automatyczne wykonywanie całych scenariuszy i raportowanie wyników.

Realna efektywność: wzrost 3–4-krotny, nie 10-krotny

Autor obserwuje dwie skrajne grupy ludzi. Pierwszy obóz: bardzo entuzjastyczny, wierzy że „zbudujesz całą aplikację jednym poleceniem”. Według autora – nie stanie się. Drugi obóz: całkowicie sceptyczny, uważa że „to tylko dla zabawy, nigdy nie działa, to buzzword”. Również nieprawda.

Rzeczywista historia: przy budowaniu czegoś złożonego jak OpenMercato, część rzeczy się zmienia, część nie.

Kluczowe rozróżnienie

Według autora: cały proces jest wspierany infrastrukturą i narzędziami LLM, ale faktyczna praca ludzi nadal tam jest. Stanowi to doskonałe podsumowanie rzeczywistości AI-assisted development.

Co się NIE zmieniło:

• Komunikacja – jeszcze ważniejsza niż przed AI
• Przegląd kodu – trudny przy 48-plikowych żądaniach, ale niezbędny
• Podejście spec-driven – teraz łatwiejsze, więc brak wymówek
• Testowanie i QA – format się zmienia, ale weryfikacja pozostaje

Co się zmieniło:

• Deweloperzy piszą mniej kodu – AI generuje implementację
• Nie czytają kodu samodzielnie – używają agentów do analizy
• Dokumentacja powstaje łatwiej – AI pisze specs i ADR
• Naprawianie i debugowanie są szybsze – natychmiastowe poprawki zamiast emocjonalnych reakcji
• Koszt zmiany dąży do zera – refaktoryzacja nie jest już kosztowna

Według prezentacji, AI-assisted engineering NIE daje 10-krotnego wzrostu efektywności z powodu wymaganej komunikacji i człowieka w pętli. Ale daje wzrost 3–4-krotny. Jeden deweloper ma produktywność 2–3 osobowego zespołu.

Praktyczne checklisty

Przepływ pracy spec-driven z AI

• Przeczytaj AgentsMD projektu przed rozpoczęciem
• Przełącz się na gałąź develop i utwórz gałąź funkcjonalności
• Wygeneruj specs z AI: „Specify requirements for ticket #XXX”
• Bądź szczegółowy – LLM świetnie pracują z przykładami i historiami użytkownika
• Sprawdź specs innym modelem (Codex → Claude lub odwrotnie)
• Przygotuj makiety UI (nawet rysowane ręcznie) jako PNG
• Zachowaj pozytywny ton w komunikacji z LLM – ma znaczenie
• Powtórz 2–3 razy – dopracuj szczegóły przed zatwierdzeniem
• Sprawdź czy specs zawiera: cel, historie użytkownika, punkty końcowe API, lokalizację
• Zapisz specs do AI-specs/nazwa-funkcji.md

Implementacja i przegląd kodu

• Zatwierdzaj zmiany często – siatka bezpieczeństwa na wypadek gdy AI pójdzie w złym kierunku
• Użyj polecenia: „Implement based on AI-specs/file.md” + załącz makietę
• Deleguj napraw błędy kompilacji i yarn test do AI równolegle
• Sprawdź czy AI użyło istniejących funkcji pomocniczych zamiast duplikować kod
• Po modyfikacji ścieżek/stron: yarn generate i build packages
• Przejrzyj wszystkie 48+ zmienione pliki ręcznie
• Zweryfikuj zgodność z AgentsMD i zasadami projektowymi
• Gdy znajdziesz problem – pomyśl jak zapobiec temu w guardrails
• Przetestuj funkcjonalność lokalnie ze zrzutami ekranu
• Utwórz żądanie scalenia z wygenerowanymi przez AI notatkami wydania i linkiem do zgłoszenia

Czego unikać

NIE pomijaj specyfikacji – myślenie „jednym poleceniem zbuduję funkcję” prowadzi do marnowania czasu na późniejsze poprawki. Podejście spec-driven oszczędza czas w długim terminie. Kluczem jest mieć to dobrze zanim LLM zacznie pracować.

NIE zakładaj że wzrost 10-krotny – realistyczne oczekiwanie to wzrost 3–4-krotny. Komunikacja i człowiek w pętli są niezbędne przy złożonych projektach. Dlatego proces jest wspierany przez LLM, ale faktyczna praca ludzi pozostaje.

NIE pomijaj przeglądu kodu – AI może generować niezgodności z architekturą. Z tego powodu żądanie scalenia z 48 plikami wymaga ludzkiego przeglądu dla kontroli jakości i krzywej uczenia. To też okazja do proaktywnego myślenia o guardrails.

NIE pracuj na rozproszonych projektach – monorepository przewyższa mikroserwisy dla kontekstu AI. W rezultacie rozproszone projekty komplikują zarządzanie kontekstem i skanowanie kodu.

NIE zmieniaj testów jednostkowych ślepo – zrozum czemu nie działają zanim AI naprawi. Ponieważ zmienianie testów tylko po to by przeszły bez zrozumienia = dług techniczny.

NIE traktuj błędów emocjonalnie – przed AI ludzie byli wkurzeni informacją zwrotną. Jednak teraz koszt zmiany jest blisko zera, więc naprawa to minuty, nie dni.

Ograniczenie okna kontekstu

Według autora, ograniczony kontekst (200 tysięcy tokenów dla Claude, wcześniej 100 tysięcy, 28 tysięcy) może być problemem dla dużych projektów. Jak słyszał, ludzie przetłumaczyli to jako „jeden dzień kontekstu prawdziwego dewelopera” – w ciągu jednego dnia deweloper może przeoczyć niektóre miejsca w kodzie.

Rozwiązanie OpenMercato: podstawowe elementy frameworka zawsze w AgentsMD, szerokie wykorzystanie funkcji pomocniczych dla powtarzalnych zadań, LLM używa funkcji pomocniczych zamiast duplikować kod. W rezultacie specyfikacje markdown API oszczędzają mnóstwo tokenów.

Biblioteka poleceń z tutorialu

Autor pokazuje konkretne polecenia które używa w codziennej pracy. Poniższa tabela prezentuje polecenia wraz z kontekstem ich zastosowania:

Przykład rzeczywistego przepływu naprawiania

Autor pokazuje konkretny przypadek: Patrick zgłosił problemy UX ze zrzutami ekranu. Deweloper:

1. Wkleił zrzuty ekranu do polecenia
2. Opisał problem krótko
3. AI wygenerowało naprawę natychmiast

Kluczowe zasady tworzenia poleceń

Zachowaj pozytywny ton: Ton „that’s cool”, „that’s great” faktycznie wpływa na jakość rezultatów. To nie tylko uprzejmość – stanowi to praktyczną wskazówkę.

Bądź szczegółowy z historiami użytkownika: Definiuj każdy szczegół – przyciski, interakcje, przypadki brzegowe. W efekcie LLM świetnie to przetwarzają.

Załączaj wizualizacje: Makiety PNG (nawet narysowane ręcznie) drastycznie poprawiają jakość implementacji UI.

Kluczowa zasada: Lepiej poświęcić czas na dobre polecenie i specs niż naprawiać źle wygenerowany kod. Jak mówi autor – kluczową rzeczą jest po prostu mieć to dobrze zanim LLM zacznie pracować.

Narzędzia i zasoby

Autor używa głównie Codex 5,2. Część zespołu głównego używa Claude Opus 4.5 (niedawny benchmark pokazał przewagę 0,9% nad Codex). GitHub Copilot działa świetnie i jest wspierany. Cursor również. Można nawet używać wersji CLI Codex lub Claude Code. Wszystko powinno działać, ponieważ OpenMercato jest świadomie zaprojektowane jako dobrze wspierane przez agentów AI.

Z materiału wynika że warto sprawdzić:

• AgentsMD standard – jako punkt wyjścia dla własnych guardrails
• OpenMercato architecture video – wcześniejszy materiał autora o strategii wdrażania i rozszerzalności
• Repozytorium GitHub OpenMercato – struktura modułowa jako przykład architektury przyjaznej AI
• MCP dla Playwright – do automatycznego testowania end-to-end
• OpenAPI Explorer w OpenMercato – generuje specyfikacje markdown API dla łatwego użycia przez LLM

Kluczowy insight

Koszt zmiany kodu zabija emocje, nie ludzie

Standardowo myślimy: Deweloperzy są wkurzeni na informację zwrotną bo są defensywni, roszczeniowi lub źle znoszą krytykę. To problem mentalności i komunikacji w zespole.

W praktyce okazuje się, że: Emocjonalna reakcja na informację zwrotną koreluje bezpośrednio z kosztem zmiany. Gdy autor pokazuje przykład z OpenMercato – przed AI ludzie byli wkurzeni na zgłoszenia błędów, teraz nie. Nie dlatego że się zmienili, ale dlatego że koszt kodowania dąży do zera. Patrick zgłasza problem UX ze zrzutami ekranu, deweloper zadaje kilka poleceń do AI i ma naprawę w kilka minut. Zero frustracji.

Dlaczego to jest istotne: Przez lata próbowaliśmy rozwiązać „problemy komunikacji w zespole” szkoleniami z informacji zwrotnej i kulturą błędu. Tymczasem prawdziwy problem był ekonomiczny – naprawa wymagała 2 dni pracy vs 5 minut. Dlatego AI nie zmienił ludzi, zmienił ekonomię zmiany kodu.

Test na jutro: Następnym razem gdy dostaniesz informację zwrotną na swój kod, zanim zareagujesz emocjonalnie, sprawdź ile czasu zajmie naprawa. W rezultacie zauważ jak Twoja reakcja emocjonalna koreluje z wymiarem: 5 minut vs 2 dni. Jeśli możesz przekazać naprawę do AI (specs + polecenie), sprawdź czy Twoja frustracja znika razem z kosztem zmiany.

---

Ten wpis jest częścią mojej kolekcji notatek z ciekawych podcastów, webinarów i innych treści, które uważam za wartościowe i do których sam chcę wracać. Jeśli chcesz sprawdzić oryginalne źródło, znajdziesz je tutaj: AI Assisted Engineering with Open Mercato