ADE’de Kod Üretimi: Sihirli Bir Kutu Değil, Sistematik Bir Süreç

Yapay zekâ destekli geliştirme ortamları (ADE — AI Development Environment), günümüzde yazılım üretim sürecinin vazgeçilmez bir parçası haline geldi. Geleneksel yazılımcı rollerini bir yana, ADE, ürün düşünme (product thinking) süreci ile yazılım geliştirme ve ürün yönetimi süreçlerini birleştirerek “solo entrepreneur” jargonunu “solo crafter” haline getiriyor. Böylece süreç tek kişilik görünse de aslında bir ekibin işlevlerini tek bir kişide topluyor. Bu ortam bize bir sihirbaz edasıyla anında -görece- kod sunsa da, gerçek potansiyelini ortaya çıkarmak için bilinçli ve sistematik bir ön hazırlık sürecinden geçmek gerekiyor.

Bu makale, yapay zekâ destekli geliştirme süreçlerinin temelini oluşturan Spec-Driven Development (SDD) metodolojisini süreç içerisinde yorumluyor. Amacım, yapay zekâyı tek başına bir araç olarak değil, bir geliştirme akışının parçası olarak konumlandırmak ve geleneksel mühendislik prensiplerini, yapay zekâ çağının gereklilikleriyle birleştiren modern çerçeveyi zenginleştirerek ideale yakın çıktı alınmasını sağlamak. ADE’ler tek başına fikri alıp kodlama aşamasına geçme süreçlerinde, sadece core teknik detaylara odaklandığından, geliştirme esnasında eksik kalan noktalar, halüsinasyon görme ya da limitasyonlar (süre ve token) gibi sorun ve kısıtlar nedeniyle süreç ağır işleyebiliyor.

Bu noktada, kodlamaya başlamadan önce “niçin?, nasıl?, şimdi ne çözülmeli?” gibi hem iş hem de teknik dünyaya ait ilgili sorulara cevap verilerek belirsizlikler netleştirilmeli; böylece projenin değeri ve kodlama yeteneği baştan güçlendirilmelidir. Bu aynı zamanda, yapay zekânın “kendinden emin ama hatalı içerikler” üretme riskini de minimize eder. Zira tüm halüsinasyonları yok etmek mümkün olmasa da (şiir veya hikaye yazma gibi yaratıcılık gerektiren alanlarda bu istenebilir), teknik, finans, güvenlik veya kritik kararlar alması gereken agent’lar söz konusu olduğunda kanıtlara dayalı sonuçlar hayati önem taşır. Amaç sıfır hayal gücü değil, seçici güvenilirlik olmalıdır.

Gelin, yapay zekâya kodu yazdırmadan önce, ona nasıl doğru talimatlar vereceğimizi adım adım inceleyelim.

1. Araştırma: Problemi ve Ekosistemi Anlamak

Her yazılım projesi, çözülmesi gereken bir problem veya yakalanması gereken bir fırsatla başlar. Bu aşamada amacımız, problemi doğru bir şekilde tanımlamak ve ekosistemdeki mevcut çözümleri tarayarak güçlü bir bilgi tabanı oluşturmaktır. Bu aşama, solo crafter’ın product manager şapkasını taktığı yerdir. AI servisleri bu araştırma ve zenginleştirme adımında kullanılabilmekle birlikte, dikkat edilmesi gereken kritik nokta, AI’ın eski verilerle eğitilmiş olması ve çıkarımlarını eski verilere göre yapmasıdır. Bu nedenle, yönlendirmelerinizde bu duruma karşı dikkatli olmalısınız.

Araştırma için Kullanılabilecek Kaynaklar:

• Akademik literatür ve whitepaper’lar (arXiv, Google Scholar) → Teorik yaklaşımları anlamak.
• Stack Overflow, Reddit, Hacker News → Gerçek dünyadaki geliştirici sorunları ve çözümlerini keşfetmek.
• ProductHunt, IndieHackers → Benzer ürün fikirleri ve uygulamaları incelemek.
• GitHub / GitLab → Açık kaynak projelerden referans mimari ve kod yapıları bulmak.
• Resmi dokümantasyonlar (Framework/SDK/API) → Teknik sınırlamaları ve imkanları anlamak.
• AI destekli analiz araçları (Firecrawl, SerpAPI vb.) → Hızlı bilgi derleme ve güncel trend analizi yapmak.

Teknikler:

• SWOT analizi
• Problem tanımlama kanvası
• Kullanıcı hikayeleri çıkarma
• Benchmarking

🔑 İpucu: Unutmayın, bu aşamada sadece problemi değil, aynı zamanda niçin şimdi çözülmeli sorusunu da cevaplamak gerekir. Bu, projenin fizibilitesine doğrudan katkı sağlar ve yol haritanızı netleştirir.

2. Fikir: İlk Taslak ve Senaryolar

Araştırma aşamasından sonra, elde edilen bilgiler ışığında ilk çözüm fikri geliştirilir. Bu fikir, tek bir cümlelik bir özetle başlayabilir ve daha sonra kullanıcı senaryoları ile zenginleştirilir. Bu, solo crafter’ın tasarımcı rolüne büründüğü kısımdır. Yine bu adımda AI servislerinden fikir oluşturma ve senaryo zenginleştirme amacıyla yararlanırken, verilerin güncelliğini sorgulamak ve eski bilgilerle verilen yönlendirmelere karşı dikkatli olmak gereklidir.

Teknikler:

• Beyin Fırtınası (Brainstorming) & Zihin Haritası (Mindmap): Fikirlerin dallanarak görselleştirilmesi.
• Kullanıcı Hikâyesi Haritalama (User Story Mapping): Kullanıcı ihtiyaçlarının senaryolara çevrilmesi.
• Tasarım Odaklı Düşünme (Design Thinking): Empati → Tanımlama → Fikre Dökme → Prototipleme → Test etme döngüsü.

3. Spec-kit: Dökümantasyon ve İlk Seviye Taslak

Bir fikri kodlama aşamasına taşımadan önce, onu spesifikasyon dokümanı (spec-kit) haline getirmek gerekir. Bu dökümantasyon, solo crafter’ın artık bir analist gibi düşündüğünü gösterir. Bu, aynı zamanda yapay zekâya “Truth & stakes’i baştan tanımla” diyerek, modelin belirsiz durumlarda “bilmiyorum” demesini sağlayacak zemin hazırlar.

Spec-kit: GitHub’ın SDD çerçevesinde, fikir paragrafından temel Ürün İhtiyaç Dokümanı (PRD), görev planı ve ihtiyaç dökümanlarını oluşturan CLI bazlı bir scripttir.

Spec-kit aşağıdaki bölümleri kapsar:

• Problem Tanımı: Çözülecek sorunun net tanımı.
• Kapsam (Scope): Projenin yapacağı ve yapmayacağı şeyler.
• Kullanım Senaryoları (Use Cases): Kullanıcı senaryoları ve akışları.
• Teknik Gereksinimler: Platform, framework, entegrasyon ihtiyaçları.
• Başarı Kriterleri (Acceptance Criteria): “Tamamlandı” tanımı.
• Risk ve Kısıtlar: Veri erişimi, performans, güvenlik gibi noktalar.

Bu aşamada hazırlanan doküman, hem ADE içinde kullanılacak prompt’ların altyapısını hem de projenin tüm geleceği için referans doküman işlevini görür.

4. Zenginleştirme: Fizibilite, PRD, Gereksinimler, Görev Planı

Spec-kit’in oluşturulmasının ardından, dokümanın teknoloji, mimari, UI ve bileşen seviyesinde zenginleştirilmesi gerekir. Bu aşama, solo crafter’ın artık bir mimara dönüştüğünü gösterir. Burada yapılacak detaylı planlama, Daron Yöndem’in bahsettiği “logic cop” ve “Guardrails” yaklaşımını koda uygulamaya hazırlık niteliğindedir. Bu adımda da AI servislerinden yardım alınabilir, ancak AI’ın eski verilerle eğitilmesi sonucu çıkarımlarının güncel olmayabileceğini göz önünde bulundurmalısınız.

4.1. Teknoloji Seçimleri

• Dil & Framework: (Örn: TypeScript + Next.js, Python + FastAPI, Java + Spring Boot)
• Veritabanı: (Supabase / PostgreSQL, MongoDB, Firebase)
• DevOps / Hosting: (Vercel, Netlify, Docker + Kubernetes, GitHub Actions)
• Kimlik Doğrulama: (Supabase Auth, Auth0, Clerk, özel JWT)

4.2. Mimari Yaklaşımlar

• Monolitik vs Mikroservisler → Projenin boyutuna göre karar verilir.
• Olay Odaklı Mimari (Event-Driven Architecture) → IoT ve gerçek zamanlı veri gerektiren alanlarda kullanılır.
• Temiz Mimari (Clean Architecture) / Altıgen Mimari (Hexagonal Architecture) → Uzun vadeli sürdürülebilirlik için tercih edilir.
• Sunucusuz (Serverless) yaklaşım → Hızlı prototipleme ve düşük maliyet için idealdir.

4.3. UI / UX Yaklaşımları

• Bileşen Tabanlı Arayüz (Component-based UI): React, Svelte, Vue gibi teknolojiler.
• Tasarım Sistemi / UI Kiti: ShadCN UI, MUI, Tailwind + Flowbite, Radix UI.
• UX Prensipleri: Yüklenme durumu, boş durum, hata yönetimi ve duyarlı tasarım (responsive design).
• Erişilebilirlik (a11y): Ekran okuyucu dostu, renk körlüğü için kontrast uyumu.

4.4. Görev Bazlı Bileşen / Kütüphane Planı

Her gereksinim için doğrudan bileşen ve kütüphane eşleştirmesi yapılabilir.

• Kimlik Doğrulama Görevi → Supabase Auth + OAuth2 akışı.
• Grafik Görevi → Recharts, D3.js veya Chart.js.
• Form Yönetimi Görevi → React Hook Form + Zod doğrulama.
• Durum Yönetimi Görevi → Zustand, Redux Toolkit veya React Query.
• Test Görevi → Vitest, Jest, Cypress (Uçtan Uca).
• Analitik Görevi → PostHog, OpenTelemetry, Plausible.

Görevlerin oluşturulması aşamasında GIT repo tanımlaması, checkpointler, gerekli ise alt dalların oluşturulması ve düzenli commit & push yapılması da atlanmaması gereken noktalardır.

4.5. Proje Standartları ve Geliştirme Rehberi

1. Teknoloji Yığını (Tech Stack)

Projenin araçları ve versiyonları açıkça belirtilir:

• Astro 4.5
• Tailwind CSS 3.4
• TypeScript 5.3
• Supabase 2.0

2. Proje Yapısı (Project Structure)

Ana klasörlerin rolleri tarif edilir:

• src/components → Yeniden kullanılabilir UI bileşenleri
• src/lib → İş mantığı ve alan servisleri
• src/pages → Rota bazlı sayfalar
• src/styles → Genel stiller ve tema yönetimi

Daha detaya inmek isterseniz ki artık bu kısmın çoğunu ADE ler onay alarak oluşturur durumdalar.

3. Komutlar (Commands)

En sık kullanılan npm / bash komutları belirtilir:

• npm run dev → Lokal geliştirme
• npm run build → Üretim (production) için derleme
• npm run test → Test çalıştırma
• npm run lint → Kod stili kontrolü
• npm run deploy → Otomatik dağıtım

🔑 Bu liste, yapay zekânın yanlış komut üretip build sürecini bozmasını önler.

3. Kod Stili ve Kuralları

• Formatlama: Prettier + ESLint.
• İsimlendirme: camelCase (değişkenler), PascalCase (bileşenler).
• Import/Export: Mümkünse destructuring (import { foo } from 'bar').
• Dosya İsimleri: kebab-case (örn: user-profile.tsx).

5. Depo Etiği (Repository Etiquette)

• Dal İsimleri: feature/TICKET-123-description.
• Commit Mesaj Formatı: [type]: kısa açıklama (örn: feat: kullanıcı giriş ekranı).
• Birleştirme Stratejisi (Merge Strategy): PR sonrası Merge Commit, üretim için squash.

6. Çekirdek Dosyalar ve Yardımcılar

ADE’nin bilmesi gereken merkezi dosyalar işaretlenir:

• src/lib/api.ts → API çağrıları için merkezi dosya.
• src/lib/utils.ts → Genel yardımcı fonksiyonlar.
• src/lib/config.ts → Ortak yapılandırmalar.

7. “Dokunma” Listesi (The “Do Not Touch” List)

ADE’nin asla değiştirmemesi gereken kritik alanlar belirtilir:

• Çalışan mevcut (legacy) kodlar.
• config/* dosyaları.
• Güvenlik politikaları ve erişim kontrolü.
• Erişilebilirlik (a11y) kontrolleri.

5. ADE: Yapay Zekâ Destekli Kodlama Ortamına Geçiş

Artık elimizde yeterince olgunlaşmış bir fikir, kapsamlı bir dökümantasyon ve netleştirilmiş görev listesi vardır. Bu noktada proje ADE’ye devredilir. Bu, Daron Yöndem’in de bahsettiği RAG (Retrieval-Augmented Generation) ve Tool Composition aşamalarını uygulamaya koyduğumuz yerdir.

Kodlamaya geçmeden önce, ADE’den dökümanları incelemesi, yorumlaması ve geliştirme aşamasında takılmamak adına netleştirilmesini gerekli gördüğü noktaları alıp netleştirmek de çok ama çok önemlidir. Tüm bu iyileştirmeler, kodlamaya başlama, token ve limit noktasında büyük bir konfor ve destek sağlayacaktır.

ADE’nin rolü:

• Kod iskeleti oluşturma.
• Gereksinimlere göre modül bazlı kod üretimi.
• Test senaryoları hazırlama.
• Eksik kalan noktaları sorgulama.

6. Detaylı Promptlar: Kodlama Öncesi Net Talimatlar

ADE’den kod üretimi isterken, ne kadar özgür alan bırakılacağı kritik bir karardır. Bu konuyu, makalenin devamı niteliğindeki 2. bölümde daha detaylı ele alacağım.

Hızlıca bahsetmek gerekirse, kodlamaya başlama noktası için karar verilmesi gereken, ADE’nin görev odaklı (task) mı yoksa manuel prompt ile mi ilerleyeceği kararıdır.6.1. “Görevi al ve geliştir” Yaklaşımı

• Avantajı: ADE daha yaratıcı çözümler önerebilir.
• Dezavantajı: Gereksinimlerin yanlış anlaşılması riski artar.
• Kullanım Alanı: Prototip geliştirme, konsept kanıtlama (PoC) ve keşif amaçlı kod üretimi.

6.2. “Detaylı prompt ile yönlendirme” Yaklaşımı

• Avantajı: Gereksinimlere %100 uyumlu kod üretilir.
• Dezavantajı: ADE’nin esnekliğini kısıtlar.
• Kullanım Alanı: Üretime yakın projeler ve ekip standardı olan ortamlar.

6.3. Hibrit Model

En verimli yöntem çoğunlukla hibrittir:

1. İlk başta ADE’ye “görevi al ve geliştir” denir → alternatif yolları görmek için.
2. Daha sonra çıkan kod gözden geçirilip detaylı prompt ile iyileştirilir.

Örnek Senaryo: Kimlik Doğrulama Modülü

• Görev: Google OAuth ile kullanıcı girişi.
• Spec-kit gereksinimi:
• Next.js + Supabase kullanılacak.
• “Beni Hatırla” seçeneği olacak.
• 3 yanlış giriş sonrası kullanıcı 5 dakika kilitlenecek.

ADE’ye Esnek Prompt:

“Next.js + Supabase kullanarak Google OAuth tabanlı bir giriş akışı yaz. ‘Beni Hatırla’ özelliğini ekle. Yanlış girişte geçici kilitleme için farklı yöntemler öner.”

ADE’ye Detaylı Prompt:

“Next.js (App Router) + Supabase auth ile Google OAuth giriş akışı için kod yaz. Kullanıcı giriş formunda ‘Beni Hatırla’ onay kutusu olacak. Bu kutu işaretliyse, yenileme token’ı tarayıcıda 30 gün saklanacak. Yanlış girişlerde Supabase’in hız sınırlama (rate limit) özelliği kullanılacak. TailwindCSS ile basit ama duyarlı bir arayüz üret. Kod sonunda Next.js middleware ile rota koruması da ekle.”

Sonuç

Kodlama sürecinde ADE kullanımı, ancak doğru ön hazırlık yapıldığında gerçek değerini gösterir. Araştırma, fikir, spec-kit ve zenginleştirilmiş dokümanlar, ADE’nin daha bilinçli ve hatasız kod üretmesini sağlar. Bu sistematik yaklaşım, Daron Yöndem’in bahsettiği “Faithfulness” ve “Calibration” metriklerinin temelini atarak, geliştiricilere şunları kazandırır:

• Belirsizliğin azalması,
• Gereksinimlerin netleşmesi,
• Yapay zekânın eksikleri sorgulayıp doldurabilmesi,
• Daha hızlı, sürdürülebilir ve yüksek kaliteli kod geliştirme.