Przygotuj opis zadania dla agenta

Opisz zmianę, którą można ocenić

„Dodaj eksport klientów” pozostawia kilka otwartych decyzji. Kto może eksportować rekordy? Jakie rekordy i pola obejmuje eksport? Co następuje po błędzie żądania? Agent może wypełnić luki wiarygodnie wyglądającymi wyborami. Nadal mogą być błędne z perspektywy biznesu.

Zacznij od użytkownika i problemu. Następnie opisz wymagane zachowanie. Uwzględnij dowody, które pokażą, czy wynik można zaakceptować.

Opis powinien ograniczać niepewność bez ustalania każdego szczegółu projektu wewnętrznego. Określ wymaganą granicę danych. Pozwól implementacji korzystać z istniejących wzorców repozytorium, chyba że jest powód do ich zmiany.

Użyj konkretnego przykładu

Poniższy opis dotyczy fikcyjnej aplikacji wsparcia. To przykład edukacyjny, a nie kompletna specyfikacja produkcyjna.

Wynik: Menedżer wsparcia może pobrać listę klientów.
Wykonawca: Menedżer w bieżącej organizacji.
Dane: Tylko aktywni klienci tej organizacji.
Pola: Identyfikator klienta, nazwa firmy i status konta.
Format: UTF-8 CSV z wierszem nagłówka.
Odrzucone żądanie: Zwróć istniejący błąd autoryzacji.
Pusty wynik: Zwróć poprawny CSV zawierający tylko nagłówek.
Zakres: Użyj istniejącej trasy eksportu i wzorca audytu.
Wykluczone: Nowe role, zależności i wdrożenie.
Dowody: Testy żądań dozwolonych, odrzuconych, pustych i dotyczących innej organizacji.

Opis wskazuje przydatne zachowanie i ograniczenia. Ujawnia też kolejne pytania. Czy system powinien ograniczać wielkość eksportu? Czy pole może zawierać formułę arkusza kalkulacyjnego? Kto ma dostęp do zapisu audytowego? Rozstrzygnij istotne pytania przed implementacją. Nie traktuj przykładu jako uniwersalnej listy kontrolnej.

Oddziel wymagania od założeń

Wymaganie określa zachowanie, które zmiana musi spełnić. Założenie to fakt, którego jeszcze nie sprawdzono. Trzymaj je osobno.

Na przykład „użyj istniejącego wzorca audytu” zakłada, że odpowiedni wzorzec istnieje. Poproś agenta o jego znalezienie. Jeśli repozytorium go nie ma, agent powinien zgłosić brak, zanim stworzy nowy system audytu.

Ograniczenie może też kolidować z wynikiem. Istniejąca trasa może z założenia zwracać wszystkie organizacje. Agent powinien pokazać konflikt i zaproponować ograniczoną poprawkę. Nie powinien po cichu usuwać granicy danych ani rozszerzać zadania do przebudowy architektury.

Wymagaj dowodów przy ukończeniu

Poproś o podsumowanie opisujące końcowe zachowanie, zmieniony zakres i wykonane kontrole. Tam, gdzie ma to znaczenie, wymagaj dokładnych poleceń i wyników. Odróżniaj kontrolę zakończoną powodzeniem od takiej, której nie udało się uruchomić.

Pull request powinien zachować powód zmiany. Późniejsza osoba utrzymująca system może zobaczyć kod bez pierwotnej rozmowy. Dodaj dość kontekstu, aby wyjaśnić, dlaczego eksport pomija określone pola i jak egzekwuje dostęp.

Wytyczne Google dotyczące opisu zmian są przydatnym punktem odniesienia. Opis powinien wyjaśniać zmianę i jej cel. Po poprawkach wynikających z przeglądu dopasuj go do końcowej implementacji.

Dostosuj szczegółowość opisu

Mała poprawka tekstu może mieć krótki opis. Eksport danych potrzebuje więcej szczegółów, ponieważ błędy mogą ujawnić informacje. Nowy proces płatności wymaga jeszcze więcej analizy i przeglądu.

Nie mierz jakości opisu długością. Sprawdź, czy kompetentny recenzent odróżni wynik poprawny od błędnego. Jeśli dwie rozsądne implementacje mogłyby różnić się istotnym zachowaniem, najpierw je doprecyzuj.