Skorzystaj z tej listy kontrolnej eksportu kodu stworzonego przez AI, by bezpiecznie przekazać projekt: zmienne środowiskowe, sekrety, lokalny setup, bootstrap bazy, CI i jasne README "jak uruchomić".

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ą.
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 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:
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.”
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.
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:
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 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.
Wybierz jedno podejście dla każdego środowiska i trzymaj się go.
.env (gitignored) ładowany przez aplikację, albo lokalny menedżer sekretów zespołuPrzykł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.
Przekazanie to dobry moment na rotację sekretów, szczególnie jeśli były kiedykolwiek używane podczas sesji współdzielonej na platformie.
.env.Jeśli eksportowałeś z Koder.ai, traktuj eksport jako nowe środowisko i wygeneruj świeże sekrety dla zespołu odbierającego.
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ść.
Umieść je na początku README, by nikt nie musiał wyczytywać ich z komunikatów o błędach:
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.
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 ./...
Większość problemów „nie działa” mieści się w kilku kategoriach:
Złe wersje (Node/Go). Objawy: błędy zależności lub kompilacji. Naprawa: zainstaluj przypisane wersje i ponów instalacje.
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.
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.
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.
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:
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.
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.
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:
README, lockfile'y, migracje, skrypty seed, .env.example.env, pliki sekretów, foldery build, logi, lokalne cacheDodaj 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.
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:
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.
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.
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.
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:
.env.example do .env (lub ustaw te same wartości w shellu) dla web i api.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.
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:
.env.example istnieje, a każda wymagana zmienna jest wyjaśniona z bezpiecznymi przykładami.Typowe pułapki są nudne — dlatego są pomijane:
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.
Wybierz jeden stabilny punkt i potraktuj go jako źródło prawdy.
Minimum powinno zawierać:
.env.example i jasną dokumentację zmiennych środowiskowychPomiń wszystko wrażliwe i żadne prawdziwe poświadczenia.
Udokumentuj każdą zmienną środowiskową w jednym miejscu (zwykle w README w katalogu głównym) i dołącz plik .env.example.
Dla każdej zmiennej podaj:
Nie commituj sekretów. Commituj tylko zastępcze wartości.
Proste podejście:
.env.example z placeholderami replace_me.env (wyłączony z gita)Dokumentuj też, jak wygenerować każdy wymagany sekret (np. „wygeneruj losowy ciąg 32+ znaków dla ”).
Rotuj wszystko, co mogło być współdzielone lub ponownie używane.
Praktyczna kolejność rotacji:
.envTraktuj eksport jak nowe środowisko i zaczynaj czysto.
Spraw, by pierwsze uruchomienie było „kopiuj, wklej, uruchom”:
Jeśli projekt wymaga Dockera lub Make, napisz to wyraźnie — nie każ ludziom odkrywać tego przez błędy.
Tak — bo wersje narzędzi i PostgreSQL mogą zmieniać zachowanie.
Zapisz przynajmniej:
Przywiązuj wersje gdy możesz i wyświetlaj wersje w CI, aby ułatwić debugowanie.
Daj powtarzalną ścieżkę „od zera”:
Dodaj zabezpieczenia do destrukcyjnych działań (np. wymagaj APP_ENV=development lub flagi potwierdzającej).
Trzymaj CI blisko poleceń lokalnych i spraw, by konfiguracja była jawna.
Jeśli testy wymagają migracji, opisz, czy CI uruchamia je automatycznie, czy jako osobny krok.
Wykonaj test „czystego klona”:
Jeśli musisz improwizować choć raz, popraw dokumentację lub skrypty, aż nie będzie to konieczne. To najszybszy sposób wykrycia ukrytych założeń środowiskowych (w tym platform vibe-codingowych jak Koder.ai).
JWT_SECRET