Temiz devretme için Yapay Zeka ile oluşturulmuş kod tabanı aktarım kontrol listesi

Neden projeler devretmeden sonra başarısız olur

Çoğu dışa aktarılmış proje basit bir nedenden başarısız olur: orijinal platform içinde her şey çalışıyordu; varsayılanlar, sırlar, veritabanı durumu ve build adımları zaten hazırdı. Kod bu balondan çıktığında, sonraki geliştirici hangi varsayımların yapıldığını tahmin etmek zorunda kalır.

Temiz bir devretme, projeyi klonlayan, yapılandıran ve onu uzun bir yazışma olmadan taze bir makinede başlatabilen birinin yapabileceği anlamına gelir. Mükemmel kod gerektirmez. Temel şeylerin açık ve tekrar edilebilir olmasını gerektirir.

Dışa aktarmalar aynı sorunlar yüzünden tekrar tekrar bozulur: gizli konfigürasyon, belirsiz sır yönetimi, muğlak yerel kurulum adımları, veritabanı sürprizleri ve sadece tek bir ortamda çalışan CI.

Bu yüzden bir Yapay Zeka ile oluşturulmuş kod tabanı aktarım kontrol listesi çoğunlukla dokümantasyon ve tekrarlanabilirlikle ilgilidir, dosya kopyalamakla değil. Eğer uygulamayı Koder.ai gibi bir vibe-coding platformunda oluşturup sonra kaynak kodunu dışa aktardıysanız, sonraki ekip hala bir haritaya ihtiyaç duyar: neyi ayarlamalı, neyi çalıştırmalı ve “çalışıyor” ne demek.

Bu kontrol listesi devretmenin esaslarına odaklanır: ortam değişkenleri, sırlar, yerel geliştirme kurulumu, veritabanı bootstrap, CI kurulumu ve pratik bir “nasıl çalıştırılır” README. Ürün kararlarını, UX cilasını veya mimariyi yeniden tasarlamayı kapsamaz.

Sahiplik de net olmalı. Oluşturan kişi varsayımları görünür kılmakla yükümlüdür (dokümanlar, betikler, güvenli varsayılanlar). Alan kişi projeyi kendi ortamına uyarlamaktan sorumludur (sır yöneticisi, barındırma, daha sıkı CI kuralları). Her iki taraf da görevini bildiğinde devretme rutin hale gelir.

Dışa aktarmadan önce: devretme sözleşmesini kararlaştırın

Temiz bir devretme, kod platformdan ayrılırken neyin “tamam” sayılacağına dair basit bir anlaşma ile başlar. Bunu yapmazsanız, ekipler sonra eksik betikler, sürpriz bağımlılıklar veya hangi sürümün gerçek olduğu konusunda tartışır.

Dışa aktarma anını seçin

Tek bir kararlı zaman noktasını seçin ve onu gerçek kaynak kabul edin. Değişimin ortasında dışa aktarmak, neredeyse çalışır halde bir repo ile sonuçlanmanın yoludur.

İyi bir dışa aktarma noktası genellikle şunlardan biridir:

• Kısa bir sürüm notu ile kararlı bir commit (ne değişti, ne test edilecek)
• Etiketlenmiş bir sürüm (örneğin v0.1.0 olsa bile)
• Bir platform anlık görüntüsü (örneğin, gerekirse dışa aktarımı tekrarlamak için geri alınabilecek bir Koder.ai anlık görüntüsü)

Bu noktanın neden doğru olduğunu açıklayan bir cümle ekleyin. Örnek: “Tüm temel akışlar geçti ve veritabanı şeması bu kilometre taşı için nihai.”

Devretme neleri içeriyor diye karar verin

Alıcının ne beklemesi gerektiğini kısa bir envanter halinde yazın. Nelerin dahil olduğunu ve nelerin kasıtlı olarak dahil edilmediğini açıkça belirtin.

Temel olanları dahil edin: kaynak kodu (uygulamalar, servisler, paylaşılan paketler), konfigürasyon şablonları (.env örnekleri), betikler (build, dev, test, migration, seed) ve dağıtım notları. Örnek veriyi sadece temizlenmiş ve güvenliyse dahil edin.

Sonra sürümleri dondurun ki “benim makinemde çalışıyor” yeni temel olmasın. Çalışma zamanı ve araç zinciri sürümlerini (Node, Go, Flutter, paket yöneticisi) ve veritabanı sürümünü (PostgreSQL major sürümü önemli) yakalayın.

Son olarak, çalıştırmadan önce yapılması gereken önkoşulları listeleyin. Kısa ve somut tutun: gerekli hesaplar, kurulu araçlar, boş olması gereken portlar ve tek seferlik kurulum adımları.

Ortam değişkenleri: hiçbir şey gizli kalmasın diye dokümante edin

Çoğu “platformda çalışıyordu” dışa aktarımı çöker çünkü ana ayarlar hiçbir zaman yazılı hale getirilmemiştir. Ortam değişkenleri genelde suçludur: repoda yaşamazlar, bu yüzden yeni bir ekip üyesi projeyi klonladığında hangi değerlerin beklendiğini bilmez.

Temiz bir dışa aktarma için her değişken keşfedilebilir, açıklanmış ve tahmin gerektirmeden kolayca ayarlanabilir olmalı.

Handoff README içinde tek bir doğruluk kaynağı oluşturun: env var isimleri, neyi kontrol ettikleri ve değerlerin nereden geldiği. Açıklamaları sade dilde tutun ve güvenlikle ilgili olanları mutlaka belirtin.

Her değişken için basit bir format:

• Name: tam anahtar (kopyala/yapıştır için uygun)
• Meaning: uygulamada neyi değiştirir
• Required?: zorunlu mu yoksa isteğe bağlı mı (eksikse ne olur)
• Example: güvenli örnek değer (gerçek sır asla değil)
• Where it differs: dev vs staging vs production

Bunların yanında repoda bir .env.example gönderin. İçinde gereken her değişkeni güvenli yer tutucularla barındırsın ki uygulama minimal düzenlemeyle başlatılabilsin.

# 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

Birkaç detay çoğu karışıklığı önler:

“Zorunlu mu yoksa isteğe bağlı mı” açıkça belirtin. Eksik bir değişken çökme nedeniysa söyleyin. Bir özelliği etkinleştiriyorsa (e-posta gönderimi, ödemeler, dosya depolama), özelliğin adını ve eksik olduğunda ne olduğunu açıklayın.

Ortamlar arasında neyin değiştiğini belirtin. DATABASE_URL ve PUBLIC_BASE_URL genelde dev, staging ve production arasında farklıyken LOG_LEVEL her yerde aynı olabilir. Koder.ai'den dışa aktardıysanız, platform varsayılanlarının (portlar, base URL'ler, izin verilen originler) dokümanlarda yansıtıldığından emin olun ki platform dışında davranış tutarlı olsun.

Son olarak, env değişkenlerinin yerelde nasıl yüklendiğini belirtin. Proje bir .env dosyası bekliyorsa, nerede olduğunu ve uygulamanın bunu otomatik okuyup okumadığını veya bir komut/araç gerektirip gerektirmediğini söyleyin.

Sırlar: repoda olmasın, ama ayarlaması kolay olsun

Sırlar, sızması durumunda zarar verecek değerlerdir: API anahtarları, veritabanı parolaları, kimlik doğrulama tokenleri, OAuth client secret'ları, özel anahtarlar, webhook imzalama sırları vb.

Dışa aktarım için basit tutun: repoda yalnızca yer tutucular olsun, gerçek gizli değerler asla. Bir sır başlatmak için gerekli ise, .env.example içinde net bir yer tutucu olarak gösterin ve gerçek bir tane nasıl üreteceğini açıklayın.

Pratik bir desen üç şeyi ayırmaktır: örnek dosya, yerel dosya ve CI/dağıtım sır deposu. Dışa aktarılan kod örneği içermeli, yerel dosyayı yok saymalı ve CI/barındırmanın sırları nasıl aldığı dokümante edilmelidir.

Sırlar nerede olmalı

Her ortam için bir yaklaşım seçin ve ona sadık kalın.

• Yerel geliştirme: uygulama tarafından yüklenen .env (gitignored) veya takımınızın yerel sır yöneticisi
• CI: CI sağlayıcısının şifrelenmiş gizli değişkenleri
• Dağıtım/barındırma: barındırma ortamında saklanan ve çalışma zamanında enjekte edilen sırlar

Örnek: repoda PAYMENTS_API_KEY=replace_me olsun. Alıcı kendi sağlayıcı panosunda kendi anahtarını üretir ve yerel .env ile CI'ya koyar. Kod aynı kalır.

Bir rotasyon adımı ekleyin

Devretme sırları özellikle paylaşıldıysa veya platform oturumu sırasında kullanıldıysa rotasyon için iyi bir zamandır.

• Harici servisler için yeni anahtarlar çıkarın ve eski olanları iptal edin.
• Veritabanı parolalarını ve herhangi bir admin tokenini sıfırlayın.
• Önce CI ve barındırma sırlarını güncelleyin, sonra yerel .env dosyalarını güncelleyin.
• Uygulamayı başlattığınızı, testlerin geçtiğini ve eski anahtarların artık çalışmadığını doğrulayın.

Koder.ai'den dışa aktardıysanız, dışa aktarmayı yeni bir ortam gibi değerlendirin ve alıcı ekip için taze sırlar üretin.

Yerel geliştirme kurulumu: ilk çalıştırmayı sıkıcı hale getirin

Devretme başarılıysa yeni bir geliştirici repoyu klonlayıp birkaç komut çalıştırarak uygulamayı sorgusuz sualsiz görebilmelidir. Tahmin edilebilir önkoşullar, net komut sırası ve gerçeklikle eşleşen kısa bir “nasıl çalıştırılır” bloğu hedefleyin.

Önkoşullar (açık olun)

Bunları README'nin en üstüne koyun ki kimse hata mesajlarından çıkarmak zorunda kalmasın:

• OS notları: “macOS ve Ubuntu’da test edildi” (Windows notlarını sadece test ettiyseniz ekleyin)
• Çalışma zamanı sürümleri: Node.js (React için), Go (API için), PostgreSQL (DB için)
• Araçlar: npm/pnpm/yarn, Make (kullanıyorsanız), Docker (sadece dayanak olarak kullanıyorsanız)

Proje Koder.ai üzerinde inşa edildiyse, yerel kurulumu dışa aktardığınızla uyumlu tutun (aynı klasör yapısı, aynı başlatma komutları). “Postgres zaten çalışıyor” varsaymayın, açıkça söyleyin.

Kurulum ve geliştirme komutları (satır başına bir komut)

Yeni bir ekip arkadaşının çalıştırması gereken tam komutları sırayla koyun. Kopyala-yapıştır yapılabilecek şekilde tutun:

# 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

Hemen altında minimal bir test ve build bölümü ekleyin:

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

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

Sorun Giderme: ilk çalıştırmadaki başlıca hatalar

Çoğu “çalışmıyor” problemi birkaç başlığa ayrılır:

1. Yanlış versiyonlar (Node/Go). Belirtiler: bağımlılık veya derleme hataları. Çözüm: sabitlenmiş versiyonları kurup install'ları yeniden çalıştırın.

2. Eksik env değerleri. Belirtiler: “undefined” konfig, kimlik doğrulama hataları, 500 hataları. Çözüm: .env ile .env.example'ı karşılaştırın ve zorunlu değerleri doldurun.

3. Veritabanına ulaşılamıyor. Belirtiler: connection refused, “database does not exist.” Çözüm: Postgres'i başlatın, host/port/kullanıcıyı doğrulayın ve veritabanı başlatma adımlarını tam olarak yazıldığı gibi çalıştırın.

Veritabanı bootstrap: migrationlar, seed'ler ve resetler

Bir proje bir platformdan dışa aktarıldığında veritabanı genellikle yeni bir makinede ilk bozulan şeydir. Amaç basit: bir takım arkadaşı “repoyu klonladım” durumundan “uygulama gerçek verilerle çalışıyor” durumuna tahmin gerektirmeden ulaşabilmeli.

Nelerin dokümante edilmesi gerekir (ve repoda tutulmalı)

Temiz bir PostgreSQL kurulumu için minimum adımları yazın ve komutları mümkünse betiklere koyun. Handoff'unuz dört soruya cevap vermeli:

• Veritabanı ve rol nasıl oluşturulur (isim, izinler ve parola nereden gelir)?
• Migrationlar sıfırdan en son sürüme nasıl uygulanır?
• Demo amaçlı uygulamayı kullanılabilir yapan seed verisi nasıl yüklenir?
• Geliştirme sırasında veritabanı güvenli biçimde nasıl sıfırlanır?

Zaten betikleriniz (Makefile hedefleri, shell betikleri, task runner komutları) varsa, manuel adımları anlatmak yerine onları kullanın. Yoksa şimdi küçük bir set ekleyin.

İşleyen sıkıcı bir bootstrap akışı

Akışı ortamlar genelinde tutarlı tutun (yerel, CI, staging). İyi bir temel şöyle görünür:

# 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

Seed'ler için üretim benzeri dökümanın yerine minimal çalışan veriyi tercih edin. Seed'ler birden fazla çalıştırıldığında güvenli olmalı (idempotent insert'ler veya “yalnızca boş DB'de çalıştır” kuralı).

Reset işlemleri için güvenlik açıkça belirtilmeli. Bir reset komutu varsayılan olarak yalnızca yerel geliştirmeyi hedeflemeli. Yıkıcı bir betik sunuyorsanız bir koruma ekleyin (örneğin CONFIRM_RESET=1 gerektirmek veya APP_ENV=development kontrolü). Ayrıca “reset”in ne anlama geldiğini tanımlayın: drop ve recreate, tabloları temizleme veya bilinen bir snapshot'a geri döndürme.

Repo hijyeni: ne kaynakta olmalı ne olmamalı

Devretme, repo bir eşya kutusu gibi hissettirdiğinde bozulur. Yeni biri neyin önemli olduğunu, neyin üretilmiş olduğunu ve ayarların nereden değiştirileceğini kolayca anlayabilmeli.

Projeyi tekrarlanabilir yapanları commit edin: lockfile'lar, migration dosyaları, küçük konfigürasyon şablonları .env.example ve uygulamayı bootstrap eden betikler.

Kişisel, üretilmiş veya hassas dosyaları kaynak kontrolden uzak tutun: yerel environment dosyaları, editör ayarları, build çıktıları, loglar, cache'ler ve erişim sağlayan herhangi bir dosya (API anahtarları, veritabanı parolaları, servis hesabı dosyaları).

Basit bir kural: değiştirilmesi herkesin işini etkiliyorsa commit edin. Makineye veya ortama göre değişiyorsa, dokümante edin ve repodan çıkarın.

Kısa bir “commit vs ignore” notu ekleyin:

• Commit: README, lockfile'lar, migrationlar, seed betikleri, .env.example
• Ignore: .env, sır dosyaları, build klasörleri, loglar, yerel cache'ler

Klasör haritası ekleyerek yapıyı tıklamadan anlaşılır kılın. Örnek: “/backend API servisi, /web frontend, /mobile uygulama, /db migrationlar ve seed'ler, /scripts kurulum yardımcıları.”

Koder.ai'den dışa aktardıysanız, dışa aktarımı bir temizleme geçişinin başlangıcı olarak değerlendirin: üretilmiş gereksiz dosyaları kaldırın, ignore kurallarını doğrulayın ve dizin haritasını yazın.

CI kurulumu: pipeline'ı tekrarlanabilir kılın

Devretme sessizce başarısız olurken CI neredeyse yerel ile aynı olduğunda. Eğer birisi projeyi laptopunda çalıştırabiliyorsa, CI da aynı komutları çalıştırmalı ve aynı sonucu almalı.

PR başına CI'nın hangi şeyleri kanıtlaması gerektiğine karar verin. Çoğu ekip için küçük bir set yeterlidir:

• Lint/format
• Unit testler
• Build (web ve server derlenebilir olmalı)

Entegrasyon testleri ve dağıtım adımları de uygun olsa kabul edilir; fakat yalnızca güvenilir ve açık şekilde sınırlandırılmışlarsa.

CI adımlarını yerel komutlara yakın tutun ki sürüklenme olmasın. Yerel make test ise CI da da make test çalıştırmalı. Makefile veya benzeri bir task runner yoksa, bir tane eklemeyi düşünün ve bunu ortak giriş noktası yapın.

Env değişkenlerini ve sırları açıkça belirtin

CI genelde gizli konfigürasyona bağlı olduğu için kırılır. README'ye CI'nın beklediği exact isimdeki değişkenleri listeleyen kısa bir “CI değişkenleri” bölümü ekleyin. Açık konfigürasyonu ve sırları ayırın.

Örnek isimler (yığınınıza göre ayarlayın): APP_ENV, DATABASE_URL, PORT, JWT_SECRET, S3_BUCKET, STRIPE_API_KEY. CI'da sırlar her zaman CI sağlayıcısının gizli deposundan gelmeli, commit edilmiş dosyalardan değil. Go + Postgres backend için migrationların otomatik çalışıp çalışmadığını veya açık bir adım gerektirip gerektirmediğini not edin.

Mergeleri durum kontrolleriyle koruyun

Merge öncesi hangi kontrollerin zorunlu olduğunu yazın. Genelde “lint + unit test + build” yeterlidir. Opsiyonel işler (örneğin mobil build'leri) eklediyseniz bunları zorlayıcı yapmayın, gerekli olmadıkça.

Ayrıca CI çıktılarını hata ayıklamayı kolaylaştırın: araç versiyonlarını yazdırın ve net mesajlarla başarısız olun. Pipeline stabil olduktan sonra cache ekleyin.

Örnek bir devretme senaryosu: klondan çalışır duruma

Maya Koder.ai'dan dışa aktarılmış tipik bir proje alır: React web uygulaması, Go API ve PostgreSQL veritabanı. Repoyu klonlayıp tahmin etmeden çalışan ekrana ulaşabilmeli.

İlk 30 dakikası şu şekilde görünmeli:

1. Repoyu klonlayıp root README'yi açar.
2. .env.example'i .env olarak kopyalar (veya aynı değerleri shell'ine koyar) hem web hem api için.
3. PostgreSQL'i başlatır (yerel veya Docker) ve boş bir veritabanı oluşturur.
4. Migrationları ve seed'leri çalıştırarak bilinen bir başlangıç dataset'i alır.
5. Backend'i sonra frontend'i başlatır ve tarayıcıda uygulamayı yükler.

Dağınık bir devretmede genelde üç engelle karşılaşır.

Birincisi: uygulama açılır, sonra muğlak bir “eksik konfig” hatasıyla çöker. Gerçek sorun AUTH_JWT_SECRET veya beklenen DATABASE_URL formatı gibi dokümante edilmemiş bir değişkendir. README her zorunlu değişkeni listeler, güvenli örnek gösterir ve nerede kullanıldığını açıklarsa bu hızlıca çözülür.

İkincisi: API başlar ama her sayfada “veri yok” görünür veya 500 hataları verir. Veritabanı var ama tablolar veya seed verisi yok. Temiz bir devretme bir veya iki güvenilir komut içerir: migrationları çalıştır, minimal demo veriyi seedle ve bir reset komutu ver.

Üçüncü: her şey çalışıyor ama frontend yanlış porta bakıyor. Maya localhost:3000 açar ama API localhost:8080 bekliyordur veya CORS istekleri engelliyordur. Tutarlı varsayılanlar yardımcı olur: WEB_PORT, API_PORT ve API_BASE_URL'i bir yerde ayarlayın ve README yerel beklenen URL'leri belirtin.

Son kontrol listesi, yaygın tuzaklar ve sonraki adımlar

Devretme, başka biri temiz bir klondan projeyi sorunsuz çalıştırabildiğinde bittir. Projeyi platformun dışına taşıdığınızda ayakta kaldığını kanıtlayın.

Temiz bir makinede veya atıl bir konteynerde bir “clean clone” testi yapın. Mevcut klasörünüzü, önbellekleri veya yerel veritabanınızı yeniden kullanmayın. README'yi tam olarak takip edin. Bir kere bile doğaçlama yapmak zorunda kalırsanız, dokümanları veya betikleri düzeltin.

Çoğu hatayı yakalayan hızlı kontroller:

• README'de tek, kopyala-yapıştır yapılabilir bir “yerelde nasıl çalıştırılır” yolu ve kısa bir “nasıl test edilir” bölümü var.
• .env.example mevcut ve her zorunlu değişken güvenli örnek değerlerle açıklanmış.
• Veritabanı bootstrap uçtan uca çalışıyor: DB oluşturma, migration, opsiyonel seed ve reset komutu.
• CI temiz bir runner'da çalışıyor ve yerel komutlarla eşleşiyor.
• Yeni bir geliştirici küçük bir değişiklik yapıp testleri çalıştırabiliyor ve bunun uygulamada görüldüğünü görebiliyor.

Yaygın tuzaklar sıkıcıdır; bu yüzden gözden kaçıyorlar:

• Dokümana girmemiş bir kerelik adımlar
• README'nin eski klasör yapısına veya eski komut isimlerine uyması
• Koda gömülü sert değerler (API URL'leri, feature flag'ler, anahtarlar) yerine konfigürasyon kullanılması gerektiği halde yerinde bırakılması
• Sırlar informal olarak paylaşılmış, temiz bir kurulum yolu yok
• CI sadece cache'lenmiş artefaktlara veya yerel servislerle geçtiği için yalnızca orijinal ortamda geçiyor

Sonraki adımlar: dışa aktarmayı 24–48 saat içinde doğrulayacak bir sahip atayın, haftalar sonra değil. Onlardan temiz klon testini yapmasını ve eksikleri raporlamasını isteyin.

Eğer Koder.ai'da (koder.ai) inşa ediyorsanız, bu kontrol listesini normal iş akışınızın bir parçası gibi ele alın: çalışma planlama modunu kullanarak çalıştırma yolunu yazın, büyük değişikliklerden önce anlık görüntü alın ve dışa aktarma paketini güncel tutmak için düzenli olarak dışa aktarın.