Yapay Zekâ Ajanları Kodunuzu Neden Bozuyor? Yeni Standartla Sorunu Çözün

Bir gereksinim listesi yazdığınızı düşünün. Net, spesifik ve her şey yolunda gibi görünüyor. AI ajanı bu gereksinimleri okuyor, tam olarak ne istediğinizi yapıyor — ve hiç bahsetmediğiniz üç şeyi bozuyor.

Bu durumun sebebi ajanların "kötü" çalışması değil. Sorun, spesifikasyonun insan okur için yazılmış olması, makine için değil. İnsan geliştiriciler belirsizliği tolere eder, eksikleri deneyimleriyle doldurur ve geri dönüşü olmayan adımlardan önce soru sorar. AI ajanları ise boşlukları eğitim verilerinden ödünç aldıkları bilgilerle doldurur. Bazen bu durum sorunsuz sonuçlanır, bazense öğleden sonranızı mahvedecek kadar büyük bir hata ortaya çıkarır.

Bu sorunla defalarca karşılaştıktan sonra, sadece daha iyi komutlar yazmaya odaklanmak yerine spesifikasyon formatını yeniden düşünmeye başladım.

Neden spesifikasyon formatları artık yeterli değil?

IEEE 830, ISO/IEC 29148 ve GOST 34.602 gibi yaygın kullanılan standartlar onlarca yıl önce, AI kodlama ajanları var olmadan önce tasarlandı. Bu formatlar, "ne demek istediğimi biliyorsun" diyebilecek bir insan okur için geliştirildi. AI ajanlarıysa ne demek istediğinizi değil, ne yazdığınızı bilir. Bu ikisi arasındaki boşluk, çoğu yeniden çalışmanın temel nedeni haline geliyor.

ANSS: AI dostu spesifikasyon standardı

AI-Native System Specification Standard (ANSS), AI ajanlarını ikinci sınıf okurlar olarak değil, ilk sırada yer alan kullanıcılar olarak ele alan bir spesifikasyon formatıdır. Bu standardı kullanmaya başladıktan sonra dikkat çekici bir fark gözlemledim: projeleri doğru şekilde tamamlamak için yapılan 5-7 geri bildirim döngüsü, şimdi sadece 2-3’e düştü. Dahası, ajanlar kod yazmaya başlamadan önce spesifikasyonumdaki çelişkileri ortaya çıkarmaya başladı. Bu basit değişiklik bile kaybettiğimi fark etmediğim saatleri kurtardı.

ANSS’in işleyişindeki dört kritik mekanizma

1. Üç katmanlı işaretleme sistemi

Her bölüm, spesifikasyonun hangi amaçla kullanılacağını belirten bir etiketle sınıflandırılır:

• [D] Domain (Alan) — Ne inşa edileceği → Ürün sahibi, proje yöneticisi
• [E] Engineering (Mühendislik) — Nasıl inşa edileceği → Geliştirici, mimar
• [A] Agent (Ajan) — Ajanın nasıl çalışacağı → AI ajanları (okuması gereken ilk bölüm)

AI ajanları ilk olarak [A] bölümlerini okur. Tahminde bulunmadan çalışabilmeleri için gereken tüm bilgiler burada yer alır. Bu yaklaşım, insanlarla yapılan görüşmelerdeki belirsizlikleri ortadan kaldırır ve ajanların spesifikasyonu doğru şekilde yorumlamasını sağlar.

2. Değişmezler (Invariants)

Değişmezler, spesifikasyonun temel kurallarını tanımlayan ve ajanların ihlal etmemesi gereken koşullardır. Örneğin:

INV-001: Dış npm paketleri kullanılamaz
- Yasağı: require() yoluyla npm modüllerinin dahil edilmesi
- Gerekçe: Uygulama npm yüklemesi olmadan çalışmalıdır
- Kontrol: server.js dosyasında node_modules ithalatı yapılmamalıdır

Bu yapı, klasik spesifikasyonlarda yer alan "kodu minimal tut" gibi belirsiz ifadelerin yerini alır. Örneğin, bir ajan daha önce "minimal" bir kod tabanı istediğimde bunu üç npm paketi ekleyerek yorumlamıştı. Değişmezler ise bu tür yanlış yorumlamaların önüne geçer.

3. Ajan Denetimi (Agent Review)

Spesifikasyon yazıldıktan ve kodlama süreci başlamadan önce ajan, spesifikasyonu aşağıdaki kontrollerden geçirir:

• Bölümler arasındaki çelişkilerin tespit edilmesi
• Kenar durumların eksik bırakılıp bırakılmadığının kontrolü
• Kabul kriterlerinin yeterliliğinin değerlendirilmesi
• Değişmezlerle çelişen durumların araştırılması

Sert kural: 3’ten fazla sorun bulunması durumunda duraklatma. Devam etmeden önce düzeltme yapılmalıdır.

İlk kez bir ajanın "Spesifikasyonunda 5 çelişki buldum" dediğini duyduğumda, ne kadar çok saatlik yeniden çalışmayı önlediğimin farkına vardım.

4. Değişiklik Spesifikasyonu (Change Specification)

Güncellemelerde kullanılan standart yapı, değişikliklerin net bir şekilde belgelenmesini sağlar:

• Mevcut durumun tanımlanması
• Hedeflenen değişiklikler
• Değiştirilmemesi gerekenler (en kritik bölüm)
• Etki analizi
• Geri alma planı

"Değiştirilmemesi gerekenler" bölümü, klasik spesifikasyon formatlarında yer almayan ve iş akışına en fazla değer katan unsur olarak öne çıkıyor. Özellikle büyük ekipler ve uzun vadeli projelerde bu bölüm, istenmeyen değişikliklerin önüne geçilmesine yardımcı oluyor.

ANSS’in uygulama düzeyleri

ANSS, farklı proje büyüklüklerine ve karmaşıklık düzeylerine göre üç seviyede uygulanabilir:

• Temel (CORE): 15–20 sayfa

Botlar, SaaS uygulamaları, API’ler ve otomasyon projeleri için ideal. Projelerin yaklaşık %80’i bu düzeyde tamamlanabilir.

• Genişletilmiş (EXTENDED): 40–60 sayfa

Güvenlik, uyumluluk ve detaylı test süreçlerini kapsar.

• Kurumsal (ENTERPRISE): Tam standart

Bankacılık, düzenleyici endüstriler ve AI platformları gibi yüksek güvenlik ve uyumluluk gerektiren projeler için tasarlanmıştır.

Beş dakikada ANSS denemesi

ANSS’i hemen uygulamaya başlamak için hızlı bir başlangıç rehberi:

1. 1.1 bölümünü doldurun: Ne inşa edileceği ve kimler için olduğu hakkında iki cümlelik bir açıklama yazın.
2. 2.1 bölümünü doldurun: Alan terimleri sözlüğünü oluşturun (5–10 terim).
3. 2.5 bölümünü yazın: 3–5 adet değişmez kural belirtin.
4. 3.2 bölümünü tamamlayın: Kullanıcı hikayeleri ve kabul kriterleriyle spesifikasyonu zenginleştirin.
5. 2.4 bölümüne kullanılan teknoloji yığını hakkında bilgi ekleyin.

Hazırlanan spesifikasyonu AI ajanınıza verin ve kod yazmaya başlamadan önce Ajan Denetimi işlemini çalıştırın. Ajanın bulduğu sorunlara göz atın ve gerekiyorsa düzeltmeler yapın.

ANSS standardını kullanmaya başlamak için GitHub deposuna göz atabilirsiniz. Standart, MIT Lisansı altında yayınlanmış olup, Claude Code, Cursor ve GitHub Copilot gibi popüler AI kodlama araçlarıyla uyumludur. Depoda ayrıca iki adet tam spesifikasyon örneği bulunmaktadır.

AI ajanlarının kodlarınızı bozmasını artık doğal karşılamak zorunda değilsiniz. ANSS gibi AI dostu spesifikasyon standartları, hem geliştirme süreçlerini hızlandırıyor hem de hatalara karşı daha dirençli bir yapı sunuyor. Bu standartları benimseyerek, projelerinizin kalitesini artırmanın yanı sıra AI araçlarından maksimum verim alabilirsiniz. Geleceğin geliştirme süreçleri, insan zekası ve yapay zekanın birlikte çalıştığı senkronize bir ortamda şekilleniyor — ANSS de bu geleceğin önemli bir parçası olmaya aday.