AI ajanları için iyi bir spesifikasyon nasıl yazılır

 (addyosmani.com)
110 puan yazan GN⁺ 2026-01-19 | 3 yorum | WhatsApp'ta paylaş
  • AI kodlama ajanına devasa bir spesifikasyonu tek seferde vermek düzgün çalışmaz; kilit nokta akıllı spesifikasyon yazımıdır
  • Önce yüksek seviyeli vizyonu sunup AI’nın ayrıntılı planı genişletmesine izin vermek, ardından Plan Mode içinde salt okunur olarak planı gözden geçirip kod yazma aşamasına geçmek önerilir
  • GitHub’daki 2.500’den fazla ajan yapılandırma dosyasının analizi, etkili bir spesifikasyonun şu 6 temel alanı içermesi gerektiğini gösteriyor: Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries
  • Büyük işler, tek bir dev prompt yerine modüler küçük görevlere bölünmeli ve yalnızca o görev için gerekli bağlam sağlanmalı; böylece kalite düşüşü önlenebilir
  • Spesifikasyona 3 aşamalı sınırlar (Always/Ask first/Never), öz doğrulama ve uygunluk testleri gömmek; bunları sürekli test edip yineleyerek geliştirmek, spesifikasyon temelli geliştirme iş akışının özüdür

TL;DR

  • Uygun düzeyde ayrıntı (yapı, stil, testler, sınırlar vb.) içeren açık bir spesifikasyon yazın
  • Büyük işleri tek parça bir prompt yerine küçük parçalara ayırmak önerilir
  • Planı önce salt okunur modda oluşturun, ardından uygulayın ve sürekli iyileştirin

Temel ilke: akıllı spesifikasyon yazımı

  • Sadece çok büyük bir spesifikasyonu AI ajanına vermek başarısız olur; çünkü bu yaklaşım hem context window sınırına hem de modelin attention budget sınırına takılır
  • “Akıllı spesifikasyon”, ajanı net biçimde yönlendiren, pratik bağlam boyutu içinde kalan ve projeyle birlikte evrilen bir belgedir
  • Claude Code, Gemini CLI gibi kodlama ajanlarını kullanma deneyimlerinden çıkarılan ilkeler bir çerçeve halinde düzenlenmiştir

İlke 1: Önce büyük resmi verin, ayrıntıların ilk taslağını AI hazırlasın

  • En baştan her şeyi aşırı ayrıntılı tasarlamaya çalışmak yerine, önce yalnızca hedef ifadesini ve birkaç temel gereksinimi netleştirerek başlayın
  • Bu ilk spesifikasyonu bir “ürün özeti” gibi konumlandırıp, ajanın buna dayanarak ayrıntılı spesifikasyonu genişletmesine izin veren yaklaşım önerilir
  • LLM tabanlı ajanlar, yüksek seviyeli talimatlar açık olduğunda ayrıntıları iyi tamamlar; ancak görev belirsizse kolayca başka yollara sapar
  • Bu yüzden asıl mesele, ajanın savrulmaması için en başta net bir görev tanımlamaktır

  • Plan Mode kullanımı

    • Claude Code’un Plan Mode özelliği, ajanı salt okunur durumda tutup yalnızca kod tabanını analiz etmesini ve ayrıntılı plan oluşturmasını sağlayan moddur
    • Shift+Tab ile Plan Mode’a girdikten sonra “ne yapmak istediğinizi” açıklarsanız, ajan mevcut kodu inceleyerek bir spesifikasyon taslağı hazırlar
    • Bu sırada planda mimari, en iyi uygulamalar, güvenlik riskleri ve test stratejisini de birlikte gözden geçirmesini isteyebilirsiniz
    • Plan, yanlış anlaşılmaya yer bırakmayacak kadar rafine edilene kadar Plan Mode’da kalın; ancak ondan sonra Plan Mode’dan çıkıp uygulama aşamasına geçin

  • Spesifikasyonu bağlam olarak kullanma

    • Kesinleşen spesifikasyonu SPEC.md gibi bir dosyaya kaydedin ve çalışırken yalnızca gereken bölümleri seçip ajanla yeniden paylaşın
    • Spesifikasyon dosyası oturumlar arasında kaldığı için, projeye yeniden başladığınızda da AI’yı aynı referans noktasına sabitlemeye yardımcı olur
    • Konuşma geçmişi uzadığında veya ajan yeniden başlatıldığında ortaya çıkan unutma sorununu azaltmaya yardımcı olur
    • Ekiplerde PRD’nin (ürün gereksinimleri belgesi) ortak referans olarak kullanılması gibi, insan ya da AI fark etmeksizin herkesin başvurduğu “tek referans belge” rolünü üstlenir

  • Hedef odaklı kalma

    • Yüksek seviyeli spesifikasyon, baştan tüm uygulama yöntemlerini yazmak yerine what/why üzerine odaklanmalı; somut how kısmı sonraya bırakılmalıdır
    • Kullanıcı hikâyeleri ve kabul kriterleri biçiminde kurgulayın: “Kullanıcı kim? / Neye ihtiyaç duyuyor? / Başarı nasıl görünür?”
    • GitHub Spec Kit de “neyi neden yaptığınıza dair yüksek seviyeli bir açıklama verin ve kodlama ajanının kullanıcı deneyimi ile başarı kriterleri etrafında ayrıntılı gereksinimler oluşturmasını sağlayın” akışını vurgular

İlke 2: Spesifikasyonu profesyonel bir PRD (veya SRS) gibi yapılandırın

  • AI spesifikasyonunu basit bir notlar yığını olarak değil, net bölümlere sahip yapılandırılmış bir belge olarak ele almak önemlidir
  • PRD veya sistem tasarım belgesi gibi kapsamlı ve düzenli bir yapı, içeriği harfi harfine yorumlayan AI için özellikle uygundur
  • GitHub’da 2.500’den fazla ajan yapılandırma dosyasının analiz edilmesi sonucunda, etkili spesifikasyonların ortak olarak 6 temel alan içerdiği görüldü

    • 1. Commands

      • Çalıştırılabilir komutları belgenin baş kısmına yerleştirin
      • Yalnızca araç adını yazmak yerine, bayraklar dahil tam komutu açıkça belirtin: npm test, pytest -v, npm run build

    • 2. Testing

      • Testlerin nasıl çalıştırılacağını, hangi framework’ün kullanıldığını, test dosyalarının konumunu ve beklenen coverage seviyesini açıkça belirtin

    • 3. Project Structure

      • Kaynak kodun, testlerin ve dokümantasyonun yerini net biçimde ayırın
      • Örnek: "src/ uygulama kodu içindir, tests/ birim testleri içindir, docs/ ise dokümantasyon içindir"

    • 4. Code Style

      • Stili uzun uzun anlatmaktansa tek bir gerçek kod parçası çok daha etkilidir
      • İsimlendirme kurallarını, biçimlendirme standartlarını ve tercih edilen çıktı örneklerini birlikte sunun

    • 5. Git Workflow

      • Branch isimlendirme kuralları, commit mesajı biçimi ve PR gereksinimleri belirtilirse ajan da bu akışı takip eder

    • 6. Boundaries

      • Ajanın asla dokunmaması gereken alanları açıkça belirtin
      • Secret’lar, vendor dizinleri, production ayarları, belirli klasörler vb.
      • GitHub araştırmasında “asla secret commit etmeyin” ifadesinin en sık görülen faydalı kısıt olduğu doğrulandı

  • Stack hakkında spesifik olun

    • “React projesi” gibi genel ifadeler kullanmak yerine, “React 18 + TypeScript + Vite + Tailwind CSS” gibi somut yazmak önemlidir
    • Sürümler ve temel bağımlılıklar birlikte yazılmalıdır; belirsiz spesifikasyonlar sonuçta belirsiz kod üretir

  • Tutarlı bir format kullanın

  • Spesifikasyonu toolchain’e entegre edin

    • Spesifikasyonu yalnızca bir belge olarak değil, sürüm kontrolü ve CI/CD ile bağlantılı “çalıştırılabilir bir artifact” olarak ele alın
    • GitHub Spec Kit, spesifikasyonu mühendislik sürecinin merkezine koyan 4 aşamalı gate workflow kullanır
      • Specify: Neyin neden yapıldığına dair üst düzey bir açıklama sunulur ve kodlama ajanı ayrıntılı spesifikasyonu üretir
      • Plan: İstenen stack, mimari ve kısıtları içeren teknik plan hazırlanır
      • Tasks: Spesifikasyon ve plan gerçek iş birimlerine bölünür, her biri test edilebilir boyutlara ayrıştırılır
      • Implement: Kodlama ajanı görevleri tek tek ya da paralel olarak işler

  • agents.md ile özelleşmiş persona

    • GitHub Copilot gibi araçlarda özelleşmiş ajan persona’ları tanımlanabilir
    • @docs-agent (teknik dokümantasyon), @test-agent (QA), @security-agent (kod inceleme) gibi rol ayrımları yapılabilir
    • Her agents.md dosyası, ilgili persona’nın davranış biçimini, komutlarını ve sınırlarını içeren odaklı bir spesifikasyon görevi görür

  • Agent Experience (AX) tasarımı

    • API’ler geliştirici deneyimine (DX) göre tasarlandığı gibi, spesifikasyonlar da ajan deneyimi (AX) gözetilerek tasarlanmalıdır
    • Temiz ve parse etmesi kolay bir format önemlidir
      • Ajanın kullanacağı API’nin OpenAPI şeması
      • LLM tüketimi için doküman özeti (llms.txt)
      • Açık tip tanımları
    • MCP (Model Context Protocol) gibi standartları izleyen spesifikasyonlar, ajanların daha istikrarlı biçimde anlamasını ve çalışmasını sağlar

  • Canlı bir belge olarak koruyun

    • Spesifikasyon, bir kez yazılıp biten bir belge değil; AI ile birlikte kararlar alındığında veya yeni gerçekler ortaya çıktığında sürekli güncellenen bir yapıdır
    • Spesifikasyon odaklı workflow yaklaşımında spesifikasyon; implementasyon, test ve görev ayrıştırmasını yönlendirir ve spesifikasyon doğrulanmadan bir sonraki aşamaya geçilmez
    • Bu spesifikasyon yalnızca AI için değil, geliştiricilerin tüm akışı denetlemesi ve AI çıktılarının gerçek gereksinimleri karşılayıp karşılamadığını doğrulaması için de temel bir araçtır

İlke 3: Görevleri modüler prompt’lara ve bağlama bölün

  • Her şeyi tek bir dev prompt’a doldurmak yerine, bağlamı aynı anda yalnızca tek bir göreve odaklanacak şekilde verin
  • Tüm projenin gereksinimlerini, kodunu ve talimatlarını tek bir prompt’a koymak, aksine kafa karışıklığını büyütmeyi kolaylaştırır
  • Yalnızca token sınırına takılma riski değil, “talimatların laneti (curse of instructions)” nedeniyle modelin odağı da hızla düşebilir

  • Talimatların laneti

    • Araştırma sonuçlarına göre, prompt’a ne kadar çok talimat veya veri yığılırsa, her bir talimata doğru şekilde uyma performansı gözle görülür biçimde düşer
    • GPT-4 veya Claude gibi güçlü modeller bile, aynı anda çok sayıda gereksinimi karşılamaları istendiğinde zorlanır
    • Örneğin 10 ayrıntılı kuralı madde madde verirseniz, ilk birkaçına uyup ilerideki kuralları giderek daha fazla görmezden gelme eğilimi ortaya çıkar
    • Daha iyi strateji yinelemeli odaklanmadır: aynı anda yalnızca tek bir alt probleme odaklanmak ve bittikten sonra bir sonrakine geçmek

  • Spesifikasyonu aşamalara veya bileşenlere bölün

    • Spesifikasyon belgesi uzunsa veya geniş bir kapsamı ele alıyorsa, onu birkaç parçaya bölmeyi düşünün
    • Örnek: “Backend API Spec” ve “Frontend UI Spec” bölümlerini ayrı başlıklar olarak ayırın
    • Backend üzerinde çalışırken frontend spesifikasyonunu her zaman birlikte vermek gerekmez
    • Çok ajanlı ortamlarda her alan için ayrı ajanlar veya alt süreçler de kullanılabilir
    • DigitalOcean AI rehberi de “kimlik doğrulama görevleriyle veritabanı şeması değişikliklerini aynı anda karıştırmayın” diye uyarır

  • Büyük ölçekli spesifikasyonlar için genişletilmiş TOC/özet

    • Ajana, önce tüm spesifikasyonu özetleyen genişletilmiş bir içindekiler tablosu (TOC) yazdırma yöntemi
    • Her bölümü birkaç temel nokta veya anahtar kelimeye sıkıştırın ve ayrıntıların bulunduğu yeri birlikte referans verin
    • Örnek: “Security: HTTPS kullanımı, API anahtarlarının korunması, girdi doğrulamasının uygulanması (tam spesifikasyon §4.2’ye bakın)”
    • Böyle hiyerarşik özetler oluşturulduğunda, prompt içinde sadece büyük resmi tutup ayrıntıları yalnızca gerektiğinde vermek mümkün olur
    • Genişletilmiş TOC bir tür indeks görevi görür; ajan da “aa, bir güvenlik bölümü varmış” diye fark edip ilgili kısmı talep eder
    • Bu tür hiyerarşik özet yaklaşımı, LLM’lerin üst düzey yapıyı korumasına yardımcı olur

  • Alt ajanlar veya “skill” kullanımı

    • Anthropic’in sözünü ettiği alt ajanlar (veya “skill”ler) gibi, rolleri ayrılmış çoklu ajanlar kullanılabilir
    • Her alt ajan belirli bir uzmanlık alanına göre yapılandırılır ve yalnızca o alana ait spesifikasyon parçasını alır
    • Örnek: Database Designer alt ajanı yalnızca veri modeli bölümünü, API Coder alt ajanı ise yalnızca API endpoint spesifikasyonunu bilir
    • Bu sayede her ajan daha küçük bir bağlam ve daha net bir rol ile daha yüksek doğruluk ve paralel çalışma sağlayabilir
    • Claude Code, kendi sistem prompt’u ve araçlarına sahip alt ajanlar tanımlamayı destekler

  • İş hacmi için paralel ajanlar

    • Birden fazla ajanı aynı anda çalıştırma yaklaşımı, geliştirici verimliliğinde bir sonraki adım olarak öne çıkıyor
    • Tek bir ajanın bitmesini beklemek yerine, birbiriyle çakışmayan işlere ajanları paralel olarak atayın
    • Simon Willison bunu “paralel kodlama ajanlarını benimsemek” diye tanımlıyor ve bunun şaşırtıcı derecede etkili ama zihinsel olarak oldukça yorucu olduğunu söylüyor
    • Kritik nokta, ajanların birbirlerinin işini bozmasını önlemek için görev kapsamlarını net biçimde ayırmaktır
    • LangGraph veya OpenAI Swarm gibi orkestrasyon framework’leri bu koordinasyona yardımcı olur,
    • Chroma gibi vektör veritabanları da paylaşılan bellek olarak kullanıldığında, ortak bağlama tekrarlı prompting yapmadan erişilebilir

  • Tek ajan vs çok ajan: ne zaman kullanılmalı

    Boyut Tek ajan Paralel/çok ajan
    Avantajlar Kurulumu basittir, ek yükü düşüktür, debug ve akış takibi kolaydır İş hacmi yüksektir; karmaşık bağımlılıklarla başa çıkabilir ve alan bazlı uzmanlaşma sağlar
    Dezavantajlar Büyük projelerde bağlam aşırı yüklenmesi, yineleme hızında düşüş, tek hata noktası Artan koordinasyon maliyeti, çakışma olasılığı, paylaşılan bellek ihtiyacı
    Uygun olduğu durumlar İzole modüller, küçük ve orta ölçekli projeler, erken prototipleme Büyük kod tabanları, kodlama-test-review ayrımı, bağımsız özellik geliştirme
    İpucu Spesifikasyon özeti kullanın, görev bazlı bağlamı güncelleyin, oturumları sık sık sıfırlayın Başta 2-3 ajanla sınırlı kalın, MCP ile araç paylaşın, sınırları netleştirin

  • Her prompt’u tek bir görev/bölüme odaklayın

    • Karmaşık çok ajanlı bir ortam olmasa bile, modülerliği manuel olarak fazlasıyla dayatabilirsiniz
    • Örnek: Spesifikasyon yazıldıktan sonra “Step 1: veritabanı şemasını uygula” aşamasında yalnızca spesifikasyonun Database bölümünü verin
    • Ana görev her değiştiğinde bağlamı yeniden kurarak, eski veya ilgisiz bilgilerin yarattığı dikkat dağınıklığını azaltın
    • Bazı rehberler, ana işlev değişimlerinde yeni bir oturum başlatmayı ve böylece bağlamı temizlemeyi önerir

  • Satır içi talimatlar ve kod TODO’larından yararlanma

    • Koda // TODO yorumlarıyla yapılacak işleri yazıp, ajanın bunları tek tek doldurmasını sağlama yöntemi
    • Her TODO, küçük bir görev için mini bir spesifikasyon işlevi görür
    • Sonuç olarak yapay zeka, “bu spesifikasyon parçasına göre yalnızca bu fonksiyonu uygula” şeklinde çok dar bir kapsama odaklanır

İlke 4: Öz denetim, kısıtlar ve insan uzmanlığını gömme

  • Spesifikasyonu yalnızca ajanın yapılacaklar listesi olarak değil, kaliteyi yöneten bir rehber olarak ele alın ve kendi uzmanlığınızı aktif biçimde yansıtın
  • İyi bir spesifikasyon, yapay zekanın nerelerde hata yapabileceğini önceden işaret eder ve bu noktalara guardrail koyar
  • Alan bilgisi, edge case’ler ve çeşitli “dikkat edilmesi gerekenler” ekleyerek yapay zekanın bağlamdan yoksun bir boşlukta çalışmasını engeller
  • Spesifikasyonu yapay zekanın koçu ve hakemi gibi düşünmek anlaşılmasını kolaylaştırır: doğru yaklaşımı yönlendirir, yanlış davranışı ise anında frenler
  • GitHub’ın 2.500’den fazla ajan dosyası analizine göre, en etkili spesifikasyonlar basit bir yasak listesi değil, 3 aşamalı bir sınır sistemi kullanır
    • Ajana ne zaman doğrudan ilerleyebileceğini, ne zaman durup sorması gerektiğini ve ne zaman tamamen durması gerektiğini açıkça söyler

    • ✅ Always do (her zaman yap)

      • Sormadan yerine getirilmesi gereken işler
      • Örn: “commit öncesi her zaman test çalıştır”, “style guide’daki naming convention’a her zaman uy”, “hataları her zaman monitoring servisine logla”

    • ⚠️ Ask first (önce sor)

      • İnsan onayı gerektiren işler
      • Örn: “veritabanı şemasını değiştirmeden önce sor”, “yeni dependency eklemeden önce sor”, “CI/CD ayarlarını değiştirmeden önce sor”
      • Teknik olarak mümkün olsa da etki alanı geniş olduğu için insan muhakemesi gerektiren değişiklikler burada elenir

    • 🚫 Never do (asla yapma)

      • Net hard stop alanları
      • Örn: “secret veya API key’leri asla commit etme”, “node_modules/ ya da vendor/ dizinlerini asla düzenleme”, “açık onay olmadan başarısız olan testleri kaldırma”
      • Araştırmada da “asla secret commit etme” ifadesinin en sık geçen faydalı kısıt olduğu doğrulandı

  • Öz doğrulamayı teşvik etme

    • Ajanın, spesifikasyona göre çıktısını kendisinin kontrol etmesini teşvik edin
    • Araçlar izin veriyorsa, kod üretiminden sonra unit test veya linting’i doğrudan çalıştırmasını iş akışına dahil edin
    • Prompt düzeyinde de yeniden kontrol talimatı verilebilir
      • Örn: “Uygulamadan sonra sonucu spesifikasyonla karşılaştır, tüm gereksinimlerin karşılanıp karşılanmadığını doğrula ve karşılanmayan maddeler varsa listele”
    • LLM’nin kendi çıktısını spesifikasyonla karşılaştırmasını sağlayarak eksikleri azaltma etkisi yaratır

  • Öznel denetim için LLM-as-a-Judge

    • Kod stili, okunabilirlik, mimari pattern’lere uyum gibi otomatikleştirilmesi zor ölçütlerde LLM-as-a-Judge yaklaşımını kullanın
    • İkinci bir ajan (veya ayrı bir prompt), ilk ajanın çıktısını spesifikasyondaki kalite kriterlerine göre inceler
    • Örn: “Bu kodun style guide’ımıza uyup uymadığını incele ve ihlalleri işaretle”
    • Hakem rolündeki ajan geri bildirim verir; bu geri bildirim uygulanabilir ya da düzeltme için tetikleyici olarak kullanılabilir

  • Uygunluk testleri

    • Willison, bir uygunluk paketi (conformance suite) oluşturulmasını öneriyor
    • Dilden bağımsız testlerdir (çoğu zaman YAML tabanlıdır) ve tüm uygulamaların mutlaka geçmesi gereken bir sözleşme işlevi görür
    • API geliştiriyorsanız, uygunluk paketi beklenen girdileri ve çıktıları tanımlar; ajanın ürettiği kodun bunların tümünü karşılaması gerekir
    • Spesifikasyonun Success bölümünde “conformance/api-tests.yaml içindeki tüm vakalardan geçmek zorunludur” gibi ölçütleri belirtin

  • Spesifikasyonda test kullanımı

    • Mümkünse, spesifikasyona ve prompt akışına test planını veya gerçek testleri doğrudan dahil edin
    • TDD’de olduğu gibi, test vakalarıyla gereksinimleri netleştirin
      • Örn: Success Criteria içinde “bu örnek girdi mutlaka şu çıktıyı üretmelidir”
    • Willison, sağlam bir test paketinin ajanlara fiilen süper güç verdiğini söylüyor
    • Çünkü test başarısız olduğunda anında doğrulama yapıp yineleme mümkün olur
    • Subagent yapısında, spesifikasyon ölçütlerini alıp kod çıktısını sürekli doğrulayan özel bir test ajanı da bulunabilir

  • Alan bilgisini yansıtma

    • Spesifikasyon, ancak deneyimli geliştiricilerin veya bağlamı bilen kişilerin bilebileceği gerçekçi içgörüleri içermelidir
    • Örn: Bir e-ticaret ajanı geliştirirken, “products” ile “categories” arasında çoktan çoğa ilişki olduğunu açıkça yazın
      • Yapay zekanın bunu kendiliğinden çıkaracağını varsaymayın
    • Belirli bir kütüphane zorluk çıkarıyorsa, sık düşülen tuzakları veya dikkat noktalarını da belirtin
    • Kendi mentorluk yaklaşımınızı spesifikasyona yedirmenin bir yoludur
      • Örn: “Library X kullanılırken Y sürümünde memory leak sorunu var, bu yüzden Z geçici çözümünü uygula”

  • Basit görevlerde minimalizm

    • Kapsamlı bir spesifikasyon önemli olsa da uzmanlığın bir kısmı, ne zaman sade kalmak gerektiğini bilmektir
    • Görece basit ve izole işlerde aşırı ayrıntılı spesifikasyon tersine kafa karışıklığını artırabilir
    • Örn: “sayfada bir div’i ortala” gibi bir görevde
      • “Çözümü sade tut, gereksiz markup veya stil ekleme” demek yeterli olabilir
    • Buna karşılık, “token yenileme ve hata işleme içeren bir OAuth akışı uygula” gibi karmaşık görevlerde ayrıntılı spesifikasyon gerekir
    • Pratik ölçüt, spesifikasyon yoğunluğunu görevin karmaşıklığına göre ayarlamaktır

  • Nihai kalite filtresi olarak insanı koruma

    • Spesifikasyon, yetkiyi ajana devreder ama nihai kalite sorumluluğu geliştiricide kalır
    • Ajan teknik olarak spesifikasyonu karşılamış olsa bile, his veya bağlam doğru gelmiyorsa kendi yargınıza güvenin
    • Gerekirse spesifikasyonu yeniden rafine etmek veya çıktıyı doğrudan elde düzenlemek de doğal sürecin parçasıdır
    • Willison, yapay zeka ajanlarıyla çalışmayı “çok tuhaf bir yönetim biçimi” olarak tanımlıyor ve bunun “insan bir stajyeri yönetmeye rahatsız edici derecede benzediğini” söylüyor
    • Sonuçta açık talimatlar (spesifikasyon), yeterli bağlam ve uygulanabilir geri bildirim sağlama görevi hâlâ insana aittir

İlke 5: Test edin, yineleyin, spesifikasyonu geliştirin (doğru araçları kullanın)

  • Spesifikasyon yazımını ve ajan geliştirmeyi tek seferlik bir iş olarak değil, yinelemeli bir döngü olarak görün
    • Hızlıca test etme, geri bildirim toplama, spesifikasyonu iyileştirme ve araçlarla kontrolleri otomatikleştirme akışı
  • İlk spesifikasyon nihai sürüm değil, döngünün başlangıç noktasıdır

  • Sürekli test

    • Tüm implementasyonların tamamlanmasını beklemeyin; önemli kilometre taşlarında veya fonksiyon bazında test ya da basit manuel kontroller yapın
    • Bir hata bulunursa olduğu gibi devam etmeyin; önce spesifikasyonu ya da prompt'u düzeltin
    • Özellikle otomatik testler çok etkilidir; testler varsa ajan doğrudan npm test gibi komutları çalıştırabilir
    • Test başarısızlığı sonuçlarını aynen bir sonraki prompt'un girdisi olarak kullanın
      • Örnek: “Çıktı X, Y, Z açısından spesifikasyonu karşılamıyor; bunu düzelt”
    • Kod → test → düzeltme → tekrar şeklinde ilerleyen ajanik döngü son derece güçlü bir yöntemdir

  • Spesifikasyonun kendisini yinelemek

    • Ajanın yanlış anladığı ya da gereksinim eksiklerinin ortaya çıktığı durumlarda, sorunu örtmeyin; önce spesifikasyon belgesini düzeltin
    • Güncellenmiş spesifikasyonu ajanla açıkça yeniden senkronize edin
      • Örnek: “Spesifikasyonu şu şekilde güncelledim. Bu değişikliği yansıtacak biçimde planı ayarla veya kodu refactor et”
    • Spesifikasyonu her zaman tek doğruluk kaynağı olarak koruyun
    • Mümkünse commit mesajları veya notlarla sürüm geçmişi bırakın; böylece neyin neden değiştiği izlenebilir

  • Bağlam yönetimi ve bellek araçlarını kullanma

    • AI ajanlarının bağlam ve bilgi yönetimine yardımcı olan araç ekosistemi hızla büyüyor
    • RAG (retrieval-augmented generation) yaklaşımı kullanılırsa, ajan vektör veritabanı gibi bir bilgi tabanından yalnızca gerekli bilgiyi anında çekebilir
    • Spesifikasyon çok büyükse, bölümleri embedding olarak saklayıp ajanın tüm metni almak yerine yalnızca en ilgili kısımları aramasını sağlayın
    • MCP (Model Context Protocol) tabanlı çerçeveler, mevcut göreve uygun bağlamı otomatik olarak sağlar
    • Context7(context7.com) gibi araçlar, üzerinde çalışılan içeriğe göre belgelerden ilgili snippet'leri otomatik olarak getirir

  • Dikkatli paralelleştirme

    • Bazı geliştiriciler hızı artırmak için birden çok ajan örneğini farklı görevlerde paralel olarak çalıştırır
    • Örnek: bir ajan kod üretirken, başka bir ajan aynı anda test yazar
    • Bu yaklaşım seçilecekse, çakışmaları önlemek için görevlerin gerçekten bağımsız ya da açıkça ayrılmış olması gerekir
    • Örnek: iki ajanın aynı dosyayı aynı anda değiştirmesini engelleyecek kısıtlar koyun
    • Yönetim yükünü azaltmak için başlangıçta en fazla 2–3 ajanla başlamak gerçekçidir

  • Sürüm kontrolü ve spesifikasyonu kilitleme

    • Ajanın çalışmalarını Git gibi sürüm kontrol araçlarıyla dikkatle takip edin
    • AI kullandıkça iyi sürüm kontrolü alışkanlıklarının önemi daha da artar
    • Spesifikasyon dosyasının kendisini de depoya commit ederek değişiklik geçmişi bırakın
    • Ajan da git diff veya blame çıktısını okuyup değişiklik bağlamını anlayabilir
      • Gerçekten de LLM'ler diff yorumlamada oldukça iyidir
    • Spesifikasyonun repoda bulunması, hem geliştiricilerin hem de AI'ın projenin evrimini birlikte izlemesini sağlar
    • Willison, modelleri “Git konusunda ürkütücü derecede yetkin” olarak tanımlıyor

  • Maliyet ve hız değerlendirmeleri

    • Büyük modeller ve uzun bağlam kullanan işler yavaş ve maliyetli olabilir
    • Model seçimini stratejik olarak ayırın
      • İlk taslaklar veya tekrarlı işler için hızlı ve ucuz modeller
      • Nihai çıktı veya karmaşık akıl yürütme için en yetkin (ve pahalı) modeller
    • Örnek: GPT-4 veya Claude planlama ve kritik aşamalar için; basit genişletmeler ya da refactor işlemleri için yerel modeller veya küçük API modelleri kullanılabilir
    • Test çalıştıran ajanlar ya da linter ajanları için nispeten küçük modeller de yeterlidir
    • Bağlam boyutu da yönetilmesi gereken bir unsurdur

  • Her şeyi izleyin ve loglayın

    • Karmaşık ajan iş akışlarında, ajanın davranış ve çıktı logları vazgeçilmezdir
    • Loglar sayesinde ajanın niyetten sapıp sapmadığını veya hata oluşup oluşmadığını kontrol edebilirsiniz
    • Birçok framework trace logları sunar ya da adım adım düşünme sürecini çıktı olarak vermeyi destekler
    • Logları incelemek, spesifikasyonun veya talimatların hangi noktada yanlış yorumlandığını ortaya çıkarır

  • Öğrenme ve iyileştirme

    • Her projeyi, spesifikasyon yazma becerisini geliştiren bir öğrenme fırsatı olarak görün
    • Hangi ifadelerin AI'ı tekrar tekrar şaşırttığını ve hangi spesifikasyon yapılarının daha iyi uygulandığını gözlemleyebilirsiniz
    • Bu dersleri bir sonraki spesifikasyona aktif biçimde yansıtın
    • AI ajanları alanı hızla gelişiyor; yeni araçlar ve en iyi uygulamalar sürekli ortaya çıkıyor

Sık yapılan hatalardan kaçının

  • GitHub'daki 2.500'den fazla ajan dosyasının analizine göre, başarısızlığın en büyük nedeni spesifikasyonların ve talimatların aşırı belirsiz olmasıdır

  • Belirsiz prompt'lar

    • “Bana havalı bir şey yap”, “Daha iyi çalışır hale getir” gibi isteklerde ajan için değerlendirme ölçütü yoktur
    • Girdi, çıktı ve kısıtları olabildiğince somut biçimde belirtmek gerekir
    • “Sen yardımcı bir kodlama asistanısın” gibi genel rol tanımları neredeyse hiç etkili değildir
    • Buna karşılık “Sen React component testleri yazan bir test mühendisisin; bu örneği izle ve kaynak kodu asla değiştirme” gibi rolü, kapsamı ve kısıtları birlikte tanımlayan talimatlar çok daha iyi çalışır

  • Özetsiz aşırı bağlam

    • 50 sayfalık bir belgeyi olduğu gibi prompt'a döküp modelin bunu kendi kendine anlamasını beklemek çoğu zaman başarısız olur
    • Şu anki görevle doğrudan ilgili içerikleri öne çıkarmak için hiyerarşik özetleme veya RAG kullanmak gerekir
    • Bağlam uzunluğunu artırmak, bağlamın kalitesizliğini telafi etmez

  • İnsan incelemesini atlamak

    • Willison'ın kişisel ilkesi: “Başkasına açıklayamadığım kodu commit etmem”
    • Ajanın testlerden geçen bir şey üretmiş olması, o kodun otomatik olarak doğru, güvenli ve bakımı yapılabilir olduğu anlamına gelmez
    • Özellikle kritik kod yolları her zaman insan tarafından doğrudan gözden geçirilmelidir
    • AI tarafından üretilen kod dışarıdan sağlam görünebilir, ancak test edilmemiş uç durumlarda çökebileceği için “iskambil kâğıdından yapılmış ev” benzetmesi yerindedir

  • Vibe coding ile production engineering'i karıştırmak

    • AI destekli hızlı prototipleme, yani “vibe coding”, keşif aşamaları veya tek seferlik projeler için uygundur
    • Sıkı spesifikasyon, test ve inceleme olmadan bu çıktıları doğrudan production'a almak büyük sorunlara yol açabilir
    • “Vibe coding” ile “AI destekli mühendislik” net biçimde ayrılmalıdır; ikincisi, bu rehberde açıklanan disiplin ve süreçleri gerektirir
    • Şu anda hangi modda çalıştığınızın farkında olmanız önemlidir

  • “Ölümcül üçlü”yü görmezden gelmek

    • Willison'ın, AI ajanlarını tehlikeli kılan üç özellik olarak uyardığı unsurlar
      • Hız: insanın inceleyebileceğinden daha hızlı sonuç üretmeleri
      • Belirlenimsizlik: aynı girdide bile her çalıştırmada farklı çıktı vermeleri
      • Maliyet: yeterli doğrulama yerine kestirme yollara yöneltmesi
    • Spesifikasyon ve inceleme süreçleri bu üçünü de baştan varsayacak şekilde tasarlanmalıdır
    • Özellikle hızın doğrulama kapasitesinin önüne geçmemesi için bilinçli kontrol gerekir

  • 6 temel alanı atlamak

    • Spesifikasyon Commands, Testing, Project Structure, Code Style, Git Workflow ve Boundaries konularını kapsamıyorsa, ajanın iş için gerekli kritik bilgileri kaçırması kolaylaşır
    • Ajana vermeden önce 6 alanlık kontrol listesiyle bir kez daha gözden geçirmek güvenlidir

Sonuç

  • AI kodlama ajanları için etkili bir spesifikasyon yazmak, sağlam yazılım mühendisliği ilkeleri ile LLM'lerin özelliklerini anlayıp buna göre uyarlayan bir yaklaşımın birlikte kullanılmasını gerektirir
  • Her şey amacı net biçimde tanımlamakla başlar; bunun üzerine AI'nın planı ve ayrıntıları genişletmesine izin verecek bir rol paylaşımı kurulur
  • Spesifikasyon, bir not değil ciddi bir tasarım belgesi olarak ele alınmalı; 6 temel alanı içermeli ve araç zinciriyle bağlantılı çalıştırılabilir bir artifact olarak görülmelidir
  • Her şeyi tek seferde vermek yerine, görev birimlerine bölerek sunmak ajanın odağını korur
    (özet TOC, alt ajanlar, paralel orkestrasyon; büyük ölçekli spesifikasyonları yönetmek için pratik araçlardır)
  • 3 aşamalı sınır (Always / Ask first / Never), öz denetim ve uygunluk testleriyle, AI'nın kolayca düştüğü tuzaklar önceden engellenebilir
  • Spesifikasyon ve uygulamayı sabit çıktılar olarak değil, yinelenen bir süreç olarak ele almak; test ve geri bildirim yoluyla spesifikasyonu ve kodu birlikte sürekli iyileştirmek kritik önemdedir
  • Bu yönergeler izlenirse, AI ajanlarının büyük bağlamlarda yönünü kaybetme veya saçmalamaya sapma olasılığı belirgin biçimde azaltılabilir

İlgili okumalar

3 yorum

 
gomjellie 2026-01-22

Yapay zeka çevirisi olsa da Korece çevirisi mevcut, bu yüzden bağlantıyı paylaşıyorum.

https://rosetta.page/post/…
 
qor0923 2026-01-20

Teşekkür ederim.
 
googol 2026-01-19

Ben kişisel olarak bir projeyi SDD (Specs Driven Development) ile geliştirdiğimde, başlangıçta belirgin bir verimlilik artışı hissettim; ancak hâlâ tüm kodu spesifikasyon tabanlı yazamıyorum ve ne zaman elle düzeltme gerekse hem kodu hem de spesifikasyonu birlikte güncellemek gerektiği için, aksine verimliliğin düştüğünü deneyimledim.