Nie można wstrzymać rozwoju. To pierwsza rzecz, którą trzeba zaakceptować. Zgłoszenia wciąż spływają, klienci oczekują dostaw, a istniejący kod nie przestaje działać tylko dlatego, że zdecydowałeś się go udokumentować. Żaden manager inżynierii nie da zielonego światła na miesięczną blokadę, aby zespół mógł napisać specyfikację, która powinna istnieć od pierwszego dnia. OpenSpec został zbudowany z myślą o rzeczywistości, a nie o fantazjach typu greenfield. Najlepiej sprawdza się, gdy doklejasz go do tego, co już masz, wraz z klientami i całym ekosystemem.

Celem nie jest przepisanie kodu. To uczciwa archeologia. Wykopujesz to, co faktycznie działa na produkcji, opisujesz to dokładnie i pozwalasz temu opisowi ewoluować wraz z kodem. Gdy Twoja specyfikacja pokrywa się z systemem, ułatwiasz życie inżynierom, którzy dołączą w następnym kwartale, oraz narzędziom AI, które teraz znajdują się w Twoim IDE. Oto jak to zrobić, nie opuszczając ani jednego wydania.

Zacznij od tego, co faktycznie robisz

Otwórz swoje repozytorium, a zobaczysz foldery o nazwach controllers, models, services i utils. To warstwy techniczne i one kłamią. Nie opisują tego, co Twój system robi dla biznesu. Folder pełen plików JavaScript nie wyjaśnia, jak zamówienie staje się przesyłką. Aby wdrożyć OpenSpec wstecznie, musisz myśleć w kategoriach możliwości biznesowych (capabilities).

Szukaj stabilnych operacji biznesowych, które przetrwałyby nawet wtedy, gdybyś przepisał cały stos technologiczny w innym języku. W większości firm produktowych pojawiają się one raz za razem: Zamówienia, Rozliczenia, Zapasy, Klienci i Powiadomienia. Wymień od pięciu do ośmiu takich kluczowych możliwości.

Dla każdej z nich zmuś się do odpowiedzi na pięć konkretnych pytań. Jaki problem z realnego świata rozwiązuje ta możliwość? Gdzie faktycznie znajduje się kod – w jednym serwisie, trzech mikroserwisach, czy w starym module, którego nikt nie chce dotykać? Co ją wyzwala: kliknięcie użytkownika, zaplanowane zadanie cron, czy przychodzący webhook? Jakie dane wchodzą, a jakie wychodzą? I na koniec, od jakich innych systemów zależy – czyli co przestanie działać, jeśli ten element przestanie działać?

Bądź brutalnie szczery. Jeśli Twoja funkcja „Klienci” jest rozproszona po monolicie Rails, API w Node i zewnętrznym CRM, zapisz to dokładnie tak, jak jest. Twoja mapa musi wyglądać jak teren, a nie jak marzenie architekta.

Pisz prawdę, a nie listę życzeń

Najniebezpieczniejszym zdaniem w jakichkolwiek pracach nad dokumentacją jest: „Skoro już to spisujemy, to moglibyśmy to przy okazji naprawić”. Przestań. Nie projektujesz na nowo procesu zakupowego. Opisujesz proces zakupowy, który właśnie teraz pobiera realne płatności z kart kredytowych.

Jeśli złożenie zamówienia wyzwala natychmiastowe pobranie płatności, a następnie wysyła e-mail przez worker w tle, udokumentuj dokładnie tę sekwencję. Nie wstawiaj kolejki zdarzeń, którą planujesz dodać w przyszłym kwartale. Nie udawaj, że walidacja odbywa się na brzegu API, jeśli w rzeczywistości znajduje się głęboko w klasie serwisu. Dokładność jest znacznie ważniejsza niż aspiracje.

Nieprawidłowa dokumentacja jest gorsza niż jej brak. Uczy nowych pracowników oczekiwać zachowań, które nie istnieją. Kieruje asystentów kodowania AI na wyimaginowane ścieżki oparte na życzeniowym myśleniu. Gdy Twoja specyfikacja zgadza się z produkcją, tworzysz niezawodną podstawę. Debugowanie staje się szybsze, ponieważ przestajesz zgadywać, jaki był „zamierzony” przepływ. Refaktoryzacja staje się bezpieczniejsza, ponieważ wiesz, że punkt wyjścia jest prawdziwy.

Wyodrębnij kontrakty ze swoich API

Twoje punkty końcowe API już wymuszają reguły. One po prostu utrzymują je w sposób niejawny. Wdrożenie OpenSpec wstecznie oznacza wydobycie tych reguł na światło dzienne.

Zacznij od danych wejściowych i walidacji. Co endpoint faktycznie przyjmuje? Udokumentuj typy, wymagane pola, maksymalne długości i zależności między polami. Następnie opisz zachowanie biznesowe. Czy to wywołanie tworzy rekord, wywołuje efekt uboczny, czy po prostu waliduje stan względem innego serwisu? Bądź konkretny.

Na koniec skataloguj odpowiedzi. Co zwraca sukces? Jakie są dokładne kody błędów i w jakich warunkach się pojawiają? Nie pisz „zwraca błąd”. Napisz „zwraca 422, gdy brakuje adresu rozliczeniowego, i 409, gdy zapas został już zarezerwowany przez inny proces”. Taki poziom precyzji zmienia niejasną trasę w kontrakt, któremu zespoły frontendowe, inżynierowie QA i narzędzia automatyzujące mogą zaufać.

Trop ukryte reguły

Niektóre z najdroższych informacji w twoim systemie kryją się w lukach. Są zakopane w blokach warunkowych wewnątrz klas serwisowych, ukryte w wyzwalaczach bazy danych lub zapisane w procedurach składowanych, których nikt nie dotykał od dwóch lat. To są twoje reguły biznesowe i zazwyczaj odkrywa się je na nowo podczas awarii lub poprzez osaczenie jedynego inżyniera, który pracuje tam od samego początku.

Wyciągnij je na światło dzienne. Zacznij od tych, które już znasz. Zamówienia powyżej pewnej wartości wymagają zatwierdzenia przez menedżera, zanim zostaną przetworzone. Nieaktywne konta użytkowników nie mogą tworzyć nowych zamówień. Zwroty są dozwolone tylko przed zakończeniem rozliczenia. Zapisz każdą regułę obok funkcjonalności, którą zarządza, w języku na tyle jasnym, aby menedżer produktu mógł ją przeczytać bez tłumacza.

Centralizując te reguły, robisz coś więcej niż tylko ich dokumentację. Ujawniasz duplikację. Wskazujesz konflikty. I dajesz całemu zespołowi jedno miejsce do debaty nad polityką, zanim ktoś wprowadzi jednowierszową zmianę, która przypadkowo naruszy ograniczenie, o którego istnieniu zapomniałeś.

Zmapuj mechanizmy wewnętrzne

Nowoczesne systemy działają w oparciu o zdarzenia. Akcja w jednym serwisie wywołuje reakcję w pół tuzina innych, zanim cokolwiek widocznego dotrze do użytkownika. Musisz narysować te ścieżki. Zmapuj przepływ od jednego zdarzenia do drugiego dla swoich kluczowych procesów. Utworzenie zamówienia prowadzi do rezerwacji zapasów, która czeka na potwierdzenie płatności. Narysuj cały łańcuch, nawet jeśli niektóre ogniwa wydają się kruche lub korzystają z różnych protokołów.

Nie zatrzymuj się na ruchu wewnętrznym. Usługi zewnętrzne są częścią twojego systemu, niezależnie od tego, czy tak je traktujesz. Dla każdej integracji zanotuj jej cel, sposób, w jaki twoja aplikacja się uwierzytelnia, oraz sposób, w jaki usługa zawodzi. Czy brama płatnicza wygasa po trzydziestu sekundach i zwraca ogólny błąd 500? Czy API wysyłkowe zwraca błędny format JSON w weekendy? Czy dostawca tożsamości unieważnia tokeny odświeżania wcześniej, niż deklaruje jego własna dokumentacja? Te szczegóły wydają się błahe