Vibe Coding'den Spec-Driven Development'a: Spec Kit ile AI'a İş

Vibe Coding’den Spec-Driven Development’a: Spec Kit ile AI’a İş

Yazılım geliştirme dünyasında, özellikle hızlı prototipleme veya başlangıç aşamalarındaki projelerde, çoğu zaman “vibe coding” olarak adlandırabileceğimiz bir yaklaşımla karşılaşıyoruz. Bu, belirli bir spec veya dokümantasyon olmadan, daha çok içgüdülerimize, anlık kararlarımıza ve “öyle iyi duruyor” hissine dayanarak kod yazma pratiğidir. Bu yaklaşım, ilk başta hızlı ilerleme sağlıyor gibi görünse de, projenin ölçeği büyüdükçe veya ekipteki kişi sayısı arttıkça ciddi sorunlara yol açabiliyor. Kodun anlaşılması zorlaşıyor, beklenmedik bug’lar ortaya çıkıyor ve en kötüsü, bu belirsizlik AI (yapay zeka) araçlarının verimli bir şekilde kullanılmasını engelliyor.

Son zamanlarda AI modellerinin yetenekleri inanılmaz bir hızla artıyor. Prompt engineering ve RAG (Retrieval-Augmented Generation) gibi tekniklerle AI’dan belirli görevleri yerine getirmesini isteyebiliyoruz. Ancak, AI’nın da bizim gibi bir “anlayış”a ihtiyacı var. Eğer biz bir işin ne olduğunu tam olarak tanımlayamazsak, AI’ya neyi yapması gerektiğini nasıl anlatabiliriz? İşte tam da bu noktada, Spec-Driven Development (SSD) ve Spec Kit gibi araçlar devreye giriyor. Bu yazıda, “vibe coding”den sıyrılıp, Spec Kit kullanarak AI’a iş yaptırmanın pratik yollarını derinlemesine inceleyeceğiz.

Vibe Coding’in Gizli Maliyetleri

“Vibe coding”, özellikle küçük ekiplerde veya tek kişilik projelerde cazip gelebilir. Hızlıca bir şeyler inşa edip denemek, fikirleri anında hayata geçirmek kulağa hoş geliyor. Ancak bu yaklaşımın uzun vadeli maliyetleri oldukça yüksek. İlk başta gözden kaçan hatalar, zamanla birikerek devasa bir teknik borç oluşturuyor. Kod tabanı karmaşıklaştıkça, yeni özellik eklemek veya mevcut bir hatayı düzeltmek bile aylar sürebiliyor.

Bu durumun en belirgin sonuçlarından biri, takım içi iletişimde yaşanan kopukluklar. Belirli bir standarda veya dokümantasyona dayanılmadığı için, bir geliştiricinin yazdığı kodun mantığını anlamak diğerleri için zorlu bir hal alabiliyor. Bu da kod incelemelerini (code review) verimsiz hale getiriyor ve hataların üretime (production) geçme olasılığını artırıyor. Kendi deneyimimde, bir üretim ERP’sinde gec sevkiyat raporunun sürekli eksik gelmesi sorunuyla karşılaştığımda, bu “vibe coding”in bir sonucu olduğunu anlamam uzun sürmemişti. Raporlama modülünün farklı geliştiriciler tarafından, farklı zamanlarda ve farklı varsayımlarla inşa edilmiş olması, veri tutarlılığını imkansız hale getirmişti. Bu tür sorunlar, sadece geliştirme sürecini yavaşlatmakla kalmıyor, aynı zamanda iş süreçlerini de doğrudan etkiliyor.

Spec-Driven Development: Sistemin İnşası

Spec-Driven Development (SSD), tam da “vibe coding”in zıttı bir yaklaşım sunuyor. Bu metodoloji, her şeyin bir spesifikasyonla başladığı prensibine dayanır. Yazılacak kodun ne yapması gerektiği, hangi girdileri alacağı, hangi çıktıları üreteceği, hangi koşullarda hangi davranışları sergileyeceği gibi detaylar, kod yazılmadan önce net bir şekilde tanımlanır. Bu spesifikasyonlar, sadece insan geliştiriciler için değil, aynı zamanda AI araçları için de birincil bilgi kaynağı haline gelir.

SSD’nin temelinde, yazılımın sadece koddan ibaret olmadığı, aynı zamanda bir dizi kural, beklenti ve davranışı tanımlayan bir “anlaşma” olduğu fikri yatar. Bu anlaşma, geliştiriciler, test mühendisleri, ürün yöneticileri ve hatta müşteriler arasında bir köprü görevi görür. Spesifikasyonlar, hem gereksinimleri netleştirmeye yardımcı olur hem de geliştirme sürecinde bir rehber niteliği taşır. Örneğin, bir API endpoint’inin tasarımı ele alınırsa, SSD yaklaşımında bu endpoint’in hangi HTTP metodunu kullanacağı (GET, POST vb.), hangi URL yapısına sahip olacağı, hangi query parametrelerini alacağı, request body’de hangi verileri bekleyeceği ve başarılı veya başarısız durumlarda hangi yanıtları döneceği gibi tüm detaylar önceden belirlenir. Bu detaylar, daha sonra test senaryolarının da temelini oluşturur.

Spec Kit ile Tanışın: Yapılandırılmış Spesifikasyonlar

Spec Kit, tam da bu SSD felsefesini hayata geçirmek için tasarlanmış bir araçtır. Bu kütüphane, spesifikasyonlarınızı yapılandırılmış bir formatta tanımlamanıza olanak tanır. Genellikle YAML veya JSON gibi makine tarafından okunabilir formatlarda tutulan bu spesifikasyonlar, hem insan tarafından okunabilir hem de çeşitli araçlar tarafından işlenebilir. Spec Kit, API tanımları, işlem akışları, veri modelleri gibi birçok farklı yapıyı tanımlamak için esnek bir yol sunar.

Örneğin, bir API tanımı için Spec Kit kullanırken, paths altında endpoint’leri, her endpoint için kullanılabilecek HTTP metodlarını (get, post vb.), bu metodların alacağı parametreleri (query, path, header, cookie), request body şemasını ve beklenen yanıtları (responses) detaylı bir şekilde belirleyebilirsiniz. Her bir parametre veya alan için veri tipi, zorunlu olup olmadığı, açıklayıcı bir metin gibi ek bilgiler de tanımlanabilir. Bu yapılandırılmış yaklaşım, sadece geliştirme sürecini kolaylaştırmakla kalmaz, aynı zamanda otomatik dokümantasyon oluşturma, test senaryoları üretme ve hatta kod üretme gibi süreçleri de mümkün kılar. Kendi geliştirdiğim bir finansal hesaplayıcı uygulamasının backend’inde, bu tür yapılandırılmış spesifikasyonlar sayesinde API’ları hem daha hızlı tasarladım hem de beklenmedik durumları öngörerek hata payını minimize ettim.

AI’a İş Yaptırmanın Yolu: Spec Kit ve Prompt Engineering

AI modelleriyle çalışırken en büyük zorluklardan biri, onlara ne istediğimizi net bir şekilde anlatabilmektir. “Vibe coding” yaklaşımında, bu anlatım genellikle belirsiz ve eksik olur. Ancak Spec Kit ile oluşturulan yapılandırılmış spesifikasyonlar, bu durumu tamamen değiştirir. Bu spesifikasyonları, AI için birincil girdi olarak kullanabiliriz.

Örneğin, bir API endpoint’i için kod üretmek istediğimizde, ilgili Spec Kit tanımını AI modeline verebiliriz. Prompt’umuzu şu şekilde formüle edebiliriz: “Aşağıdaki Spec Kit tanımına göre, FastAPI kullanarak Python dilinde bir API endpoint’i oluştur. Endpoint, POST /users olmalı ve request body’de name (string, zorunlu) ve email (string, zorunlu, geçerli email formatında) alanlarını kabul etmeli. Başarılı isteklerde 201 Created durumu ve oluşturulan kullanıcının ID’sini içeren bir JSON dönmeli. Hata durumlarında ise uygun hata mesajları ile 400 Bad Request durumu dönmeli.” Bu şekilde, AI’dan ne istediğimizi son derece net bir şekilde belirtmiş oluruz.

Bir diğer kullanım alanı ise test senaryoları üretmektir. Spec Kit tanımındaki parametreler, veri tipleri ve kısıtlamalar, AI’a hangi test senaryolarını oluşturması gerektiği konusunda yol gösterir. “Bu Spec Kit tanımına göre, geçerli ve geçersiz durumlar için pytest kullanarak test senaryoları yaz” gibi bir prompt ile otomasyonu bir üst seviyeye taşıyabiliriz. Kendi yan ürünüm olan Android spam engelleyici uygulaması üzerinde çalışırken, kullanıcı girişlerinin doğruluğunu kontrol etmek için bu tür AI destekli test senaryosu üretiminden faydalandım. Spec Kit’teki veri doğrulama kuralları, AI’a hangi geçerli ve geçersiz girdileri denemesi gerektiğini net bir şekilde gösterdi.

Spec Kit ile Kod Üretimi: Örnek Bir Senaryo

Şimdi, Spec Kit’in kod üretme potansiyelini daha somut bir örnekle görelim. Diyelim ki, bir kullanıcı kayıt API’ı için bir spesifikasyonumuz var. Bu spesifikasyonu bir YAML dosyası olarak tanımlayalım:

paths:
  /users:
    post:
      summary: Kullanıcı kaydı oluştur
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Kullanıcının tam adı
                  minLength: 2
                  maxLength: 50
                email:
                  type: string
                  format: email
                  description: Kullanıcının e-posta adresi
                  pattern: "^\\S+@\\S+\\.\\S+$" # Basit email regex'i
              required:
                - name
                - email
      responses:
        '201':
          description: Kullanıcı başarıyla oluşturuldu
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Oluşturulan kullanıcının benzersiz ID'si
                  message:
                    type: string
                    example: "Kullanıcı başarıyla kaydedildi."
        '400':
          description: Geçersiz istek verisi
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Geçersiz e-posta formatı."

Bu YAML dosyasını bir AI modeline vererek, örneğin Python ve FastAPI kullanarak bu endpoint’i oluşturmasını isteyebiliriz. Prompt’umuz şu şekilde olabilir:

Aşağıdaki OpenAPI (Swagger) benzeri spec tanımını kullanarak, Python ve FastAPI ile bir API endpoint'i oluştur.

Spec Tanımı:
---
paths:
  /users:
    post:
      summary: Kullanıcı kaydı oluştur
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Kullanıcının tam adı
                  minLength: 2
                  maxLength: 50
                email:
                  type: string
                  format: email
                  description: Kullanıcının e-posta adresi
                  pattern: "^\\S+@\\S+\\.\\S+$" # Basit email regex'i
              required:
                - name
                - email
      responses:
        '201':
          description: Kullanıcı başarıyla oluşturuldu
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Oluşturulan kullanıcının benzersiz ID'si
                  message:
                    type: string
                    example: "Kullanıcı başarıyla kaydedildi."
        '400':
          description: Geçersiz istek verisi
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Geçersiz e-posta formatı."
---

Beklenen çıktı, FastAPI app'inin ilgili route'unu içeren bir Python kodu olmalı. İhtiyaç duyulan import'ları da ekle.

AI’dan alacağımız çıktı kabaca şöyle olacaktır (basitleştirilmiş hali):

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, EmailStr, Field
import uuid

app = FastAPI()

class UserCreateRequest(BaseModel):
    name: str = Field(..., min_length=2, max_length=50)
    email: EmailStr # FastAPI'nin EmailStr kullanımı bu formatı otomatik kontrol eder

class UserCreateResponse(BaseModel):
    id: str
    message: str

# Basit bir veritabanı simülasyonu
users_db = {}

@app.post("/users", response_model=UserCreateResponse, status_code=status.HTTP_201_CREATED)
async def create_user(user_request: UserCreateRequest):
    if user_request.email in users_db:
        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Bu e-posta adresi zaten kullanılıyor.")

    user_id = str(uuid.uuid4())
    users_db[user_request.email] = {"id": user_id, "name": user_request.name, "email": user_request.email}

    return UserCreateResponse(id=user_id, message="Kullanıcı başarıyla kaydedildi.")

# Ek olarak, spec'teki 400 hatasını yakalamak için model seviyesinde validationlar zaten Pydantic tarafından yapılıyor.
# Örneğin, email formatı yanlışsa veya name alanı boşsa Pydantic otomatik olarak 422 Unprocessable Entity dönecektir.
# Bizim özel 400 hatamız (e-posta tekrarı) için yukarıdaki if bloğu eklendi.

Bu örnekte, AI’ın sadece kodu üretmediğini, aynı zamanda Pydantic modellerini doğru bir şekilde oluşturduğunu, UUID ürettiğini ve basit bir hata kontrolünü (e-posta tekrarı) dahil ettiğini görüyoruz. EmailStr kullanımı gibi detaylar, Pydantic’in yerleşik doğrulamalarının AI tarafından anlaşıldığını gösteriyor. Bu, “vibe coding” ile manuel olarak yazılacak yüzlerce satır koda kıyasla inanılmaz bir verimlilik artışı sağlıyor. Yaklaşık 40 satırlık YAML tanımından, 30+ satırlık fonksiyonel kod üretilmiş oldu. Bu, özellikle tekrarlayan API endpoint’leri veya veri modelleri söz konusu olduğunda, geliştirme süresini önemli ölçüde kısaltır.

Test Senaryolarını Otomatikleştirmek

Spec Kit, sadece kod üretmekle kalmaz, aynı zamanda test senaryoları oluşturmak için de mükemmel bir temel sunar. Spesifikasyonlardaki alanların veri tipleri, minLength, maxLength, pattern gibi kısıtlamalar ve required alanlar, AI’a hangi tür test senaryolarını oluşturması gerektiği konusunda net bilgiler verir.

AI’a şu şekilde bir prompt verebiliriz: “Verilen Spec Kit tanımına göre, pytest kullanarak aşağıdaki API endpoint’i için hem geçerli hem de geçersiz durumları test eden senaryoları Python dilinde yaz.”

AI, spesifikasyondaki tüm gereksinimleri analiz ederek aşağıdaki gibi test senaryoları üretebilir:

• Geçerli E-posta ve İsim: name ve email alanları doğru formatta ve zorunlu şartları sağlıyorsa 201 Created dönmeli.
• Geçersiz E-posta Formatı: E-posta alanı ”@” veya ”.” içermiyorsa veya belirtilen regex’e uymuyorsa 400 Bad Request (veya Pydantic’in otomatik olarak döneceği 422) dönmeli.
• Eksik Alanlar: name veya email alanı boş bırakıldığında veya gönderilmediğinde 400 (veya 422) dönmeli.
• İsim Uzunluk Kısıtlamaları: name alanı minLength ve maxLength değerlerinin dışına çıktığında hata dönmeli.
• Tekrarlayan E-posta: Daha önce kaydedilmiş bir e-posta ile kayıt denenirse 400 Bad Request dönmeli.

Bu tür otomatik test senaryoları, geliştirme sürecinin başından itibaren kod kalitesini artırır ve regresyon hatalarını önlemeye yardımcı olur. Kendi projelerimde, özellikle CI/CD pipeline’larına entegre ettiğim bu otomatik testler sayesinde, üretim ortamına gönderdiğim kodun güvenilirliği %99’lara ulaştı. Bir üretim ERP’sinde yaptığım çalışmalarda, bu tür test otomasyonu sayesinde, raporlama modülündeki kritik hataların üretime geçmeden tespit edilmesini sağlamıştım.

RAG ile Bilgi Tabanlı AI Uygulamaları

Retrieval-Augmented Generation (RAG), AI modellerinin harici bilgi kaynaklarından yararlanarak daha doğru ve bağlamsal yanıtlar üretmesini sağlayan bir tekniktir. Spec Kit ile oluşturulan yapılandırılmış spesifikasyonlar, RAG sistemleri için harika bir bilgi kaynağı olabilir.

Bir RAG sisteminde, kullanıcının sorduğu soruya yanıt vermek için AI modeli öncelikle bir “retrieve” aşamasından geçer. Bu aşamada, kullanıcının sorusuyla ilgili en alakalı bilgiyi, örneğin Spec Kit tanımları, dokümantasyonlar veya veritabanı şemaları gibi kaynaklardan arar. Bulunan bilgiler daha sonra AI modeline “generate” aşaması için girdi olarak verilir. Böylece AI, sadece genel bilgisini değil, aynı zamanda projenize özgü detayları da kullanarak yanıtlar üretebilir.

Örneğin, bir geliştirici AI’a “Kullanıcı profili güncelleme API’ı hangi parametreleri alıyor?” diye sorduğunda, RAG sistemi ilgili Spec Kit tanımını bulur ve AI modeline bu tanımı girdi olarak sunar. AI da spesifikasyondaki PUT /users/{id} endpoint’inin kabul ettiği alanları, zorunlu olup olmadıklarını ve veri tiplerini listeleyebilir. Bu, yeni başlayan geliştiriciler için veya karmaşık sistemlerde çalışan herkes için büyük bir kolaylık sağlar. Kendi özel finansal hesaplayıcılarımın dokümantasyonunu oluştururken RAG’dan faydalandım; Spec Kit tanımları ve kod yorumları, AI’ın tutarlı ve doğru dokümantasyon üretmesini sağladı.

Trade-off’lar ve Geleceğe Bakış

Spec-Driven Development ve Spec Kit kullanmak elbette ki bazı trade-off’ları beraberinde getiriyor. Başlangıçta spesifikasyonları hazırlamak, “vibe coding”e göre daha fazla zaman alabilir. Ancak bu erken yatırım, projenin ilerleyen aşamalarında ortaya çıkacak maliyetleri ve sorunları önlediği için uzun vadede büyük bir tasarruf sağlar. Spesifikasyonların güncel tutulması da ayrı bir dikkat gerektirir. Eğer kod spesifikasyonlardan saparsa veya spesifikasyonlar güncelliğini yitirirse, sistemin tutarlılığı bozulur. Bu nedenle, CI/CD pipeline’larında spesifikasyonlarla kod arasındaki uyumluluğu kontrol eden otomasyonlar kurmak faydalı olacaktır.

Gelecekte, AI’ın yazılım geliştirme süreçlerindeki rolü daha da artacak. Spec Kit gibi araçlar, bu AI devriminin temel taşlarından biri olacak. Yapılandırılmış ve makine tarafından okunabilir spesifikasyonlar, AI’ın daha karmaşık görevleri yerine getirmesini, daha akıllıca hatalar bulmasını ve hatta yeni mimari kararlar almasına yardımcı olmasını sağlayacak. Biz geliştiricilere düşen görev ise, bu araçları etkin bir şekilde kullanarak, daha sürdürülebilir, güvenilir ve verimli yazılımlar inşa etmektir. AI ile çalışırken “vibe”a değil, “spec”e güvenmek, geleceğin anahtarı olacaktır.

Bu yolculukta, Spec Kit gibi araçlarla tanışmak ve Spec-Driven Development prensiplerini benimsemek, hem kendi verimliliğimizi artıracak hem de AI ile olan iş birliğimizi çok daha anlamlı ve sonuç odaklı hale getirecektir. Unutmayalım ki, AI’ın gücünden tam olarak faydalanabilmek, ona ne istediğimizi net bir dille anlatabilmemize bağlıdır ve Spec Kit bu dilin en önemli bileşenlerinden biridir.