Lista kontrolna eksportu kodu stworzonego przez AI — czyste przekazanie

Dlaczego projekty po eksporcie zawodzą po przekazaniu

Większość wyeksportowanych projektów zawodzi z prostego powodu: działały poprawnie wewnątrz oryginalnej platformy, gdzie domyślne ustawienia, sekrety, stan bazy danych i kroki builda już istniały. Gdy kod wychodzi z tej bańki, następny deweloper musi zgadywać, co zostało przyjęte za oczywiste.

Czyste przekazanie oznacza, że projekt można sklonować, skonfigurować i uruchomić przez kogoś, kto go nie budował, na świeżym komputerze, bez długich wymian informacji. Nie wymaga idealnego kodu — wymaga, by podstawy były jawne i powtarzalne.

Eksportom zagrażają wciąż te same problemy: ukryta konfiguracja, niejasne obchodzenie się z sekretami, nieprecyzyjne kroki lokalnego setupu, niespodzianki związane z bazą danych oraz CI działające tylko w jednym środowisku.

Dlatego lista kontrolna eksportu kodu stworzonego przez AI to w dużej mierze dokumentacja i powtarzalność, a nie kopiowanie plików. Jeśli budowałeś aplikację na platformie vibe-codingowej jak Koder.ai i potem wyeksportowałeś kod źródłowy, następny zespół i tak potrzebuje mapy: co ustawić, co uruchomić i co znaczy „działać”.

Ta lista koncentruje się na elementach niezbędnych do przekazania: zmienne środowiskowe, sekrety, lokalne środowisko deweloperskie, bootstrap bazy danych, konfiguracja CI oraz praktyczne README "jak uruchomić". Nie obejmuje decyzji produktowych, dopracowania UX ani przebudowy architektury.

Również odpowiedzialności powinny być jasne. Twórca odpowiada za ujawnienie założeń (dokumentacja, skrypty, bezpieczne domyślne wartości). Odbiorca odpowiada za dostosowanie projektu do swojego środowiska (menedżer sekretów, hosting, bardziej rygorystyczne reguły CI). Gdy obie strony znają swoje zadania, przekazanie staje się rutyną.

Przed eksportem: ustal kontrakt przekazania

Czyste przekazanie zaczyna się od prostego porozumienia: co znaczy „zrobione”, gdy kod opuszcza platformę. Bez tego zespoły później spierają się o brakujące skrypty, zaskakujące zależności czy która wersja była tą właściwą.

Wybierz moment eksportu

Wybierz jeden stabilny punkt w czasie i potraktuj go jako źródło prawdy. Eksport w trakcie zmian to droga do repo, które prawie działa.

Dobry punkt eksportu to zwykle:

• Stabilny commit z krótką notką release (co się zmieniło, co sprawdzić)
• Oznaczony release (nawet jeśli to tylko v0.1.0)
• Snapshot platformy (np. snapshot Koder.ai, do którego można wrócić, jeśli trzeba powtórzyć eksport)

Dodaj jedno zdanie wyjaśniające, dlaczego to właściwy punkt eksportu. Przykład: „Wszystkie kluczowe przepływy działają, a schemat bazy jest finalny dla tego kamienia milowego.”

Zdecyduj, co obejmuje przekazanie

Napisz krótki spis tego, czego odbiorca powinien oczekiwać. Bądź konkretny, co jest dołączone, a co celowo pominięte.

Dołącz podstawy: kod źródłowy (aplikacje, usługi, wspólne pakiety), szablony konfiguracji (przykładowe pliki env), skrypty (build, dev, test, migracje, seed), oraz notatki wdrożeniowe. Dane przykładowe dołączaj tylko, jeśli są oczyszczone i bezpieczne.

Zamroź wersje, by „działa na mojej maszynie” nie stało się nową bazą. Zapisz runtime i wersje narzędzi (Node, Go, Flutter, menedżer pakietów), oraz wersję bazy danych (główna wersja PostgreSQL ma znaczenie).

Na koniec wypisz wymagania wstępne, które trzeba wykonać przed uruchomieniem czegokolwiek. Niech będą krótkie i konkretne: wymagane konta, zainstalowane narzędzia, wolne porty i jednorazowe kroki konfiguracji.

Zmienne środowiskowe: udokumentuj je, by nic nie było ukryte

Większość „działało na platformie” eksportów zawodzi, ponieważ kluczowe ustawienia nigdy nie zostały spisane. Zmienne środowiskowe to zwykle winowajca: żyją poza repo, więc nowy członek zespołu klonuje projekt i nie ma pojęcia, jakich wartości oczekiwać.

Traktuj to jako wymóg czystego eksportu: każda zmienna powinna być odnajdywalna, wyjaśniona i łatwa do ustawienia bez zgadywania.

Stwórz jedno źródło prawdy w README przekazania: lista nazw zmiennych, co kontrolują i skąd pochodzą wartości. Wyjaśnienia w prostym języku; wyróżnij wszystko związane z bezpieczeństwem.

Prosty format dla każdej zmiennej:

• Name: dokładny klucz (do kopiowania)
• Meaning: co zmienia w aplikacji
• Required?: wymagane czy opcjonalne (i co się stanie, gdy brak)
• Example: bezpieczna przykładowa wartość (nigdy prawdziwy sekret)
• Where it differs: dev vs staging vs production

Równolegle do dokumentacji dołącz plik .env.example w repo. Powinien zawierać każdą zmienną, która może być potrzebna, z bezpiecznymi placeholderami, aby aplikacja mogła się uruchomić przy minimalnych zmianach.

# Required
APP_ENV=development
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/app_dev

# Optional
LOG_LEVEL=info
CORS_ORIGINS=http://localhost:5173

# Environment specific
PUBLIC_BASE_URL=http://localhost:3000

Kilka szczegółów zapobiega większości nieporozumień:

Uczyń „wymagane vs opcjonalne” jawne. Jeśli brak zmiennej powoduje awarię, napisz to. Jeśli włącza funkcję (wysyłka maili, płatności, przechowywanie plików), nazwij funkcję i opisz, co się stanie, gdy nie będzie ustawiona.

Wyróżnij, co się zmienia między środowiskami. DATABASE_URL i PUBLIC_BASE_URL często różnią się między dev, staging i production, podczas gdy LOG_LEVEL może być wszędzie taki sam. Jeśli eksportowałeś z Koder.ai, sprawdź, czy domyślne ustawienia platformy (porty, base URL, dozwolone originy) są odzwierciedlone w dokumentacji, aby zachować spójne zachowanie poza platformą.

Na koniec poinformuj, jak zmienne są ładowane lokalnie. Jeśli projekt oczekuje pliku .env, napisz gdzie on się znajduje i czy aplikacja czyta go automatycznie, czy potrzebne jest konkretne polecenie/narzędzie.

Sekrety: trzymaj je poza repo i łatwo dostępne do ustawienia

Sekrety to wartości, których wyciek mógłby wyrządzić szkody: klucze API, hasła do baz, tokeny autoryzacyjne, sekrety klienta OAuth, klucze prywatne, sekrety webhooków i podobne.

Dla eksportu trzymaj to prosto: w repo powinny być tylko placeholdery, nigdy prawdziwe sekretne wartości. Jeśli sekret jest wymagany do uruchomienia, umieść go jako wyraźnie nazwany placeholder w .env.example i wyjaśnij, jak wygenerować prawdziwy.

Praktyczny wzorzec to rozdzielenie trzech rzeczy: pliku przykładowego, pliku lokalnego i magazynu sekretów dla CI/deploymentu. Wyeksportowany kod powinien zawierać próbkę, ignorować lokalny plik i udokumentować, jak CI/hosting otrzymuje sekrety.

Gdzie powinny mieszkać sekrety

Wybierz jedno podejście dla każdego środowiska i trzymaj się go.

• Lokalny development: .env (gitignored) ładowany przez aplikację, albo lokalny menedżer sekretów zespołu
• CI: szyfrowane zmienne sekretów dostawcy CI
• Wdrożenie/hosting: sekrety przechowywane w środowisku hostingu i wstrzykiwane w czasie wykonywania

Przykład: repo zawiera PAYMENTS_API_KEY=replace_me. Odbiorca generuje własny klucz w panelu dostawcy i ustawia go w swoim lokalnym .env oraz w CI. Kod pozostaje bez zmian.

Dodaj krok rotacji

Przekazanie to dobry moment na rotację sekretów, szczególnie jeśli były kiedykolwiek używane podczas sesji współdzielonej na platformie.

• Wydaj nowe klucze dla zewnętrznych usług i unieważnij stare.
• Zresetuj hasła do bazy i wszelkie tokeny administratora.
• Najpierw zaktualizuj sekrety w CI i hostingu, potem lokalne .env.
• Potwierdź, że aplikacja się uruchamia, testy przechodzą i stare klucze nie działają.

Jeśli eksportowałeś z Koder.ai, traktuj eksport jako nowe środowisko i wygeneruj świeże sekrety dla zespołu odbierającego.

Lokalne środowisko deweloperskie: spraw, by pierwsze uruchomienie było nudne

Przekazanie jest udane, gdy nowy deweloper może sklonować repo, uruchomić kilka poleceń i zobaczyć działającą aplikację bez zgadywania. Dąż do przewidywalnych wymagań, jasnej kolejności poleceń i krótkiego bloku „jak uruchomić”, który odzwierciedla rzeczywistość.

Wymagania wstępne (bądź konkretny)

Umieść je na początku README, by nikt nie musiał wyczytywać ich z komunikatów o błędach:

• Notatki o OS: „Testowano na macOS i Ubuntu” (dodaj Windows tylko jeśli testowałeś)
• Wersje runtime: Node.js (dla React), Go (dla API), PostgreSQL (dla DB)
• Narzędzia: npm/pnpm/yarn, Make (jeśli używasz), Docker (tylko jeśli go wymagasz)

Jeśli projekt powstał na Koder.ai, utrzymaj lokalny setup zgodny z tym, co wyeksportowałeś (ta sama struktura folderów, te same polecenia startowe). Nie zakładaj „Postgresa już działa”, jeśli tego nie napiszesz.

Instalacja i polecenia deweloperskie (po jednym poleceniu na wiersz)

Podaj dokładne polecenia w kolejności, w jakiej nowy współpracownik powinien je wykonać. Niech będą gotowe do kopiuj-wklej:

# 1) Install dependencies
cd web
npm ci

cd ../server
go mod download

# 2) Create your env file
cp .env.example .env

# 3) Start dependencies (if needed)
# e.g., start Postgres locally or via docker compose

# 4) Run the app
cd server
go run ./cmd/api

cd ../web
npm run dev

Dodaj minimalną sekcję testów i budowania tuż poniżej:

# Tests
cd server && go test ./...
cd web && npm test

# Build
cd web && npm run build
cd server && go build ./...

Rozwiązywanie problemów: najczęstsze błędy przy pierwszym uruchomieniu

Większość problemów „nie działa” mieści się w kilku kategoriach:

1. Złe wersje (Node/Go). Objawy: błędy zależności lub kompilacji. Naprawa: zainstaluj przypisane wersje i ponów instalacje.

2. Brakujące wartości env. Objawy: nieokreślona konfiguracja, błędy autoryzacji, błędy 500. Naprawa: porównaj .env z .env.example i uzupełnij wymagane wartości.

3. Baza danych nieosiągalna. Objawy: connection refused, „database does not exist”. Naprawa: uruchom Postgresa, sprawdź host/port/user i wykonaj dokładnie kroki inicjalizacji bazy.

Bootstrap bazy danych: migracje, seedy i resety

Po eksporcie projektu z platformy baza danych często psuje się jako pierwsza na nowej maszynie. Cel jest prosty: współpracownik powinien przejść od „sklonowałem repo” do „aplikacja działa z rzeczywistymi danymi” bez zgadywania.

Co udokumentować (i trzymać w repo)

Zapisz minimalne kroki dla świeżej konfiguracji PostgreSQL i umieść polecenia w skryptach tam, gdzie to możliwe. Twoje przekazanie powinno odpowiedzieć na cztery pytania:

• Jak utworzyć bazę i rolę (nazwy, uprawnienia i skąd pochodzi hasło)?
• Jak uruchomić migracje od zera do najnowszej wersji?
• Jak załadować dane seed, które uczynią aplikację użyteczną do demo?
• Jak bezpiecznie zresetować bazę w trakcie developmentu?

Jeśli już masz skrypty (Makefile, skrypty shell, zadania), użyj ich zamiast opisywania kroków ręcznych. Jeśli nie, dodaj mały zestaw teraz.

Nudny flow bootstrapu, który działa

Utrzymaj flow spójny między środowiskami (lokalnym, CI, staging). Dobry punkt wyjścia wygląda tak:

# 1) Create role + database (example names)
createuser app_user --pwprompt
createdb app_db --owner=app_user

# 2) Apply migrations
# Replace with your repo's migration command
./scripts/migrate up

# 3) Seed minimal demo data
./scripts/seed

Dla seedów preferuj minimalne działające dane zamiast zrzutu produkcyjnego. Seedy powinny być bezpieczne do wielokrotnego uruchamiania (idempotentne inserty lub jasna zasada „uruchamiać tylko na pustej DB”).

Dla resetów bądź jawny co jest bezpieczne. Komenda reset powinna domyślnie dotyczyć lokalnego developmentu. Jeśli dostarczasz destrukcyjny skrypt, dodaj zabezpieczenie (np. wymagaj CONFIRM_RESET=1 albo sprawdzaj APP_ENV=development). Zdefiniuj też, co znaczy „reset”: drop i recreate, wyczyszczenie tabel czy przywrócenie snapshotu.

Porządek w repo: co powinno, a co nie powinno się znaleźć w źródle

Przekazanie idzie na bok, gdy repo wygląda jak schowek. Nowy członek zespołu powinien móc stwierdzić, co jest istotne, co jest generowane i gdzie zmieniać ustawienia.

Commity powinny zawierać rzeczy, które czynią projekt powtarzalnym: lockfile'y, pliki migracji, małe szablony konfiguracji jak .env.example oraz skrypty bootstrapujące aplikację.

Trzymaj poza VCS pliki osobiste, generowane lub wrażliwe: lokalne pliki środowiska, ustawienia edytora, output z builda, logi, cache i wszystko, co daje dostęp (klucze API, hasła do baz, pliki kont usług).

Prosta zasada: jeśli zmiana wpływa na wszystkich, commituj. Jeśli zmienia się per maszyna lub środowisko, udokumentuj i trzymaj poza repo.

Jeśli dodasz krótką notkę „co trzymać vs ignorować”, niech będzie zwięzła:

• Commit: README, lockfile'y, migracje, skrypty seed, .env.example
• Ignore: .env, pliki sekretów, foldery build, logi, lokalne cache

Dodaj krótki mapę katalogów, aby struktura była oczywista bez klikania. Przykład: „/backend serwis API, /web frontend, /mobile aplikacja, /db migracje i seedy, /scripts pomocniki setupu.”

Jeśli eksportowałeś z Koder.ai, potraktuj eksport jako początek tej rundy porządkowej: usuń wygenerowane śmieci, potwierdź reguły ignore i napisz mapę katalogów.

CI: spraw, by pipeline był powtarzalny

Przekazanie kończy się cicho, gdy CI jest prawie takie samo jak lokalne. Jeśli ktoś może uruchomić projekt na swoim laptopie, CI powinno uruchamiać te same polecenia i uzyskiwać taki sam wynik.

Zdecyduj, co CI musi weryfikować przy każdym pull requeście. Większość zespołów potrzebuje małego zestawu:

• Lint/format
• Testy jednostkowe
• Build (frontend i backend kompilują się czysto)

Testy integracyjne i kroki deployu są ok, ale tylko jeśli są niezawodne i jasno ograniczone.

Trzymaj kroki CI blisko lokalnych poleceń, by uniknąć dryfu. Jeśli lokalnie uruchamiasz make test, CI powinno też uruchamiać make test. Jeśli nie masz Makefile (lub odpowiednika), rozważ dodanie jednego i używanie go jako wspólnego punktu wejścia.

Uczyń zmienne i sekrety w CI jawne

CI najczęściej zawodzi, bo zależy od ukrytej konfiguracji. Dodaj krótką sekcję „zmienne CI” do README, wymieniając dokładne nazwy, których CI oczekuje. Oddziel publiczną konfigurację od sekretów.

Przykładowe nazwy (dostosuj do stosu): APP_ENV, DATABASE_URL, PORT, JWT_SECRET, S3_BUCKET, STRIPE_API_KEY. W CI sekrety powinny pochodzić ze sklepu sekretów CI, nigdy z plików w repo. Dla backendu Go + Postgres (częsty w eksportach z Koder.ai) zaznacz, czy migracje uruchamiają się automatycznie, czy wymagają jawnego kroku.

Chroń mergery przez status checks

Zdecyduj, które checki są wymagane przed mergem i zapisz je. „lint + unit tests + build” zwykle wystarcza. Jeśli dodajesz opcjonalne zadania (np. buildy mobilne), zostaw je jako nieblokujące, chyba że są naprawdę konieczne.

Również ułatw debugowanie wyników CI: drukuj wersje narzędzi i kończ błędem z jasnym komunikatem. Dodaj cache dopiero, gdy pipeline jest stabilny.

Przykładowy scenariusz przekazania: od klonu do działającej aplikacji

Maya dostaje wyeksportowany projekt z Koder.ai. To typowa konfiguracja: aplikacja React, API w Go i baza PostgreSQL. Powinna móc sklonować repo i bez zgadywania dojść do działającego ekranu.

Jej pierwsze 30 minut powinno wyglądać tak:

1. Sklonuj repo i otwórz główny README.
2. Skopiuj .env.example do .env (lub ustaw te same wartości w shellu) dla web i api.
3. Uruchom PostgreSQL (lokalnie lub w Dockerze) i stwórz pustą bazę.
4. Uruchom migracje i seedy, aby uzyskać znany punkt startowy.
5. Uruchom backend, potem frontend i otwórz aplikację w przeglądarce.

W bałaganiarskim przekazie zwykle napotyka trzy blokery.

Po pierwsze: aplikacja startuje, potem się zawiesza z mało mówiącym błędem „missing config”. Prawdziwą przyczyną jest nieudokumentowana zmienna jak AUTH_JWT_SECRET lub wymagany format DATABASE_URL. Jeśli README wymienia każdą wymaganą zmienną, pokazuje bezpieczny przykład i wyjaśnia, gdzie jest używana, to szybko da się to naprawić.

Po drugie: API startuje, ale strony pokazują „brak danych” lub zwracają 500. Baza istnieje, ale nie ma tabel lub seedów. Czyste przekazanie zawiera jedno lub dwa niezawodne polecenia: uruchom migracje, zrób seed minimalnych danych demo i polecenie resetu na wypadek problemów.

Po trzecie: wszystko działa, ale frontend wskazuje zły port. Maya otwiera localhost:3000, a API oczekuje localhost:8080, albo CORS blokuje żądania. Tu pomagają spójne domyślne ustawienia: jedno miejsce do ustawienia WEB_PORT, API_PORT i API_BASE_URL, z README opisującym oczekiwane lokalne URL-e.

Końcowa lista kontrolna, typowe pułapki i następne kroki

Przekazanie jest ukończone tylko wtedy, gdy ktoś inny może uruchomić projekt ze świeżego klona bez pytań. Udowodnij, że projekt przeżyje poza platformą.

Wykonaj końcowy test „czysty klon” na świeżej maszynie lub wyrzuconym kontenerze. Nie używaj istniejącego folderu, pamięci podręcznej zależności czy lokalnej bazy. Postępuj dokładnie według README. Jeśli musisz improwizować, popraw dokumentację lub skrypty, aż nie będzie to konieczne.

Szybkie kontrole, które wykrywają większość awarii:

• README ma jedną, kopiowalną ścieżkę „jak uruchomić” dla lokalnego deva oraz krótki „jak testować”.
• .env.example istnieje, a każda wymagana zmienna jest wyjaśniona z bezpiecznymi przykładami.
• Bootstrap bazy działa end-to-end: utwórz DB, uruchom migracje, opcjonalnie seed i polecenie resetu.
• CI działa na czystym runnerze i odpowiada lokalnym poleceniom.
• Nowy deweloper może wprowadzić małą zmianę, uruchomić testy i zobaczyć ją w aplikacji.

Typowe pułapki są nudne — dlatego są pomijane:

• Ukryte jednorazowe kroki, które nigdy nie trafiły do dokumentów
• README pasujące do starszej struktury folderów lub starych nazw poleceń
• Zakodowane wartości (URL-e API, flagi funkcji, klucze) zamiast konfiguracji
• Sekrety udostępniane nieformalnie bez jasnej, bezpiecznej ścieżki konfiguracji
• CI przechodzący tylko dlatego, że polega na cache lub lokalnych usługach

Kolejne kroki: wyznacz jedną osobę, która zweryfikuje eksport w ciągu 24–48 godzin, nie tygodni później. Niech wykona test czystego klona i zgłosi luki.

Jeśli budujesz na Koder.ai (Koder.ai), warto traktować tę listę kontrolną jako część normalnego workflow: używaj trybu planowania, aby zapisać ścieżkę uruchomieniową, rób snapshoty przed większymi zmianami i eksportuj źródła regularnie, aby pakiet przekazania był aktualny.