To, co piszę poniżej, to nie tutorial „jak użyć ChatGPT do napisania strony”. To dokumentacja decyzji architektonicznych, które podjąłem świadomie pod współpracę z AI, i pułapek, które napotkałem po drodze. Jeśli chcesz wdrożyć podobny model u siebie - tu znajdziesz więcej niż w materiałach promocyjnych dostawców.
Stack: Astro zamiast Next.js
Wybór frameworka był decyzją operacyjną, nie estetyczną.
Strona consultingowa nie potrzebuje interaktywności React. Potrzebuje szybkiego ładowania i dobrej pozycji w wynikach wyszukiwania. Astro 5 generuje statyczne HTML z zerowym JavaScript po stronie klienta tam, gdzie JS nie jest potrzebny. To wprost przekłada się na Core Web Vitals - a te wprost przekładają się na SEO.
Tailwind 4.2 podłączyłem przez wtyczkę @tailwindcss/vite, bez pliku konfiguracyjnego. Design tokeny żyją w bloku @theme {} w globalnym CSS: kolory marki, czcionki (Outfit dla nagłówków, Source Serif 4 dla treści), breakpointy. Jeden plik, jedno źródło prawdy dla całego systemu wizualnego.
Decyzja, która miała największe znaczenie dla AI workflow, nie dotyczyła ani Astro, ani Tailwinda. Dotyczyła tego, gdzie mieszka copy.
Każda podstrona ma dedykowany plik JSON w katalogu content/: sections.json dla strony głównej, operacje.json, it.json, kontakt.json i tak dalej. Komponenty Astro importują z tych plików i renderują. Nie trzymają ani jednego zdania treści w kodzie szablonu.
Świadoma decyzja pod AI editing: agent, który ma zmodyfikować copy, dotyka pliku JSON, nie pliku komponentu. Ryzyko wprowadzenia błędu w logice renderowania przez zmianę treści spada do zera.
Claude Code jako pętla wytwórcza
Najczęstszy błąd przy pracy z AI w wytwarzaniu: traktowanie go jak generatora. „Wygeneruj mi stronę” - to nie działa w żadnym projekcie, który musi spełniać konkretne wymagania techniczne i brandingowe.
Działa iteracyjna pętla: spec → implementacja → review → korekta. AI jest w niej wytwórcą, ale potrzebuje specyfikacji na wejściu.
Pierwszą rzeczą, którą zrobiłem przed napisaniem jakiegokolwiek kodu, był plik CLAUDE.md w korzeniu repozytorium. To persistentna instrukcja dla agenta: konwencje nazewnicze komponentów (PascalCase), klucze JSON (snake_case), zakazane słowa w copy (rewolucja, magia, transformacja), domyślny pattern CTA, zasady struktury JSON. Każda sesja z agentem zaczyna się od przeczytania tego pliku. Nie tłumaczę konwencji od zera przy każdym zadaniu.
Drugi element: agenci specjalizowani. Zamiast jednego agenta do wszystkiego, mam oddzielne konfiguracje dla różnych typów pracy: copywriter do treści, ui-dev do komponentów, qa-agent do testów. Każdy agent ma własny zakres kontekstu i instrukcji. Agent copywriter nie ma dostępu do konfiguracji deploymentu. Agent qa-agent nie generuje copy.
Przykład: audit copy na 8 podstronach. Zadanie: sprawdzić, czy zatwierdzone pliki copy w doc/copy/ zgadzają się z tym, co faktycznie renderuje strona. Raport ujawnił 23 rozbieżności: zmienione nagłówki, brakujące elementy, przestarzałe CTA. Batch fix: 12 plików w jednej sesji z agentem - pliki JSON treści, dwa komponenty Astro, schemat walidacji, aktualizacja testów. Czas: około dwóch godzin łącznie z review każdej zmiany. Szacunek bez AI: pół dnia roboty, z ryzykiem pominięcia kilku przypadków.
Żeby ta pętla działała, agent musi mieć dostęp do zatwierdzonej specyfikacji. Bez CLAUDE.md, bez plików copy jako spec, bez struktury JSON - AI produkuje coś, ale nie to, czego potrzebujesz.
Content-first: copy zatwierdzone przed kodowaniem
Porządek pracy był nienaruszalny: najpierw tekst, potem kod.
Copywriter tworzył pliki Markdown w doc/copy/: od 01_strona_glowna.md do 08_kontakt.md. Każdy plik zawierał zatwierdzone teksty sekcji, nagłówki, CTA, opisy. Dopiero po zatwierdzeniu przeze mnie agent implementował.
Ten porządek wymuszała architektura. Komponent Astro importuje treść z JSON-a - jeśli JSON jest pusty, komponent nie ma czego renderować. Nie da się wdrożyć sekcji z placeholderem „do uzupełnienia później”.
Kiedy copy się zmieniło (zmieniło się kilka razy, bo tak wygląda rzeczywistość), edytowałem pliki JSON. Nie ruszałem komponentów. Zmiana nagłówka sekcji na stronie operacje to edycja jednej linii w content/operacje.json, nie przeszukiwanie pliku Astro w poszukiwaniu zahardkodowanego stringa.
Raport rozbieżności między zatwierdzonym copy a aktualnym stanem strony jest możliwy tylko dlatego, że treść ma jedno kanoniczne miejsce, a specyfikacja drugie. Bez tego modelu porównanie staje się ręczną pracą.
Generowanie grafik: nanobanana
Każdy artykuł na blogu ma dedykowaną grafikę generowaną przez agenta nanobanana, który korzysta z Gemini CLI.
Grafika to nie opcja. Artykuł bez obrazu nie wygląda kompletnie, a zdjęcia stockowe z treścią o AI wyglądają dokładnie jak zdjęcia stockowe z treścią o AI.
Prompt buduje się z 6 elementów: medium (styl renderowania), lighting (warunki oświetlenia), composition (układ kadru), mood (nastrój), technical (parametry techniczne), brand constraints (specyfikacja wizualna marki). Ten ostatni element jest kluczowy: kremowe tło, płaski styl diagramatyczny, paleta slate i copper. To nie jest instrukcja „zrób ładną grafikę o AI” - to specyfikacja, która daje powtarzalne wyniki spójne z identyfikacją wizualną.
Gemini ma jedną właściwość, która robi różnicę: może modyfikować istniejący obraz zamiast generować od nowa. Jeśli strzałka na diagramie powinna być miedziana zamiast szarej, podaję obraz i instrukcję zmiany. Iteracja przez edycję jest szybsza niż iteracja przez regenerację z nowym promptem.
QA z Playwright
Każda zmiana na stronie kończy się sesją agenta qa-agent, który uruchamia testy Playwright.
Co agent sprawdza:
- Brak horizontal scroll na mobile - to najczęstszy bug przy pracy z Tailwind, szczególnie gdy AI generuje nowy komponent i pomija overflow na kontenerze
- Widoczność kluczowych elementów: CTA, formularz kontaktowy, nagłówek H1
- Responsywność w breakpointach sm (480px) i lg (900px)
- Brak błędów w konsoli przeglądarki
Agent nie raportuje „wydaje mi się, że działa”. Raport zawiera screenshoty z każdego widoku jako dowód. Jeśli bug jest wizualny, screenshot go pokazuje. Jeśli testy przeszły, screenshoty potwierdzają stan po zmianie.
Ta zasada skaluje się poza ten projekt: każdy output agenta powinien mieć mierzalny artefakt weryfikacji. Nie opis słowny, ale dowód - screenshot albo log testu.
Deploy: push do mastera, live w 2 minuty
Cloudflare Pages śledzi repozytorium git. Każdy push do gałęzi master wyzwala automatyczny build Astro i deploy na domenę docelową. Nie ma osobnego CI/CD do konfigurowania, nie ma pipeline’ów YAML do pisania.
Czas od git push do dostępności zmiany na produkcji: około dwóch minut.
Dla treści bloga działa Decap CMS dostępny pod adresem /admin. Edytor loguje się przez GitHub OAuth, wprowadza zmiany przez interfejs webowy, zapisuje - commit trafia do master, deploy startuje automatycznie. Redaktor nie potrzebuje dostępu do repozytorium ani znajomości Markdown. Workflow działa poza IDE.
Przekierowania z poprzedniej wersji strony obsługuje plik public/_redirects w formacie Cloudflare Pages. Zero konfiguracji serwera, zero reguł w panelu dostawcy hostingu.
Co zadziałało, co nie
Trzy decyzje, które oszczędziły mi najwięcej czasu:
JSON content model. AI edytuje pliki treści bez ryzyka złamania kodu komponentu. Przy każdej zmianie copy, przy każdym audicie, przy każdym batch fixie - agent dotyka JSON, nie Astro. Eliminuje to całą klasę błędów.
CLAUDE.md jako persistentna instrukcja. Konwencje nazewnicze, zakazane słowa, przykłady poprawnych i błędnych patternów. Nie tłumaczę tego przy każdej sesji. Agent ma ten kontekst od początku każdej rozmowy.
Agenci specjalizowani zamiast jednego generalisty. Copywriter nie generuje kodu, qa-agent nie generuje copy, ui-dev nie pisze artykułów. Każdy agent ma wąski, dobrze zdefiniowany zakres. Wyniki są przewidywalne.
Co mnie zaskoczyło:
Polskie cudzysłowy „” w plikach JSON łamią parser Vite. Nieoczywiste, bo edytor tekstu wyświetla je poprawnie, ale build kończy się błędem. Rozwiązanie: unicode escapes \u201e\u201d lub proste cudzysłowy angielskie ". Pierwszy błąd tego typu zajął zbyt dużo czasu na diagnozę.
AI bez kontekstu popełnia błędy nazewnicze i stylistyczne dokładnie tam, gdzie tego nie chcesz. Agent bez CLAUDE.md napisze „innowacyjne rozwiązania” tam, gdzie specyfikacja marki tego zabrania. Instrukcja persistentna to nie opcja - to warunek spójności outputu przy wielu sesjach.
I najważniejsze: „zrób całą stronę” nie działa. „Zaimplementuj sekcję X wg specyfikacji w tym pliku JSON, stosując konwencje z CLAUDE.md” - działa. Różnica to nie jakość narzędzia. To jakość specyfikacji na wejściu.
Jeśli chcesz wdrożyć podobny model pracy w swoim zespole IT - zaczniemy od konkretnego procesu, nie od generycznych rekomendacji. Sprawdź, jak wygląda dowód wartości dla AI w wytwarzaniu.
