DotMDJak przejrzeć specyfikację napisaną przez AI:lista kontrolna przed budową.
Agent AI w minutę pisze pewną siebie, schludną specyfikację. I w tym tkwi zagrożenie: dobrze się ją czyta, nawet gdy jest błędna. Ta lista pokazuje, na co patrzeć, zanim każesz agentowi zacząć budować.
macOS 14 lub nowszy. Czytanie jest bezpłatne; edycja i przeglądy to jednorazowa płatność.
Krótka odpowiedź
Przeglądaj specyfikację napisaną przez AI tak, jak przeglądasz pull request: sprawdź, czy rozwiązuje właściwy problem, a potem szukaj tego, czego brakuje. Przejdź przez zakres i elementy poza zakresem, przypadki brzegowe, dane i migracje, testy i wycofanie, i zostaw komentarz przy każdym fragmencie do zmiany, zanim agent napisze jakikolwiek kod.
- [ ] Scope matches what I asked for
- [ ] Non-goals are listed
- [ ] Edge cases and errors are covered
- [ ] Data and migrations are explicit
- [ ] Tests prove each requirement
- [ ] There is a rollback·
Dlaczego specyfikacje od AI wymagają innego przeglądu
Człowiek piszący specyfikację zostawia luki tam, gdzie nie ma pewności. Model pisze płynny tekst o wszystkim, także o częściach, które zgadł. Brakuje więc zwykłych oznak słabej specyfikacji, niejasnych sformułowań i oczywistych dziur, a problemy kryją się w pewnych siebie zdaniach. Przeglądaj pod kątem rzeczy, o które zapytałby dobry autor.
Lista kontrolna
-
Zakres: czy rozwiązuje to, o co prosiłeś?
Porównaj pierwszy akapit z prośbą. Szukaj rozwiązania innego problemu i funkcji, o które nikt nie prosił.
-
Poza zakresem: czego nie zrobi?
Specyfikacja bez elementów poza zakresem nie ma granic. Dodaj dodatki, których nie chcesz.
-
Założenia: co zgadł?
Szukaj słów "prawdopodobnie", "zapewne" i wszystkiego, co jest podane jako fakt o kodzie lub danych, których mógł nie czytać. Poproś, by wskazał pliki.
-
Przypadki brzegowe: co się stanie, gdy coś pójdzie źle?
Puste dane, bardzo duże dane, brak uprawnień, brak sieci, dwóch użytkowników naraz, ta sama akcja dwa razy.
-
Dane: co jest zapisywane, zmieniane lub usuwane?
Pola, formaty, kto może je czytać i co dzieje się z istniejącymi rekordami.
-
Migracje: jak przechodzą stare dane?
Zmiana schematu wymaga kolejności kroków, planu na awarię w połowie i sposobu na bezpieczne uruchomienie jej dwa razy.
-
Interfejsy: co jeszcze jest dotknięte?
API, ekrany, zadania, kod innych zespołów. Wszystko, co specyfikacja zmienia, ale nie wymienia, będzie później niespodzianką.
-
Bezpieczeństwo i prywatność: kto co może?
Nowe uprawnienia, nowe dane opuszczające system, sekrety w logach.
-
Testy: skąd wiesz, że działa?
Każde wymaganie powinno mieć odpowiadające mu sprawdzenie. Jeśli wymagania nie da się przetestować, przepisz je.
-
Wdrożenie i wycofanie: jak to cofnąć?
Flaga, wdrożenie etapami, droga powrotna. "Poprawimy w następnym wydaniu" to nie plan.
-
Otwarte pytania: kto o nich zdecyduje?
Uczciwa specyfikacja wymienia to, czego nie wie. Jeśli nie ma żadnych, bądź podejrzliwy.
Komentarz, który działa
Niejasna uwaga daje niejasne przepisanie. Dobry komentarz z przeglądu wskazuje jeden fragment, mówi, co jest nie tak i czego chcesz zamiast tego:
> The export runs when the user taps Export.
Missing: what happens with a 2 GB file? Add a limit (R4) and an
error message, and say whether the export can be cancelled.Trzymaj komentarze oddzielnie od tekstu specyfikacji, żeby plik pozostał czysty, i zbieraj je razem: przeczytaj całą specyfikację raz, potem komentuj, by agent przepisywał raz, a nie dziesięć razy.
Pętla przeglądu
-
Najpierw przeczytaj całość
Przed komentowaniem upewnij się, że rozumiesz cały plan.
-
Komentuj dokładne fragmenty
Jeden problem na komentarz.
-
Pozwól agentowi poprawić
Poprawia każdy komentarz i tworzy nową wersję.
-
Sprawdź, co się zmieniło, a nie cały dokument
Czytaj różnice. Poprawka może zepsuć coś, co było w porządku.
-
Zatwierdź dopiero, gdy lista jest czysta
Wtedy pozwól budować, według numerowanych wymagań.
Ta sama lista działa, gdy jeden agent przegląda specyfikację innego. Poproś recenzenta, by na każdy punkt odpowiedział cytatem ze specyfikacji.
Robienie tego w DotMD
Wszystko to możesz zrobić na samej stronie. W DotMD zaznaczasz fragment i piszesz do niego komentarz; komentarze są przechowywane w DotMD, a nie w pliku. Agent je poprawia i wysyła dokument ponownie, a przegląd zmian pokazuje stary tekst na czerwono, a nowy na zielono, więc możesz je akceptować jedna po drugiej. Konfigurację opisuje przegląd specyfikacji AI. Czytanie jest bezpłatne; przeglądy opisuje cennik.
Częste błędy
- Przegląd stylu, a nie treści. Schludna specyfikacja nadal może być błędna.
- Zatwierdzanie, bo jest długa. Długość to nie pokrycie.
- Pomijanie elementów poza zakresem i wycofania, dwóch sekcji, które modele najczęściej zostawiają chude.
- Poprawianie kodu zamiast specyfikacji. Jeśli plan jest zły, popraw go najpierw.
- Brak drugiego spojrzenia. Gdy agent poprawi, sprawdź diff.
Pytania o przegląd specyfikacji napisanych przez AI
Jak przejrzeć specyfikację napisaną przez AI?
Sprawdź, czy rozwiązuje właściwy problem, potem szukaj tego, czego brakuje: elementów poza zakresem, przypadków brzegowych, danych i migracji, testów i wycofania. Skomentuj każdy fragment i każ agentowi poprawić, zanim napisze kod.
Co powinna zawierać lista kontrolna przeglądu specyfikacji?
Zakres, elementy poza zakresem, założenia, przypadki brzegowe, dane, migracje, interfejsy, bezpieczeństwo, testy, wdrożenie i wycofanie oraz otwarte pytania.
Czy jeden agent AI może przejrzeć specyfikację innego agenta?
Tak. Daj recenzentowi listę i poproś, by na każdy punkt odpowiedział cytatem ze specyfikacji. Nadal ty decydujesz, co przyjąć.
Dlaczego po prostu nie przeczytać kodu?
Wtedy decyzje już zapadły i trudno je zmienić. Błędne założenie najtaniej poprawić w specyfikacji.