SEO, AI i repozytorium projektu
Agent AI w repozytorium to model językowy, który pracuje bezpośrednio na plikach projektu: czyta kod i treści, uruchamia polecenia, pobiera dane przez API lub MCP i przygotowuje zmiany, które zatwierdza człowiek. Szerszy przegląd zastosowań, od analizy słów kluczowych po monitoring, opisuję w przewodniku jak wykorzystać AI w SEO.
Punktem 0 jest dostęp do repozytorium, w którym możemy odpalić albo kilku agentów. Przyda się trochę podstawowej wiedzy programistycznej i zakładam, że taką posiadasz, masz dostęp do repozytorium projektu i skonfigurowany proces pracy w Gicie. W omawianym przykładzie będę pracował w Visual Studio Code z pobranymi wtyczkami Codex i Claude Code. Dla własnej wygody lubię pracować z oboma agentami, by mogły się skuteczniej sprawdzać nawzajem, robić lub ulepszać swoją pracę.
Jak przygotować dane dla agenta AI?
W tym kroku wszystko zależy od tego, skąd i ile mamy danych oraz jak łatwo możemy je przekazać agentowi. Punktem startowym, poza właściwą konfiguracją agentów AI, jest dostęp do danych z . Historia projektu pomaga w porównaniach, ale jej brak nie wyklucza audytu technicznego. jest źródłem opcjonalnym, które może pomóc ustalić priorytety według wejść organicznych i kluczowych zdarzeń, np. wysłania formularza, jeśli pomiar jest poprawnie skonfigurowany. W omawianym przypadku, czyli przy sprawdzaniu indeksacji, GA4 nie jest potrzebne.
Nie chcę się tutaj zagłębiać w konfigurację dostępu do danych, ponieważ może to być MCP płatny lub darmowy, ale grunt, by model mógł na naszą komendę sięgać do surowych danych analitycznych. Warto dać modelowi także kontekst w postaci surowych danych z raportu PageSpeed Insights albo cały plik HAR wygenerowany w narzędziach deweloperskich przeglądarki (DevTools).
Do agenta można też podłączyć Screaming Frog SEO Spider przez MCP, dostępne od wersji 24.0. Po skonfigurowaniu połączenia agent może uruchamiać skanowanie serwisu, analizować wyniki i eksportować dane, które następnie zestawi z GSC oraz kodem projektu. Integracja nie obejmuje jeszcze wszystkich funkcji SEO Spidera, dlatego przed zleceniem zadania warto sprawdzić dostępne narzędzia.
Każde źródło odpowiada na inne pytanie i każde ma swoje ograniczenia, które warto przekazać agentowi razem z danymi:
| Źródło | Co daje agentowi | Czego nie pokaże |
|---|---|---|
| Search Console: raport skuteczności (Search Analytics API) | Kliknięcia, wyświetlenia, CTR i pozycje do 16 miesięcy wstecz | Stanu indeksacji, części zapytań pominiętych ze względu na prywatność |
| URL Inspection API | Stan indeksacji, adres kanoniczny wybrany przez Google, datę ostatniego skanowania pojedynczego adresu | Testu na żywo, historii stanów; limit 2000 zapytań dziennie |
| PageSpeed Insights API (Lighthouse) | Dane laboratoryjne i rekomendacje dla wybranego adresu | Doświadczeń realnych użytkowników ani terenowego INP |
| CrUX API | Dane terenowe LCP, INP i CLS (75. percentyl) | Danych dla adresów o zbyt małym ruchu |
| Screaming Frog przez MCP | Wynik skanowania serwisu: kody odpowiedzi, adresy kanoniczne, linki wewnętrzne | Danych Google o indeksacji i ruchu |
| GA4 (opcjonalnie) | Wejścia organiczne i kluczowe zdarzenia | Informacji o indeksacji |
Jakość i aktualność danych
Liczy się przede wszystkim jakość danych oraz ich związek z pytaniem, aktualność i znane źródło. Chcę tutaj zaznaczyć, by zadbać o aktualność danych, ponieważ nieaktualne albo sprzeczne informacje mogą utrudnić analizę. W związku z powyższym razem z danymi przekazujemy zakres dat, filtry i ograniczenia źródła, a wnioski nadal sprawdzamy. Surowe odpowiedzi API warto zachować w JSON lub CSV, a w pliku .md zapisać analizę i odwołania do tych plików. Dzięki temu drugi agent lub człowiek może sprawdzić liczby bez polegania na streszczeniu modelu. Trzeba pamiętać, by eksporty zawierające dane klienta przechowywać w miejscu z odpowiednimi uprawnieniami, poza publicznym repozytorium.
Jak zlecić agentowi AI audyt SEO?
Pierwszym krokiem będzie zastanowienie się, do czego potrzebujemy właściwie agenta. Przyjmijmy, że chcemy szybko poznać główne problemy projektu, po tym, jak krótko przeklikaliśmy wybrane sekcje w Google Search Console. Konkretnie rzecz biorąc, chcemy sprawdzić stan jego indeksacji oraz . Do interpretacji sprzecznych sygnałów wybieram model dobrze radzący sobie z analizą kodu i danych. Osobiście preferuję najlepsze modele, najlepiej z rodziny Opus (Claude) lub Astra/Sol (OpenAI). Czym różnią się modele w codziennej pracy, porównuję w artykule Programowanie z AI: Claude, ChatGPT czy Gemini.
Raport indeksacji z URL Inspection API
Zanim napiszemy prompt, trzeba wiedzieć, skąd agent ma wziąć dane, bo API Search Console nie udostępnia raportu indeksowania stron w całości. Informacje o indeksacji pojedynczych adresów można pobierać przez , z limitem 2000 zapytań dziennie i 600 na minutę na usługę. Trzeba pamiętać, że API zwraca informacje dostępne w Google o wersji zapisanej w indeksie, nie wykonuje testu strony na żywo, a data pobrania raportu i data ostatniego skanowania to dwie różne rzeczy.
API inspekcji URL nie udostępnia historii stanów dla pojedynczego adresu, jednak możemy budować ją samodzielnie, zapisując kolejne wyniki. Z kolei panel GSC prezentuje zagregowaną historię w raporcie indeksowania. Dodatkowo dane o kliknięciach i wyświetleniach z raportu skuteczności są dostępne do 16 miesięcy wstecz, co świetnie sprawdza się w analizie historycznej projektu. Dlatego prompt musi wskazać źródło adresów, sposób ich sprawdzenia oraz zachowanie po wyczerpaniu limitu i przy błędzie narzędzia.
Piszemy prompt:
Zanim jednak wyślesz taki prompt, upewnij się, że serwer MCP, z którego korzystasz, w ogóle udostępnia narzędzie do inspekcji adresów. Lista adresów z mapy witryny daje kontrolowany zbiór, więc od razu widać, czego agent nie sprawdził. To jednak audyt adresów z mapy witryny, a nie całego serwisu. Przy pełniejszej analizie porównujemy ją z trasami i treściami w repozytorium, wynikiem własnego skanowania serwisu oraz adresami znanymi z GSC. W innym wypadku pominiemy np. stronę, której zabrakło w generatorze mapy.
Hipotezy: dlaczego strony nie są w indeksie
Idąc dalej, zebraliśmy właśnie wnioski i czekają one w pliku .md, więc teraz kolejnym krokiem jest analiza samego raportu. Pierwsze wnioski, jakie posiada model, są niepełne — nas interesuje teraz kontekst, jak to się ma do stanu technicznego strony internetowej. Każda hipoteza musi mieć jednoznaczne pokrycie w kodzie, odpowiedzi serwera lub danych z raportu, bo inaczej trudno odróżnić trafną diagnozę od zgrabnie brzmiącej halucynacji.
Piszemy prompt:
Agent powinien przedstawić nam kompleksowy raport zapisany w pliku .md który będzie w projekcie. Dlaczego operowanie na plikach jest takie ważne? Modele gubią i nie pamiętają informacji, to raz, a dwa, gdy dzielimy takie zadania na wyraźne kroki, LLM jest skuteczniejszy i lepiej radzi sobie ze wskazanymi zadaniami. Generalna zasada to nie stosować zbyt szerokich promptów do skomplikowanych zadań.
Core Web Vitals z PageSpeed Insights i CrUX
Analizę warto uzupełnić o wydajność i Core Web Vitals. Dane CrUX (RUM) pokazują realne doświadczenia użytkowników, podczas gdy Lighthouse bada stronę w laboratoryjnych warunkach. Pamiętaj, że wskaźnik TBT w Lighthouse nie jest zamiennikiem terenowego INP.
Przekazywanie agentowi AI linków do PageSpeed Insights bywa zdradliwe, bo raporty renderują się przez JavaScript, co prowadzi do halucynacji danych. By tego uniknąć, po prostu zasil swojego agenta danymi bezpośrednio przez API. Co ważne, z uwagi na zapowiadane przez Google zmiany w PSI API, warto od razu rozdzielić pobieranie danych laboratoryjnych od dedykowanego CrUX API (lub CrUX History API). Analizę zaczynaj od próbki diagnostycznej, czyli po jednym reprezentatywnym adresie z każdego szablonu strony, zamiast ograniczać się tylko do strony głównej:
Cały proces pracy na plikach
Tak wygląda cały przepływ pracy na plikach, od surowych danych do wdrożenia. Każdy krok zostawia po sobie plik, który można przejrzeć, poprawić albo przekazać drugiemu agentowi do sprawdzenia.
Przykład z praktyki: audyt serwisu inspektomat.pl
Tak prowadzona analiza sprawdziła się w serwisie inspektomat.pl. W danych z Search Console wyszła wpisów o tematyce gazowej i elektrycznej, czyli kilka artykułów konkurujących ze sobą o te same zapytania. Po audycie część z nich skasowałem, a część połączyłem ze sobą, bo odpowiadały na podobne intencje użytkowników. Takie porządki w treści zajęłyby stosunkowo dużo czasu.
Drugim wątkiem były strony z poniżej 1%. Taki wynik jest sygnałem do analizy, ale sam nie dowodzi rozminięcia z . Trzeba uwzględnić pozycję, zapytania, urządzenie, liczbę wyświetleń i wygląd wyników wyszukiwania; ten sam CTR na odległej pozycji i w pierwszej trójce wymaga innej interpretacji. Dla wybranych z nich poprawiłem tytuły i opisy meta tak, żeby lepiej pasowały do zapytań, które faktycznie wpisują użytkownicy. Najważniejszym wnioskiem okazało się jednak rozpoznanie, gdzie leżą największe problemy z indeksacją części stron typu usługa/miasto.
Samo pojawianie się kilku adresów na te same zapytania nie wystarcza do rozpoznania szkodliwej kanibalizacji, dlatego najpierw porównujemy intencję, zawartość i widoczność poszczególnych stron w czasie, a dopiero potem myślimy o scalaniu lub ewentualnie kasowaniu wpisu. Przy połączeniu treści trzeba też zaplanować przekierowania starych URL-i do odpowiedniego następcy i zaktualizować linki oraz mapę witryny. W sytuacji, kiedy usuwana strona nie ma odpowiednika, właściwe może być 404 lub 410 zamiast przekierowania do niepowiązanej strony.
Od diagnozy do zmiany: trzy przykłady w repozytorium
Poniższe scenariusze pokazują sposób pracy, a w każdym przypadku najpierw zatwierdzamy diagnozę i zakres, a potem zlecamy zmianę na osobnej gałęzi. Agent powinien znać docelowy URL, odpowiedzialne pliki i kryteria sprawdzenia efektu.
Błędny adres kanoniczny w szablonie strony
Załóżmy, że samodzielna podstrona /uslugi/przeglad-instalacji/ deklaruje adres kanoniczny wskazujący stronę główną. W odpowiedzi HTML widać ten adres, a w repozytorium agent znajduje wspólną konfigurację metadanych, która przypisuje go wszystkim usługom. Najpierw sprawdzamy, czy podstrona rzeczywiście ma być osobno indeksowana i nie jest duplikatem innej wersji.
Zmiana w repozytorium: poprawiamy generator metadanych lub nadpisanie dla danej trasy, tak aby adres kanoniczny wskazywał pełny docelowy adres tej strony, z protokołem i właściwą domeną produkcyjną. Jeśli przyczyna leży we wspólnym szablonie, sprawdzamy również inne korzystające z niego podstrony. Adres kanoniczny jest sygnałem dla Google, więc samo jego ustawienie nie gwarantuje, że wyszukiwarka wybierze wskazany adres.
Po buildzie sprawdzamy adres kanoniczny w wynikowym HTML, docelowy status HTTP i zgodność adresu z linkowaniem oraz mapą witryny. Powtarzamy kontrolę po wdrożeniu. Dopiero późniejsza inspekcja, po ponownym skanowaniu przez Google, może pokazać zmianę wyboru adresu kanonicznego.
Osierocona strona bez linków wewnętrznych
Strona może być opublikowana i obecna w mapie witryny, a mimo to nie mieć linków prowadzących z innych stron serwisu. Agent porównuje listę tras lub treści z linkami znalezionymi podczas skanowania. Brak odnośnika w kilku plikach nie wystarcza: trzeba uwzględnić nawigację i linki generowane przez komponenty. W raporcie zapisujemy zakres sprawdzenia.
Zmiana w repozytorium: dodajemy kontekstowy link z powiązanego artykułu, strony kategorii lub listy usług. Jeśli brak wynika z filtra w komponencie listującym wpisy, poprawiamy ten filtr zamiast ręcznie dopisywać link do każdej strony. Wybieramy miejsce przydatne czytelnikowi i opisowy tekst odnośnika.
Po zmianie sprawdzamy, czy wyrenderowana strona źródłowa zawiera zwykły link <a href="…">, czy adres docelowy odpowiada poprawnie i czy ponowne skanowanie odnajduje połączenie. Obecność w mapie witryny pomaga odkrywać URL, ale nie zastępuje nawigacji i kontekstowego linkowania.
Treść niskiej jakości, która nie odpowiada na pytanie użytkownika
Załóżmy, że strona usługi zawiera głównie ogólniki, a strony miast różnią się tylko nazwą miejscowości. Agent może wskazać powtórzenia i pytania, na które tekst nie odpowiada. Sam brak indeksacji, niski CTR ani mała liczba słów nie dowodzą jednak niskiej jakości. Oceniamy przydatność treści wobec rzeczywistej oferty i potrzeb użytkownika.
Zmiana w repozytorium: redagujemy odpowiedni plik MDX lub źródło treści, uzupełniając potwierdzone informacje o zakresie usługi, przebiegu realizacji, ograniczeniach i pytaniach klientów. Przy stronach lokalnych opisujemy rzeczywiste różnice w obsłudze, jeśli istnieją. Gdy strony nie mają odrębnej wartości, rozważamy ich połączenie zamiast produkowania kolejnych parafraz.
Po redakcji porównujemy tekst z materiałami źródłowymi, sprawdzamy diff, renderowanie MDX i linki.
Jak zlecić zmianę i sprawdzić jej efekt
Po zatwierdzeniu wybranego rozwiązania można użyć takiego polecenia:
Przed publikacją zachowujemy punkt odniesienia: wyniki inspekcji, metryki dla wybranych URL-i i datę wdrożenia. Od razu po publikacji sprawdzamy efekt techniczny. Później obserwujemy ponowne skanowanie, indeksację i widoczność, porównując podobne okresy i te same segmenty danych. Zmiana pozycji, sezonowość lub inne wdrożenie mogą wpływać na wynik, dlatego nie przypisujemy automatycznie całej różnicy pracy agenta. Poprawny build i usunięcie błędu nie gwarantują indeksacji ani wzrostu ruchu.
Zagrożenia w pracy z danymi analitycznymi
Agent zgaduje stan indeksacji
Teraz mały kubeł zimnej wody, ponieważ nawet najdokładniejszy prompt nie gwarantuje, że dane będą poprawne. Polecenie o zbieraniu danych o indeksowalności brzmi prosto, ale w opisanym procesie informacje o indeksacji pobieramy pojedynczo przez URL Inspection API, a aktualny stan techniczny sprawdzamy osobno. W związku z tym, jeśli agent nie ma do niego dostępu albo wyczerpie limit, potrafi wywnioskować indeksację z wyświetleń w raporcie skuteczności („strona miała wyświetlenia, więc jest w indeksie”) albo ją po prostu zgadnąć, a raport i tak będzie wyglądał na kompletny. Dlatego zanim zaczniesz wyciągać wnioski, sprawdź w raporcie, ile adresów faktycznie przeszło inspekcję i skąd pochodzą liczby przy każdym wniosku.
Niepełne i opóźnione dane w Search Console
Z tym wiąże się druga sprawa, czyli niepełne dane w samej Search Console. Świeże dane raportu skuteczności mogą być niepełne. Raport pomija też część zapytań ze względu na prywatność użytkowników. Z kolei raport indeksowania stron wyświetla najwyżej 1000 przykładowych adresów dla każdego problemu; nie gwarantuje kompletnej listy nawet poniżej tego limitu. Stan zapisany w GSC bywa też nieaktualny o wiele dłużej, niż się spodziewamy, bo zdarzało mi się widzieć adresy oznaczone jako błąd 404 sprzed pół roku, choć od dawna działały. Te dane są bardzo cenne, ale nie mamy ich w 100%, więc wnioski agenta weryfikuję na żywo, sprawdzając, co serwer odpowiada dziś.
Search Analytics API domyślnie zwraca do 1000 wierszy, pozwala zwiększyć rowLimit do 25 000 i pobierać kolejne strony przez startRow. Paginacja nie usuwa jednak wszystkich ograniczeń: Google nie gwarantuje zwrócenia każdego wiersza. Raport musi więc opisywać zakres pobrania, a brak rekordu odróżniać od potwierdzonego wyniku zero.
Halucynacje przy błędach narzędzi
Osobnym ryzykiem są przy błędach narzędzi. Gdy serwer MCP zwróci błąd, pusty wynik albo uciętą odpowiedź, model nie zawsze to zgłosi i czasem uzupełni lukę wiarygodnie wyglądającymi liczbami. W związku z powyższym, kilka wartości z raportu zawsze warto porównać z panelem, zanim zaczniemy podejmować wiążące decyzje.
Zagrożenia w pracy agenta AI w repozytorium
Regulaminy B2B i B2C a trening modelu
Zanim wprowadzimy agenty do projektu, trzeba zapoznać się z zasadami usług w chmurze: wykorzystaniem danych do treningu, ustawieniami prywatności, retencją oraz warunkami integracji MCP. Ten temat szerzej poruszał jeden z paneli w ramach Umiejętności Jutra AI, gdzie prelegentki opowiadały o różnicach w regulaminach B2B (modele nie uczą się na danych) i B2C (modele uczą się na danych). W praktyce podział nie jest taki oczywisty i bywa różnie. Dlatego musisz sprawdzić regulamin danej usługi pod tym kątem. Poza tym, w praktyce nigdy nie zapisuj sekretów w promptach ani w raportach i zawsze ograniczaj uprawnienia do plików oraz narzędzi do danego zadania. Przykładowo Anthropic opisuje w produktach konsumenckich wykorzystanie danych zależne od zgody oraz określone wyjątki; w produktach komercyjnych domyślnie nie trenuje na danych, ale osobne zasady dotyczą m.in. przesłanych opinii.
Bezpieczeństwo w dostępie do kluczy i tokenów
Osobną sprawą jest bezpieczeństwo, ponieważ agent pracujący w repozytorium ma dostęp do plików z kluczami i tokenami, a treść analizowanych stron może zawierać , więc warto ograniczyć jego uprawnienia i nie zatwierdzać niezrozumianych przez nas komend.
Kontrola pracy agenta AI w repozytorium
Gdy agent przechodzi od analizy do zmian w plikach, najważniejsze staje się pilnowanie zakresu zmian. Agent lubi poprawiać rzeczy, o które nie prosiliśmy, a automatyczne skrypty potrafią po cichu coś zgubić. Tutaj na pierwszy plan wysuwają się przypadki, kiedy przy masowych zmianach we frontmatterze plików MDX automatyczny skrypt odpalony przez Codex zepsuł wszystkie te pliki. Zdarzało się to kilkukrotnie w starszych modelach, natomiast aktualnie zdarza się rzadziej, a model podczas nieprzerwanej pracy sam naprawia błędy. Inny przykład to nagminne wprowadzanie przekierowań 301, podczas gdy projekt realnie ich nie potrzebuje. Receptą na część z tych problemów są stałe instrukcje projektu. Plik CLAUDE.md (w Claude Code) lub AGENTS.md (w Codex) agent wczytuje na starcie każdej sesji, więc to dobre miejsce na zasady obowiązujące zawsze, np. „nie dodawaj przekierowań bez zgody”. Skille działają inaczej: na początku agent zna tylko ich krótkie opisy, a pełną treść wczytuje dopiero wtedy, gdy uzna ją za potrzebną do zadania. Nadają się więc do powtarzalnych procedur, a nie do reguł, które muszą obowiązywać od pierwszej komendy. W ten sposób możemy zabezpieczyć się przed wieloma nie do końca kontrolowanymi zachowaniami agenta, by nie musieć sprzątać po nim po przejrzeniu zmian w kontroli wersji.
Pracując w jakimkolwiek edytorze kodu, czy to w Cursorze, czy w Visual Studio Code, pamiętaj, by dobrze przyjrzeć się (Source Control) i zakresowi pracy swojego agenta AI. Każda zmiana powinna zostać przez Ciebie zatwierdzona wtedy i tylko wtedy, gdy jesteś pewny, że ją zleciłeś, a agent nie wprowadza zmian bez uzasadnienia. Pamiętaj, że to Ty odpowiadasz za ostateczny rezultat pracy agenta i co zostało wdrożone. Część błędów możesz wyłapywać automatycznie, na przykład testami SEO w GitHub Actions, które pilnują meta tagów, i przekierowań przy każdym wdrożeniu. A jeśli coś mimo wszystko przejdzie, zmianę cofniesz w Gicie, co opisuję w artykule o cofaniu commitów i odzyskiwaniu zmian.


