Dokumentacja techniczna mówi jedno. System robi drugie. Jak naprawdę audytować przejęty projekt IT?

Przejęcie istniejącego projektu IT rzadko zaczyna się od pustego repozytorium. Zwykle dostajesz dokumentację, dostęp do kodu, listę funkcjonalności i zapewnienie, że „większość rzeczy już działa".

I właśnie wtedy bardzo łatwo popełnić pierwszy błąd. Zacząć naprawiać system, zanim sprawdzisz, co tak naprawdę przejąłeś.

Po kilku projektach, w których wchodziłem do istniejących środowisk, coraz częściej dochodzę do tego samego wniosku: pierwszym zadaniem osoby technicznej nie powinno być wdrażanie zmian. Powinno być ustalenie stanu faktycznego.

Dokumentacja nie jest systemem

Dokumentacja techniczna jest potrzebna. Bez niej przejmowanie projektu może być jeszcze trudniejsze.

Problem pojawia się wtedy, gdy zaczynamy traktować ją jako źródło prawdy. W istniejącym projekcie dokumentacja mogła powstać kilka miesięcy albo kilka lat wcześniej. W tym czasie mogła zmienić się architektura, sposób wdrażania, wykorzystywane usługi, baza danych albo nawet główna technologia.

Czasami dokumentacja opisuje rozwiązanie, które nigdy nie zostało w pełni wdrożone. Czasami opisuje poprzednią wersję systemu. Czasami wszystko się zgadza, ale brakuje jednego elementu, który w praktyce jest niezbędny do uruchomienia całości.

Dlatego po przejęciu projektu traktuję dokumentację jako hipotezę dotyczącą stanu systemu, którą trzeba zweryfikować. Nie jako dowód, że system wygląda dokładnie tak, jak został opisany.

Najpierw uruchamiam, później analizuję

Kiedy przejmuję projekt, bardzo łatwo wpaść w pułapkę wielogodzinnego czytania dokumentacji. Diagramy architektury, opisy modułów, specyfikacje, backlog, dokumentacja API, listy technologii. To wszystko jest przydatne.

Ale w pewnym momencie trzeba zamknąć dokumentację i uruchomić system. Chcę zobaczyć:

• Czy aplikacja faktycznie startuje?
• Czy można się zalogować?
• Czy działa podstawowy proces?
• Czy komponenty komunikują się ze sobą?
• Czy dane przechodzą przez cały system?
• Czy można wykonać deployment?
• Czy wiadomo, którą wersję właściwie wdrażamy?

Dopiero wtedy zaczyna być jasne, z czym naprawdę mamy do czynienia. Bo może się okazać, że problem, który na papierze wygląda na niewielką poprawkę, w rzeczywistości jest konsekwencją kilku innych zależności.

„Działa" nie jest wystarczającą informacją

Jedno z najbardziej zdradliwych zdań w projektach IT brzmi: „Ten moduł działa."

Dobrze. Ale co właściwie znaczy „działa"?

• Czy działa lokalnie na komputerze developera?
• Czy działa w środowisku testowym?
• Czy działa po wdrożeniu?
• Czy działa z prawdziwymi danymi?
• Czy działa przy większym obciążeniu?
• Czy działa razem z pozostałymi komponentami?
• Czy użytkownik może dzięki niemu wykonać cały proces?

To zupełnie różne poziomy gotowości. W jednym z projektów, przy którym pracowałem, samo uruchomienie poszczególnych elementów nie było wystarczające. Trzeba było przeanalizować cały przepływ danych i sposób, w jaki poszczególne komponenty współpracują ze sobą.

Dopiero wtedy można było odpowiedzieć na najważniejsze pytanie: czy mamy działający produkt, czy tylko kilka działających komponentów?

Repozytorium również może wprowadzać w błąd

Kod jest konkretny. Wydaje się więc, że skoro coś znajduje się w repozytorium, to znaczy, że jest częścią działającego systemu. Niekoniecznie.

W większych albo długo rozwijanych projektach można znaleźć:

• kod pozostały po poprzednich wersjach,
• nieużywane moduły,
• eksperymentalne rozwiązania,
• funkcje, które nigdy nie trafiły na produkcję,
• fragmenty wymagające nieistniejących już usług,
• kilka sposobów realizowania tego samego procesu.

Dlatego samo przejrzenie repozytorium nie daje jeszcze odpowiedzi na pytanie, jak działa system. Trzeba połączyć kilka źródeł informacji: kod + konfigurację + środowisko + deployment + dane + rzeczywiste zachowanie aplikacji. Dopiero ich porównanie daje obraz sytuacji.

Najważniejszy jest przepływ, nie pojedynczy komponent

To szczególnie dobrze widać w projektach wykorzystujących AI. Załóżmy, że mamy system do przetwarzania dokumentów. Możemy powiedzieć: „OCR działa." Świetnie.

Ale użytkownik nie korzysta z samego OCR. Użytkownik przesyła dokument, system musi go odebrać, dokument musi trafić do odpowiedniego procesu, OCR musi go przetworzyć, wynik musi zostać przekazany dalej, kolejny komponent musi wyciągnąć potrzebne informacje, dane muszą zostać zapisane — a użytkownik musi dostać wynik.

Jeżeli jeden element tego łańcucha nie działa, cały proces może być bezużyteczny.

Sprawdzam też, czego nie ma

Audyt nie polega wyłącznie na szukaniu istniejących elementów. Równie ważne jest sprawdzenie braków:

• Czy istnieje środowisko produkcyjne? Czy jest środowisko testowe?
• Czy można odtworzyć system od zera?
• Czy są backupy? Czy ktoś sprawdził, czy z backupu można faktycznie odtworzyć dane?
• Czy wiadomo, kto ma dostęp do infrastruktury?
• Czy istnieje sposób monitorowania systemu?
• Czy deployment jest powtarzalny?
• Czy konfiguracja jest opisana?
• Czy wiadomo, które elementy są krytyczne?

Produkt nie kończy się na kodzie. Infrastruktura, bezpieczeństwo, backup i monitoring to integralna część systemu — nie coś, co można zostawić „na później".

Najbardziej niebezpieczne są rzeczy, które „jakoś działają"

Czasami system działa. I właśnie wtedy można przestać zadawać pytania. A to może być błąd.

Jeżeli deployment wykonuje jedna osoba — system może działać. Jeżeli jedna osoba zna konfigurację serwera — system może działać. Jeżeli ktoś ręcznie wykonuje kilka czynności przed uruchomieniem aplikacji — system może działać. Dopóki ta osoba jest dostępna i nic się nie zmienia.

Problem zaczyna się wtedy, kiedy trzeba wdrożyć nową wersję, odtworzyć środowisko, przenieść system, naprawić awarię, zwiększyć skalę lub przekazać projekt kolejnemu zespołowi.

Dlatego podczas przejęcia szukam nie tylko rzeczy, które działają. Szukam również ukrytych zależności.

Nie każda wada wymaga natychmiastowej naprawy

Podczas audytu można znaleźć dziesiątki problemów: słaba dokumentacja, stare biblioteki, brak testów, problemy architektoniczne, niedoskonały kod, brak automatyzacji.

I wtedy pojawia się pokusa, żeby zacząć naprawiać wszystko. Tylko że audyt nie jest konkursem na liczbę znalezionych błędów.

Jeżeli projekt ma zostać dowieziony w konkretnym terminie, trzeba odpowiedzieć na inne pytanie: które problemy rzeczywiście blokują osiągnięcie celu?

Jeżeli błąd nie wpływa na krytyczny proces, można czasami świadomie zostawić go na później. Jeżeli natomiast blokuje wdrożenie, bezpieczeństwo, dane albo podstawowy proces użytkownika, jego priorytet jest zupełnie inny.

To właśnie tutaj audyt techniczny zaczyna łączyć się z zarządzaniem produktem.

Największym błędem jest przepisywanie systemu bez diagnozy

To temat, który wraca w praktycznie każdym projekcie przejmowanym po innym wykonawcy. Nowy zespół widzi stary kod, trudną architekturę, niepełną dokumentację. I pojawia się naturalna myśl: „Zróbmy to od nowa."

Czasami rzeczywiście trzeba. Ale zanim podejmie się taką decyzję, trzeba wiedzieć, co dokładnie chcemy uzyskać dzięki przepisywaniu:

• Czy obecna architektura rzeczywiście uniemożliwia rozwój?
• Czy problem dotyczy całego systemu, czy jednego modułu?
• Czy obecna wersja ma funkcje, których nowa wersja jeszcze nie posiada?
• Ile czasu zajmie dojście nowej wersji do poziomu, który już osiągnęła obecna?

Audyt powinien zakończyć się decyzjami

Nie jestem zwolennikiem audytów, których efektem jest kilkadziesiąt stron problemów i brak odpowiedzi na pytanie: „Co robimy jutro?"

Dobry audyt przejętego projektu powinien pozwolić odpowiedzieć przynajmniej na kilka podstawowych pytań:

• Co naprawdę mamy? Nie według prezentacji, tylko w działającym systemie.
• Co faktycznie działa? I na jakim środowisku.
• Czego brakuje? Nie tylko funkcjonalnie, ale również infrastrukturalnie i organizacyjnie.
• Co blokuje produkt? Problemy, które rzeczywiście uniemożliwiają osiągnięcie celu.
• Co możemy zostawić na później? Bo nie wszystko musi być naprawione przed pierwszym wdrożeniem.
• Jaka jest kolejność działań? Bez tego lista problemów pozostaje tylko listą problemów.

Jak wygląda mój pierwszy etap po przejęciu projektu?

Nie mam jednej uniwersalnej checklisty. Każdy system jest inny. Ale zwykle zaczynam od tych obszarów:

1. Dostępy — repozytoria, serwery, chmura, domeny, bazy danych, narzędzia CI/CD.
2. Uruchomienie — czy system można uruchomić i czy wiadomo, jak to zrobić.
3. Architektura — co z czym się komunikuje i gdzie znajdują się krytyczne zależności.
4. Przepływ danych — co dzieje się z danymi od wejścia do uzyskania wyniku.
5. Deployment — czy można wdrożyć system w sposób powtarzalny.
6. Środowiska — czy dev, test i produkcja są rozdzielone i czym się różnią.
7. Bezpieczeństwo i backup — kto ma dostęp, gdzie są dane i czy można je odtworzyć.
8. Monitoring — czy po wdrożeniu będziemy wiedzieć, że coś przestało działać.
9. Zgodność dokumentacji z rzeczywistością — co opisano, a co faktycznie istnieje.
10. Priorytety — co trzeba zrobić, żeby projekt rzeczywiście ruszył do przodu.

Dopiero po przejściu przez te punkty zaczynam podejmować większe decyzje architektoniczne.

Nie chodzi o to, żeby znaleźć winnego

Przejęcie projektu po innym wykonawcy bardzo łatwo może zamienić się w poszukiwanie osoby odpowiedzialnej za wcześniejsze problemy. Można godzinami analizować, kto podjął decyzję, kto napisał kod, kto wybrał technologię.

Tylko że z perspektywy nowego zespołu najważniejsze pytanie brzmi: co robimy z sytuacją, którą zastaliśmy?

Celem przejęcia projektu jest odzyskanie kontroli nad produktem, a nie napisanie aktu oskarżenia wobec poprzedniego zespołu.

Najdroższy błąd przy przejęciu projektu

Nie jest nim zły kod. Nie jest nim stara technologia. Nie jest nim brak dokumentacji.

Dlatego kiedy przejmuję istniejący projekt, pierwszym celem nie jest „naprawienie kodu". Pierwszym celem jest ustalenie prawdy o systemie.

Dopiero później można zdecydować, co naprawdę trzeba naprawić.