Plan, którego nie da się uruchomić, nie może się mylić

Markdown to format, którego ani ty, ani model nie możecie uruchomić. Nie da się go zweryfikować, więc nie generuje feedbacku. A planowanie bez feedbacku jest zgadywaniem, tylko ładnie sformatowanym.

Plan na papierze miał sens, gdy kod pisaliśmy ręcznie albo gdy agent potrzebował wielu podejść do samej składni. Dziś częściej trafia za pierwszym razem, więc taniej jest zbudować i wyrzucić niż opisać.

Plan w .md jest zawsze wewnętrznie spójny, bo nic nie może go obalić.

Poniżej opis cyklu życia procesu: osiem stanów, dziewięć przejść. Lewy panel renderuje go jako tabelę markdown. Prawy jako klikalny graf. Na dole ten sam opis przechodzi przez walidator. Wszystkie trzy panele czytają jedną tablicę w JavaScripcie, więc informacja jest identyczna. Różni się tylko to, co da się z nią zrobić.

W specyfikacji brakuje jednego przejścia. Zacznij od lewego panelu i zmierz, ile zajmie ci znalezienie go tam.

Tekst mówi prawdę i nie pomaga. Widok pokazuje ślepy zaułek jako kształt, zanim zdążysz przeczytać nazwy. Uruchomienie zamienia go w zdanie, które trafia do zgłoszenia. To jest cała różnica między planem a artefaktem.

Jeśli naprawdę potrzebujesz kontekstu przenoszonego między sesjami, użyj .mdx albo .mdsvx, czyli markdownu z osadzonymi komponentami. Dokument dostaje wtedy warstwę wizualną i interaktywną, a nie tylko akapity. Nadal się go czyta, ale można go też obejrzeć i kliknąć.

Wireframe i skrypt mogą się wywalić i to jest ich największa zaleta. Błąd wychodzi w minutę, a nie po dwóch dniach implementacji. Dokument tej właściwości nie ma, bo nie istnieje stan, w którym akapit zwraca exit 1.

Druga rzecz to stratność tłumaczenia. Opis w markdownie zostawia luki, które model wypełnia zgadywaniem, a każda taka luka to jedna decyzja podjęta bez ciebie. HTML i działający skrypt są już w tej samej domenie co produkt, więc konwersja jest w dużej mierze mechaniczna.

Ta zasada dotyczy planów o kształcie kodu. Nie dotyczy planów o kształcie decyzji. Pytanie „który wariant liczymy”, „jaki próg przyjmujemy”, „załącznik idzie mailem czy linkiem” nie ma odpowiedzi, którą wyprodukuje uruchomienie skryptu, bo to nie jest pytanie techniczne. Tego rodzaju ustalenia dalej warto mieć zapisane, bo ich wartością jest akceptacja, a nie weryfikacja.

Drugi wyjątek to pamięć. Przy kilku równoległych sesjach agentów na jednym repozytorium ktoś musi wiedzieć, co już zostało ustalone i wdrożone. Notatka jest do tego dobrym narzędziem, bo jej zadaniem nie jest specyfikowanie, tylko przypominanie.

Wszystko poniżej warstwy decyzji, czyli „jak dokładnie ma wyglądać ten ekran” albo „co ten parser ma zrobić z tym plikiem”, faktycznie rozstrzyga się szybciej wykonywalnym artefaktem niż akapitem.