Zapomnij o składni? Co naprawdę liczy się w programowaniu z AI

Agenci AI potrafią szybko wygenerować kod, który wygląda poprawnie. Cały czas jednak trzeba ustalić, co dokładnie ten kod ma robić, jak wpisuje się w istniejącą już strukturę projektu i po czym poznamy, że spełnia swoje zadanie. Znajomość języków programowania pomaga opisać wymagania, rozpoznać ważne przypadki brzegowe i ocenić kod wygenerowany przez model. W tym artykule pokazuję, jak przekazywać agentowi kontekst i wymagania, by wygenerowany kod był zgodny z założeniami i nie wymagał później serii poprawek.

Kluczowe wnioski z tekstu:

• Jakość kodu generowanego przez AI zależy od tego, czy agent rozumie cel zmiany, ograniczenia projektu i oczekiwany sposób działania.
• Opis zadania powinien uwzględniać istotne przypadki brzegowe, kryteria akceptacji i sposób sprawdzenia rozwiązania.
• Wymagania warto dopasować do konkretnego problemu. Uniwersalny szablon nie zastąpi wiedzy o domenie ani decyzji zespołu.

Czym jest specyfikacja AI?

Specyfikacja AI to dokument, który ma opisać zadanie dla modelu, np. Claude Code. Dzięki temu nie ma ryzyka, że AI wypełni luki swoimi własnymi założeniami.

Prompt jest poleceniem przekazanym agentowi AI w danej chwili. W prostym zadaniu może wystarczyć. Przy większej zmianie potrzebny jest również trwały opis ustaleń, do którego można wrócić podczas planowania i przeglądu kodu.

Taki opis nie musi mieć jednej narzuconej formy. Może on być częścią zgłoszenia, dokumentacji technicznej albo planu zmiany. Ważne, aby był dostępny dla osób pracujących nad zadaniem i wskazywał decyzje, których model nie powinien sam podejmować.

Jak precyzyjnie opisać intencję dla AI?

Dobra specyfikacja powinna zawierać 4 elementy:

• Kontekst i cel – odnosi się do tego, po co funkcja istnieje i kto z niej korzysta; dzięki temu AI będzie w stanie samodzielnie podjąć decyzje w sytuacjach, w których nie zostały one opisane wprost.
• Format danych wejściowych i wyjściowych – to najczęstsze źródło rozjazdu między oczekiwaniami a implementacją, dlatego zadbaj o dokładną strukturę, typy pól, opcjonalność i format błędów.
• Przypadki brzegowe – sytuacje, w których coś idzie nie tak (np. puste pole, przekroczony limit, duplikat). Bez tej sekcji AI implementuje tylko idealny scenariusz.
• Kryteria akceptacji – powinny być sformułowane tak, by dało się je zamienić na test (schemat: „gdy [warunek], wtedy [oczekiwany rezultat]”).

Co opisać przed implementacją?

Najpierw wyjaśnij cel zmiany i jej kontekst. Napisz, kto lub co będzie korzystać z nowej funkcji i jaki rezultat ma zobaczyć użytkownik albo inny element systemu.

Opisz także wejście i wyjście w zakresie potrzebnym do implementacji. Podaj typy danych, wymagane i opcjonalne pola, jednostki, format odpowiedzi oraz sposób zgłaszania błędów. W istniejącym projekcie odwołaj się do używanych wzorców.

Wymień przypadki brzegowe wynikające z konkretnego problemu. Mogą to być puste wartości, duplikaty, przekroczenie limitu, ponowienie żądania, timeout albo równoległe operacje. Nie ma sensu kopiować pełnej listy do każdego zadania.

Określ zakres i ograniczenia. Wskaż, których obszarów nie należy zmieniać, jakie zależności można dodać oraz jakie wymagania dotyczą bezpieczeństwa. Zaznacz też, czy agent może modyfikować testy i konfigurację. Takie ustalenia pomagają uniknąć zmian, które pozornie rozwiązują problem, ale osłabiają kontrolę jakości.

Zapisz kryteria akceptacji w sposób, który pozwala sprawdzić rezultat. Możesz opisać stan początkowy, wykonaną akcję i oczekiwany wynik. Nie każde kryterium musi być osobnym testem automatycznym, ale każde powinno dać się jednoznacznie ocenić.

Podaj, jak zweryfikować zmianę: które testy lub kontrole uruchomić i jaki wynik uznać za poprawny. Jeśli agent tworzy testy, sprawdź, czy testują wymagane zachowanie, a nie tylko aktualny sposób implementacji.

Dlaczego sam czat może nie wystarczyć?

Długa rozmowa nie zawsze jest dobrym miejscem na przechowywanie wszystkich decyzji. Część kontekstu może z czasem stracić widoczność, a kolejna sesja może rozpocząć się bez wcześniejszych ustaleń. Wspólny, aktualny opis zadania ułatwia powrót do wymagań.

Taki opis pomaga również utrzymać spójność między kolejnymi zmianami. Agent może odwołać się do istniejących rozwiązań, a zespół może sprawdzić, czy kod odpowiada uzgodnionemu zakresowi. Dokumentacja wymagań powinna jednak pozostać aktualna. Nieaktualny opis może wprowadzać w błąd równie skutecznie jak jego brak.

Jak pracować z agentem AI?

• Przy większej zmianie poproś najpierw o plan i listę niejasności. Odpowiedz na pytania przed rozpoczęciem implementacji. Dzięki temu łatwiej jest wychwycić różnice w rozumieniu problemu, zanim pojawią się w kodzie.
• Dziel pracę na niewielkie, możliwe do sprawdzenia kroki. Wskazuj przykłady z repozytorium, które pokazują obowiązujące wzorce. Konkretne odwołanie do istniejącej obsługi błędów bywa bardziej pomocne niż ogólne polecenie.
• Ważna jest jednoznaczność, a nie język promptu. Możesz opisywać zadanie po polsku, ale preferowany jest język angielski. Nazwy pól, klas i endpointów przepisuj dokładnie z kodu, aby nie tworzyć dodatkowych niejasności.
• Kod wygenerowany przez agenta powinien przejść te same testy i przegląd co każda inna zmiana. Trzeba też sprawdzić nowe zależności i upewnić się, że testy obejmują wymagane zachowanie.

Ważne! Agent może przyspieszyć pracę, ale nie przejmuje odpowiedzialności za decyzje techniczne.

Jak pisać prompty do generowania kodu?

Powodem większości złych odpowiedzi od AI jest nie tylko brak specyfikacji, ale też to, że użytkownik nie daje wystarczająco dużo informacji narzędziu.

Chcąc stworzyć najlepszy prompt, warto:

• wykorzystać do tego samo narzędzie (Claude, ChatGPT, Gemini);
• podać mu kontekst i dane, na których powinno oprzeć swoje rozwiązania;
• użyć gotowych frameworków (np. Framework 1: Role, Task, Format).

FAQ – Najczęściej zadawane pytania o programowanie z AI