Piątek, godzina 14:00. Nowy developer przejął projekt wczoraj. Klient zgłasza bug na produkcji - coś nie działa z custom queue workerem. Dawniej taki scenariusz oznaczał szukanie poprzedniego developera, który zna ten kod. Konsultacje, wyjaśnianie kontekstu, tracenie czasu. I to wszystko w piątek.
Teraz? Developer otwiera Cursor, pyta AI o ten queue worker i AI odpowiada sensownie, bo zna projekt. Wie, że używamy DDEV, że cache jest skonfigurowany w określony sposób, że mamy custom prefiksy modułów. Jak to możliwe? Wystarczy zastosowanie jednego pliku w projekcie: AGENTS.md.
W tym artykule:
- Problem: AI nie zna Twojego projektu
- Rozwiązanie: AGENTS.md
- Jak nasze narzędzie AGENTS.md działa w praktyce?
- Co się zmienia po dodaniu AGENTS.md?
- 3 elementy, które chcemy dopracować
- Co zawiera gotowy szablon AGENTS.md?
- Narzędzie AGENTS.md - podsumowanie
Problem: AI nie zna Twojego projektu
Pewnie znasz ten scenariusz: prosisz AI (Cursor, Copilot, Claude) o pomoc z Drupalem i dostajesz kod, który… nie pasuje.
AI nie wie, że używasz Paragraphs. Nie wie, że theme nazywa się inaczej niż zakłada. Nie wie, że masz specyficzną strukturę katalogów. Nie wie, jakie masz standardy kodowania.
Musisz tłumaczyć kontekst. Przy każdej rozmowie od nowa. AI halucynuje, bo nie ma źródła informacji i nie wie, jak wygląda Twój projekt.
Rozwiązanie: AGENTS.md
AGENTS.md to plik w głównym katalogu projektu, który AI czyta automatycznie na początku każdej sesji. Zawiera wszystko, co AI musi wiedzieć o projekcie.
Znajdują się tam takie informacje jak: - wersja Drupala i PHP, - struktura katalogów (web/, docroot/ czy może coś innego), - custom modules i ich prefiksy, - theme i jego organizacja, - standardy kodowania (PHPStan, PHPCS), - workflow (DDEV, Git, Composer), - content types, encje, integracje Drupala.
Zapowiada się dużo pracy? Aby tego uniknąć, opracowaliśmy proste narzędzie, które generuje ten plik automatycznie.
Jak nasze narzędzie AGENTS.md działa w praktyce?
Cały proces zajmuje około 5 minut:
- Pobierasz
AGENTS-TEMPLATE.mdz repozytorium (jedna komenda curl w README). - Kopiujesz prompt z README do swojego narzędzia AI.
- AI skanuje Twój projekt - sprawdza composer.json, konfigurację, moduły, theme.
- Dostajesz gotowy
AGENTS.mddopasowany do Twojego projektu.
Robisz to raz, a korzystasz przy każdej sesji z AI.
Narzędzie działa z takimi asystentami jak: Cursor, Copilot, Claude Code, Codex, Aider, Gemini CLI, Roo Code, Zed, Devin - i pewnie z innymi, których jeszcze nie testowaliśmy.
Repozytorium: github.com/droptica/drupal-agents-md
Co się zmienia po dodaniu AGENTS.md?
Nie będę pisał, że “produktywność wzrosła o 47%”, bo tego nie mierzyłem. Ale oto, co zauważyłem na projektach, dla których mamy AGENTS.md:
Onboarding nowych osób jest kilkukrotnie szybszy. Nowy developer nie musi pytać “a jakie są konwencje?”, “a jak nazywa się ten theme?”, “a czego używacie do cache?”. AI już to wie i podpowiada zgodnie z projektem.
Debugowanie z kontekstem. Kiedy zgłaszasz problem, nie musisz pisać elaboratu o architekturze. AI wie, że masz Paragraphs, że używasz określonego modułu do kolejek, że cache działa w określony sposób.
Mniej wyjaśniania, więcej kodowania. Zamiast zaczynać każdą rozmowę od “używamy DDEV, mamy web/ jako root, prefiksy modułów to xyz_” - po prostu piszesz, co chcesz zrobić.
Mniej halucynacji. AI nie wymyśla rzeczy, których nie ma w projekcie. Wie co jest zainstalowane, jakie są encje, jakie są zależności – podobnie jak moduły AI w Drupalu wykorzystują kontekst projektu do generowania treści.
3 elementy, które chcemy dopracować
Żeby nie było, że AGENTS.md to same superlatywy. Jest kilka rzeczy, które jeszcze dopracowujemy:
- Duże projekty generują duże pliki. Jeśli masz 50 custom modułów i skomplikowaną architekturę, AGENTS.md może być długi. Pracujemy nad tym, żeby AI brał tylko to, co potrzebne w danym kontekście.
- Plik wymaga aktualizacji przy większych zmianach. Dodajesz nowy moduł, zmieniasz strukturę - warto przegenerować plik. Nie jest to automatyczne (jeszcze).
- Zależy od jakości Twojego projektu. Jeśli masz chaos w kodzie, AGENTS.md ten chaos udokumentuje. AI będzie wiedział, że jest bałagan, ale sam tego bałaganu nie naprawi.
Co zawiera gotowy szablon AGENTS.md?
Template pokrywa większość rzeczy, które są istotne w projekcie na Drupalu:
- Środowisko: DDEV, Git workflow, Composer.
- Jakość kodu: PHPStan, PHPCS, PHPUnit, Codeception, Xdebug.
- Development: standardy kodowania, encje, moduły, formularze, baza danych.
- Modern Drupal: headless/API, SEO, multilingual.
- Frontend: themes, SCSS, optymalizacja JS/CSS, caching.
- Operacje: config management, wydajność i bezpieczeństwo strony, troubleshooting, automatyczne audyty.
Jeśli czegoś brakuje dla Twojego projektu, możesz dodać własne sekcje. To zwykły plik markdown.
Narzędzie AGENTS.md - podsumowanie
W ciągu kilku-kilkunastu minut możesz dodać AGENTS.md do swojego projektu na Drupalu i od razu zobaczyć różnicę w jakości podpowiedzi AI.
Repozytorium: github.com/droptica/drupal-agents-md
A jeśli szukasz agencji Drupala, która zajmie się rozwojem Twojego projektu z użyciem najnowszych technologii, skontaktuj się z nami.
