To część 5 serii o migracji holas.pl z WordPressa do własnego generatora stron statycznych opartego na Symfony. Część 4 opisuje środowisko deweloperskie i deployment.

Budowanie holas.pl wymagało napisania sporej ilości PHP, Twig i SCSS — i podejmowania decyzji architektonicznych, których cofnięcie byłoby uciążliwe. Przez cały czas używałem Claude Code jako AI pair programmera. Ten wpis opisuje jak ten workflow faktycznie wygląda, gdzie działa dobrze, a gdzie nadal wymaga ludzkiego osądu.

AGENTS.md — instrukcja obsługi dla AI

Pierwsze praktyczne spostrzeżenie z tego projektu: asystent AI jest tak dobry jak instrukcje, które dostaje. Bez jawnych wytycznych Claude domyślnie generuje funkcjonalny, ale generyczny kod — rozsądne wybory, ale niekoniecznie takie, jakie sam byś podjął.

Rozwiązaniem jest AGENTS.md, plik w korzeniu projektu, który Claude Code czyta na początku każdej sesji. Dokumentuje:

  • Zasady architektury — tylko klasy final, bez dziedziczenia, segregacja interfejsów, value objects zamiast tablic asocjacyjnych
  • Styl kodu — strict types w każdym pliku, warunki Yoda, pusta linia przed return, konwencja przestrzeni nazw PSR-4
  • Konwencje nazewnictwa — nazewnictwo interfejsów (ContentServiceInterface → ContentService), readonly value objects, constructor property promotion
  • Polecenia DDEV — jak uruchomić środowisko, uruchomić buildy, sprawdzić jakość kodu
  • Struktura treści — gdzie mieszkają pliki Markdown, jak działa frontmatter, jakie są konwencje slug URL

Z tym kontekstem Claude generuje kod zgodny z rzeczywistymi konwencjami projektu. Przeglądanie wygenerowanej klasy wygląda jak przeglądanie pull requesta od kolegi, który przeczytał przewodnik stylu — nie jak przeglądanie outputu wymagającego tłumaczenia na konwencje projektu.

EDITOR_GUIDE.md — delegowanie tworzenia treści

Ta sama zasada dotyczy treści. EDITOR_GUIDE.md dokumentuje:

  • Format i długość tytułu (poniżej 70 znaków, nazwy technologii uwzględnione, bez clickbaitu)
  • Format opisu (120–160 znaków, bez "W tym wpisie...", zacznij od korzyści dla czytelnika)
  • Struktura wstępu (2–3 zdania, bez powitania, najpierw problem)
  • Konwencje treści (bloki kodu dla wszystkich poleceń, krótkie akapity, ponumerowane kroki dla procedur)
  • Wymagania parytetu EN/PL (obie wersje równej głębokości, te same bloki kodu)
  • Pola frontmatter i ich formaty

Dzięki temu przewodnikowi workflow tworzenia treści staje się:

  1. Napisz wpis w surowej formie — pomysły, fragmenty kodu, struktura
  2. Przekaż go Claude z: "sprawdź korektę, popraw angielski, przetłumacz na polski i wygeneruj dwa pliki .md z poprawnym frontmatter"
  3. Przejrzyj wynik

Przewodnik jest na tyle konkretny, że Claude nie musi zadawać pytań wyjaśniających. Format tytułu, konwencja slug, wartości kategorii, format tagów, wzorzec ścieżki do obrazu — wszystko jest udokumentowane. Wynik jest gotowy do zacommitowania.

Generowanie obrazów z Draw Things i MCP

Każdy wpis potrzebuje obrazu wyróżniającego (minimum 1200×630px). Dla holas.pl obrazy są generowane lokalnie za pomocą Draw Things przez integrację MCP (Model Context Protocol) w Claude Code.

Workflow:

  1. Claude Code wywołuje mcp__draw-things__generate_image z promptem opisującym obraz, 4 równoległe warianty 1024×576px z steps=4
  2. Najlepszy wariant jest wybierany z .generated/YYYY-MM-DD-nazwa-sesji/
  3. ImageMagick skaluje go do rozmiaru produkcyjnego:
ddev exec convert .generated/sesja/obraz.jpg \
    -resize 1920x1080! -filter Lanczos -quality 92 \
    assets/images/wynik.jpg
  1. Obraz jest przenoszony do content/blog/kategoria/nazwa-wpisu/files/ i referencjonowany w frontmatter

Katalog .generated/ jest w gitignore — zawiera jednorazowe podglądy. Tylko zatwierdzone obrazy zacommitowane do files/ stają się produkcyjnymi assetami.

MCP (Model Context Protocol) to właśnie to, co sprawia że to działa: standardowy interfejs łączący asystentów AI z zewnętrznymi narzędziami. Claude Code łączy się z Draw Things działającym lokalnie, przestrzeniami Hugging Face i innymi serwisami bez opuszczania sesji deweloperskiej. Generowanie obrazów dzieje się na lokalnej maszynie — bez limitu API, bez zewnętrznego serwisu, bez kosztu per obraz.

Co AI robi dobrze

Boilerplate i wzorce — generowanie nowego serwisu z interfejsem, value objectem i poprawną kolejnością importów jest natychmiastowe. Struktura jest spójna z resztą bazy kodu, bo konwencje są udokumentowane.

SCSS z opisu — opisanie układu komponentu słowami i otrzymanie działającego SCSS z nazwami zmiennych projektu jest szybsze niż pisanie od podstaw.

Tłumaczenie — polska i angielska treść równej jakości. Konkretność przewodnika redakcyjnego w kwestii tego, co "równa jakość" oznacza (te same bloki kodu, ta sama głębokość, nie streszczenie) daje tłumaczenia niewymagające znaczącej edycji.

Powtarzalna praca strukturalna — generowanie list przekierowań nginx, aktualizowanie frontmatter w wielu plikach, pisanie wpisów mapy strony — zadania z jasnymi zasadami, ale wieloma instancjami.

Pozostawanie w kontekście — Claude Code czyta pliki projektu, rozumie istniejące wzorce i generuje kod, który pasuje bez mówienia mu, co robi każda klasa.

Gdzie nadal potrzebny jest ludzki osąd

Decyzje architektoniczne — które abstrakcje wprowadzić, kiedy value object jest uzasadniony, jak ustrukturyzować pipeline treści — wymagają rozumienia kompromisów w sposób wykraczający poza dopasowywanie wzorców. AI generuje wiarygodne opcje; decyzja nadal należy do człowieka.

Estetyka designu — zmienne SCSS mogą być generowane, ale decyzja czy paleta kolorów dobrze wygląda na ciemnym tle w stylu terminala wymaga oczu i gustu.

Głos treści — przewodnik redakcyjny ujmuje konwencje tonu, ale faktyczne pomysły — co warto pisać, który kąt jest interesujący — pochodzą z doświadczenia, nie z promptu.

Przeglądanie outputu AI — kod i treść nadal muszą być czytane. Kod generowany przez AI wygląda wiarygodnie; wymaga developera, żeby zauważyć, gdy coś jest technicznie poprawne, ale architektonicznie złe.

Praktyczny wynik

Cała strona — architektura, frontend, pipeline treści, formularz kontaktowy, skrypty deploymentu, ta seria wpisów blogowych — została zbudowana z Claude Code. Inwestycja czasu w AGENTS.md i EDITOR_GUIDE.md zwróciła się natychmiast: mniej czasu na korygowanie stylu, mniej czasu na tłumaczenie tych samych konwencji sesja po sesji, więcej czasu na faktyczną pracę.

Najbardziej zaskakującą korzyścią była treść. Napisanie wpisu w surowej formie, korekta, tłumaczenie na angielski i konwersja do dwóch poprawnie ustrukturyzowanych plików .md z prawidłowym frontmatter w jednym kroku — to usuwa wystarczająco dużo tarcia, że publikowanie faktycznie się dzieje.

Architektura zbudowana w ten sposób nie tylko produkuje łatwy w utrzymaniu kod — daje mierzalne wyniki. Następny wpis omawia wyniki Lighthouse: co napędza każdy z czterech wskaźników i dlaczego większość z tego wynika z architektury, nie z pracy optymalizacyjnej.