Vibe-coding platformundan kaynak kodunu temizce dışa aktarma

Dışa aktarmadan sonra sahiplenmek ne demektir

Kodu sahiplenmek, platformdan bir zip almaktan daha fazlasıdır. Bu, orijinal çalışma alanına, özel butonlara veya gizli ayarlara ihtiyaç duymadan uygulamayı derleyip çalıştırabildiğiniz, değiştirebildiğiniz ve teslim edebildiğiniz anlamına gelir. Gerçekten sahip olduğunuz bir proje, yeni bir ekip arkadaşının onu klonlayıp dizüstünde çalıştırmaya başlayabileceği ve standart bir boru hattı üzerinden dağıtabileceği normal bir repo gibi davranır.

Çoğu kilitlenme endişesi aynı birkaç eksikten kaynaklanır:

• Sadece platform UI’sında var olan konfigürasyon
• "Başka bir yerde" gerçekleşen derleme adımları
• Varsayılan ama yazılı olmayan bağımlılıklar

Diğer yaygın sürpriz, uygulamanın barındırılan sürümde sorunsuz çalışıp yerelde başarısız olmasıdır; bunun nedeni ortam değişkenleri, veritabanı kurulumu veya gizli bilgilerin açıkça belirtilmemiş olmasıdır.

Bir vibe-coding platformundan temiz bir dışa aktarma dört sonuca yol açmalıdır:

• Dışa aktarılan uygulamayı öngörülebilir adımlarla yerelde çalıştırabilirsiniz.
• Kendi repodan CI kullanarak dağıtabilirsiniz; manuel tıklamalara gerek yok.
• Gizli bilgiler güvenli şekilde yönetilir (Git’te anahtar yok, tahmin yok).
• Repo devreye hazırdır; yeni bir kişi hızla onboard olabilir ve gördüklerine güvenebilir.

Bu, platformu terk etmeyi hiç planlamasanız bile önemlidir. Sağlam bir sahiplik duruşu riskleri azaltır, denetimleri kolaylaştırır ve ajans kiralama, yatırım alma veya ekip değiştirme durumlarında pazarlıkları basitleştirir.

Eğer Koder.ai kullandıysanız, dışa aktarma genellikle React web uygulaması, Go backend, PostgreSQL veya bir Flutter mobil uygulaması gibi yaygın yığınları içerebilir. Yığın, ilkenin kendisinden daha az önemlidir: çalıştırmak için gereken her şey depo içinde görünür olmalıdır, barındırılan ortamda saklı olmamalıdır.

Bir kurucunun bir uygulamayı bir yükleniciye verdiğini hayal edin. "İşte repo" demek yeterli olmalıdır. Yüklenicinin API base URL’sini bulmak, veritabanı şemasını oluşturmak veya ön yüzü nasıl derleyeceğini öğrenmek için orijinal platform projesine erişmesi gerekmemelidir.

Dışa aktarılan projede neler beklemelisiniz

Dışa aktarmadan sonra, bir editörde açabileceğiniz, dizüstünde çalıştırabileceğiniz ve orijinal platforma ihtiyaç duymadan başka bir ekibe teslim edebileceğiniz normal bir repository olmalıdır.

Koder.ai projelerinde dışa aktarmalar genellikle tanıdık yapılara denk gelir: bir React web uygulaması, bir Go backend ve (varsa) bir Flutter mobil uygulaması. Klasör adları değişebilir, ancak repo her parçanın nerede olduğunu ve nasıl bağlandığını açıkça göstermelidir.

Proje biçimi: klasörler, giriş noktaları ve hangi parçanın neyi çalıştırdığı

Öncelikle giriş noktalarını ve amaçlanan iş akışını bulun. Her uygulamayı başlatan ilk dosyayı ve geliştirme/çalıştırma için kullanılacak scriptleri görmek istersiniz.

Tipik işaretler:

• Web: bir package.json ve src/ klasörü (genellikle main.tsx veya benzeri)
• Backend: go.mod ve bir cmd/ klasörü veya main.go
• Mobil: Flutter için pubspec.yaml ve lib/main.dart
• Her şeyi nasıl çalıştıracağınızı anlatan üst seviye bir README veya Makefile
• Birden fazla servis olarak çalışacaksa docker-compose.yml

Bağımlılıklar, konfigürasyon ve veritabanı parçaları

Bağımlılıklar sabitlenmiş olmalıdır. JavaScript için bu bir lockfile demektir (package-lock.json, yarn.lock veya pnpm-lock.yaml). Go için go.mod ve go.sum bulunmalıdır. Eksik pinler projeyi çalıştırılamaz yapmaz ama tekrarlanabilir derlemeleri zorlaştırır.

Konfigürasyon koddan ayrı olmalıdır. .env.example veya config.example.yaml gibi örnekler arayın. Gerçek sırların (API anahtarları, prod şifreleri) dışa aktarmada commitlenmiş olmaması gerekir. Eğer görürseniz, bunu bir sızıntı olarak ele alıp hemen döndürün.

Veritabanı işleri için migrations/ veya db/migrations/ gibi bir klasör veya zaman damgalı SQL dosyaları bulun. Go + PostgreSQL uygulamalarında küçük bir migration runner veya göçleri uygulayan bir script de olabilir.

Hızlı bir sağlık kontrolü: önce build ve çalıştırma komutlarını (npm run dev, go run, make ve benzeri) bulun. Bir script platforma özgü bir komuta bağlıysa, repo bağımsız hale gelmeden önce bunu standart araçlarla değiştirin.

Adım adım: dışa aktar, commitle ve yerelde çalıştır

Dışa aktarmayı bir release artefakti gibi ele alın. Hiçbir şeyi çalıştırmadan önce "her şey burada mı?" diye hızlıca kontrol edin. Eksik parçalar değişiklik yapmadan önce yakalanması daha kolaydır.

Pratik bir tamlık kontrolü, her parçanın "köklerini" aramaktır: React için package.json, Go backend için go.mod ve PostgreSQL için göç/seed dosyaları.

Temiz bir ilk commit (geçmiş okunabilir başlasın diye)

Dışa aktarılan klasörden yeni bir Git repository oluşturun ve aldığınız her şeyi önce olduğu gibi commitleyin. Bu size temiz bir başlangıç verir ve sonraki değişiklikleri incelemeyi kolaylaştırır.

git init
# Optional: set default branch name
# git branch -M main

git add -A
git commit -m "Initial export"

Şimdi yerelde küçük, doğrulanabilir adımlarla çalıştırın. Bağımlılıkları kurun, yerel konfigürasyonu oluşturun, önce veritabanını sonra backend’i sonra frontend’i başlatın. Her kullandığınız komutu not alın. Bu notlar README’iniz olur.

Aşağıda dışa aktarılan yapınıza uyarlayabileceğiniz basit bir komut dizisi var:

# Frontend
cd web
npm install
npm run dev

# Backend
cd ../server
go mod download
go run ./cmd/server

Veritabanının gerçekten çalıştığını doğrulayın (sadece "sunucu başladı" yeterli değil)

Bir sunucu ayağa kalkmış olabilir ancak uygulama yine de bozuk olabilir. Okuma ve yazma yapabildiğini doğrulayın.

Ürüne uygun hızlı kontroller seçin:

• Veriye bağlı bir sayfayı açın (liste, profil, gösterge paneli).
• Bir kayıt oluşturun (kayıt olma, öğe oluşturma, not ekleme), yenileyin ve kalıcı olduğunu doğrulayın.
• UI destekliyorsa bir güncelleme ve bir silme işlemi tetikleyin.
• Göç hataları veya "relation does not exist" gibi hatalar için logları izleyin.

Yerelde çalışan bir sürümünüz olduğunda, karalama notlarınızı gerçek bir README.mdye dönüştürün: hangi dizinden komut çalıştırılacağı, servislerin hangi sırayla başlatılacağı ve hangi ortam değişkenlerinin gerektiği gibi kopyala-yapıştır adımlar olsun.

Dışa aktarmayı devreye hazır bir repoya dönüştürün

Bir dışa aktarma çalışıyor olabilir ama hâlâ "üretilmiş" hissi verebilir. Devreye hazır bir repo, şeylerin nerede olduğunu, nasıl çalıştırılacağını ve tutarlılığın nasıl korunacağını açıkça gösterir.

Başlangıç olarak üst seviye bir düzen belirleyin. İsimler tutarlılık kadar önemli değildir.

• apps/ kullanıcıya yönelik ön yüzler (web, mobil)
• services/ backend API’ler, worker’lar ve işler
• shared/ paylaşılan tipler ve yardımcılar
• infra/ dağıtım şablonları, scriptler ve ortam örnekleri
• docs/ mimari notlar ve işletme el kitapları

Sonra belirsizliği azaltan birkaç dosya ekleyin:

• Gereksinimler ve kesin komutlarla README.md
• Birkaç kural içeren CONTRIBUTING.md (branchler, PR’lar, gizli bilgi yok)
• Yerel env dosyalarını ve build çıktılarını Git’ten uzak tutacak .gitignore

README’i pratik tutun. Repo birden fazla parçayı içeriyorsa (React frontend, Go API, PostgreSQL) başlatma sırasını ve konfigürasyonun nerede olduğunu net biçimde yazın (ör. ".env.example’ı .env olarak kopyalayın").

Temiz bir makine testi yapın: yeni bir klasöre klonlayın ve README’inizi takip edin. Koder.ai’dan dışa aktardıysanız, dışa aktarmayı yeni bağımsız projenin ilk commit’i olarak değerlendirin ve sonra başkalarını davet edin.

Yeni gelenlerin takip edebileceği yerel geliştirme kurulumu

İyi bir yerel kurulum soruyu hızlıca yanıtlar: yeni bir kişi uygulamayı 15 dakika içinde tahmin yapmadan çalıştırabilir mi?

Varsayılan bir yerel yaklaşım seçin ve açık olun. Yerel kurulumlar araçları hazır olanlar için hızlıdır. Container’lar makineler arası tutarlıdır ama ek yük getirir. Her iki yaklaşımı da destekliyorsanız birini varsayılan, diğerini opsiyonel olarak etiketleyin.

Çalışan bir desen: tek sayfalık README, tek örnek env dosyası ve tek bir bootstrap komutu.

Minimal, güvenli bir env kurulumu

Sahte değerler içeren bir örnek dosyayı commitleyin ki insanlar hangi değerleri ayarlamaları gerektiğini görsün, gerçek sırlar sızmasın.

# .env.example (örnek değerler)
APP_ENV=local
PORT=8080
DATABASE_URL=postgres://app_user:app_pass@localhost:5432/app_db?sslmode=disable
JWT_SECRET=change-me
API_BASE_URL=http://localhost:8080

README’de gerçek dosyanın nerede tutulduğunu (ör. ".env.example’ı .env olarak kopyalayın") ve hangi değişkenlerin zorunlu/opsiyonel olduğunu açıklayın.

Bir komut ile başlatma

Sıkıcı adımları doğru sırayla çalıştıran küçük bir script ekleyin. Okunabilir tutun.

#!/usr/bin/env bash
set -euo pipefail

cp -n .env.example .env || true

# Backend deps
cd backend
go mod download

# Database: create, migrate, seed
./scripts/db_create.sh
./scripts/db_migrate.sh
./scripts/db_seed.sh

# Frontend deps
cd ../web
npm install

Veritabanı planı için üç şeyi belgeleyin: veritabanını nasıl oluşturacağınız, göçlerin nasıl çalıştırıldığı ve gerçekçi bir ilk çalıştırma için seed verisinin nasıl elde edileceği.

Son olarak, insanların uygulamanın çalıştığını tıklamadan önce doğrulayabilmesi için hızlı bir health check ekleyin. GET /health gibi küçük bir endpoint "ok" döndürmeli ve veritabanı bağlantısını doğrulamalıdır.

Gizli bilgileri sızdırmadan yönetmek

Projeyi dışa aktardığınızda kod sizin olabilir ama sırlar gizli kalmalı. Repoyu yeni ekip arkadaşlarıyla paylaşılacağını varsayın.

İlk olarak uygulamanın neye ihtiyacı olduğunu listeleyin. Tahmin etmeyin. Kodu ortam değişkeni okumaları veya konfigürasyon dosyaları için tarayın ve etkinleştirdiğiniz entegrasyonları kontrol edin.

Temel bir gizli bilgi envanteri genelde şunları içerir: veritabanı kimlik bilgileri, üçüncü taraf API anahtarları, kimlik doğrulama ayarları (OAuth veya JWT), depolama kimlik bilgileri ve uygulamaya özel sırlar (şifreleme anahtarları veya webhook imza anahtarları).

Her sırın hangi ortamda nerede saklanacağını kararlaştırın. İyi bir varsayılan kural:

• Lokal: geliştiriciye ait .env (commitlenmez)
• CI: CI sağlayıcısının gizli deposu
• Prodüksiyon: özel bir secret manager veya barındırma ortam değişkenleri

Eğer vibe-coding platformu gibi bir araçtan dışa aktardıysanız (örneğin Koder.ai), sohbetlerde, loglarda veya ayarlar panellerinde görünen her şeyin kopyalanmış olabileceğini varsayın. Sırları derhal repodan çıkarın.

Pratik yaklaşım: güvenli bir şablon commitleyin (.env.example), gerçek değerleri Git’e koymayın (.env’yi .gitignorea ekleyin) ve prodüksiyon sırlarını dağıtım zamanında enjekte edin.

Eğer dışa aktarma sırasında sırların açığa çıktığına dair en ufak şüphe varsa, döndürün. Öncelik veritabanı parolaları, OAuth client sırları ve webhook imza anahtarları olmalı.

Tekrar yaşanmaması için birkaç koruyucu önlem ekleyin: açık gizli desenleri için bir pre-commit kontrolü, CI’da gizli tarama, eksik zorunlu değişkenlerde hızla hata veren sıkı konfigürasyon yükleme ve her ortam için ayrı kimlik bilgileri.

Kısa bir SECRETS.md devretmelerde yardımcı olur. Basit tutun: gerekli değişkenler, her ortam için nerede saklandıkları ve kimlerin döndürebileceği.

Repo sağlığını koruyacak CI kurulumu

Sahipliği aldıktan sonra CI sizin güvenlik ağınız olur. İlk sürümü küçük tutun. Her push, projenin hâlâ derlenebildiğini, temel kontrollerin geçtiğini ve testlerin (varsa) çalıştığını göstermeli.

CI hızlıca şu soruyu yanıtlamalı: "Bu değişiklik merge edilmeye güvenli mi?" Çoğu repo için bu, bağımlılıkları yükleme, derleme, lint ve birim testlerini çalıştırma demektir.

İşleri uygulama parçalarına göre ayırın ki başarısızlıklar belirgin olsun:

• Web: install, lint/typecheck, build, testleri çalıştır
• Backend: build, birim testleri, linter/format kontrolleri
• Opsiyonel mobil (Flutter): analyze, test, build
• Opsiyonel veritabanı kontrolü: göçleri geçici bir ortamda uygulama

Önbellekleme kullanın ama cache’in sorunları gizlemesine izin vermeyin. Cache kaçırıldığında CI hâlâ çalışmalı, sadece daha yavaş olmalıdır.

Her adım için tek bir komut (make test, npm run test vb.) tercih edin ki aynı komut hem yerelde hem de CI’da çalışsın. Bu kafa karışıklığını azaltır ve logları kısaltır.

Örnek yapı (repo’ya göre isimleri ayarlayın):

jobs:
  web:
    steps:
      - run: npm ci
      - run: npm run lint
      - run: npm run build
  api:
    steps:
      - run: go test ./...
      - run: go build ./...

Temeller stabil hale geldikten sonra basit bir release akışı ekleyin: sürümleri tag’leyin, artefaktlar oluşturun ve bunları CI artefaktı olarak saklayın. Bugün hâlâ bir platformdan dağıtıyor olsanız bile, tekrarlanabilir artefaktlar barındırmayı kolaylaştırır.

Yaygın hatalar ve nasıl kaçınılır

Kod dışa aktarılması işin yarısıdır. Diğer yarısı projenin platform dışında aynı şekilde davranmasını sağlamaktır.

Hata 1: Hiç kurulum beklememek

Dışa aktarmalar genellikle ortam değişkenleri, göçler, seed verisi ve sizin için halledilen derleme adımlarına bağımlıdır. İlk çalıştırmada boş ekran veya veritabanı hatası normaldir.

Değişiklik yapmadan önce bir temel çalıştırma yapın: bağımlılıkları kurun, ortam değişkenlerini ayarlayın, göçleri çalıştırın, servisleri sırayla başlatın. Sorunu sadece dışa aktarma ile mi yoksa yaptığınız değişikliklerle mi yarattığınızı anlamak için önce çalışır hale getirin.

Hata 2: Gizli bilgileri Git’e sızdırmak

En yaygın kaza, kopyalanmış bir .env dosyası veya araç tarafından üretilmiş bir konfigürasyon nedeniyle gerçek API anahtarları veya parolaların commitlenmesidir.

Sadece şablon commitleyin. Gerçek değerleri yerelde veya gizli depoda saklayın.

Hata 3: Çok erken bağımlılıkları değiştirmek

Paketleri güncellemek veya klasörleri yeniden düzenlemek hemen sorunları ayırt etmeyi zorlaştırır: problem dışa aktarmadan mı yoksa değişikliklerinizden mi kaynaklanıyor?

Önce çalışan bir sürüm elde edin, sonra ayrı küçük commit’lerle iyileştirin.

Hata 4: Versiyonları pinlememek

"Benim makinemde çalışıyor" genellikle pinlenmemiş araç versiyonlarından (Node, Go, Flutter, hatta paket yöneticileri) gelir.

Çalışma zamanı versiyonlarını net bir yerde pinleyin (bir dosya veya README), lockfile’ları (package-lock, go.sum, pubspec.lock) saklayın ve kurulumu ikinci bir makinada veya temiz bir container’da doğrulayın.

Hata 5: Dokümantasyonu atlayıp sonra ödemek

Devretmeler, uygulamayı başlatmak için gereken o tuhaf adım hatırlanmadığında başarısız olur. Taze iken yazın: gerekli ortam değişkenleri, göçleri nasıl çalıştıracağınız, logların nerede olduğu ve lokal durumu nasıl sıfırlayacağınız.

Gerçekçi bir örnek: platform projesinden bağımsız repoya

Üç kişilik bir ekip Koder.ai’da bir müşteri portalı inşa etti: React web, Go API ve PostgreSQL. Dışa aktarımı dış geliştirici ekibine teslim ederken, export’un bir kişi tarafından birinci günde çalıştırılabilecek normal bir repo gibi hissettirmesini istiyorlar.

Gün 1: dışa aktarıp temiz bir Git repo oluşturuyorlar ve yerelde çalıştırıyorlar. Frontend başlıyor ama API eksik ortam değişkenleri yüzünden başarısız oluyor. Tahmin etmiyorlar; kodu okuyup kullanılan anahtarları belirliyor ve yer tutucularla bir .env.example oluşturuyorlar. Gerçek değerler parola yöneticisinde ve yerel .envlerde kalıyor.

Ayrıca platformda düzgün çalışan portlar ve CORS ayarlarının yerelde varsayılanlara ihtiyaç duyduğunu fark ediyorlar. Yeni makinelerin aynı davranması için öngörülebilir varsayılanlar koyuyorlar (ör. API 8080, web 3000).

Gün 2: göçler ve demo kullanıcı ile birkaç satır ekleyen küçük bir seed script’i ekliyorlar. Sonra gereksinimler, çalıştırma komutları ve çalışanlığı doğrulamak için kısa bir README yazıyorlar (API için health endpoint ve UI için örnek bir giriş).

Gün 3: her pull request’te iki hizmet için test, lint ve build çalıştıran temel bir CI akışı ekliyorlar. Staging için basit bir plan belgeliyorlar: konteynerleri build et, ortam değişkenlerini ayarla, deploy sırasında göçleri çalıştır ve geri alma seçeneğini tut.

İyi bir devretme genelde şu öğeleri içerir: taze klonla yerelde çalışabilen repo, .env.example ve sırların nerede tutulduğuna dair notlar, göçler ve seed verisi, hızlıca başarısız olan CI kontrolleri ve staging/geri alma için kısa bir dağıtım notu.

Hızlı kontroller ve sonraki adımlar

Dışa aktarmayı tamam ilan etmeden önce projeyi platform dışında yaşayabildiğini kanıtlayın. Başka bir geliştirici tahmin yapmadan çalıştırabiliyorsa, iş büyük oranda tamamlanmıştır.

Son kontrol listesi:

• Repo okunabilir: açık README, mantıklı klasör adları ve uygulamayı başlatmanın tek bir yolu.
• Temiz bir klonla yerelde çalışma: clone, install, configure, run ve uygulamayı görme adımları tahmin gerektirmiyor.
• Testler çalışıyor (bile bir smoke testi veya health check bile hiç yoktan iyidir).
• CI her push’ta çalışıyor: lint, test ve hızlıca başarısız olan bir build.
• Sırlar ayrılmış: repoda anahtar yok ve örnek konfigürasyon gerekli değişkenleri gösteriyor.
• Dokümantasyon temel konuları kapsıyor: nasıl çalıştırılır, nasıl deploy edilir ve sık değişen ayarlar nerede değiştirilir.

Teknik kontrol sonrası sahipliği açıkça belirleyin. Bağımlılık güncellemelerinden, altyapı değişikliklerinden (veritabanları, queue’lar, DNS) ve sürümlerden kim sorumlu olacak karar verin. Sahibi olmayan işler zamanla bozulur, uygulama bugün çalışıyor olsa bile.

Büyük özellik işlerine başlamadan önce kısa bir stabilize dönemi planlayın. İki ila beş çalışma günü genellikle dışa aktarma kusurlarını gidermek, README’yi sıkılaştırmak ve "benim makinemde çalışıyor" sorunlarını çözmek için yeterlidir.

Eğer Koder.ai (koder.ai) kullanıyorsanız, dışa aktarmalar ve snapshot/geri alma gibi özellikler repo’yu sertleştirirken yinelemeyi kolaylaştırır. Repo stabil olduğunda Git’i gerçek kaynak olarak tutun ve gelecekteki dışa aktarmaları ana geçmiş yerine kontrol noktası olarak değerlendirin.

Son handoff hedefini açık bir dilde tanımlayın: "Her geliştirici 30 dakika içinde çalıştırabilir." Sonra bunu yeni bir kişiye temiz bir makinada README’yi takip ederek test ettirin. Onların soruları sizin son yapılacaklar listeniz olur.