Greenfield workflow w Claude Code — od pustego repozytorium do pierwszego pionowego przekroju

Czego unikać przy starcie greenfield

Zaczynanie od pustego repozytorium daje poczucie wolności, ale często zamienia się w chaotyczny rozbieg: mnóstwo wygenerowanych plików, częściowo działający build i brak jasnego miejsca na kolejną zmianę. Celem greenfield workflow Claude Code jest uniknięcie tego pierwszotygodniowego chaosu.

Kilka powtarzających się porażek:

• Kod, który „działa na mojej maszynie”, bo konfiguracja żyje w czyjejś pamięci, a nie w skryptach.
• Drzewo folderów, które odzwierciedla kolejność tworzenia, a nie sposób rozwoju aplikacji.
• Pętla, w której każdy nowy prompt przepisuje wcześniejsze wybory, więc nic nie staje się stabilne.

Wczesne decyzje trudno cofnąć, bo wszystko na nich się buduje. Myląca struktura cały czas się utrwala. Ręczny build rozrasta się do dziesięciu różnych sposobów uruchomienia. Jeśli nie zablokujesz prostej komendy deweloperskiej wcześnie, nie odróżnisz, czy zmiana zepsuła aplikację, czy tylko środowisko.

Kiedy w tym poście mówimy „działająca aplikacja”, mamy na myśli coś konkretnego: jedną komendę, która uruchamia projekt, wypisuje przewidywalny output i głośno sygnalizuje, gdy czegoś brakuje. Powinieneś móc usunąć lokalną instalację, sklonować repo, uruchomić tę komendę i zobaczyć ten sam rezultat.

„Pionowy przekrój” (vertical slice) to najmniejsza funkcja end-to-end, która udowadnia, że aplikacja jest prawdziwa. Nie jest to makieta UI ani sama tabela w bazie. To cienka ścieżka przez cały system: strona z formularzem, jedno API zapisujące dane, jedno odczytanie z bazy i widoczny wynik na stronie.

Jeśli możesz uruchomić aplikację jedną komendą i wdrożyć jeden pionowy przekrój, masz bazę, na której można iterować bez zgadywania.

Zdecyduj o pierwszym przekroju zanim cokolwiek wygenerujesz

Jasny pierwszy przekrój utrzymuje repo w porządku i skupia prompt. To moment, by zdecydować, co chcesz zademonstrować end-to-end, nie to, czym może się stać pełny produkt.

Wybierz najmniejszą historię użytkownika, która udowadnia działanie aplikacji na całej ścieżce. Dobry przekrój dotyka UI, danych i jednej rzeczywistej akcji. Przykład: „Jako użytkownik mogę dodać zadanie i zobaczyć je na liście po odświeżeniu.” To maleńkie, ale wymusza routing, walidację, przechowywanie i podstawowy ekran.

Wybierz jedną platformę docelową na tydzień 1 i trzymaj się jej. Jeśli zaczynasz od web, rób tylko web. Nie dorzucaj ekranów mobilnych „na wszelki wypadek”. Nawet jeśli planujesz użyć platformy takiej jak Koder.ai później, lepsze rezultaty osiągniesz, gdy pierwszy przekrój zostanie w jednej „linii” (React web, albo Go API, albo Flutter).

Zdefiniuj, co oznacza „gotowe na tydzień 1” prostymi słowami:

• Działa lokalnie ze świeżego klonu jedną komendą
• Jedna działająca funkcja, przez którą można przejść klikając
• Błędy pokazują wiadomość zrozumiałą dla człowieka (nie stack trace)
• Dane utrwalają się gdzieś prosto (nawet lokalna baza danych)

Potem zapisz trzy non-goals, które chronią zakres. Na przykład: brak autoryzacji, brak systemu motywów, brak zadań w tle.

Gdy te decyzje są zapisane, możesz dać Claude surowszy prompt: buduj tylko to, co wspiera przekrój, a resztę zostaw jako TODO.

Kilka decyzji z góry, które oszczędzają pracy później

Zanim poprosisz Claude o wygenerowanie czegokolwiek, ustal kilka domyślnych wyborów. Wydają się małe, ale zapobiegają bałaganowi z późniejszym „zmienianiem wszystkiego”.

Najpierw zdecyduj kształt aplikacji. Jeśli naprawdę potrzebujesz UI w przeglądarce i backendu, zacznij od dwóch wyraźnych części (frontend + API) i wspólnego miejsca na kontrakty (typy API albo prosty schemat). Jeśli aplikacja może być jednym serwerowo-renderowanym webem, trzymaj ją w jednym repo, żeby lokalny development był prosty.

Następnie ustal zasady konfiguracji. Używaj lokalnego pliku env, trzymaj go poza gitem i zatwierdź szablon (na przykład .env.example) z bezpiecznymi placeholderami i krótkimi komentarzami. To ułatwia onboarding i zmniejsza wycieki sekretów.

Wybierz domyślne porty deweloperskie i trzymaj je stabilnie. Porty trafiają do skryptów, dokumentacji i komunikatów o błędach, więc ich zmiana później jest uciążliwa. To samo z nazewnictwem: foldery, serwisy i pakiety powinny trzymać jedną konwencję. Konsystencja ważniejsza od „idealnej” konwencji.

Prosty zestaw startowy decyzji:

• Kształt aplikacji: jedna aplikacja albo frontend + API
• Konfiguracja: .env lokalnie, .env.example w repo
• Porty: jeden dla web, jeden dla API, jeden dla DB (jeśli potrzeba)
• Nazwy: jeden styl zapisu nazw dla folderów, spójne nazwy serwisów
• Sekrety: nigdy nie commitować, rotować jeśli wyciekły

Przykład: wybierasz web na porcie 3000 i api na porcie 8080. Twój szablon env zawiera API_URL=http://localhost:8080 i DATABASE_URL=.... Gdy Claude później wygeneruje skrypty i dokumenty, wszystko trzyma się kupy zamiast dryfować.

Jak promptować Claude Code, żeby zachował strukturę

Zacznij od prośby o uruchomialny szkielet, nie o „całą aplikację”. Najszybsza droga do nieporządku to żądanie funkcji zanim masz miejsce, gdzie je umieścić.

Bądź konkretny co do struktury. Poproś o układ folderów z krótkimi komentarzami wyjaśniającymi, co należy gdzie umieszczać, a czego nie. To wymusza decyzje z góry zamiast rozrzucać pliki w miarę postępu.

Prosty sposób na dyscyplinę to narzucić reguły w promptcie:

• Najpierw wygeneruj najmniejszy uruchomialny szkielet (strona powitalna, health endpoint lub jeden ekran).
• Zaproponuj strukturę folderów i wyjaśnij każdy folder jednym zdaniem.
• Dodaj skrypty, które działają na świeżej maszynie (install, dev, test, build) i podaj wymagania wstępne.
• Trzymaj zmiany w jednym PR-owym fragmencie i wypisz dokładnie, które pliki zostaną utworzone lub edytowane.
• Zatrzymaj się po scaffoldu i powiedz, jak to uruchomić.

Oto prompt, którego możesz używać i dopasowywać:

You are working in an empty repo. Create a minimal runnable skeleton.

Constraints:
- Keep it small: no real features yet.
- Propose a clear folder structure and add brief comments in each folder’s README.
- Add scripts for: setup, dev, test, build. They must work on a fresh machine.
- Tell me exactly how to run it, and what output I should see.
- After generating, stop and wait for my “ran it” confirmation.

Output:
1) File tree
2) Key files (only)
3) Run instructions

Potem utrzymuj krótką pętlę. Nie żądaj pięciu zmian naraz. Wygeneruj jedną drobną zmianę, uruchom ją, wklej dokładny błąd (lub sukces), a potem poproś o minimalną poprawkę. Ta rytmika generuj-uruchom-poprawia utrzymuje projekt przewidywalnym i zmniejsza możliwość dryfu struktury.

Krok po kroku: od pustego repo do uruchomialnego szkieletonu

Zacznij z jedną obietnicą: każdy powinien móc sklonować repo i uruchomić jedną komendę, żeby zobaczyć coś działającego. To daje stabilną bazę zanim poprosisz AI o dodanie prawdziwych funkcji.

Utwórz repo i napisz malutkie README, póki wszystko jest świeże. Bądź praktyczny: wymagania, jedna komenda deweloperska i jak uruchomić testy (nawet jeśli testy są na razie puste).

Następnie wybierz układ top-level, który pasuje do wybranego kształtu aplikacji.

Jeśli budujesz wiele wdrożalnych kawałków (na przykład frontend + API), pomocny może być layout z workspace:

/
  apps/
  packages/
  scripts/
  docs/
  README.md

Jeśli budujesz jedną aplikację, trzymaj to prościej i unikaj dodatkowych poziomów, dopóki nie będą potrzebne.

Teraz dodaj minimalne strażniki, żeby kod pozostał spójny. Wybierz jeden formatter i jeden linter, zaakceptuj ich domyślne ustawienia i dodaj pojedynczy plik konfiguracyjny każdego z nich. Celem są czytelne diffy, nie idealne reguły od pierwszego dnia.

Uczyń doświadczenie deweloperskie przewidywalnym jedną komendą, która zawsze działa z katalogu głównego repo. Oto prosty kształt:

{
  "scripts": {
    "dev": "echo \"start dev server here\"",
    "build": "echo \"build here\"",
    "test": "echo \"tests here\"",
    "lint": "echo \"lint here\""
  }
}

Zanim wygenerujesz cokolwiek dalej, uruchom tę komendę dev, potwierdź, że kończy się czysto (albo uruchamia placeholderowy serwer), a potem zrób pierwszy commit zawierający tylko scaffolding. Jeśli kolega (albo przyszły Ty) może odtworzyć setup od zera, jesteś gotów budować pierwszy przekrój.

Struktura folderów, która przetrwa wzrost aplikacji

Dobra greenfieldowa struktura robi dwie rzeczy: pomaga szybko znaleźć kod i daje Claude mniej pola do wymyślania nowych wzorców za każdym razem, gdy poprosisz o zmianę. Celem nie jest perfekcja. Celem jest stabilność.

Jeśli pracujesz w jednej aplikacji (albo w folderze apps/<name>/), prosty wewnętrzny układ zwykle się sprawdza:

• src/ kod aplikacji (funkcje, elementy współdzielone, punkty wejścia)
• config/ konfiguracja bez sekretów
• tests/ testy wysokiego poziomu, które czytają się jak zachowania użytkownika
• scripts/ pomocnicze skrypty (setup deva, reset bazy, zadania release)
• docs/ krótkie notatki i checklisty, które faktycznie utrzymujesz

W src/ oddziel kod funkcji od kodu współdzielonego w oparciu o wzorce zmian. Kod funkcji zmienia się często i powinien być blisko siebie. Kod współdzielony powinien być nudny i wielokrotnego użytku.

Praktyczna zasada: umieszczaj ekrany UI, handlery i logikę specyficzną dla funkcji pod src/features/<nazwaFunkcji>/.... Rzeczy takie jak logowanie, klienci API, komponenty design systemu i ogólne narzędzia trafiają pod src/shared/.... Jeśli pomocnik ma sens tylko dla jednej funkcji, trzymaj go w tej funkcji nawet jeśli wygląda na przydatny. Przenieś go później, kiedy pojawi się drugi rzeczywisty przypadek użycia.

Nazwy folderów powinny opisywać przeznaczenie, nie technologię. „features” i „shared” pozostają zrozumiałe, gdy zmieni się stack. Unikaj nazw typu „misc” czy „new”.

Trzymaj docs/ małe. Dobry start to docs/checklists.md z kilkoma liniami: jak uruchomić, jak testować, jak dodać nowy folder funkcji i co oznacza „done”.

Skrypty build, które czynią projekt przewidywalnym

Repo wygląda na prawdziwe, gdy każdy może uruchomić te same komendy i uzyskać ten sam rezultat. Skrypty są barierkami: zmniejszają zgadywanie, trzymają zmiany małymi i sprawiają, że widać, kiedy coś się zepsuło.

Zacznij od małego zestawu komend i trzymaj je nudnymi. Jeśli ktoś nowy dołączy (albo wrócisz po dwóch tygodniach), nie powinien potrzebować specjalnych flag czy ukrytych kroków.

Oto prosta baza, którą możesz dopasować do dowolnego stacku:

{
  "scripts": {
    "dev": "node ./scripts/dev.js",
    "build": "node ./scripts/build.js",
    "test": "node ./scripts/test.js",
    "test:quick": "node ./scripts/test.js --quick",
    "test:full": "node ./scripts/test.js --full",
    "format": "node ./scripts/format.js",
    "lint": "node ./scripts/lint.js",
    "smoke": "node ./scripts/smoke.js"
  }
}

Spraw, by skrypt dev był ścieżką szczęścia. Powinien uruchomić aplikację, wypisać gdzie działa i utrzymywać logi czytelnymi. Jeżeli serwer nie może wystartować, powinien szybko zakończyć się z jednym jasnym komunikatem (brakująca zmienna env, port zajęty, baza niedostępna).

Skrypt build zawsze powinien tworzyć czysty katalog wyjściowy. Usuń stare artefakty najpierw, a potem wygeneruj świeże. To zapobiega dziwnym błędom spowodowanym plikami z wczoraj.

Dla testów podziel szybkie i wolne sprawdzenia. Szybkie testy uruchamiają się przy każdej zmianie (testy jednostkowe, sprawdzenia typów). Pełne testy obejmują integrację i uruchamiają się przed mergem.

Utrzymuj styl spójny jedną komendą. Prosta zasada: format naprawia, lint narzeka.

Na koniec dodaj smoke check, który waliduje podstawy zanim stracisz czas na debug:

• Wymagane zmienne env są ustawione (i nie są puste)
• Wybrane porty są wolne
• Aplikacja może wystartować i odpowiedzieć na jedno proste zapytanie
• Połączenie z bazą działa (jeśli używana)
• Po build istnieje output

Zbuduj pierwszy pionowy przekrój

Twój pierwszy pionowy przekrój powinien udowodnić działanie aplikacji end-to-end, nie tylko ładny wygląd UI. To oznacza małą funkcję, która dotyka ekranu, logiki i jakiegoś rodzaju przechowywania, nawet jeśli przechowywanie jest tymczasowe.

Wybierz coś nudnego i użytecznego, jak „Dodaj notatkę” czy „Utwórz zadanie”. Trzymaj to małe, żeby skończyć w jednym podejściu, ale kompletne na tyle, by móc kliknąć i zobaczyć realną zmianę stanu.

Dobry przekrój ma cztery części: jedną trasę lub ekran, jeden formularz, jedną akcję zapisu i jedno wyświetlenie. Przykład: strona „Nowe zadanie” z polem tytułu, przyciskiem Zapisz, który wywołuje jedną funkcję, i listą pokazującą zapisane zadania.

Zacznij od placeholderowego store, żeby iść szybko. Tablica w pamięci, lokalny plik JSON albo prosty stub interfejsu są w porządku. Kluczowe jest utworzenie granicy, którą później zastąpisz. Jeśli dziś twój kod wywołuje taskRepository.save(task), przesiadka na prawdziwą bazę później będzie małą zmianą, a nie przeróbką.

Utrzymuj UI prosty. Pomiń dyskusje o design systemie, stany puste i animacje.

Sprawdzenia akceptacyjne, które zajmą dwie minuty:

• Strona otwiera się bez błędów
• Możesz wpisać wartość i nacisnąć Zapisz
• Nowy element pojawia się od razu
• Odświeżenie pokazuje oczekiwane zachowanie (utrwalone jeśli prawdziwe przechowywanie, zresetowane jeśli fałszywe)
• Złe dane są obsłużone (pusty tytuł pokazuje komunikat i nie zapisuje)

Uczyń to na tyle stabilnym, by móc iterować

Gdy masz uruchomialny szkielet i jeden pionowy przekrój, cel zmienia się: niech awaria będzie oczywista, a naprawa szybka. Tu wiele greenfieldów się rozsypuje — nie dlatego, że funkcja jest trudna, lecz dlatego, że drobne zmiany zaczynają powodować niespodzianki.

Ustal maleńkie minimalne kryteria stabilności, które spełniasz przy każdym dodaniu przekroju:

• Jeden smoke test, który udowadnia, że aplikacja się bootuje i główna trasa/ekran renderuje
• Jeden smoke test, który trafia w przekrój end-to-end (nawet jeśli używa testowej bazy)
• Jasne komunikaty o błędach zrozumiałe dla użytkownika (nie stack trace)
• Logi deva, które wyjaśniają, co się stało, bez wypluwania sekretów
• Minimalne zależności, z przypiętymi wersjami, aktualizacje robione świadomie

Konkretny przykład: twój pierwszy przekrój pozwala użytkownikowi utworzyć „Projekt” i zobaczyć go na liście. Dodaj test, który uruchamia serwer, wywołuje endpoint tworzenia, potem pobiera listę i sprawdza, że nowy element się pojawił. Jeśli test pada, niech padnie głośno z jednym pomocnym komunikatem, jak „Create Project endpoint returned 500”, a nie ścianą outputu.

Dla obsługi błędów trzymaj się małego zestawu spójnych odpowiedzi. Błędy walidacji zwracają krótką wiadomość („Nazwa jest wymagana”) i pole. Nieoczekiwane błędy zwracają „Coś poszło nie tak. Spróbuj ponownie.” Szczegóły zapisuj do logów.

Logowanie jest najbardziej przydatne, gdy odpowiada na pytania: jakie żądanie, jaki użytkownik (albo anonim), co się zepsuło i gdzie. W dewelopmencie dołącz id żądania i czas, ale unikaj wypisywania tokenów, haseł, kluczy API czy pełnych ładunków domyślnie.

Dodaj mały health check. W webie może to być endpoint /health zwracający ok. Na mobile — stan „Connected”, który zmienia się na „Offline”, gdy aplikacja nie może się połączyć z backendem. To szybki sygnał, zanim zaczniesz debugować niewłaściwą rzecz.

Typowe pułapki przy używaniu AI do projektów greenfield

Najszybszy sposób zmarnować greenfield to poprosić model o całą aplikację, a potem uruchomić ją później. Duże generacje ukrywają drobne błędy: brakujące zależności, złe ścieżki importów, skrypty zakładające narzędzia, których nie masz. Traktuj każdy output jako coś, co powinieneś być w stanie uruchomić w kilka minut.

Inna pułapka to projektowanie idealnej architektury zanim będzie funkcja. Debatowanie nad nazwami folderów wydaje się produktywne, ale bez rzeczywistego przekroju nie wiesz, co będzie niewygodne. Prosta struktura wspierająca jedną działającą ścieżkę przebije sprytną strukturę, której nie przetestowano.

Dryf komend też jest powszechny. AI dodaje nowy sposób startu serwera, ty dodajesz kolejny dla testów i wkrótce nikt nie wie, która komenda jest „tą właściwą”. Jeśli kolega sklonuje repo i pyta „Jak to uruchomić?”, już płacisz odsetki.

Błędy powodujące największe przeróbki:

• Generowanie wielu serwisów, ekranów i konfiguracji naraz zamiast zbudowania jednej wykonalnej ścieżki najpierw
• Wciąganie auth, płatności, złożonego stylowania i pełnego modelu danych przed uruchomieniem pierwszej funkcji end-to-end
• Trzymanie instrukcji setupu w czacie zamiast w skryptach (albo jednym README)
• Zapomnienie czystego szablonu env, więc kolejna maszyna nie może wystartować bez domysłów

Prosty przykład: generujesz „kompletną” aplikację z logowaniem, themingiem i billingiem, ale pierwszy run pada, bo brak klucza sekretu i nie ma .env.example. Spędzasz godzinę na poprawkach setupu zamiast sprawdzać, czy funkcja jest użyteczna.

Bądź szczery: jedna uruchamialna komenda, jedna mała funkcja, jeden szablon env, potem rozwijaj.

Szybka lista kontrolna przed dalszymi iteracjami

Zanim dodasz „jeszcze jedną funkcję”, upewnij się, że projekt będzie łatwy do podjęcia jutro (albo przez kogoś innego). Szybkość nie jest celem samym w sobie. Celem jest przewidywalność.

• Jednokomendowe uruchomienie: nowy deweloper może skopiować szablon env, ustawić kilka wymaganych wartości i uruchomić aplikację jedną komendą. Jeśli potrzebne są dodatkowe kroki (setup DB, migracje, seedy), uchwyć je w skrypcie.
• Skrypty obejmują podstawy: jasne komendy dla dev, test, build i szybki smoke check.
• Oczywista struktura: układ opowiada historię (kod aplikacji, konfiguracja, skrypty, testy) bez potrzeby czytania całego repo.
• Ścieżka demonstracyjna pionowego przekroju: potrafisz opisać demo jednym zdaniem, np. „utwórz element, zobacz go na liście, odśwież, nadal tam jest.”
• Punkt przywrócenia: przed dużymi zmianami masz bezpieczny punkt powrotu (czysty commit, tag albo snapshot/rollback).

Jeśli którykolwiek punkt zawodzi, napraw to teraz. Dopinanie skryptów i nazewnictwa jest tanie, gdy repo jest małe.

Następne kroki: zamień workflow w powtarzalny nawyk

Greenfieldowy start się opłaca tylko wtedy, gdy potrafisz go powtórzyć. Po tym jak pierwszy pionowy przekrój działa end-to-end, zamroź dobre elementy w mały szablon: te same wzorce folderów, te same nazwy skryptów i ten sam sposób łączenia UI, API i danych.

Traktuj pierwszy przekrój jak referencyjną implementację. Gdy zaczynasz przekrój #2, kopiuj kształt, nie kod. Jeśli przekrój #1 ma trasę, handler, warstwę dostępu do danych i podstawowy test, przekrój #2 powinien iść tą samą ścieżką.

Planuj lekko. Jednostronicowa notatka wystarczy na następne 2–3 przekroje: cel i akcję użytkownika dla każdego przekroju (jedno zdanie), dane, które potrzebujesz, kryteria „done” i ryzyka do przetestowania wcześnie.

Potem uczyniaj utrzymanie nawykiem. Raz w tygodniu zrób krótkie porządki: dopnij skrypty, zaktualizuj README o nowe kroki setupu i odśwież szablon env, żeby onboarding pozostał łatwy.

Jeśli wolisz pętlę budowy opartą na czacie, Koder.ai (koder.ai) jest jedną z opcji, która wspiera tryb planowania plus snapshoty i przywracanie, i potrafi eksportować źródła, gdy chcesz przenieść projekt gdzie indziej.

Celem jest workflow, który działa bez myślenia: zaplanuj 2–3 przekroje, zbuduj jeden przekrój, ustabilizuj, powtarzaj.