Vibe coderze, udokumentuj swoją pracę — 3 pliki, które ratują projekt
Opowiem ci, jak to wygląda z drugiej strony stołu.
Dostałem od klienta PoC projektu — chciał, żebym podpiął to do reszty systemu i wdrożył. Brzmi prosto. I nadal, tygodniami, odkrywam, czego tam brakuje. Przedzieram się przez pliki albo sam klikam w każdy element aplikacji, żeby zrozumieć, co się ma dziać. Cała praca przedłuża się o kolejne tygodnie. Pomimo tego, że zaprzęgnąłem do analizy również model AI. Jednak masa wygenerowanego kodu, który ma już wiele ścieżek, które działają jedynie na przykładowych danych, nie ułatwia odkrywania wszystkich zakamarków.
To nie jest anegdota, żeby kogoś obrażać. To jest pokazanie ceny, której vibe coder nie widzi, bo płaci ją ktoś inny — programista odbierający projekt, albo on sam za pół roku, gdy spróbuje coś rozwinąć.
Jestem programistą .NET-a i Reacta. Widzę z bliska, co się dzieje, gdy ktoś nietechniczny oddaje projekt deweloperowi do rozwoju. W 9 na 10 przypadków pierwszy tydzień schodzi na jedno pytanie: „co to właściwie ma robić?”
Nie dlatego, że kod jest zły. Dlatego, że nigdzie nie siedzi intencja.
To jest wpis o tym, jak tego uniknąć w ciągu 20 minut.
Co to jest vibe coding i dlaczego tu jesteśmy
Andrej Karpathy — ten od OpenAI i Tesli — ukuł w lutym 2025 roku termin „vibe coding”. W wolnym tłumaczeniu: widzę rzeczy, mówię rzeczy, wklejam rzeczy — i to głównie działa. Opisuje styl pracy, w którym nie piszesz kodu linijka po linijce. Opisujesz, co ma powstać, a AI to składa.
W 2025 roku przestało to być zabawką dla geeków. Dziś nietechniczne osoby składają w weekend mini-CRM-y, generatory ofert, MVP-y produktowe — rzeczy, które dwa lata temu wymagały dewelopera.
Działa. Naprawdę działa.
Ale ma jeden ślepy punkt.
Ślepy punkt: kod nie zapisuje „dlaczego”
Kod opisuje, co robi program. Nie opisuje, dlaczego akurat tak. A „dlaczego” jest na dłuższą metę ważniejsze.
Prosty przykład. Vibe-codujesz aplikację do śledzenia nawyków. Świadomie nie dodajesz logowania — bo to prototyp dla Ciebie i dwójki znajomych. Wracasz po dwóch tygodniach i prosisz Claude Code o „możliwość dzielenia się nawykami ze znajomymi”.
Co zrobi AI bez dokumentacji? Dopisze ci system userów, bazę znajomych, zaproszenia mailowe, reset hasła. Bo „tak się to normalnie robi”.
Tydzień roboty. A ty chciałeś tylko prywatny link do udostępnienia.
To nie jest wina AI. Model nie wiedział, że celowo nie masz autoryzacji. Nie miał skąd tego wiedzieć.
Demo
Przykład wykorzystania plików, które pokazuję poniżej, możesz znaleźć na moim kanale Youtube, dokładnie tutaj jest film.
Trzy pliki. Razem mniej niż strona A4.
Sam tego używam. Wsadzam do każdego projektu, nawet 2-dniowego. Koszt: 20 minut przy starcie, 2 minuty przy każdej większej zmianie. Często wręcz automatyzuję Claude Code tak, żeby sam pamiętał o aktualizowaniu tych plików (jeżeli chcesz wiedzieć jak sprawnie pracować z Claude Code, a do tej pory wszystko robiłeś ręcznie – zapraszam Cię na konsultacje (znajdziesz je pod tym linkiem Konsultacje)
Poniżej są przykłady tych plików. Zwróć szczególną uwagę na sekcję „Zasady” w pliku CLAUDE.md. To jest moim zdaniem najważniejsza część.
Plik 1: WHAT_WE_DO.md
Po ludzku. Po polsku. Kilka akapitów, każdy 2–3 zdania. Zwykle będzie to to, co i tak wpisujesz agentowi AI, kiedy chcesz, żeby zbudował Ci aplikację. Po prostu zachowaj to na później.
# Habit Tracker (projekt roboczy) ## Po co to istnieje Chcę śledzić 5 swoich nawyków bez używania 20 aplikacji, które mają powiadomienia, social i plany premium. ## Kto tego używa Tylko ja, lokalnie na komputerze - to jest wersja do przetestowania czy mi pasuje. ## Co to robi - Dodaję nawyk z prostej listy. - Codziennie zaznaczam "zrobione". - Widzę serię dni pod rząd. ## Czego NIE robi (i nie zrobi w tej wersji) - Nie loguje użytkowników (używam lokalnie). - Nie ma powiadomień push. - Nie ma aplikacji mobilnej, tylko strona. ## Stan Prototyp. Dane testowe. Backup raz w tygodniu ręcznie.
Dlaczego sekcja „czego NIE robi” jest najważniejsza? Bo to ona zatrzyma AI (i programistę) przed dobudowywaniem rzeczy, których nie chcesz. Bez niej wszyscy — ludzie i modele — dopisują „co by się przydało”.
Plik 2: DECISIONS.md
# Dziennik decyzji - 2026-03-12 — wybrałem JavaScript i tekstową bazę danych SQLite - 2026-03-14 — odrzuciłem logowanie. MVP dla 1 osoby - 2026-03-20 — UI po polsku, nazwy plików po angielsku. - 2026-03-28 — nie robię aplikacji mobilnej. PWA wystarczy. - 2026-04-05 — backup raz w tygodniu ręcznie do Google Drive. Wystarczy na tym etapie.
To się zwraca przy dwóch rzeczach: rozmowie z programistą i kolejnych promptach do AI. Pięć linijek tłumaczy to, co inaczej zajmuje godzinę dyskusji.
Plik 3: CLAUDE.md (albo cursor.rules lub ekwiwalent)
To jest plik, który twoje narzędzie AI automatycznie odczytuje na początku każdej sesji. Nie musisz go wklejać — Claude Code robi to sam.
# Kontekst projektu dla AI ## Stack - Frontend: React + Vite. - Backend: NodeJS + Express + SQLite - Hosting: brak, localhost. ## Konwencje - UI po polsku. Nazwy zmiennych, plików i commitów — po angielsku. - Pliki React: PascalCase. Utility: camelCase. ## Czerwone linie - Nie dodawaj systemu użytkowników bez mojej zgody. Serio. - Nie ruszaj struktury tabel bez pytania. - Nie instaluj nowych zależności bez uzasadnienia. ## Skrót projektu Habit tracker dla 1 osoby. PoC. Dane testowe. Szczegóły — patrz WHAT_WE_DO.md i DECISIONS.md. ## Zasady - Każdą decyzję projektową dodawaj do pliku @DECISIONS.md - Każdy opis nowej funkcjonalności dodawaj do pliku @WHAT_WE_DO.md - Po każdej zmianie w projekcie sprawdzaj czy nie trzeba zaktualizować plików @DECISIONS.md lub @WHAT_WE_DO.md, jeżeli tak, zrób to - Jeżeli zmiana jest sprzeczna z treścią @DECISIONS.md lub @WHAT_WE_DO.md zapytaj użytkownika o to, czy ma być wprowadzona - Jeżeli coś nie zostało ustalone - zapytaj - Pamiętaj, że użytkownik jest osobą nietechniczną, nie pytaj o szczegóły techniczne, ewentualnie wyjaśnij różnice i opcje jeżeli to konieczne
Prosty test: jeśli otwierasz projekt po 2 tygodniach i nie pamiętasz, gdzie byłeś — dokumentacji jest za mało. Jeśli zaczynasz myśleć: „gdzie to było zapisane” — dokumentacji jest za dużo.
Co z tego ma biznes
1. Projekt staje się oddawalny programiście
Wróćmy do historii z początku wpisu. Ta współpraca była długofalowa, a prototyp miał mi znacznie przyspieszyć pracę. Nie przyspieszył aż tak bardzo — dużo czasu poświęciłem na samą analizę. I to jest wniosek, który chcę zostawić tu wyraźnie: prototyp bez dokumentacji nie oszczędza czasu programiście. On tylko przesuwa koszt — z twojego biurka na jego. A ponieważ godzina programisty jest droższa niż twoja godzina pisania 5 akapitów po polsku, matematyka nie jest po Twojej stronie.
Pierwszym pytaniem dewelopera przy odbiorze albo rozwoju projektu będzie zawsze: „co to ma robić i czego ma nie robi?”. Jeśli masz WHAT_WE_DO.md — odpowiadasz w 5 minut. Jeśli nie — płacisz programiście za odtworzenie historii twojego pomysłu z kodu. A to jest droga robota.
2. AI przestaje wymyślać Twój projekt od nowa
Modele zmieniają się co kilka miesięcy. Okno kontekstu resetuje się na początku każdej sesji. Bez dokumentacji każde nowe otwarcie projektu to ruletka stylów i konwencji. Z dokumentacją — jest ciągłość.
3. Dokumentacja to twoja obrona
Przy vibe codingu zawsze coś pójdzie nie tak. Skasujesz przypadkiem plik. AI zepsuje coś, co działało. Klient zapyta: „Dlaczego wybraliśmy takie rozwiązanie?” Dziennik decyzji to twój backup w takich momentach.
Zastrzeżenia, żeby nie brzmieć naiwnie
Dwie rzeczy uczciwie.
Po pierwsze — te trzy pliki nie zastąpią ci programisty przy poważnym projekcie. Od dokumentacji do produkcji jest daleko (bezpieczeństwo, testy, wydajność, utrzymanie). Ale z dokumentacją jesteś w stanie rozmawiać z programistą jak partner, a nie jak klient, który nie wie, co kupuje.
Po drugie — łatwo wpaść w drugą skrajność i napisać zbyt bogato. 30 stron z diagramami, raz napisane i nigdy więcej nieaktualizowane. To nie ma sensu. Jedna strona, aktualna, bije dziesięć nieaktualnych. Jeśli WHAT_WE_DO.md rośnie ponad jedną stronę — dziel projekt, nie pompuj pliku.
Co dalej
Na YouTube robię pokaz na żywo na moim projekcie-zabawce — widać różnicę między projektem bez tych plików a projektem z nimi. Film jest tutaj. Jeśli wolisz zobaczyć niż czytać — idź tam.
Jeśli vibe codujesz w firmie i czujesz, że projekt zaczyna się wymykać — napisz do mnie na LinkedIn albo na maila podanego na stronie Konsultacje. Pierwsza rozmowa: 30 minut, patrzymy, co masz i co dalej.
I napisz mi w komentarzu albo mailu — jakie dokumenty trzymasz w swoich projektach? Ciekaw jestem, czy jest coś, czego nie wymyśliłem.
Leave a Comment