Jak napisać dobry raport o błędzie (dla AI lub programisty)

Dobry raport o błędzie pozwala komuś innemu, programiście lub AI, zobaczyć ten sam problem, który Ty widziałeś, bez zadawania Ci pytań. Potrzebuje konkretnego tytułu, dokładnych kroków odtworzenia, opisu tego, czego się spodziewałeś, tego, co faktycznie się stało, komunikatu błędu skopiowanego słowo w słowo oraz informacji, gdzie to się wydarzyło: na której stronie, w jakiej przeglądarce, na jakim urządzeniu i jako jaki użytkownik. Jeden błąd na raport, a jeśli pomaga, dołącz zrzut ekranu.

Większość błędów trudniej zrozumieć, niż naprawić. Jasny raport usuwa etap zrozumienia. To szczególnie ważne przy narzędziach AI: AI nie może dopytać, co miałeś na myśli, pisząc „kasa jest dziwna”, więc zgaduje, a błędne zgadywanie może zepsuć coś innego.

Szablon

Skopiuj go i uzupełnij:

Tytuł: [Co jest nie tak, gdzie] — np. „Formularz rezerwacji odrzuca godziny po 18:00”

Kroki do odtworzenia:
1. ...
2. ...
3. ...

Oczekiwany wynik: [co powinno się stać]
Rzeczywisty wynik: [co stało się zamiast tego]

Komunikat błędu: [dokładny tekst, jeśli jest]
Gdzie: [strona/URL, przeglądarka, urządzenie, zalogowany jako który użytkownik]
Jak często: [za każdym razem / czasem / raz]
Zrzut ekranu lub nagranie: [dołączone]

Reszta przewodnika wyjaśnia każdą część.

Krok 1: Najpierw odtwórz błąd

Przed napisaniem spróbuj wywołać błąd ponownie. Dowiesz się, które kroki mają znaczenie i czy zdarza się za każdym razem.

Zacznij od czystego stanu: odśwież stronę albo wyloguj się i zaloguj ponownie.
Zapisuj każde kliknięcie i każdą wpisaną rzecz.
Spróbuj znaleźć najkrótszą ścieżkę, która go wywołuje.
Wypróbuj drugą przeglądarkę lub konto. Jeśli dzieje się tylko u jednego użytkownika, to duża wskazówka.

Więcej na ten temat znajdziesz w jak debugować aplikację zbudowaną przez AI.

Krok 2: Napisz konkretny tytuł

Tytuł powinien mówić, co jest nie tak i gdzie, żeby ktoś przeglądający listę wiedział, o który błąd chodzi.

Słaby	Mocny
Płatność nie działa	Przycisk płatności nic nie robi, gdy w koszyku jest kod rabatowy
Problem na telefonie	Karty cenowe wychodzą poza ekran na telefonach węższych niż 400 px
Błąd przy zapisie	Zapis profilu z emoji w imieniu pokazuje „500 Internal Server Error”

Krok 3: Wypisz dokładne kroki

Ponumeruj je. Bądź dosłowny: która strona, który przycisk, co wpisałeś.

Zaloguj się jako klient (konto testowe: customer@example.com).
Dodaj „Starter kit” do koszyka.
Wpisz kod rabatowy WELCOME10 i kliknij Zastosuj.
Kliknij Zamów.

Sformułowanie „spróbuj zapłacić z kodem” pomija szczegóły, które często mają znaczenie: który użytkownik, który produkt, który kod, czy najpierw został zastosowany.

Krok 4: Oczekiwane kontra rzeczywiste

To serce raportu. Napisz oba, bo różnica to właśnie błąd.

Oczekiwane: strona płatności otwiera się z widocznym w sumie rabatem 10%.
Rzeczywiste: przycisk pokazuje kręcące się kółko przez sekundę, a potem nic się nie dzieje. Bez kodu rabatowego płatność działa.

Bez „oczekiwanego” czytelnik może nie wiedzieć, że zachowanie jest błędne. Bez „rzeczywistego” nie wie, czego szukać.

Krok 5: Kopiuj błędy dokładnie

Komunikaty błędów to najszybsza droga do przyczyny. Kopiuj je jako tekst, słowo w słowo, nie parafrazuj.

Gdzie ich szukać:

Na ekranie: każdy komunikat, jaki pokazuje aplikacja.
Konsola przeglądarki: otwórz narzędzia deweloperskie (F12 lub prawy przycisk → Zbadaj) i sprawdź zakładkę Console pod kątem czerwonych linii.
Zakładka Network: w narzędziach deweloperskich znajdź nieudane żądanie i zapisz jego URL oraz kod statusu (na przykład POST /api/checkout → 500).
Logi serwera, jeśli masz do nich dostęp.

Linia w rodzaju TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 często wskazuje prosto na problem.

Krok 6: Dodaj kontekst

Gdzie: URL strony, środowisko (podgląd, staging lub produkcja).
Kto: który użytkownik lub rola: administrator, członek, niezalogowany.
Urządzenie i przeglądarka: „Safari na iPhonie” a „Chrome na Windows” mogą mieć znaczenie.
Dane: wszystko nietypowego w rekordzie: bardzo długi tekst, znaki specjalne, duża liczba pozycji.
Kiedy się zaczęło: „po wczorajszej zmianie w kodach rabatowych” to złoto.
Jak często: za każdym razem albo raz na dziesięć prób.

Krok 7: Pokaż to

Zrzut ekranu z zaznaczonym problemem albo krótkie nagranie ekranu usuwa dwuznaczność, zwłaszcza przy błędach układu. Jeśli Twoje narzędzie AI przyjmuje obrazy, dołącz jeden. Zakryj wszystko prywatne, w tym klucze i dane innych osób.

Pisanie raportów dla kreatora AI

Ta sama struktura działa jak polecenie. Dwa dodatki pomagają:

Napisz, co nie może się zmienić, żeby poprawka nie wywołała nowego problemu.
Poproś o sprawdzenie poprawki, a nie tylko o jej napisanie.

Zalogowany jako klient, z „Starter kit” w koszyku i zastosowanym kodem WELCOME10, kliknięcie Zamów nic nie robi. Oczekiwane: strona płatności otwiera się z 10% zniżką na sumę. Rzeczywiste: krótkie kółko, potem nic. Zakładka network pokazuje, że POST /api/checkout zwrócił 500. Płatność bez kodu działa. Znajdź przyczynę i napraw ją, nie zmieniając sposobu liczenia cen dla zamówień bez kodu. Następnie sprawdź płatność z kodem procentowym, kodem kwotowym i bez kodu.

Jeśli nie masz pewności co do przyczyny, najpierw poproś o diagnozę:

Na razie nie zmieniaj kodu. Na podstawie tego raportu, jakie są prawdopodobne przyczyny i co potwierdziłoby każdą z nich?

Typowe błędy

„To jest zepsute.” Brak kroków, brak oczekiwanego wyniku, nic do działania.
Kilka błędów w jednym raporcie. Część zostaje naprawiona, a inne giną.
Parafrazowane błędy. „Jakaś rzecz undefined” ukrywa użyteczną część.
Brak użytkownika lub roli. Wiele błędów dotyczy tylko administratorów albo tylko nowych użytkowników.
Opisywanie tylko poprawki, której chcesz („dodaj sprawdzenie null”), zamiast problemu.
Udostępnianie sekretów na zrzutach ekranu lub wklejonych logach.

Lista kontrolna

Odtworzyłem błąd i znalazłem najkrótsze kroki.
Tytuł mówi, co jest nie tak i gdzie.
Kroki są ponumerowane i dosłowne.
Podałem zarówno oczekiwany, jak i rzeczywisty wynik.
Komunikaty błędów są skopiowane dokładnie, wraz z nieudanym żądaniem i kodem statusu.
Podałem stronę, środowisko, użytkownika, urządzenie i przeglądarkę.
Napisałem, jak często się dzieje i od kiedy.
Dołączyłem zrzut ekranu lub nagranie, bez prywatnych danych.
Jeden błąd na raport.

Zgłaszanie błędów agentowi Mythex

W projekcie Mythex raport jest poleceniem. Kilka funkcji pomaga:

Dołącz zrzut ekranu podglądu lub ekranu błędu, do 5 plików w jednej wiadomości.
/fix kieruje agenta na naprawę błędu; tryb Plan pozwala mu najpierw zbadać sprawę, zanim zacznie edytować.
/test każe agentowi odtworzyć przepływy w samym podglądzie i opisać, co widzi.
Przywróć do tego punktu cofa poprawkę, która pogorszyła sprawę.

Strona dokumentacji debugowanie za pomocą poleceń używa tej samej struktury kroki / oczekiwane / rzeczywiste. Pętlę poprawiania i sprawdzania wokół tego opisuje jak iterować nad aplikacją zbudowaną przez AI.

Pytania

Co powinien zawierać raport o błędzie?

Konkretny tytuł, dokładne kroki odtworzenia problemu, to, czego się spodziewałeś, co się faktycznie stało, dosłowny komunikat błędu, gdzie to się wydarzyło (strona, przeglądarka, urządzenie, użytkownik), a także zrzut ekranu lub nagranie, jeśli pomaga.

Jak napisać raport o błędzie dla kreatora aplikacji AI?

Użyj tej samej struktury co w przypadku programisty: kroki, oczekiwany wynik, rzeczywisty wynik i dokładny błąd. Dodaj, co nie może się zmienić, i poproś o naprawę, a potem o sprawdzenie poprawki. Ogólne polecenia typu „to jest zepsute” prowadzą do zgadywania.

Co zrobić, jeśli nie mogę odtworzyć błędu?

Zgłoś go mimo to, ale napisz o tym wprost. Dołącz, co robiłeś, o której godzinie to się stało, na jakim koncie i jaki błąd zobaczyłeś. Zaznacz, jak często się powtarza, na przykład raz na dziesięć prób, bo przerywające się błędy często wskazują na problem z czasem lub danymi.

Czy umieścić kilka błędów w jednym raporcie?

Nie. Jeden błąd na raport, żeby każdy mógł zostać naprawiony, przetestowany i zamknięty osobno. Jeśli uważasz, że dwa problemy są powiązane, napisz to w każdym raporcie.