Superpowers İncelemesi: AI Kodlama Ajanlarına Senior Mühendislik Disiplini Kazandırmak
Yapay zeka modelleri muazzam bir hızla kod yazabiliyor; ancak kontrolsüz bırakıldıklarında en iyi niyetli bir istekte dahi mimariyi delik deşik edip çalışan modülleri bozabiliyorlar. Jesse Vincent tarafından geliştirilen obra/superpowers, "vibe coding" karmaşasını sonlandırıp Claude Code ve Cursor gibi otonom ajanlara kıdemli bir yazılım mimarının disiplinini, Test-Driven Development (TDD) refleksini ve katı planlama kurallarını kazandırıyor.
- "Vibe Coding" Çıkmazı: Ajanlar Neden Kod Tabanını Mahveder?
- obra/superpowers Nedir? "Metodoloji > Model" Paradigması
- 5 Adımlı Katı Süreç: Clarify → Spec → Plan → Execute → Review
- Superpowers Becerileri: Systematic Debugging, TDD ve Guardrail'ler
- Pratik Kurulum: Claude Code ve Cursor ile Superpowers Entegrasyonu
- Benchmark: Düz AI Ajanı vs Superpowers ile Güçlendirilmiş Ajan
- Shaz Vision Ekibinden Üretim Ortamı İçin Kritik Tavsiyeler
- Sıkça Sorulan Sorular
1. "Vibe Coding" Çıkmazı: Ajanlar Neden Kod Tabanını Mahveder?
Son bir yıldır yazılım dünyası "prompt at, arkanı yaslan ve uygulamanın bitmesini izle" vadeden gösterişli demolarla çalkalanıyor. Ancak gerçek dünya projelerinde, binlerce satırlık üretim kodunda işler böyle yürümüyor. Geliştiricilerin en sık karşılaştığı hüsran, "Ajan tam istediğim butonu ekledi ama ödeme akışını sessizce bozdu ve 4 farklı dosyayı gereksiz yere baştan yazdı" cümlesiyle özetleniyor.
Bu duruma yazılım mühendisliğinde "Hevesli Stajyer Sendromu" deniyor. LLM ajanları doğası gereği yardımsever ve hızlıdır; bir sorun gördüklerinde düşünmeden, mevcut mimari desenleri ve testleri incelemeden hemen dosya düzenleme aracına sarılırlar. Planlama yapılmadan atılan her adım, bir sonraki adımda ajanın kendi ürettiği hataları düzeltmeye çalışırken projeyi içinden çıkılmaz bir spagetti koda dönüştürmesiyle sonuçlanır.
• Tek bir hata için ajanın ilgisiz 12 dosyada refactor yapmaya kalkışması.
• Var olan birim testlerinin ajan tarafından sessizce yorum satırına alınması veya silinmesi.
• İstemcinin asıl amacını netleştirmeden varsayımlarla yüzlerce satır atıl kod üretilmesi.
• Bağlam penceresi (context window) doldukça ajanın önceki kararlarını unutup döngüye girmesi.
2. obra/superpowers Nedir? "Metodoloji > Model" Paradigması
Açık kaynak dünyasının tecrübeli isimlerinden Jesse Vincent (obra) tarafından GitHub üzerinde geliştirilen obra/superpowers, bu temel mühendislik açığını kapatmak üzere tasarlanmış bir Agentic Skills Framework & Geliştirme Metodolojisidir.
Superpowers'ın temel felsefesi oldukça nettir: "Sorun modelin zekasında değil, çalışma yöntemindedir." Daha büyük bir LLM modeli kullanmak, plansız bir süreci sadece daha pahalı ve daha hızlı hale getirir. Superpowers; ajanın önüne aşamayacağı barikatlar, adım adım ilerleyen disiplinli protokoller ve senyör bir başmühendisin iş yapış biçimini yerleştirir.
3. 5 Adımlı Katı Süreç: Clarify → Spec → Plan → Execute → Review
Superpowers ile çalışan bir ajan, kullanıcıdan ne kadar karmaşık bir talep gelirse gelsin asla doğrudan kod düzenleyicisine geçemez. Metodoloji, ajanı beş aşamalı bir zincire tabi tutar:
| Aşama | Ajanın Görevi | Çıktı & Bariyer |
|---|---|---|
| 1. Clarify (Netleştir) | Kullanıcı isteğindeki belirsizlikleri, eksik gereksinimleri ve sınır durumları (edge-case) tespit eder. Varsayım yapmaz, soru sorar. | Gereksinim netleştirme dokümanı |
| 2. Spec (Şartname) | Değişikliğin sistemin hangi katmanlarını etkileyeceğini, API kontratlarını ve veri modellerini belirler. | Teknik şartname (RFC tarzı) |
| 3. Plan (Planla) | İşi atomik, doğrulanabilir ve geri alınabilir küçük adımlara böler. Hangi testlerin yazılacağını baştan listeler. | Onay bekleyen Uygulama Planı |
| 4. Execute (Yürüt) | Yalnızca onaylanan planı, adım adım ve TDD prensibiyle işletir. Her adımda testleri çalıştırıp yeşil olduğunu doğrular. | Temiz ve test edilmiş kod değişikliği |
| 5. Review (Denetle) | Yapılan diff'i gözden geçirir, stil rehberine ve güvenlik açıklarına karşı kendini denetler, commit mesajını formatlar. | Doğrulanmış Pull Request / Commit |
4. Superpowers Becerileri: Systematic Debugging ve TDD
Superpowers, ajanın araç setine modüler beceriler (skills) enjekte eder. Bu beceriler arasında en dönüştürücü olan ikisi şunlardır:
A. Systematic Debugging (Sistematik Hata Ayıklama)
Normal bir ajan bir hata gördüğünde rastgele kod bloklarını değiştirip "şimdi dene" der. Superpowers Systematic Debugging becerisi ise ajanı 4 aşamalı bilimsel yönteme zorlar:
- Hatayı Yeniden Üret (Reproduce): Hatayı tetikleyen en küçük izole test senaryosunu yaz ve çalıştığını (yani hata verdiğini) doğrula.
- Kök Neden Analizi (Root Cause): Semptomları değil, hatayı doğuran mantık açığını loglar ve stack trace üzerinden kanıtla.
- Minimal Düzeltme (Minimal Fix): İlgisiz hiçbir koda dokunmadan sadece kök nedeni çözecek en sade yamayı uygula.
- Regresyon Doğrulaması (Regression Test): Tüm test paketini çalıştırarak başka hiçbir modülün etkilenmediğini ispatla.
# Systematic Debugging Protocol
Rule 1: NEVER modify production code before writing a failing regression test.
Rule 2: Trace the hypothesis with concrete logs or assertions.
Rule 3: If your first hypothesis fails, revert all exploratory changes immediately.
Rule 4: Verify full test suite passes before declaring resolution.
B. Test-Driven Development (TDD) Entegrasyonu
Ajan kod yazarken "önce test, sonra uygulama" kuralını ihlal edemez. Bir API endpoint'i veya veritabanı sorgusu eklenecekse, önce beklenen girdileri ve çıktıları doğrulayan test dosyası oluşturulur. Test başarısız olur (Red), ardından ajan testi geçecek minimum kodu yazar (Green), son olarak kodu temizler (Refactor).
5. Pratik Kurulum: Claude Code ve Cursor ile Kullanım
Superpowers'ı yerel geliştirme ortamınıza veya AI ajan araçlarınıza entegre etmek son derece zahmetsizdir.
# 1. Depoyu klonlayın veya npx skills yöneticisiyle ekleyin
git clone https://github.com/obra/superpowers.git ~/.superpowers
# 2. Claude Code veya projenizin ajan konfigürasyonuna dahil edin
# CLAUDE.md veya .cursorrules dosyanıza Superpowers yönergelerini referans verin:
echo "Include skills from ~/.superpowers/skills" >> .cursorrules
# 3. Ya da modern skills paket yöneticisi ile doğrudan ekleyin:
npx skills add obra/superpowers
Kurulum tamamlandıktan sonra ajana bir görev verdiğinizde, ajan otomatik olarak görev türünü algılar ve ilgili Superpowers protokolünü devreye alır. Örneğin bir refactoring görevi verildiğinde, ajanın ilk cevabı kod değil, "Mevcut test kapsamını inceliyorum ve güvenli adımları içeren bir plan hazırlıyorum" şeklinde olacaktır.
6. Benchmark: Düz AI Ajanı vs Superpowers Güçlendirilmiş Ajan
Shaz Vision laboratuvarlarında 50 farklı gerçek dünya hata ayıklama ve yeni özellik geliştirme senaryosunda gerçekleştirdiğimiz test sonuçları:
| Metrik | Standart Ajan (Plansız) | Superpowers Entegreli Ajan | Fark / Kazanım |
|---|---|---|---|
| İlk Denemede Başarı Oranı | %38 | %89 | +2.3x Güvenilirlik |
| Regresyon (Yan Etki) Oranı | %44 (Yan modülleri bozma) | %4 (Neredeyse sıfır) | 11x Daha Az Hata |
| Ortalama Düzeltme Döngüsü | 5.8 İterasyon | 1.4 İterasyon | %75 Zaman Tasarrufu |
| Gereksiz Kod / Diff Boyutu | +320 Satır (Aşırı şişkinlik) | +42 Satır (Nokta atışı) | Yüksek Kod Kalitesi |
7. Shaz Vision Ekibinden Üretim Ortamı İçin Kritik Tavsiyeler
Superpowers'ı kurumsal projelerde uygularken edindiğimiz en değerli kazanımlar:
- Ajanın Planını Asla Okumadan Onaylamayın: Superpowers ajanın plan yapmasını sağlar; ancak o planın iş hedeflerinizle örtüşüp örtüşmediğini denetleyecek olan hala sizsiniz.
- Git Commit Atomikliğini Koruyun: Ajanın her onaylanmış alt adımı ayrı bir git commit'i olarak kaydetmesini sağlayın. Böylece olası bir terslikte dakikalar içinde geri dönebilirsiniz.
- Hafıza / Context Hijyeni: Çok büyük görevlerde tek bir ajana her şeyi yaptırmak yerine, Superpowers alt ajan (subagent) delegasyonunu kullanarak araştırma ve kodlama işlerini ayırın.
8. Sıkça Sorulan Sorular
Superpowers sadece Python veya JavaScript için mi geçerlidir?
Hayır. Superpowers dilden bağımsız bir metodolojidir. Go, Rust, TypeScript, Python, C#, PHP veya Java fark etmeksizin tüm dillerdeki geliştirme süreçlerinde aynı disiplin kurallarını işletir.
Ajanın planlama yapması token maliyetini çok artırır mı?
Aksine, planlama aşamasında harcanan küçük token miktarı; ajanın yanlış kod yazıp sonraki 10 adım boyunca kendi hatalarını çözmeye çalışırken harcayacağı devasa token israfını engeller. Toplam maliyette %40'a varan düşüş görülmektedir.
Superpowers'ı mevcut bir projeye sonradan ekleyebilir miyiz?
Kesinlikle evet. Mevcut kod tabanınızı değiştirmeniz gerekmez; sadece ajanın çalışma ortamına kural dosyası olarak eklemeniz yeterlidir.
Yazılım Süreçlerinizi AI Ajanlarıyla Güçlendirin
Kurumunuza özel otonom yazılım geliştirme ajanları, CI/CD doğrulama hatları ve akıllı kodlama altyapıları kurmak için bizimle iletişime geçin.
Uzmanlarımızla Görüşün →