Claude Code greenfield çalışma akışı: boş repodan ilk dilime

Greenfield başlangıcında kaçınmak istediğiniz şeyler

Boş bir repodan başlamak özgürlük gibi hissettirir, ama genellikle karışık bir ivmeye dönüşür: çok sayıda üretilmiş dosya, yarım çalışan bir build ve bir sonraki değişikliğin nereye koyulacağı belirsizdir. Claude Code greenfield çalışma akışının amacı bu ilk hafta kaosundan kaçınmaktır.

Birkaç hata tekrar tekrar görünür:

• Kurulum birinin hafızasında yaşadığı için "makinemde çalışıyor" olan kod.
• Uygulamanın nasıl büyümesi gerektiğini değil, dosyaların hangi sırayla oluşturulduğunu yansıtan bir klasör ağacı.
• Her yeni istemin önceki seçimleri yeniden yazdığı bir döngü, böylece hiçbir şey kararlı hale gelmez.

Erken kararları geri almak acı vericidir çünkü her şey onların üzerine inşa edilir. Kafa karıştırıcı bir yapı sürekli pekişir. Manuel bir build on farklı ayara dönüşür. Basit bir dev komutunu erken kilitlemezseniz, bir değişikliğin uygulamayı mı yoksa sadece ortamı mı bozduğunu anlayamazsınız.

Bu yazıda "çalışan uygulama" dediğimizde özel bir şeyi kastediyoruz: projeyi başlatan, tahmin edilebilir çıktı veren ve bir şey eksikse yüksek sesle hata veren tek bir komut. Yerel kurulumunuzu silebilmeli, repoyu klonlayabilmeli, o komutu çalıştırmalı ve aynı sonucu görmelisiniz.

Bir "dikey dilim", uygulamanızın gerçek olduğunu kanıtlayan en küçük uçtan uca özelliktir. Bir UI mock'ı değil. Tek başına bir veritabanı tablosu değil. Form içeren bir sayfa, veri kaydeden ve okuyan tek bir API uç noktası ve sayfada görünen bir sonuç gibi sistemin tamamına ince bir çizgi çeker.

Tek komutla uygulamayı çalıştırabiliyor ve bir dikey dilimi gönderebiliyorsanız, tahmin yürütmeden yineleyebileceğiniz bir tabana sahipsiniz.

Herhangi bir şey üretmeden önce ilk dilimi belirleyin

Net bir ilk dilim repoyu düzenli tutar ve istemleri odaklı kılar. Bu, uçtan uca demo etmek istediğiniz şeyi — tam ürünün ne olacağını umduğunuz şeyi değil — kararlaştırma anıdır.

Uygulamanın tüm yol boyunca çalıştığını kanıtlayan en küçük kullanıcı hikayesini seçin. İyi bir dilim UI, veri ve tek bir gerçek etkileşimi kapsar. Örnek: “Bir kullanıcı görev ekleyebilir ve yeniledikten sonra listede görünmesini görebilir.” Küçüktür ama yönlendirme, doğrulama, depolama ve temel bir ekran zorunluluğu getirir.

1. hafta için bir hedef platform seçin ve ona bağlı kalın. Web ile başlıyorsanız sadece web yapın. "İhtimal olsun diye" mobil ekranlar eklemeyin. Koder.ai gibi bir platformu daha sonra kullanmayı planlıyorsanız bile, ilk dilim tek bir hatta kaldığında daha iyi sonuçlar alırsınız (React web, veya bir Go API'si, ya da Flutter).

"1. hafta için tamamlandı"nın ne anlama geldiğini açıkça tanımlayın:

• Taze bir klondan tek bir komutla yerelde çalışır
• Uçtan uca tıklanabilir bir çalışan özellik
• Hatalar insan okunur mesaj gösterir (stack trace değil)
• Veriler basit bir yerde kalıcı olur (hatta yerel bir veritabanı bile olabilir)

Sonra kapsamı koruyan üç non-goal (yapılmayacaklar) yazın. Örneğin: kimlik doğrulama yok, tema sistemi yok, arka plan işleri yok.

Bu kararlar yazıya döküldüğünde, üretim isteminiz katı olabilir: sadece dilimi destekleyen şeyi oluştur, geri kalan her şeyi TODO olarak bırak.

Tekrar iş yapmayı önleyen birkaç ön karar

Claude'dan bir şey üretmesini istemeden önce birkaç varsayılanı kilitleyin. Küçük görünseler de, "sonra her şeyi yeniden adlandırma" karışıklığını önlerler.

Önce uygulamanın şeklini belirleyin. Gerçekten bir tarayıcı UI'sı ve bir backend gerekiyorsa, iki net parçayla başlayın (frontend + API) ve sözleşmeler için paylaşılan bir yer (API tipleri veya basit bir şema). Uygulama tek sunucu render'lı olabiliyorsa, yerel geliştirme basit kalsın diye tek bir kod tabanı tutun.

Sonra yapılandırma kurallarında anlaşın. Yerelde bir env dosyası kullanın, bunu git'e dahil etmeyin ve bir şablon (.env.example gibi) commit edin; güvenli yer tutucular ve kısa yorumlar olsun. Bu onboarding'i kolaylaştırır ve gizli bilgilerin sızmasını azaltır.

Varsayılan geliştirme portlarını seçin ve sabit tutun. Portlar scriptlerde, dokümantasyonda ve hata mesajlarında yer alır, sonra değiştirmek can sıkıcı olur. Aynı şeyi adlandırma için yapın: klasörler, servisler ve paketler tek bir konvansiyon izlesin. Mükemmel konvansiyondan çok tutarlılık önemlidir.

Basit bir başlangıç kararı seti:

• Uygulama şekli: tek uygulama veya frontend + API
• Konfig: yerelde .env, commit edilmiş .env.example
• Portlar: web için bir, API için bir, veritabanı için bir (gerekliyse)
• İsimler: klasörler için tek bir yazım stili, tutarlı servis isimleri
• Gizli bilgiler: asla commit edilmez, açığa çıkarsa döndürülür

Örnek: web için port 3000 ve api için 8080 seçtiniz. Env şablonunuz API_URL=http://localhost:8080 ve DATABASE_URL=... içerir. Claude daha sonra scriptler ve doküman üretirken her şey yerli yerine oturur, sürüklenmez.

Claude Code'a nasıl istem verirsiniz ki yapısı bozulmasın

Bir çalıştırılabilir iskelet isteyerek başlayın, "tüm uygulama" diyerek değil. Özellikleri, koyacak yeriniz olmadan istemek çıktıyı hızla karıştırır.

Yapı hakkında açık olun. Hangi dosyanın nereye ait olduğunu ve nereye ait olmadığını kısa yorumlarla açıklayan bir klasör düzeni isteyin. Bu, kararları başta zorunlu kılar ve dosyaların rastgele dağılmasını engeller.

Onu disiplinli tutmanın basit bir yolu, isteme kurallar koymaktır:

• En küçük çalıştırılabilir iskeleti önce üret (hello sayfası, health endpoint veya tek ekran).
• Bir klasör yapısı öner ve her klasörün ne işe yaradığını 1 cümleyle açıkla.
• Taze bir makinede çalışacak scriptler ekle (install, dev, test, build) ve önkoşulları belirt.
• Değişiklikleri tek bir PR boyutunda tut ve hangi dosyaların oluşturulacağını/editleceğini tam listele.
• İskeleti ürettikten sonra dur ve "çalıştırdım" onayımı bekle.

İşte yeniden kullanabileceğiniz ve uyarlayabileceğiniz bir istem:

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

Sonra döngüyü dar tutun. Bir kerede beş değişiklik istemeyin. Bir küçük değişiklik üretin, çalıştırın, tam hatayı (veya başarıyı) yapıştırın, sonra minimal bir düzeltme isteyin. Bu üret-çalıştır-düzelt ritmi projeyi öngörülebilir kılar ve yapının sapmasını zorlaştırır.

Adım adım: boş repodan çalıştırılabilir iskelete

Bir sözle başlayın: herkes repoyu klonlayıp tek bir komutla bir şey çalıştırabilmeli. Bu, AI'dan gerçek özellik eklemesini istemeden önce size kararlı bir temel verir.

Repoyu oluşturun ve her şey taze iken küçük bir README yazın. Prereqs, tek dev komutu ve testleri nasıl çalıştıracağınız (testler şimdi boş olsa bile) pratik olsun.

Sonra seçtiğiniz uygulama şekline uyan üst seviye düzeni belirleyin.

Birden fazla dağıtılabilir parça oluşturuyorsanız (ör. frontend + API), bir workspace düzeni yardımcı olabilir:

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

Tek bir uygulama inşa ediyorsanız, daha basit tutun ve ihtiyaç olana kadar ekstra seviyelerden kaçının.

Şimdi kodun tutarlı kalması için minimum koruyucuları ekleyin. Bir formatter ve bir linter seçin, varsayılanlarını kabul edin ve her biri için tek bir konfigürasyon dosyası ekleyin. Amaç güncel diffların temiz olması, birinci günde mükemmel kurallar değil.

Geliştirici deneyimini repo kökünden her zaman çalışan tek bir komutla öngörülebilir kılın. Basit bir şekil:

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

Başka bir şey üretmeden önce o dev komutunu çalıştırın, temiz çıktıyla çıktığını (veya bir placeholder sunucuyu başlattığını) doğrulayın, sonra yalnızca iskelet içeren ilk commitinizi yapın. Bir ekip üyesi (veya gelecekteki siz) kurulumu sıfırdan yeniden üretebiliyorsa, ilk dilimi inşa etmeye hazırsınız.

Uygulama büyüdükçe koruyabileceğiniz bir klasör yapısı

İyi bir greenfield yapısı iki şey yapar: kodu hızlı bulmanıza yardımcı olur ve Claude'a her istekte yeni desenler icat etmesi için fazla alan vermez. Amaç mükemmellik değil; kararlılıktır.

Tek uygulama içinde çalışıyorsanız (veya apps/<name>/ klasöründe), basit bir iç düzen genellikle iyi dayanır:

• src/ uygulama kodu (özellikler, paylaşılan parçalar, giriş noktaları)
• config/ gizli olmayan konfigürasyon
• tests/ kullanıcı davranışı gibi okunan üst düzey testler
• scripts/ yardımcı scriptler (dev kurulum, db sıfırlama, release görevleri)
• docs/ kısa notlar ve gerçekten tuttuğunuz kontrol listeleri

src/ içinde, özellik kodunu ve paylaşılan kodu değişim desenlerine göre ayırın. Özellik kodu sık değişir ve yakın tutulmalı. Paylaşılan kod sıkıcı ve yeniden kullanılabilir olmalı.

Pratik bir kural: UI ekranlarını, handler'ları ve özellik-özel mantığı src/features/<featureName>/... altında tutun. Logging, API client'ları, design system bileşenleri ve genel yardımcılar gibi şeyleri src/shared/... altında tutun. Bir yardımcı sadece bir özellik için anlamlıysa, görünüşte yeniden kullanılabilir olsa bile o özellikte tutun. İkinci gerçek kullanım olduğunda taşıyın.

Klasör isimleri amacı tanımlamalı, teknolojiyi değil. “features” ve “shared” yığın değiştikçe bile anlamlı kalır. "misc" veya "new" gibi isimlerden kaçının.

docs/'u küçük tutun. İyi bir başlangıç docs/checklists.md içerir: nasıl çalıştırılır, nasıl test edilir, yeni bir özellik klasörü nasıl eklenir ve "tamamlandı" ne demektir.

Projeyi öngörülebilir kılan build scriptleri

Bir repo gerçek hissettirir khi herkes aynı komutları çalıştırıp aynı sonucu alabilir. Scriptler koruyuculardır: tahmin yürütmeyi azaltır, değişiklikleri küçük tutar ve bir şey kırıldığında bunun açık olmasını sağlar.

Küçük bir komut seti ile başlayın ve sıkıcı tutun. Yeni birisi (veya iki hafta sonra siz) gizli bayraklara veya gizli adımlara ihtiyaç duymamalı.

Herhangi bir yığına uyarlanabilir basit bir temel:

{
  "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"
  }
}

Dev scriptini mutlu yol yapın. Uygulamayı başlatmalı, nerede çalıştığını yazmalı ve logları okunabilir tutmalı. Sunucu başlatılamazsa eksik env var, port meşgul veya veritabanı ulaşılamıyor gibi tek bir net mesajla hızlıca başarısız olsun.

Build scripti her zaman temiz bir çıktı dizini oluşturmalı. Önce eski çıktıyı silin, sonra yeni artefaktları üretin. Bu, dünkü dosyalardan kaynaklanan garip hataları önler.

Testler için hızlı kontrolleri yavaş kontrollerden ayırın. Hızlı testler her değişiklikte çalışsın (unit testler, tip kontrolleri). Tam testler entegrasyon kontrollerini içerir ve merge öncesi çalıştırılır.

Stili tek bir komutla tutun. Basit bir kural: format düzeltir, lint şikayet eder.

Son olarak, zaman kaybetmeden önce temel doğrulayan bir smoke check ekleyin:

• Gerekli env değişkenleri ayarlı ve boş değil
• Seçilen portlar boş
• Uygulama başlatılıp basit bir isteğe yanıt verebiliyor
• Veritabanı bağlantısı çalışıyor (kullanılıyorsa)
• build sonrası çıktı mevcut

İlk dikey dilim özelliğini inşa etme

İlk dikey diliminiz uçtan uca uygulamanın çalıştığını kanıtlamalı, sadece UI'nın güzel göründüğünü değil. Yani ekranı, mantığı ve bir tür depolamayı (geçici olsa bile) dokunan küçük bir özellik seçin.

Sıkıcı ama faydalı bir şey seçin: “Not ekle” veya “Görev oluştur” gibi. Tek oturumda bitirebilecek kadar küçük, ama üzerine tıklayıp gerçek durum değişimini görebilecek kadar tamam olmalı.

İyi bir dilim dört parçaya sahiptir: bir rota veya ekran, bir form, bir kaydetme aksiyonu ve bir gösterim. Örnek: başlık girdisi olan bir "Yeni Görev" sayfası, Save düğmesi tek bir fonksiyonu çağırır ve kaydedilen görevleri gösteren bir liste.

Hızlı ilerlemek için placeholder bir store ile başlayın. Bellek içi bir dizi, yerel bir JSON dosyası veya basit bir stub arayüz uygundur. Önemli olan, daha sonra değiştirebileceğiniz bir sınır oluşturmak. Bugün kodunuz taskRepository.save(task) çağırıyorsa, gerçek bir veritabanına geçiş küçük bir değişiklik olur, yeniden yazma değil.

UI'ı sade tutun. Tasarım sistemi tartışmalarını, boş durumları ve animasyonları atlayın.

İki dakika içinde yapabileceğiniz kabul kriterleri:

• Sayfa hatasız açılır
• Bir değer yazıp Kaydet'e basabilirsiniz
• Yeni öğe hemen görünür
• Yeniden yükleme beklenen davranışı gösterir (gerçek depolamada kalıcı, sahte depolamada sıfır)
• Kötü girişler ele alınır (boş başlık mesaj gösterir ve kaydetmez)

Üzerinde yineleme yapmak için yeterince kararlı hale getirin

Çalıştırılabilir bir iskelet ve bir dikey dilim elde ettikten sonra hedef değişir: bozulmayı açık hale getirin ve düzeltmeleri hızlı yapın. Birçok greenfield başlangıcı burada bozulur; özellik zor olmadığı için değil, küçük değişikliklerin sürprizlere yol açması yüzünden.

Her dilim eklediğinizde karşılamanız gereken küçük bir kararlılık çıtası belirleyin:

• Uygulamanın başlatıldığını ve ana rota/ekranın render edildiğini kanıtlayan bir smoke testi
• Dilimi uçtan uca vuran bir smoke testi (test veritabanı kullansa bile)
• Normal kullanıcıya yönelik net hata mesajları (stack trace değil)
• Geliştirici logları ne olduğunu açıklayıcı, sırları yazdırmayacak şekilde
• Minimal bağımlılıklar, versiyonların sabitlenmesi, yükseltmelerin kasıtlı yapılması

Somut örnek: ilk diliminiz kullanıcıya bir “Proje” oluşturma ve listede görme imkanı veriyor. Sunucuyu başlatan, oluşturma uç noktasını çağıran ve sonra listeyi getirip yeni öğenin göründüğünü kontrol eden bir test ekleyin. Başarısız olursa tek yardımcı mesajla yüksek sesle başarısız olsun: "Create Project endpoint 500 döndürdü" gibi, devasa bir çıktı duvarı değil.

Hata işleme için küçük ve tutarlı cevap setine bağlı kalın. Doğrulama hataları kısa bir mesaj döndürsün ("İsim gerekli") ve alan adını. Beklenmeyen hatalar "Bir şeyler ters gitti. Tekrar deneyin." dönsün. Ayrıntıları loglara kaydedin.

Logging en faydalı olduğunda şu sorulara cevap verir: hangi istek, hangi kullanıcı (veya anonim), ne başarısız oldu ve nerede. Geliştirmede istek id'si ve zamanlama ekleyin, ama jetonlar, parolalar, API anahtarları veya tam payload'ları varsayılan olarak dökmeyin.

Küçük bir health check ekleyin. Web için /health endpoint'i ok döndürebilir. Mobilde backend'e erişilemiyorsa "Offline" durumuna geçen bir "Bağlı" durumu olabilir. Debug etmeye başlamadan önce hızlı bir sinyal sağlar.

AI kullanarak greenfield projelerde sık düşülen tuzaklar

Greenfield başlangıcını boşa harcamanın en hızlı yolu modele tüm uygulamayı istemek ve sonra bunu çalıştırmamaktır. Büyük üretimler küçük hataları gizler: eksik bağımlılıklar, yanlış import yolları, araçlarınızın olmadığı varsayılan scriptler. Her çıktıyı dakikalar içinde çalıştırabileceğiniz bir şey olarak değerlendirin.

Bir diğer tuzak, gerçek bir özellik olmadan mükemmel mimariyi tasarlamaktır. Klasör isimleri üzerine tartışmak üretken hissettirebilir, ama gerçek bir dilim olmadan neyin garip olduğunu söyleyemezsiniz. Bir çalışan yolu destekleyen basit yapı, test edilmemiş zeki bir yapıdan iyidir.

Komut sürüklenmesi de yaygındır. AI sunucuyu başlatmanın yeni bir yolunu ekler, siz teste başka bir tane eklersiniz ve yakında kimsenin "çalıştıracak" tek komutu kalmaz. Bir ekip arkadaşı repoyu klonlayıp "Bunu nasıl çalıştırırım?" diye sorduğunda, zaten faiz ödemeye başlarsınız.

En çok yeniden çalışmaya yol açan hatalar:

• Çalıştırılabilir bir yol oluşturmadan bir kerede birden çok servis, ekran ve konfig üretmek
• İlk uçtan uca özellik çalışmadan auth, ödemeler, karmaşık stil ve tam veri modelini çekmek
• Kurulum talimatlarını chat'te bırakmak yerine scriptlerde (veya tek README) tutmamak
• Temiz bir env şablonunu unutmak, böylece sonraki makine tahmin gerektirmeden başlamaz

Basit bir örnek: giriş, tema ve faturalama içeren "tam" bir uygulama üretiyorsunuz ama ilk çalıştırma eksik bir gizli anahtar yüzünden başarısız oluyor ve .env.example yok. Bu durumda bir saatiniz kurulum düzeltmekle geçer; özelliğin faydalı olup olmadığını öğrenemezsiniz.

Dürüst olun: tek çalıştırılabilir komut, küçük bir özellik, bir env şablonu, sonra genişletme.

Yinelemeye başlamadan önce hızlı kontrol listesi

"Bir özellik daha eklemeden" önce projenin yarın veya başka biri tarafından kolayca devralınabilir olduğundan emin olun. Hız tek amaç değil. Öngörülebilirlik amaçtır.

• Tek komut çalıştırma: yeni bir geliştirici env şablonunu kopyalayıp birkaç gerekli değeri ayarlayıp uygulamayı tek bir komutla başlatabilmeli. Ek adımlar (DB kurulumu, migrationlar, seed verisi) gerekiyorsa bunları bir scriptte yakalayın.
• Scriptler temeli kapsıyor: dev, test, build ve hızlı bir smoke check için net komutlar.
• Açık yapı: düzen okunduğunda bir hikaye anlatmalı (uygulama kodu, config, scriptler, testler) tüm kod tabanını okumadan.
• Dikey dilim demo yolu: demoyu bir cümleyle tanımlayabilmelisiniz, örn. "bir öğe oluştur, listede gör, yenile, hâlâ orada."
• Geri alma noktası: büyük değişikliklerden önce geri dönebileceğiniz güvenli bir nokta (temiz commit, tag veya snapshot/rollback mekanizması).

Herhangi bir madde başarısızsa, şimdi düzeltin. Scriptleri ve isimlendirmeyi sıkılaştırmak repoyken ucuzdur.

Sonraki adımlar: iş akışını tekrarlanabilir bir alışkanlığa dönüştürün

Greenfield başlangıcı, tekrar edilebildiği sürece değer üretir. İlk dikey diliminiz uçtan uca çalıştıktan sonra, iyi parçaları küçük bir şablona dondurun: aynı klasör desenleri, aynı script isimleri ve UI, API ve veriyi aynı şekilde bağlama yöntemi.

İlk dilimi referans implementasyon olarak düşünün. İkinci dilime başlarken kodu değil, şekli kopyalayın. Eğer 1. dilim bir rota, bir handler, bir veri erişim katmanı ve temel bir test içeriyorsa, 2. dilim de aynı yolu izlemeli.

Planlamayı hafif tutun. Bir sayfalık not, sonraki 2-3 dilim için yeterlidir: her dilim için hedef ve kullanıcı eylemi (bir cümle), ihtiyaç duyulan veri, "done" kontrolleri ve erken test edilmesi gereken riskler.

Sonra bakım bir alışkanlık olsun. Haftada bir kısa bir temizlik turu yapın: scriptleri sıkılaştırın, README'yi yeni kurulum adımlarıyla güncelleyin ve env örneğinizi yenileyin ki onboarding kolay kalsın.

Eğer sohbet-öncelikli bir build döngüsünü tercih ediyorsanız, Koder.ai (koder.ai) planlama modu, snapshotlar ve geri alma desteği sağlayan bir seçenek sunar ve istediğinizde kaynak kodunu dışa aktarabilir.

Amaç, düşünmeden çalıştırabileceğiniz bir iş akışı: 2-3 dilim planla, bir dilim inşa et, kararlı hale getir, tekrarla.