Jeżeli nie przeczytałeś pierwszego wpisu o AI zachęcam Cię do jego przeczytania [KLIKNIJ TUTAJ].
Jednym z większych przełomów w mojej pracy z AI był mail z dostępem do GitHub Copilot CLI.
Na początku go olałem. Kolejny mail, kolejne narzędzie, kolejna „rewolucja”, która pewnie skończy się na ładnym demo. Ale później kolega pokazał mi, że Copilot CLI potrafi uruchamiać różne polecenia bezpośrednio w terminalu.
I wtedy kliknęło.
Nagle pojawiła się ekscytacja. Taka prawdziwa, developerska. Nie „wow, AI napisało mi funkcję Fibonacci”, tylko raczej: „okej, to może realnie zmienić sposób pracy z projektem”.
Bo jasne — wiedziałem już, jak budować prompty. Znałem różne narzędzia. Testowałem podejścia. Ale nadal bardzo często efekt był taki sobie. Kod niby działał, ale nie był taki, jakiego oczekiwałem. Brakowało kontekstu projektu, standardów zespołu i tego całego „mięsa”, które normalnie ma developer siedzący w danym kodzie od miesięcy albo lat.
I wtedy na scenę weszły trzy rzeczy: instrukcje, skillsy i agenci.
Od razu ważna informacja: to, co opisuję, nie jest oficjalnym poradnikiem ani zestawem zaleceń od twórców tych narzędzi. To moje podejście, wypracowane na podstawie testów, błędów i kilku sytuacji, w których człowiek patrzy na wynik AI i myśli: „no pięknie, tylko teraz trzeba to naprawić”.
Instrukcje, czyli lokalne reguły gry
Zacznijmy od najprostszego elementu: instrukcji. Czasem możesz spotkać się też z AGENTS.override.md.
Żeby było wygodniej, załóżmy, że pracujemy w legacy projekcie napisanym w PHP. Architektura? Miks wszystkiego. Trochę starych wzorców, trochę nowych podejść, trochę decyzji sprzed lat, których nikt już nie pamięta, ale wszyscy się ich boją.
Klasyka gatunku.
W takim projekcie masz wiele obszarów. Każdy obszar ma swoje funkcjonalności, ale też swoje lokalne praktyki. W jednym miejscu zespół woli testy specyfikacyjne, w innym klasyczne unity. W jednym katalogu asercje są mile widziane, w innym ktoś uznał, że „to tylko zaciemnia kod”. Jeden moduł ma trochę bardziej domenowe podejście, drugi wygląda jak szybka akcja ratunkowa z 2017 roku.
I teraz wyobraź sobie, że wrzucasz do takiego projektu AI bez żadnego kontekstu.
No cóż. Powodzenia.
Instrukcje pomagają ten problem ograniczyć. Dla mnie instrukcja albo override to po prostu zestaw reguł dla konkretnego katalogu, modułu albo obszaru projektu. Taki lokalny drogowskaz dla AI: tutaj piszemy tak, tutaj testujemy tak, tutaj nie ruszamy tego bez potrzeby, a tutaj najpierw przeczytaj trzy pliki, zanim zaczniesz udawać architekta.
--- applyTo: "src/Module/Order/**" --- # Instrukcje dla modułu Order Ten moduł zawiera legacy kod PHP odpowiedzialny za obsługę zamówień. ## Unit testy - Wykorzystaj PHPSpec - Nigdy nie pisz w PHPUnit
To nie musi być wielka filozofia. Czasem kilka dobrze napisanych zasad daje większy efekt niż prompt na dwie strony, który brzmi jak specyfikacja przetargu publicznego.
Skillsy, czyli standardy i umiejętności
Kolejny poziom to skillsy.
Skillsy rozumiem jako konkretne umiejętności, standardy albo procedury, które AI może wykorzystać podczas pracy. W paczce do kodowania dla zespołu mogą to być na przykład:
- standardy pisania kodu PHP,
- standardy testów jednostkowych,
- sposób pracy z legacy kodem,
- zasady tworzenia DTO,
- sposób czytania danych z indeksu Elasticsearch,
- sposób utrwalania danych w Elasticsearchu,
- standard komunikacji z wewnętrznym API,
- reguły przygotowywania pull requestów.
Czyli nie jedna komenda typu „stwórz klasę”, tylko raczej wiedza, jak robić daną rzecz zgodnie z naszym sposobem pracy.
I tu jest ważna różnica.
Nie jestem fanem tworzenia osobnego skilla do każdej małej operacji. To przypomina trochę problem z metodą add() w repozytorium. Najpierw jest add(), potem pojawia się update(), później remove(), potem jeszcze restore(), archive(), softDelete(), hardDelete() i nagle masz pięć metod, które w praktyce bardzo często mogłyby być jednym sensownym save() i remove().
Ze skillsami jest podobnie.
Według mnie lepiej budować skillsy jako standardy pracy, a nie jako katalog mikroakcji. Dzięki temu AI nie dostaje tylko polecenia, co ma zrobić. Dostaje też informację, jakim stylem i według jakich zasad ma to zrobić.
Dla mnie to jest złoty środek.
--- name: n8n-read-workflow description: Odczytuj istniejacy workflow z n8n przez public API i wspolny skrypt PHP. Uzywaj, gdy agent `n8n` potrzebuje read-only snapshotu workflow przed analiza albo update. --- Zakres: - Skill jest read-only wsparciem dla agenta `n8n`. - Uzywaj go wtedy, gdy bez aktualnego stanu workflow nie da sie przygotowac bezpiecznej analizy albo update. Workflow: 1. Ustal `workflowId`. 2. Jesli wynik ma byc wykorzystany dalej jako plik, uzyj `.ai/tmp/n8n-read-workflow/workflow.json`. 3. Uruchom `php ../../helper/php/bin/console n8n:workflow:get --workflow-id=123`. 4. Jesli chcesz zapisac snapshot do pliku, dodaj `--output=.ai/tmp/n8n-read-workflow/workflow.json`. 5. Zwroc snapshot workflow albo sciezke do zapisanego pliku. Zasady: - Skill jest tylko do odczytu. - Nie probuj nim wykonywac update ani aktywacji. - Jesli brakuje `workflowId`, zatrzymaj sie i zwroc brakujace dane. Few-shot: Input: - `workflowId`: `123` - `output`: `.ai/tmp/n8n-read-workflow/workflow.json` Command: - `php ../../helper/php/bin/console n8n:workflow:get --workflow-id=123 --output=.ai/tmp/n8n-read-workflow/workflow.json` ```
W moim przypadku jednym z takich skillsów jest obsługa komunikacji z n8n. Nie chciałem oddawać wszystkiego bezpośrednio LLM-owi, więc przygotowałem helper w PHP, który odpowiada za konkretną część komunikacji.
To jest dla mnie ważny kierunek: łączenie tradycyjnego kodu, MCP, automatyzacji i LLM-a w taki sposób, żeby każde narzędzie robiło to, w czym faktycznie jest dobre.
O tym, kiedy warto pisać klasyczny kod, kiedy używać MCP, a kiedy pozwolić LLM-owi działać bardziej samodzielnie, opowiem w osobnym wpisie.
Agenci, czyli eksperci od konkretnych tematów
Na końcu są agenci.
Agent to dla mnie nie magiczny byt, który „zrobi projekt”. Nie traktuję go jak developera, analityka, QA i architekta w jednym, bo to prosta droga do rozczarowania. Agent powinien mieć konkretną rolę i konkretny zakres odpowiedzialności.
Dla mnie agent to ekspert od wybranego obszaru.
Może to być na przykład:
- ekspert od n8n,
- ekspert od code review w PHP,
- PHP developer,
- analityk biznesowy,
- ekspert od bezpieczeństwa aplikacji webowych,
- specjalista od testów jednostkowych,
- agent do pracy z legacy kodem.
Dobry agent nie musi wiedzieć wszystkiego. Wręcz przeciwnie — im bardziej konkretny zakres, tym większa szansa, że będzie użyteczny.
Agent od wszystkiego bardzo szybko staje się agentem od niczego. Taki cyfrowy stażysta z ambicjami CTO. Niby chce dobrze, ale potem i tak trzeba po nim sprzątać.
model = "gpt-5.4" model_reasoning_effort = "low" sandbox_mode = "workspace-write" developer_instructions = """ Jestes `n8n`, prostym agentem end-to-end do zadan zwiazanych z n8n. Zakres odpowiedzialnosci: - zrozumiec, co uzytkownik chce osiagnac - doprecyzowac tylko brakujace, krytyczne dane - przeanalizowac istniejacy workflow albo zaprojektowac nowy - przygotowac payload albo patch, gdy to potrzebne - wykonac create, update albo import przez skille, jesli uzytkownik chce realnej operacji - zatrzymac sie na analizie albo propozycji, jesli uzytkownik nie chce jeszcze wykonywac zmian Skille, ktorych mozesz uzyc: - `n8n-read-workflow` - `n8n-create-workflow` - `n8n-update-workflow` - `n8n-import-workflow` Sposob pracy: 1. Ustal, czy chodzi o analize, create, update czy import. 2. Jesli brakuje krytycznych danych, np. `workflowId`, sciezki do plikow, oczekiwanego efektu albo decyzji "przygotowac czy wykonac", zadaj jedno krotkie pytanie. 3. Jesli zadanie jest jasne, doprowadz je samodzielnie do konca. 4. Przy update pobierz aktualny workflow, gdy bez tego zmiana nie bedzie bezpieczna. 5. Gdy tworzysz albo modyfikujesz workflow, opisuj krotko: - co zmieniasz - jakie zalozenia przyjmujesz - co zostalo wykonane, a co tylko przygotowane 6. Odpowiadaj zwyklym tekstem. Nie narzucaj structured output ani stalego kontraktu JSON. 7. JSON pokazuj tylko wtedy, gdy jest wlasciwym artefaktem zadania, np. payloadem workflow albo patchem. Twarde zasady: - Nie zgaduj brakujacych identyfikatorow, sciezek ani ograniczen wdrozenia. - Nie aktywuj workflow, jesli uzytkownik tego nie chce. - Nie wykonuj akcji wysokiego ryzyka typu delete workflow, project, credentials albo users bez wyraznego polecenia. - Jesli uzytkownik chce tylko review albo propozycje, nie uruchamiaj skilli zapisujacych. """
Trzeba zrobić to kraftowo
Najważniejsza rzecz jest taka: nie warto zlecać wszystkiego AI na ślepo (może on uporządkować agenta, skilla ale napisać go powinieneś/-aś sam/-a).
To nadal wymaga kraftowej roboty.
Trzeba usiąść, przemyśleć proces, opisać standardy, przygotować instrukcje, zbudować skillsy, przetestować agentów i poprawiać ich zachowanie. AI może bardzo dużo przyspieszyć, ale najpierw trzeba dać mu sensowny kontekst.
Bez tego będzie produkować kod, który wygląda dobrze tylko na pierwszy rzut oka.
A pierwszy rzut oka to za mało, szczególnie w legacy projekcie, gdzie jedna niewinna zmiana potrafi odpalić efekt domina w miejscu, którego nikt nie dotykał od pięciu lat.
Czas, testy i poprawki
Poza kraftową robotą najważniejsze są testy.
Najdłużej dopracowywałem swojego pierwszego agenta, czyli agenta do kodowania w PHP. Tworzyłem go wspólnie z kolegą i zajęło nam to około czterech miesięcy.
I nie, to nie wyglądało tak, że napisaliśmy prompt, odpaliliśmy narzędzie i po chwili mieliśmy seniora.
Wyglądało to bardziej tak:
- uruchom agenta,
- zobacz, co zrobił,
- złap się za głowę,
- popraw instrukcję,
- doprecyzuj standard,
- przetestuj ponownie,
- odkryj nowy problem,
- wróć do punktu pierwszego.
Aktualnie też potrafi to trwać tygodniami. Szczególnie jeśli celem nie jest tylko „żeby działało”, ale żeby agent działał optymalnie, stabilnie i z minimalną liczbą błędów.
Bo tu nie chodzi o jednorazową sztuczkę.
Chodzi o narzędzie, które realnie pomaga w codziennej pracy.
Największy zysk przychodzi z czasem
Budowanie własnych narzędzi do Claude Code, Codex, Copilot CLI czy Gemini CLI jest technicznie dość proste. Wystarczy plik z instrukcją, kilka standardów, trochę opisanej wiedzy i konkretna rola agenta.
Ale proste nie znaczy szybkie.
Największy zysk pojawia się dopiero wtedy, gdy zaczynasz to iterować. Gdy widzisz, gdzie AI popełnia błędy. Gdy poprawiasz instrukcje. Gdy dopisujesz standardy. Gdy usuwasz ogólne zdania i zamieniasz je na konkretne reguły.
Wtedy narzędzie zaczyna coraz bardziej pasować do Twojego projektu i Twojego sposobu pracy.
Nie do idealnego projektu z dokumentacji.
Do Twojego prawdziwego projektu. Tego z legacy kodem, dziwnymi wyjątkami, historycznymi decyzjami i komentarzami, których nikt nie chce czytać po godzinie 16:00.
Podsumowanie
Instrukcje, skillsy i agenci to dla mnie trzy praktyczne warstwy pracy z AI w CLI.
Instrukcje pomagają opisać lokalne zasady projektu. Skillsy pozwalają zebrać standardy i konkretne umiejętności. Agenci zamykają to w rolach ekspertów, którzy mogą wspierać nas w wybranych obszarach.
Sama konfiguracja nie jest trudna. Trudniejsze jest myślenie, testowanie i dopracowywanie szczegółów.
I właśnie tutaj jest największa różnica.
Możesz wrzucić AI do projektu i liczyć, że jakoś sobie poradzi. Albo możesz potraktować to jak budowę własnego narzędzia developerskiego.
Według mnie druga opcja wygrywa. Nie od razu, nie magicznie, ale konsekwentnie.
A dlaczego nie warto oddawać wszystkiego LLM-owi bez kontroli? O tym opowiem w kolejnym wpisie.