Szybka kawka z AI #1: daj AI kontekst

Tym wpisem rozpoczynam serię krótkich wpisów o tym, jak korzystam z AI i jakie błędy najczęściej widzę u innych.

Bez sztywnego planu i kolejności. Będę opisywać to, co akurat wpadnie mi do głowy, zwróci moją uwagę albo kolejny raz wydarzy się podczas rozmowy ze znajomymi.

Taka szybka kawka z AI.

Część rzeczy będzie dla Ciebie oczywista. I bardzo dobrze. Nie opisuję ich dlatego, że odkryłem właśnie tajemnicę działania LLM-ów, ale dlatego, że są to błędy, które regularnie zauważam u znajomych.

Zacznijmy od kontekstu.

Gdzie zniknęły wszystkie tokeny?

Coraz częściej słyszę:

Skończyły mi się tokeny, a przecież zleciłem AI tylko jedną prostą rzecz.

Kiedy jednak pytam o prompt, okazuje się, że był on bardzo ogólny.

Załóżmy, że przychodzi do Ciebie Product Owner i mówi:

Janek, przygotuj mi raport kliknięć produktów na liście produktów.

Mówisz: „Spoko” i zabierasz się do pracy.

Po chwili zaczynają się pytania:

• Skąd mam pobrać dane?
• Jak ma wyglądać raport?
• Ma to być plik czy HTML?
• Jak często raport ma się generować?
• Czy potrzebujemy przechowywać dane historyczne?
• Jakie pola powinny znaleźć się w raporcie?
• Czy dane wymagają normalizacji?
• Jaki zakres dat ma obejmować raport?
• Jak rozpoznać kliknięcie produktu?
• Gdzie raport ma zostać zapisany?

Gdybym zastanowił się dłużej, ta lista byłaby znacznie większa.

AI nie zna odpowiedzi na te pytania. Jeżeli mu ich nie przekażesz, musi zacząć zgadywać albo samodzielnie szukać kontekstu.

I tutaj nawet dopisanie w prompcie „nie halucynuj” raczej nie pomoże 😀

Tokeny robią brrr

Pomijając już to, że AI nie wie dokładnie, co ma zrobić, często musi jeszcze przeskanować sporą część projektu.

Może odpowiedź znajduje się w repozytorium odpowiedzialnym za produkty.

Może w innym module jest już podobny raport.

Może definicje ORM podpowiedzą, jak wyglądają dane.

Może gdzieś istnieje klient Elasticsearcha, którego powinno użyć.

Może w konfiguracji znajduje się ścieżka, do której zapisywane są raporty.

A może niczego takiego nie ma i po przeczytaniu setek plików AI nadal wie tyle samo co na początku.

W międzyczasie tokeny robią brrr.

Oczywiście codex, claude code itd. potrafią przeszukiwać projekt i często robią to naprawdę dobrze. Nie oznacza to jednak, że powinny za każdym razem przeprowadzać śledztwo archeologiczne tylko dlatego, że nie chciało nam się przekazać kilku informacji.

Przekaż to, co już wiesz

Konkluzja jest prosta: zlecając zadanie AI, dostarcz mu maksimum przydatnej wiedzy, które jesteś w stanie zebrać w racjonalnym czasie.

Nie chodzi o to, żeby przed każdym zadaniem pisać dokumentację techniczną na dwadzieścia stron.

Chodzi o przekazanie tego, co już wiesz.

W przypadku naszego raportu kontekst może wyglądać tak:

Dane o kliknięciach znajdują się w Elasticsearchu.

Poniżej znajduje się gotowe zapytanie, które zwraca wszystkie dane potrzebne do raportu:

{
  "query": {
    "bool": {
      "filter": [
        {
          "range": {
            "clicked_at": {
              "gte": "now-1d/d",
              "lt": "now/d"
            }
          }
        }
      ]
    }
  },
  "sort": [
    {
      "clicked_at": {
        "order": "asc"
      }
    }
  ]
}

Zapytanie umieść w istniejącym ProductClickRepository. Nie twórz nowego klienta Elasticsearcha.

Dane zwracane przez indeks są już znormalizowane i nie wymagają dodatkowej obróbki.

Raport ma zostać zapisany jako plik JSON w katalogu:

var/reports/product-clicks/

Plik powinien mieć nazwę zgodną ze schematem:

product-clicks-YYYY-MM-DD.json

Oczekiwana struktura raportu:

{
  "generated_at": "2026-07-12T08:00:00+00:00",
  "date": "2026-07-11",
  "products": [
    {
      "product_id": "123",
      "product_name": "Example product",
      "clicks": 42
    }
  ]
}

Produkty mają być posortowane malejąco według liczby kliknięć.

W projekcie istnieje już mechanizm zapisywania plików. Znajdziesz go w ReportFileStorage i jego należy użyć.

Raport ma być generowany na wzór istniejących commandów w src/Command. Mogę podczas uruchomienia zdefiniować daty od/do raportu.

To nie jest prompt. To kontekst lub dla części ludzi kryteria akceptacji/todo zadania.

Dzięki niemu AI nie musi zgadywać:

• skąd pobrać dane,
• jakiego klienta użyć,
• gdzie umieścić zapytanie,
• czy dane wymagają normalizacji,
• jaki format ma mieć raport,
• gdzie zapisać plik,
• czy powinno tworzyć nową komendę albo konfigurację crona.

Może od razu skupić się na właściwym zadaniu.

Nie zawsze będziesz wiedzieć wszystko

Oczywiście nie zawsze jesteśmy w stanie dostarczyć kompletny kontekst.

Możemy pracować w obcym projekcie, używać języka, którego dobrze nie znamy, albo zwyczajnie nie wiedzieć, gdzie wykonywana jest konkretna operacja.

Czasami sami nie wiemy jeszcze, jak powinna wyglądać architektura.

To normalne.

W takiej sytuacji również warto powiedzieć AI, czego nie wiesz:

Nie wiem, gdzie w projekcie pobierane są dane o kliknięciach. Najpierw znajdź odpowiedzialny za to fragment aplikacji. Nie przygotowuj implementacji raportu, dopóki nie ustalisz źródła danych.

To także jest kontekst.

Dzięki temu AI nie zaczyna od generowania rozwiązania na podstawie własnych założeń. Najpierw ma znaleźć brakującą informację.

Podsumowanie

AI nie czyta w myślach.

Jeżeli nie przekażesz mu kontekstu, będzie musiało go znaleźć albo wymyślić. Pierwsza opcja zużyje czas i tokeny. Druga może skończyć się rozwiązaniem, które wygląda dobrze, ale nie pasuje do Twojego projektu.

Przekaż więc:

• co chcesz osiągnąć,
• skąd pochodzą dane,
• jakie elementy projektu należy wykorzystać,
• jak ma wyglądać efekt,
• jakie są ograniczenia,
• czego AI nie powinno tworzyć,
• czego sam jeszcze nie wiesz.

Nie musisz przygotowywać idealnej specyfikacji.

Przekaż po prostu wszystko, co już wiesz i co może uchronić AI przed niepotrzebnym zgadywaniem.

Bo czasami pięć minut poświęcone na opisanie kontekstu oszczędza kilkadziesiąt minut rozmowy z AI, które bardzo pewnie rozwiązuje nie ten problem, który miało rozwiązać.