Tworzenie stron WordPress z AI to nie magia. Jak wbudowaliśmy agenta AI w CHISEL

W tym roku wbudowaliśmy zestaw narzędzi AI w CHISEL, nasz framework WordPress. Spisaliśmy wszystko, co wiemy o budowaniu dobrych stron WordPress, tak żeby agent AI mógł się tym kierować.

Można by opowiedzieć tę historię tak, że wpisujesz jedno zdanie, agent pisze idealny motyw WordPress, a programista popija kawę, podczas gdy praca robi się sama. Tej historii nie opowiemy.

Prawda jest mniej magiczna i bardziej przydatna. Przez ostatni rok zespół developerski xfive wbudował zestaw narzędzi AI w CHISEL, nasz framework do tworzenia stron WordPress. Wzięliśmy wszystko, co już wiedzieliśmy o dobrym budowaniu stron, od konwencji, przez decyzje wymagające doświadczenia, po rzeczy, których nowa osoba w zespole zwykle uczy się, patrząc na innych. Potem spisaliśmy to na tyle starannie, żeby agent mógł się tego trzymać.

Dlaczego dodaliśmy AI do frameworka CHISEL?

Dodaliśmy AI, bo wciąż ręcznie powtarzaliśmy te same czynności, takie jak rejestrowanie bloków, podłączanie custom post types, dodawanie skryptów i tworzenie szkieletów wzorców. Chcieliśmy, żeby za każdym razem były zrobione po naszemu, przez każdego programistę, niezależnie od tego, czy pracuje z nami pięć lat, czy pięć tygodni, i bez rezygnowania ze standardów na rzecz szybkości. Zanim wprowadzimy AI do projektów klienckich, chcieliśmy też sami dobrze je poznać, na własnych zasadach.

Jak pracować z agentem AI? Cztery zasady zamiast jednego promptu

Dobra praca z agentem AI opiera się na czterech osobnych umiejętnościach. Trzeba zdecydować, co mu przekazać, jasno sformułować zadanie, ocenić, co zwrócił, i wziąć odpowiedzialność za wynik. Wystarczy pominąć jedną, żeby całość się posypała. Podejście „wpisz prompt i licz na szczęście” to tylko formułowanie zadania, bez pozostałych trzech elementów.

Nasz zestaw narzędzi to właśnie te cztery umiejętności przeniesione do praktyki. Zasady i skills to opis zadania. Dwa punkty kontrolne z udziałem człowieka to moment, w którym programista ocenia pracę i bierze za nią odpowiedzialność. A decyzję, które zadania w ogóle warto przekazać agentowi, podejmujemy, zanim cokolwiek się zacznie. Bardziej formalną wersję tego podejścia opisuje framework 4D dla biegłości w pracy z AI.

Co zawiera zestaw narzędzi AI w CHISEL?

Zestaw narzędzi AI to pliki z zasadami, wiedzą i procedurami, które agent czyta na początku każdego zadania. Jest dołączany do każdego nowego projektu CHISEL i dostępny jako open source. Zaprojektowaliśmy go tak, żeby oszczędzał tokeny, dlatego składa się z wielu małych plików, które agent wczytuje, gdy ich potrzebuje, zamiast jednego ogromnego pliku z instrukcjami.

Punktem wejścia są pliki CLAUDE.md i AGENTS.md. To zawsze wczytywany spis treści, który zawiera kluczowe zasady i kieruje agenta do szczegółów potrzebnych przy danym zadaniu. Trzymamy oba pliki, bo zestaw celowo nie jest przywiązany do jednego modelu. Używamy go z Claude Code i z Codexem, a wspólna konwencja AGENTS.md sprawia, że działa w obu środowiskach.

Pod spodem zestaw dzieli się na trzy części, czyli co, jak i przykłady.

CLAUDE.md / AGENTS.md          # entry point: load-bearing rules + routing
ai/
├── ai-new-session-prompt.md   # the "start here" prompt for every session
├── rules/
│   ├── reference/             # the WHAT: facts like file locations, design
│   │                          #   tokens, block/CPT conventions, Twig,
│   │                          #   REST API, MCP workflow, WooCommerce…
│   └── templates/             # the EXAMPLES: copy-paste code scaffolds
└── skills/                    # the HOW: step-by-step procedures,
                               #   discovered and run by the agent

Dokumentacja referencyjna to „co”, czyli gdzie co leży, jak działa dana funkcja i jakie mamy konwencje nazewnictwa. Skills to „jak”, czyli uporządkowane przepisy na stworzenie czegoś, na przykład szkieletu bloku albo komponentów CHISEL z projektu w Figmie. Agent sam je znajduje i wykonuje, gdy zadanie tego wymaga. Celowo trzymamy te dwie rzeczy osobno, bo plik, który próbuje być jednym i drugim, jest dla agenta trudniejszy do wykonania. Szablony to konkretne szkielety struktury, z których agent kopiuje kod tylko wtedy, gdy go pisze. Kolejność wczytywania jest zawsze taka sama. Najpierw plik wejściowy, potem pasująca dokumentacja referencyjna, potem pasujący skill, a na końcu szablon, jeśli trzeba skopiować kod.

Przygotowaliśmy też szablon promptu na początek sesji. Dzięki niemu każdy zaczyna sesję tak samo, a my mamy pewność, że agent przeczytał instrukcje, zanim czegokolwiek dotknie.

Jak agent AI buduje stronę WordPress krok po kroku?

Agent pracuje w stałej pętli z dwoma punktami, w których zatrzymuje się i czeka na decyzję programisty. Tu najlepiej widać, dlaczego to nie magia. Agent nie przechodzi samodzielnie od promptu do pull requesta.

Po opisaniu zadania agent wczytuje zestaw narzędzi i sprawdza, czy jakieś prace nie są już w toku. Potem klasyfikuje zadanie. Drobne poprawki pomijają całą procedurę i od razu trafiają do weryfikacji. Przy większych zadaniach agent czyta odpowiedni kod i dokumentację, a następnie zatrzymuje się, żeby doprecyzować i zatwierdzić z tobą decyzje. Dopiero wtedy pisze plan. Potem zatrzymuje się drugi raz, przy bramce, i czeka na zgodę, zanim zacznie budować. Po zbudowaniu sprawdza build, testy i lint, przekazuje podsumowanie z propozycją commita i wraca do kolejnego zadania.

Te dwa przystanki, doprecyzowanie i bramka, są najważniejsze w całej pętli. W obu agent proponuje, a programista zatwierdza, zanim cokolwiek pójdzie dalej.

Powiedzmy, że prosisz o sekcję hero. Agent wczytuje zestaw narzędzi, czyta odpowiednie bloki i dokumentację, a potem zatrzymuje się z pytaniami. Czy ma to być blok ACF, czy wzorzec? Jakich pól potrzebuje? Jak nagłówek odpowiada projektowi? Odpowiadasz na te pytania, a agent pisze plan. Zatrzymuje się przy bramce, ty zatwierdzasz. Dopiero wtedy tworzy blok, a MCP wstawia go na prawdziwą stronę, żebyś mógł zobaczyć efekt w WordPressie bez ręcznego składania bloków. Sprawdzasz wynik, agent proponuje commit i jest gotowy na kolejne zadanie.

Jak agent AI dokumentuje postęp prac?

Przy każdym większym zadaniu agent prowadzi pisemny zapis w zwykłych plikach markdown, które trafiają do repozytorium w folderze ai-progress/. Zapis dzieli się na trzy części.

• INDEX.md to drogowskaz. Każde zadanie jest tu wpisane w jednej linii, w grupach „W toku” i „Zakończone”. Agent zawsze czyta go jako pierwszy.
• FINDINGS.md zbiera błędy i obserwacje, które agent zauważył przy okazji.
• changes/{NN}-{task}/ to osobny folder dla każdego zadania. Zawiera ROADMAP.md (zakres, zatwierdzone decyzje i tabelę etapów), LOG.md, do którego można tylko dopisywać, i po jednym pliku na każdy etap.

Tabela etapów w roadmapie to jedyne miejsce, w którym sprawdza się status. Każdy etap ma status „nierozpoczęty”, „w toku”, „gotowy” albo „zablokowany”, a każdy zakończony wiersz ma jednozdaniowe podsumowanie, żeby nikt nie wracał do zamkniętych spraw. Nowa sesja czyta indeks, potem aktywną roadmapę, a potem tylko plik bieżącego etapu. To trzy małe pliki zamiast wycieczki po całym kodzie.

Pliki etapów powstają na początku etapu, więc są planem, który programista zatwierdza, zanim powstanie jakikolwiek kod.

Wpisy w logu pisane są z myślą o kolejnym kroku, więc zapis kończy się wskazówką, co dalej, a nie samym potwierdzeniem wykonania. W praktyce pełny stan projektu jest zapisany, kilka osób może przejąć pracę w miejscu, w którym ktoś inny skończył, a historia zmian pokazuje, co się zmieniło i dlaczego. Na takiej historii polega osoba robiąca code review, a po kilku miesiącach także ty sam.

Czy przy pracy z AI nadal trzeba znać WordPressa?

Tak. Zestaw narzędzi działa tylko dlatego, że już wcześniej umieliśmy dobrze budować strony WordPress, od konwencji i architektury po preferencje wynikające z lat wdrożeń. Ta wiedza najbardziej przydała się przy testowaniu i debugowaniu. Znamy CHISEL od podszewki, więc od razu widzieliśmy, kiedy agent szedł w złym kierunku, często już na etapie planu, zanim powstała pierwsza linijka kodu, i mogliśmy go zawrócić.

Najlepszym przykładem jest nazewnictwo. Agent pozostawiony sam sobie wymyśla własne nazwy, a spójne nazewnictwo w projektach, dla grup pól ACF i wszystkiego innego, to dokładnie to, co przez lata standaryzowaliśmy. Dlatego zasady jasno określają nasze konwencje. Musieliśmy też kazać agentowi korzystać z istniejących bloków (z rdzenia WordPressa, z CHISEL lub z projektu), zanim zacznie budować nowe, bo sam z siebie chętnie budował od zera to, co już było.

Inne zasady opisują techniczne pułapki, których agent nie wywnioskuje sam. Wyjaśniają, jak ogólnie działa block.json, żeby agent wiedział, co gdzie należy. Musieliśmy też wprost napisać, że CSS bloku trzeba zaimportować w pliku JS tego bloku, bo inaczej Webpack go nie skompiluje. Kilka mniejszych zasad dotyczy reszty, czyli naszej flagi ignoreScripts, trzymania skryptów każdego bloku w jego własnym folderze zamiast w globalnym i konwencji wrapperów we wzorcach. Preferujemy też bloki ACF zamiast natywnych, więc musieliśmy jasno określić, co należy do kodu projektu, a co dodaje się w edytorze.

Najważniejsza zasada brzmi tak, że reguły nigdy nie zawierają konkretnych wartości na sztywno.

Opisują stan startowy CHISEL, a nie stan konkretnego, dostosowanego projektu. Gdy projekt zmieni padding przycisków, kolory albo nazwy odstępów, wszystko, co wpisalibyśmy do reguł, niepostrzeżenie by się zdezaktualizowało. A agent, który pewnie powołuje się na nieaktualne fakty, jest gorszy od takiego, który zatrzyma się i sprawdzi. Dlatego w regułach są tylko stałe elementy, takie jak chronione slugi, konwencje przestrzeni nazw, struktura plików i mechanika pipeline'u budowania. Wszystko, co zależy od projektu, agent odczytuje z samego projektu. Ta jedna decyzja odróżnia reguły, którym można ufać, od reguł, które wprowadzają w błąd.

Czym jest WordPress MCP i do czego służy?

WordPress MCP to serwer, który łączy to, co buduje agent AI, z działającą stroną WordPress. Nasz serwer, xfive-mcp, jest open source i opiera się na WordPress Abilities API oraz adapterze WordPress MCP.

Gdy agent stworzy zestaw bloków, MCP wstawia je na stronę jako prawdziwe bloki Gutenberga, żeby programista mógł zobaczyć efekt bez ręcznego klikania. Może też przenieść pracę bezpośrednio do WordPressa, łącznie z wdrożeniami. Potrafi tworzyć kategorie, generować dane testowe, na przykład przykładowe produkty, czytać wpisy oraz aktualizować i usuwać treści, wszystko za pomocą natywnych funkcji WordPressa. Większość usuwanych treści trafia do kosza, tak jak przy usuwaniu w panelu administracyjnym, a nie znika na zawsze. MCP działa przez WordPressa, a nie za jego plecami, dzięki czemu jest uniwersalny. Nie jest powiązany z CHISEL, więc można go użyć w dowolnym projekcie WordPress.

W czym AI radzi sobie gorzej? Backend kontra frontend

AI zdecydowanie lepiej radzi sobie z backendem niż z frontendem, nawet z pomocą Figma MCP. To było dla nas największe zaskoczenie. Zadania backendowe to głównie logika, a w logice modele są mocne. Problemy zaczynają się na frontendzie, gdzie trzeba wiernie odtworzyć projekt i sprawić, żeby działał na różnych ekranach i w różnych przeglądarkach.

Nasze projekty graficzne są zwykle bogate wizualnie, z tłami i elementami rozciągającymi się na kilka sekcji oraz detalami, które muszą być idealnie ustawione. Agent potrafi stworzyć coś, co wygląda dobrze w jednym miejscu, ale często psuje się w innych przeglądarkach albo gubi lub przesuwa elementy. Praca z Figmą to tak naprawdę dwa różne zadania. Przenoszenie treści i struktury z projektu do bazy danych działa dobrze i eliminuje żmudne kopiowanie. Wierne odtworzenie projektu graficznego na różnych przeglądarkach i ekranach wciąż sprawia nam kłopot.

Nauczyliśmy się też, że lepiej zacząć od własnego pomysłu i dać agentowi go zrealizować, niż pozwolić mu wymyślić całe podejście samodzielnie. Pisanie dobrych instrukcji okazało się rzemiosłem, które doskonali się iteracyjnie. Testujesz na prawdziwych projektach, obserwujesz, gdzie agent się potyka, i poprawiasz. To ruchomy cel, bo same modele ciągle się zmieniają. Jeden model sformułuje coś tak, że inny źle to zrozumie, więc testujemy na kilku modelach. Dlatego zestaw narzędzi jest projektem w ciągłym rozwoju, za który odpowiada programista.

Co daje AI w projektach WordPress?

AI przyspiesza powtarzalną pracę, ułatwia nowym programistom wejście w projekt i daje pewność, że dobre praktyki są faktycznie stosowane. Mniej doświadczeni programiści szybciej odnajdują się w projekcie, bo standardy są już zapisane, a my nie musimy liczyć na to, że ktoś o nich pamięta. To także zupełnie inny i dający dużo frajdy sposób pracy, w którym myślisz o tym, jak zachowują się agenci i jak z nimi współpracować.

[dodane] W projektach klienckich wsparcie AI w CHISEL pozwala przyspieszyć pracę programistyczną nawet o 30%. Klient płaci mniej za powtarzalne elementy, a zakres prac się nie zmniejsza. Tak dziś wygląda u nas tworzenie stron WordPress (link: hub WordPress).

Pierwsza wersja zestawu narzędzi powstała w kilka dni. Wszystko, co było potem, to stałe ulepszanie na podstawie lekcji z kolejnych projektów. Następny krok to udostępnienie zestawu jako pakietu npm, żeby jeszcze łatwiej było dodać go do projektu. Ten proces nie ma końca, nie przy tym tempie zmian, i będzie już tylko lepiej.

Sam CHISEL ma dłuższą historię, dekadę lekcji z projektów WordPress, które ukształtowały framework, na którym opiera się ten zestaw. Opisujemy ją w osobnym artykule. Zestaw narzędzi AI i xfive-mcp są open source, więc jeśli chcesz poznać szczegóły, najlepszą dokumentacją jest sam kod.

‍