Cursor ve Claude Code: Otonom Refactoring Regresyonlarını Önleyen 5 Prompt Chaining Deseni

Giriş

Otonom kod ajanlarına (Cursor Composer, Claude Code) birden fazla dosyayı kapsayan refactoring yetkisi vermek, geliştirme döngüsünde %15-20 zaman kazancı sağlasa da, geri alınması 3-4 gün süren sessiz regresyonlara yol açabilir. Transformer mimarisine dayalı modeller (Claude 3.5 Sonnet, GPT-4o), 200k token bağlam penceresi (context window) sunmalarına rağmen, 80k token üzerinde dikkat hatırlama (attention recall) oranları %95’ten %73 seviyelerine düşer. Bu dikkat azalması, ajanın 800 satır uzaktaki bir retry mekanizmasını veya dokümante edilmemiş bir metrik çağrısını gereksiz kod sanıp silmesiyle sonuçlanır.

Bu problemi çözmenin yolu, tek ve devasa bir “Şu modülü refactor et” komutu (zero-shot prompt) yerine, Prompt Chaining (Prompt Zincirleme) kullanmaktır. Prompt chaining, büyük refactoring görevlerini deterministik, doğrulanabilir ve sınırlandırılmış alt adımlara böler. Bu makalede, production ortamında bizzat test edilmiş ve SonarQube regresyon oranlarını %18’den %1.2’ye düşürmüş 5 mimari prompt zinciri desenini inceleyeceğiz.

İçindekiler

• Desen 1: Arayüz Sabitleme (Contract-First Constraint)
• Desen 2: Gölge Test Zinciri (Test-Driven Shadowing)
• Desen 3: Bağımlılık İzolasyonu (Dependency Stubbing)
• Desen 4: Durum Makinesi Doğrulaması (State-Machine Verification)
• Desen 5: Telemetri ve Yan Etki Kilitleme (Side-Effect Locking)
• Pratik Öneriler / Production Notları
• Sık Sorulan Sorular
• Sonuç

Desen 1: Arayüz Sabitleme (Contract-First Constraint)

Problem

Ajan, bir sınıfı veya modülü refactor ederken, dışarıya açılan (public) API imzalarını (DTO’lar, metod parametreleri, dönüş tipleri) değiştirir. Bu durum, modülü tüketen (consume eden) diğer 15 farklı dosyada derleme hatalarına veya daha kötüsü runtime type hatalarına neden olur.

Çözüm

Refactoring işlemini iki kesin adıma bölmek: İlk zincir adımı sadece mevcut public arayüzü çıkarır ve kilitler. İkinci adım, refactoring işlemini yapar ancak birinci adımda çıkarılan arayüze kesinlikle uymaya zorlanır.

Çalışan Kod / Konfigürasyon

Cursor içinde .cursorrules dosyasına veya ardışık promptlara şu zinciri ekleyin:

{
  "prompt_chain": [
    {
      "step": 1,
      "instruction": "Read src/payment/Processor.ts. Extract all public methods, parameter types, and return types into a strict TypeScript Interface. Do NOT output any implementation logic. Output ONLY the interface code wrapped in  tags."
    },
    {
      "step": 2,
      "instruction": "Refactor the internal logic of src/payment/Processor.ts to use the new RetryPolicy module. CONSTRAINT: The refactored class MUST strictly implement the interface extracted in . Do not add, remove, or modify any public method signatures."
    }
  ]
}

Ne Zaman Uygulanır?

Geniş bir codebase içinde, bağımlılığı yüksek (high-fan-in) core servislerde veya shared kütüphanelerde yapısal değişiklikler yapılırken.

Ne Zaman Uygulanmaz?

Sadece tek bir izole script üzerinde çalışırken veya amaç zaten API imzasını değiştirmek/modernize etmek olduğunda (örneğin callback’ten Promise yapısına geçerken).

Desen 2: Gölge Test Zinciri (Test-Driven Shadowing)

Problem

Test kapsamı (coverage) %20’nin altında olan legacy kodlarda (örneğin 5 yıllık bir faturalandırma modülü) ajanın yaptığı refactoring, edge case’leri (uç durumları) yok eder. Ajan, “spagetti” kodu temizlerken, o spagettinin içindeki kritik bir vergi hesaplama istisnasını atlar.

Çözüm

Ajan refactoring yapmadan önce, mevcut kodun davranışsal bir kopyasını çıkaran (snapshot test) bir gölge test iskeleti oluşturmasını sağlamak. Refactoring bittikten sonra bu testler doğrulanır.

Çalışan Kod / Konfigürasyon

Claude CLI (veya benzeri terminal tabanlı AI toolları) kullanarak bash üzerinde bir pipeline:

# Adım 1: Mevcut davranış için exhaustive (kapsamlı) testler yaz
claude -p "Analyze legacy_billing.js. Write a Jest test suite (billing.test.js) that covers 100% of the current functional branches, including mocked edge cases. DO NOT refactor legacy_billing.js yet."

# Adım 2: Testlerin mevcut koda karşı yeşil (pass) olduğunu doğrula
npm run test billing.test.js || exit 1

# Adım 3: Şimdi refactor et
claude -p "Refactor legacy_billing.js to use the Strategy pattern. It MUST pass the existing billing.test.js without modifying the tests."

# Adım 4: Regresyon kontrolü
npm run test billing.test.js

Ne Zaman Uygulanır?

İş kurallarının yoğun olduğu (vergi, sepet tutarı, indirim kuponu hesaplama) ve manuel testin saatler süreceği domain logic modüllerinde.

Ne Zaman Uygulanmaz?

UI bileşenleri (React component styling) veya tamamen boilerplate kod (CRUD controller) refactoring işlemlerinde. Bu alanlarda test yazma maliyeti elde edilecek faydayı aşar.

Desen 3: Bağımlılık İzolasyonu (Dependency Stubbing)

Problem

Ajan, 10 farklı import içeren 1500 satırlık bir dosyayı incelerken, import edilen dosyalardaki RedisCache veya AuthGuard gibi sınıfların iç yapısını halüsinasyon (hallucination) görerek uydurur. Olmayan metodları çağırır, derleme anında TypeError: undefined is not a function hatası alırsınız.

Çözüm

Hedef modülü ajana vermeden önce, bağımlılıkların AST (Abstract Syntax Tree) üzerinden sadece imzalarını (stub/mock) çıkarıp ajana sadece bu sınırlı bağlamı vermek. Böylece token limiti düşer, dikkat (attention) hedefe odaklanır.

Çalışan Kod / Konfigürasyon

# AST kullanarak bağımlılıkların stub'larını çıkaran bir script
import ast

def extract_stubs(filepath):
    with open(filepath, "r") as f:
        tree = ast.parse(f.read())
    stubs = []
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            stubs.append(f"def {node.name}(): pass")
        elif isinstance(node, ast.ClassDef):
            stubs.append(f"class {node.name}: ...")
    return "
".join(stubs)

# Zincir Mantığı:
# 1. extract_stubs('database.py') çıktısını al
# 2. Ajana ver: "İşte kullanacağın database modülünün stub'ları: . Sadece bunları kullanarak target.py'yi refactor et."

Ne Zaman Uygulanır?

Dosya boyutunun ve import edilen ağacın çok derin olduğu, LLM bağlam penceresinin 40k token üzerine çıktığı monorepo mimarilerinde.

Ne Zaman Uygulanmaz?

Microservice içindeki zaten izole ve küçük (under 300 LOC) modüllerde. Burada doğrudan agent’a dosyanın tamamını vermek daha az işlem gerektirir.

Desen 4: Durum Makinesi Doğrulaması (State-Machine Verification)

Problem

Asenkron (async/await) veya event-driven (olay güdümlü) kodlarda, ajan refactoring yaparken bir state geçişini siler. Örneğin try/catch bloğundaki catch içinde isLoading = false yapılmasını unutur. Bu, arayüzde sonsuz yükleme (infinite spinner) veya backend’de kilitlenme (deadlock) yaratır.

Çözüm

Zincirin ilk adımında kodun mantıksal State Machine (Durum Makinesi) diyagramını (Mermaid formatında) çıkarttırmak. Refactoring sonrasında yeni kodun diyagramını tekrar çıkartıp, ilk diyagram ile karşılaştırmak.

Çalışan Kod / Konfigürasyon

# Prompt Chain Step 1
Analyze `OrderSaga.ts`. Generate a strict Mermaid state diagram capturing all state transitions (e.g., PENDING -> PAID, PENDING -> FAILED).
Output only the mermaid code block.

# Prompt Chain Step 2
Refactor `OrderSaga.ts` to replace nested Promises with async/await and centralize error handling.

# Prompt Chain Step 3
Analyze the NEW `OrderSaga.ts`. Generate a Mermaid state diagram.
Compare this new diagram with the diagram from Step 1. If any transition (e.g., error fallbacks) is missing, output 'REJECT: Missing transition ' and fix the code.

Ne Zaman Uygulanır?

Redux reducer’ları, Saga pattern uygulamaları, ödeme akışları veya WebRTC bağlantı durumları gibi state mutasyonunun kritik olduğu yerlerde.

Ne Zaman Uygulanmaz?

Statik (stateless) utility fonksiyonlarında (örneğin string formatlama, tarih dönüştürme). Bu tür kodlarda state geçişi olmadığı için bu zincir gereksiz karmaşıklık yaratır.

Desen 5: Telemetri ve Yan Etki Kilitleme (Side-Effect Locking)

Problem

LLM’ler doğaları gereği “optimizasyon” ve “kod temizleme” eğilimindedir. Bir fonksiyonun ana iş mantığına katkı sağlamadığını düşündüğü Datadog.increment('checkout.failed') veya Kafka.emit('UserCreated') gibi kritik telemetri ve audit-log satırlarını “dead code” sanıp silerler.

Çözüm

Zincirlemenin başında, codebase içindeki tüm yan etki (side-effect) yaratan fonksiyon çağrılarının tam listesini çıkarıp bunları bir kilit (lock) dosyasına kaydetmek. Ajanı, bu çağrıların tamamını yeni koda enjekte etmesi yönünde kesin bir kural ile (constraint) sınırlandırmak.

Çalışan Kod / Konfigürasyon

# Cursor Custom Rule (.cursorrules)
side_effect_locking:
  trigger: "Refactor any service class"
  chain:
    - step: 1
      action: "Regex scan for `Metrics.*`, `Logger.*`, `EventBus.*` in the target file."
      output: "Create a checklist of exact side-effect lines."
    - step: 2
      action: "Perform the requested refactoring."
    - step: 3
      action: "Audit the refactored code against the checklist. Ensure EVERY telemetry and event line exists in the correct logical branch. If missing, restore them before presenting the final code."

Ne Zaman Uygulanır?

Production ortamında monitoring ve alerting altyapısının doğrudan loglara veya metrik fırlatmalara (metric emission) bağlı olduğu tüm backend servislerinde.

Ne Zaman Uygulanmaz?

PoC (Proof of Concept) projelerinde veya lokal ortamda çalışan, production telemetrisi içermeyen geçici scriptlerde.

Pratik Öneriler / Production Notları

Otonom ajanları production CI/CD pipeline’larına veya günlük geliştirme süreçlerine entegre ederken şu metrikleri ve checklist’i göz önünde bulundurun:

• Diff Limitleri: Ajanın tek bir zincirde değiştirebileceği satır sayısını kısıtlayın. 400 satırın üzerindeki diff’ler, insan tarafından code review sürecinde bilişsel yük (cognitive load) yaratır ve gözden kaçan regresyonlara sebep olur.
• Observability (Gözlemlenebilirlik): Ajan tarafından refactor edilmiş modülleri canlıya alırken Datadog veya New Relic üzerinden p99 latency metriklerini izleyin. Ajan, O(N) karmaşıklığındaki bir döngüyü fark etmeden O(N^2) karmaşıklığına çıkaran süslü bir functional map/reduce zincirine çevirmiş olabilir.
• Fallback Stratejisi: Eğer ajan 3 defa zincir doğrulama adımından (örneğin gölge testleri geçememe) kalırsa, otonom işlemi iptal edin ve AST tabanlı deterministik araçlara (JSCodeshift, AST-Grep) geri dönün (fallback).

Sık Sorulan Sorular

Prompt chaining kullanmak token maliyetini (API Cost) artırmıyor mu?

Evet, bir zincir 3-4 LLM çağrısı gerektirdiğinden doğrudan prompt maliyetini artırır. Ancak, 1.20$ tutan bir API maliyeti, bir Senior Developer’ın sessiz bir regresyonu debug etmek için harcayacağı 4 saatin (yaklaşık 200$) yanında istatistiksel olarak önemsizdir.

Neden tek bir prompt içine tüm kuralları yazmıyoruz?

Araştırmalar, LLM’lere tek bir prompt içinde 4’ten fazla kompleks görev (instruction) verildiğinde, talimatlara uyum (instruction adherence) oranının %45’e kadar düştüğünü göstermektedir. Ajan, refactoring yapmaya odaklandığında test yazmayı veya telemetriyi unutur. Zincirleme, bu bilişsel yükü ayrıştırır.

Cursor Composer ile Claude CLI arasındaki fark nedir?

Cursor Composer IDE içine entegredir, dosya sistemi bağlamını (workspace context) otomatik yönetir ve UI üzerinden diff onayı sunar. Claude CLI ise CI/CD pipeline’larında (GitHub Actions/GitLab CI) gözetimsiz (headless) agentik zincirler kurmak için idealdir.

Ajanın çıkardığı gölge testlerin (Shadow Tests) hatalı olma ihtimali yok mu?

Vardır. Bu nedenle gölge testlerin temel amacı kodun doğru çalışıp çalışmadığını test etmek değil, kodun mevcut halinin (hatalıysa bile hatalı halinin) birebir davranışsal imzasını (snapshot) kilitlemektir. Amaç refactoring sırasında mevcut işleyişi değiştirmemektir.

Sonuç

Otonom AI kod ajanları (Cursor ve Claude Code), geliştirici üretkenliğini devasa ölçekte artırma potansiyeline sahiptir; ancak kontrolsüz bırakıldıklarında production ortamında felaketlere yol açabilirler. Arayüz sabitleme, gölge testler, bağımlılık izolasyonu, durum makinesi doğrulaması ve telemetri kilitleme desenleri, deterministik olmayan LLM’leri deterministik yazılım mühendisliği standartlarına uymaya zorlar.

Hemen bugün, ekibinizin en çok regresyon yaşadığı bir backend servisinde Gölge Test Zinciri (Test-Driven Shadowing) desenini uygulayarak ajan bazlı refactoring işlemlerindeki hata oranını ölçümlemeye başlayın.