Przez lata słaba dokumentacja była po prostu irytująca. Nowa osoba dłużej wdrażała się do projektu, ważne decyzje ginęły w Slacku, a README często kończyło jako plik, który ktoś kiedyś napisał i potem już nikt do niego nie wracał.
Dziś problem robi się większy, bo ten sam bałagan czyta już nie tylko człowiek, ale też agent AI. A agent nie ma tego luksusu, że podejdzie do biurka obok i zapyta: „ej, o co tu chodzi?”. Jeśli repo mówi niejasno, agent bardzo często uzupełni brakujący kontekst własnym domysłem.
I właśnie dlatego dokumentacja przestaje być miłym dodatkiem. Coraz częściej staje się częścią interfejsu projektu.
Problem nie w tym, że agent jest „głupi”
Najprościej powiedzieć: modele halucynują, więc nie ma co im ufać. To brzmi efektownie, ale trochę spłyca temat. W praktyce sporo dziwnych decyzji agenta nie bierze się z jakiejś tajemniczej „głupoty AI”, tylko z tego, że repo samo daje mu mętny obraz sytuacji.
Człowiek, który zna projekt od środka, ma mnóstwo ukrytej przewagi. Wie, które moduły są tymczasowe. Wie, którego API lepiej nie dotykać. Pamięta stary kompromis z klientem albo decyzję, która wygląda dziwnie w kodzie, ale ma bardzo konkretne uzasadnienie. Agent tego nie wie. On składa sobie obraz systemu z nazw plików, README, testów, komentarzy i lokalnych zasad.
Jeśli więc projekt nie opisuje swoich granic, agent może zrobić zmianę, która wygląda rozsądnie, a mimo to rozwala ważne założenie. Kiedyś zła dokumentacja głównie spowalniała pracę. Teraz potrafi przyspieszać błędne decyzje.
Samo README „dla ludzi” to już często za mało
W wielu repozytoriach README robi dziś jedną z dwóch rzeczy. Albo jest małym landing page’em z badge’ami i ładnym opisem, albo szybką instrukcją uruchomienia projektu. I jasne, obie formy mają sens. Tyle że w świecie agentów to coraz częściej nie wystarcza.
Agent nie potrzebuje tylko odpowiedzi na pytanie „co to za projekt?” i „jak go odpalić?”. Potrzebuje też wiedzieć, gdzie są granice odpowiedzialności, czego lepiej nie ruszać, jak czytać strukturę repo i jakie są lokalne zasady bezpiecznej zmiany.
To jest duża zmiana. README przestaje być wyłącznie wizytówką projektu. Staje się mapą wejścia. Jeśli tej mapy nie ma, agent porusza się po repo trochę jak ktoś obcy w mieście bez nazw ulic. Niby idzie do przodu, ale łatwo skręca nie tam, gdzie trzeba.
Najgorsza nie jest nawet całkowita pustka, tylko pozór porządku. README istnieje, wygląda profesjonalnie, ale nie odpowiada na pytania, które naprawdę pomagają podejmować decyzje. A wtedy projekt sprawia wrażenie lepiej opisany, niż jest w rzeczywistości.
Jaki kontekst naprawdę przydaje się agentowi
Dobra wiadomość jest taka, że dokumentacja pod agenta wcale nie musi być długa ani nadęta. Musi być po prostu konkretna.
Najpierw przydaje się jasny opis celu projektu i jego zakresu. Nie tylko „to aplikacja do zarządzania zadaniami”, ale na przykład: „to repo zawiera backend i panel admina, ale nie aplikację mobilną”. Jeden taki detal potrafi od razu zawęzić błędne interpretacje.
Druga rzecz to lokalne uruchomienie. Brzmi banalnie, ale brak prostej ścieżki startu generuje mnóstwo złych założeń. Agent powinien wiedzieć, jakie komendy są obowiązkowe, jakie usługi trzeba podnieść i gdzie leży przykładowa konfiguracja.
Trzecia sprawa to struktura modułów. Jeśli logika billingowa siedzi w jednym katalogu, a autoryzacja w drugim, warto to nazwać wprost. Nie zakładajmy, że „to przecież widać z kodu”, bo bardzo często wcale nie widać.
Czwarta rzecz to zasady zmian. Czy każdy nowy endpoint wymaga testu integracyjnego? Czy migracje muszą być odwracalne? Czy zmiany w auth trzeba konsultować szerzej? Dla ludzi w zespole to często oczywistość. Dla agenta nie.
Piąta rzecz to obszary ryzyka. Billing, auth, feature flagi, integracje zewnętrzne, procesy asynchroniczne, migracje danych. Jeśli tego nie oznaczysz, agent potraktuje cały projekt jak jednorodne pole do zmian. A prawie nigdy tak nie jest.
No i wreszcie rzeczy, których nie da się wyczytać z samego kodu. Tu wchodzą ADR-y.
Dobre README powinno być bardziej operacyjne
Zamiast pytać: „czy nasze README wygląda profesjonalnie?”, lepiej zadać sobie inne pytanie: „czy ktoś nowy zrozumie po 10 minutach, jak bezpiecznie poruszać się po tym repo?”. To dużo lepszy test.
Naprawdę nie trzeba robić z README małej książki. W praktyce wystarcza prosty układ: krótki opis projektu i zakresu, sekcja o uruchomieniu lokalnym, mapa repozytorium, zasady wprowadzania zmian i linki do ważniejszych decyzji architektonicznych oraz dokumentacji operacyjnej.
To brzmi zwyczajnie, ale robi ogromną różnicę. Znika język w stylu „nowoczesna, skalowalna architektura”, a pojawia się język, z którego da się skorzystać. Na przykład zamiast pustego hasła możesz napisać wprost: „cała logika rozliczeń jest w services/billing/, a każda zmiana w tym module wymaga testów integracyjnych i review od właściciela domeny”.
Taka dokumentacja pomaga i człowiekowi, i agentowi. Nie dlatego, że ma więcej słów, tylko dlatego, że zamienia ogólniki na decyzje.
ADR-y to pamięć projektu, a nie biurokracja
W wielu zespołach ADR-y dalej brzmią jak coś „na kiedyś”. Jak dokumentacyjny luksus dla dużych organizacji albo ludzi, którzy mają za dużo czasu. Problem w tym, że wraz z wejściem agentów takie podejście robi się coraz droższe.
ADR nie jest po to, żeby opisywać kod. Kod już mamy. ADR ma zapisać, dlaczego wybrano taką drogę, a nie inną. Dla człowieka to skrót historii projektu. Dla agenta to sygnał: „nie optymalizuj tego automatycznie, bo ten układ wynika z konkretnych ograniczeń”.
Wyobraź sobie repo, w którym warstwa autoryzacji wygląda staro i średnio elegancko. Agent może dojść do wniosku, że warto ją uprościć. Jeśli jednak istnieje ADR mówiący, że obecny układ wynika z wymogów zgodności, integracji z legacy albo potrzeby utrzymania kompatybilności z ważnym klientem, to nagle cały obraz się zmienia.
Bez ADR-u agent widzi tylko dziwny stan końcowy. Z ADR-em widzi też historię kompromisu.
Dobry ADR wcale nie musi być długi. Wystarczy kontekst, opcje, decyzja, konsekwencje, data i status. Tyle. Chodzi nie o formalizm, tylko o to, żeby pamięć projektu nie mieszkała wyłącznie w głowach kilku osób.
Sama architektura to nie wszystko. Liczy się też dokumentacja operacyjna
Jest jeszcze jeden rodzaj wiedzy, który w wielu zespołach żyje głównie „między ludźmi”. To wiedza operacyjna. Jak przepchnąć zmianę bezpiecznie. Kiedy użyć feature flaga. Jak robić migracje. Jak wygląda rollback. Które checki muszą przejść przed mergem.
Dla developera z wewnątrz to codzienność. Dla agenta to często niewidzialna warstwa systemu. A właśnie ona potrafi zdecydować, czy zmiana jest tylko technicznie poprawna, czy też faktycznie bezpieczna dla projektu.
To jeden z najciekawszych skutków ubocznych pracy z AI: dokumentacja operacyjna nagle zyskuje na wartości. Już nie służy tylko onboardingowi. Zaczyna też chronić projekt przed zmianami, które wyglądają sensownie w kodzie, ale organizacyjnie albo produkcyjnie są ryzykowne.
Jeśli agent ma realnie pomagać, musi wiedzieć nie tylko jak zmienić kod, ale też jak zrobić to bezpiecznie.
Cztery antywzorce, które podkładają nogę
Pierwszy antywzorzec to README jako landing page. Ładnie wygląda, ale nie pomaga podjąć żadnej sensownej decyzji technicznej.
Drugi to dokumentacja sprzeczna z kodem. To jeden z najgorszych przypadków, bo agent dostaje dwa źródła prawdy i musi zgadywać, któremu ufać.
Trzeci to decyzje architektoniczne istniejące wyłącznie w głowach seniorów albo w zamkniętych wątkach komunikatora. Dla nowej osoby taka wiedza praktycznie nie istnieje. Dla agenta też nie.
Czwarty to ogólniki. „System jest modułowy”, „dbamy o jakość”, „architektura wspiera skalowanie”. To nie jest dokumentacja. To dekoracja.
Typowy błąd zwykle zaczyna się nie od modelu, tylko od repo
Weźmy prosty scenariusz. Agent dostaje zadanie: dodać nowy sposób autoryzacji użytkownika. Otwiera repo, widzi kilka plików związanych z auth, trochę middleware, konfigurację i istniejącego providera.
Nie widzi jednak jasnego opisu granic modułów. Nie widzi ADR-u tłumaczącego, dlaczego auth jest spięty z legacy providerem. README nie wspomina też, że zmiany w tym obszarze zawsze wymagają testów integracyjnych i sprawdzenia flow dla klientów enterprise.
Więc agent robi coś, co z jego perspektywy jest całkiem logiczne: upraszcza kod, porządkuje zależności, dodaje nową ścieżkę logowania. Zmiana wygląda schludnie. Być może przechodzi część testów. Może nawet dobrze wypada w pierwszym review.
Tyle że po drodze łamie niejawne założenie projektu.
I właśnie o to chodzi: to nie zawsze jest porażka modelu. Bardzo często to porażka repozytorium jako nośnika wiedzy.
Jak poprawić repo bez wielkiej akcji dokumentacyjnej
Dobra wiadomość? W wielu zespołach nie trzeba od razu uruchamiać półrocznego programu naprawy dokumentacji. Czasem wystarczy godzina porządnej pracy.
Najpierw dopisz do README, czym dokładnie jest projekt i czego nie obejmuje. Potem dodaj prostą sekcję o lokalnym uruchomieniu i testach. Następnie opisz strukturę modułów i wskaż obszary ryzyka. Po tym zapisz jeden ważny ADR, najlepiej o decyzji, która dziś najczęściej bywa źle rozumiana. Na końcu usuń najbardziej mylące fragmenty starej dokumentacji.
To często wystarcza, żeby repo przestało być zbiorem domysłów, a zaczęło być środowiskiem, w którym agent może działać z dużo mniejszym ryzykiem.
Bo celem nie jest napisanie większej liczby dokumentów. Celem jest ograniczenie liczby błędnych interpretacji.
Dokumentacja staje się częścią interfejsu projektu
Przez lata można było traktować dokumentację jako koszt uboczny tworzenia software’u. Coś ważnego, ale łatwego do odkładania. W świecie, w którym kod coraz częściej czytają i modyfikują także agenci, ta logika zaczyna się sypać.
Jeśli chcesz, żeby agent był realnym wsparciem, nie wystarczy lepszy prompt. Trzeba jeszcze dać mu repo, które jasno komunikuje cel, granice, ryzyka i zasady zmian. README, ADR-y i dokumentacja operacyjna nie są już tylko pomocą dla człowieka. Coraz częściej stają się warstwą sterującą pracą na kodzie.
Dobra dokumentacja nie sprawi, że agent nagle stanie się nieomylny. Ale bardzo skutecznie ograniczy całą klasę błędów, które biorą się nie z jakości modelu, tylko z jakości kontekstu.
A to w praktyce może być różnica między narzędziem, które przyspiesza zespół, a narzędziem, które po prostu szybciej produkuje bałagan.
