Yapay zekâ destekli kodlama araçları yazılım geliştirme biçimini önemli ölçüde değiştirdi.

Codex, Claude Code, Cursor ve benzeri coding agent’lar özellikler üretebilir, API’ler oluşturabilir, arayüzler geliştirebilir, kodu refactor edebilir, test yazabilir ve çalışan uygulamalarla etkileşime girebilir.

Ancak büyük projelerde kısa sürede görülen önemli bir gerçek var:

Bir yapay zekâya uzun bir prompt vermek, ona bir yazılım mühendisliği süreci vermekle aynı şey değildir.

Ajana yalnızca “kimlik doğrulama, dashboard, ödeme ve yapay zekâ özellikleri olan full-stack bir uygulama geliştir” derseniz çok miktarda kod üretebilir. Fakat farklı özellikler zamanla tutarsızlaşabilir, veritabanı kararları değişebilir, çalışan gibi görünen butonlar işlevsiz kalabilir ve arayüz birbirinden kopuk AI bileşenlerinin toplamına dönüşebilir.

Daha güvenilir yaklaşım, yapay zekâyı yapılandırılmış bir geliştirme ortamının içine almaktır.

Bu ortam; ürün dokümantasyonu, tasarım talimatları, agent skill’leri ve otomatik test araçlarının birlikte kullanılmasına dayanır.

project/
├── docs/
│   ├── PRD.md
│   ├── TRD.md
│   ├── USER_FLOWS.md
│   ├── UI_UX_DESIGN.md
│   ├── DATABASE_SCHEMA.md
│   └── IMPLEMENTATION_PLAN.md
│
├── skills/
├── apps/
├── packages/
└── README.md

Şimdi bu parçaların ne işe yaradığını ve AI ile yazılım geliştirirken neden önemli olduklarını inceleyelim.

1. PRD — Ürün Gereksinimleri Dokümanı

Product Requirements Document, yani PRD, ürünün ne yapması gerektiğini açıklar.

PRD implementasyondan çok ürüne odaklanır. Uygulamanın amacı, hedef kullanıcıları, ana özellikleri, kullanıcı problemleri, iş kuralları, öncelikler, başarı kriterleri ve platform gereksinimleri burada tanımlanabilir.

Örneğin bir sağlık takip uygulaması için kullanıcıların hesap oluşturması, Google veya Apple ile giriş yapması, günlük kayıt eklemesi, görsel yüklemesi, geçmiş kayıtlarını görmesi ve AI tarafından üretilen içgörüleri alması istenebilir.

PRD, backend’in Node.js, Go, Java veya Python ile yazılıp yazılmayacağına karar vermez. Basitçe şu soruya cevap verir:

Ne inşa ediyoruz ve bunu neden inşa ediyoruz?

AI coding agent için PRD projenin kaynak gerçeğidir. Uygulamayı her prompt’ta yeniden anlatmak yerine agent PRD.md dosyasına dönebilir.

2. TRD — Teknik Gereksinimler Dokümanı

PRD ne inşa ettiğimizi anlatıyorsa Technical Requirements Document, yani TRD, bunu nasıl inşa edeceğimizi tanımlar.

TRD; frontend ve backend teknolojilerini, veritabanını, API yaklaşımını, kimlik doğrulamayı, yetkilendirmeyi, caching stratejisini, background job’ları, hata yönetimini, gözlemlenebilirliği, güvenliği, deployment ve test stratejisini içerebilir.

Frontend: React + Next.js + TypeScript
Backend: Node.js REST API
Database: PostgreSQL
ORM: Prisma
Authentication: Google Sign-In ve Sign in with Apple
Deployment: Web hosting + managed database

TRD olmadan her özellik için yeni bir mimari karar alınabilir: bir özellik REST API kullanırken diğeri doğrudan veritabanına erişebilir, başka bir özellik GraphQL kullanabilir. Her karar tek başına çalışsa da toplamda mimari karmaşa oluşur.

TRD, AI agent’ın karar alanını bilinçli sınırlarla daraltır.

3. Kullanıcı Akışları

User flow dosyaları kullanıcıların uygulama içinde nasıl ilerlediğini gösterir. AI tek tek ekranlar üretmekte başarılı olsa da ekranların birbirine nasıl bağlandığını otomatik olarak doğru anlamayabilir.

Uygulamayı aç
      ↓
Kimlik doğrulama
      ↓
Dashboard
      ↓
Kayıt oluştur
      ↓
Görsel yükle
      ↓
Kaydet
      ↓
AI analizi
      ↓
Sonuçlar

Başarısızlık yolları da tanımlanmalıdır. Örneğin görsel yükleme başarısız olduğunda hata gösterilmeli ve kullanıcıya yeniden deneme seçeneği sunulmalıdır.

4. UI/UX Tasarım Spesifikasyonu

UI/UX dokümanı uygulamanın nasıl görüneceğini ve nasıl hissettireceğini tanımlar. PRD “dashboard son projeleri göstermeli” diyebilir; tasarım dokümanı kartların yatay kaydırılacağını, hangi bilgileri içereceğini, padding, radius, renk, tipografi, loading, empty ve error durumlarını tarif eder.

Bu doküman özellikle tasarım kaymasını önler. Bir sayfada 12px, diğerinde 16px, üçüncüsünde 24px radius kullanılmasının önüne geçer. Aynı şekilde renkler, yazı hiyerarşisi, buton yüksekliği ve boşluk sistemi de tutarlı kalır.

5. Veritabanı Şeması

Veritabanı şeması uygulama verisinin nasıl yapılandırıldığını açıklar.

User
├── id
├── email
├── name
└── createdAt

Entry
├── id
├── userId
├── imageUrl
├── notes
├── createdAt
└── updatedAt

AIAnalysis
├── id
├── entryId
├── result
├── model
└── createdAt

Modeller, alanlar, tipler, ilişkiler, foreign key’ler, index’ler, unique constraint’ler, cascade davranışları ve migration stratejisi dokümante edilmelidir. Böylece bir agent imageUrl alanını kullanırken sonraki agent’ın imagePath adında ikinci bir gerçeklik oluşturması engellenir.

6. Uygulama Planı

Implementation plan, mimariyi uygulanabilir bir sıraya dönüştürür.

Faz 1 — Temel yapı
- Repository ve TypeScript kurulumu
- Lint ve environment ayarları
- Veritabanı kurulumu

Faz 2 — Kimlik doğrulama
- Session yönetimi
- Protected route’lar

Faz 3 — Temel ürün
- Dashboard
- Kayıt oluşturma ve düzenleme
- Görsel yükleme

Faz 4 — AI
- Analiz endpoint’i
- Model entegrasyonu
- Fallback davranışı

Faz 5 — Test ve production
- Unit, integration ve Playwright testleri
- Deployment ve monitoring

AI’nin bütün platformu tek seferde üretmesini istemek yerine agent’ın tamamlanmamış bir fazı sırayla ele almasını sağlarsınız. Bu yaklaşım Git geçmişini de daha anlamlı hale getirir.

Dokümantasyon Sistemin Yalnızca Yarısıdır

Dokümanlar AI agent’a yazılımın ne olması gerektiğini söyler. Bir başka soru daha vardır: Agent bu yazılımı üretirken nasıl davranmalıdır?

Reusable SKILL.md dosyaları burada devreye girer. Design, testing, accessibility, image-to-code veya code review gibi iş türleri için tekrar kullanılabilir çalışma kuralları tanımlanabilir.

PRD
→ Ürün ne yapmalı?

TRD
→ Sistem nasıl çalışmalı?

Tasarım spesifikasyonu
→ Ürün nasıl görünmeli?

Agent skill’i
→ AI bu işe nasıl yaklaşmalı?

TasteSkill ve Görsel Kalite

AI tarafından üretilen frontend’lerin sık karşılaştığı sorunlardan biri, teknik olarak doğru ama birbirine benzeyen arayüzlerdir: dev hero başlıkları, her yerde rounded card’lar, zayıf tipografi ve gereksiz animasyonlar.

Bir design skill’i yalnızca renk ve radius token’ları vermez; tasarım kararı için de rehberlik eder. Her bölümü karta dönüştürmemek, her içeriği ortalamamak, güçlü bir tipografi hiyerarşisi kurmak ve hareketi yalnızca etkileşimi iyileştiriyorsa kullanmak gibi kurallar belirleyebilir.

Web Tasarım Kuralları ve Image-to-Code

Güzel görünen bir arayüz kullanılabilir olmak zorunda değildir. Klavye navigasyonu, focus göstergeleri, dokunma alanları, form hataları, kontrast ve responsive davranış ayrıca denetlenmelidir.

Oluşturma ve inceleme ayrı adımlar olmalıdır. Agent arayüzü geliştirdikten sonra accessibility, responsive davranış, eksik interaction state’leri ve keyboard navigation için ikinci bir audit yapmalıdır.

Image-to-code yaklaşımı ise referans görselden tasarım sistemi çıkarmayı hedefler:

Referans görsel
       ↓
Görsel analiz
       ↓
Tasarım sistemi çıkarımı
       ↓
Bileşenlerin belirlenmesi
       ↓
Implementasyon
       ↓
Görsel karşılaştırma

Bu yöntem Figma tasarımlarını, ekran görüntülerini, mobil mockup’ları ve mevcut web sitelerini daha tutarlı biçimde koda taşımaya yardımcı olur.

Playwright: AI Uygulamayı Gerçekten Kullansın

Kodun doğru görünmesi uygulamanın çalıştığını kanıtlamaz. Bir buton işlevsiz olabilir, route yanlış sayfaya gidebilir veya form submit sırasında hata verebilir.

Playwright CLI ile agent çalışan uygulamayı kullanıcı gibi kullanabilir:

localhost:3000’i aç
Yeni hesap oluştur
Onboarding’i tamamla
Kayıt oluştur
Görsel yükle
Sayfayı yenile
Kaydın durduğunu doğrula
Düzenle ve sil
Aynı akışı mobil viewport’ta tekrarla

Bu aşamada agent artık yalnızca kendi kodunu okumaz; gerçek bir kullanıcı akışını doğrular.

AI Geliştirme Bir Döngü Olmalıdır

FİKİR
  ↓
PRD.md
  ↓
USER_FLOWS.md
  ↓
UI_UX_DESIGN.md
  ↓
DATABASE_SCHEMA.md
  ↓
TRD.md
  ↓
IMPLEMENTATION_PLAN.md
  ↓
AI CODING AGENT
  ↓
KOD
  ↓
UI AUDIT
  ↓
PLAYWRIGHT TESTİ
  ↓
DÜZELTME
  ↓
YENİDEN TEST
  ↓
PRODUCTION

Kod üretimi sürecin yalnızca bir parçasıdır. Daha doğru model şudur: belirt, tasarla, planla, uygula, incele, test et, düzelt ve çalıştığını kanıtla.

Markdown Dosyaları Neden İşe Yarar?

Bu dokümanları repository içinde Markdown dosyaları olarak tutmak; gereksinimleri, mimariyi ve kodu aynı versiyon kontrolü içinde yaşatır. Mimari değiştiğinde git diff yalnızca kodu değil, karar dokümanlarındaki değişiklikleri de görünür kılar.

Bir özellik değiştiğinde ideal akış şudur:

PRD’yi güncelle
      ↓
Gerekirse TRD’yi güncelle
      ↓
Şemayı ve planı güncelle
      ↓
Kodu değiştir
      ↓
Testleri çalıştır

AI Coding Agent İçin Daha İyi Prompt

“Authentication, dashboard ve AI analizi olan bir SaaS uygulaması geliştir” demek yerine agent’a proje dokümanlarını kaynak gerçek olarak okutun.

docs/PRD.md, docs/TRD.md, docs/USER_FLOWS.md, docs/UI_UX_DESIGN.md, docs/DATABASE_SCHEMA.md ve docs/IMPLEMENTATION_PLAN.md dosyalarını oku.

Tamamlanmamış bir sonraki fazı uygula.

Design skill’ini ve UI kurallarını takip et.

Yeni mimari kalıplar ekleme.

Lint, typecheck, unit test ve Playwright akışlarını çalıştır.

Bulduğun sorunları düzelt, tekrar test et ve planı güncelle.

Bu prompt, AI’ye tek seferlik görev değil, mühendislik ortamı verir.

Dokümantasyon Geliştiricilerin Yerini Tutmaz

AI kod üretimini hızlandırır; fakat ne yapılacağına, mimarinin nasıl olması gerektiğine, veri modeline, güvenlik kurallarına, UX kalitesine ve sonucun gerçekten problemi çözüp çözmediğine hâlâ insanların karar vermesi gerekir.

AI kötü bir kararı da çok hızlı yayabilir. Bu nedenle yapı, sınırlar ve doğrulama mekanizmaları daha önemli hale gelir.

Önerilen AI Proje Yapısı

project/
├── docs/
│   ├── PRD.md
│   ├── TRD.md
│   ├── USER_FLOWS.md
│   ├── UI_UX_DESIGN.md
│   ├── DATABASE_SCHEMA.md
│   └── IMPLEMENTATION_PLAN.md
├── skills/
│   ├── design/
│   └── testing/
├── apps/
├── packages/
├── tests/e2e/
├── AGENTS.md
└── README.md

Projeye göre klasörler değişebilir. Değişmemesi gereken prensip ise şudur: AI’ye bağlam, kısıtlar, mimari, tasarım kuralları, uygulama planı ve kendi işini doğrulama yöntemi verin.

Sonuç

AI coding agent’larla ortalama bir proje ile production kalitesinde AI-assisted bir proje arasındaki fark genellikle daha uzun bir prompt değildir. Fark, agent’ın etrafında daha iyi bir geliştirme sistemi kurmaktır.

PRD ürünü, TRD mimariyi, user flow davranışı, UI/UX deneyimi, database schema veri modelini, implementation plan yürütmeyi, design skill’leri görsel tutarlılığı, web kuralları kalite kontrollerini, image-to-code görsel belirsizliği ve Playwright gerçek tarayıcı doğrulamasını yönetir.

Yani yaklaşım “AI, uygulamamı geliştir” seviyesinden şuna dönüşür:

İşte ürün. İşte mimari. İşte tasarım dili. İşte uygulama planı. Geliştir, test et, incele, düzelt ve çalıştığını kanıtla.

AI mühendislik sürecinin yerini almamalıdır.

AI, iyi tanımlanmış bir mühendislik sürecinin içinde çalışmalıdır.