Planlama Yapmadan AI Asistanlarıyla Çalışmanın Riskleri

Şöyle bir sahne hayal et: Aklında net bir özellik var. Favori AI kodlama asistanına giriyorsun, hızlıca bir istek yazıyorsun ve o da kod tabanının yarısını kendi başına yeniden yazıveriyor. Bir saat sonra, istediğin problemi değil de bambaşka bir problemi çözen, ama aslında çözmesini istemediğin şeyleri bozan bir PR ile karşılaşıyorsun.

Bu tanıdık geliyor mu? Yalnız değilsin. AI kodlama asistanları soru-cevap modellerinden kod düzenleyicilere evrildikçe, birçok geliştirici fark ediyor ki chatbot'larda işe yaran rahat prompts tarzı, gerçek repository'ler söz konusu olduğunda yetersiz kalıyor.

Çözüm daha detaylı prompt'lar yazmak değil. Bu asistanlara gönderdiğimiz belgeleri düşünme biçimimizde temel bir değişiklik yapmak.

Prompt mu, Spec mi? Aslında İkisi Farklı Şeyler

Prompt'ların ne için optimize edildiğini anlamak önemli: işe başlamak için. Hızlı açıklamalar, tek seferlik scriptler ve keşif niteliğindeki konuşmalar için harikalar. Bir prompt sohbet oturumunda yaşar, kısaltmalar kullanabilir ve genellikle sadece yazarın bildiği bağlamı varsayar.

Bu yaklaşım, sadece soru sorduğunuzda gayet iyi çalışıyor.

Ama bir AI asistanı paylaşılan kodu düzenleyecekse, terminal komutları çalıştıracaksa ve takım arkadaşlarının inceleyeceği branch'ler üretecekse? O zaman rahat prompt'unuz bir ödev niteliği kazanıyor. Ve ödevler, iyi ifade edilmiş sözcüklerden fazlasını gerektirir — doğru bağlamı, net sınırları, somut örnekleri ve doğrulama kriterlerini.

İşte spec'ler tam bu noktada devreye giriyor.

Bir spec, sadece daha güzel hazırlanmış bir prompt değil. Hangi problemi çözdüğünüzü, hangi davranışın değişmesi gerektiğini, neyin aynı kalması gerektiğini ve işin başarılı olup olmadığını nasıl anlayacağınızı belgeleyen yapılandırılmış bir belge. Prompt chat oturumu başladığında yok olurken, spec tüm iş akışı boyunca görünür kalır — asistanı yönlendirir, inceleyenleri bilgilendirir ve gelecekteki bakımcılara kararların neden alındığını açıklar.

İyi Bir AI-Agent Spec'i Nasıl Oluşturulur?

Yirmi sayfalık bir belge yazmanıza gerek yok. İhtiyacınız olan beş temel unsur:

1. Bağlam: Bu görev neden var? Hangi kullanıcı problemi veya teknik borç bunu tetikliyor? Asistanın bilmesi gereken kod tabanındaki kısıtlamalar neler?

2. Değiştirilecek davranış: Hangi spesifik işlevsellik değiştirilecek, eklenecek veya kaldırılacak? Somut olun — "X olduğunda kullanıcılar e-posta bildirimi almalı" ifadesi "bildirim sistemini iyileştir" cümlesinden çok daha net.

3. Korunması gereken kısıtlamalar: Kesinlikle değişmemesi gereken ne? Hangi mevcut işlevsellik, API kontratları veya performans özellikleri yerinde kalmalı?

4. Doğruluğa dair örnekler: İyi çalışmanın nasıl görüneceğini gösteren somut senaryolar. Given/When/Then formatı burada işe yarar, ama birkaç açık test case'i bile asistanın beklentilerinizi anlamasına yardımcı olur.

5. Doğrulama kriterleri: Bir inceleyici işin tamamlandığını nasıl anlayacak? Neyi kontrol etmeli? Hangi soruları sormalı?

Bu çerçeve, behavior-driven development (BDD) senaryoları, kabul kriterleri içeren issue şablonları veya tasarım belgeleriyle çalıştıysanız size tanıdık gelecektir. Spesifik format çok da önemli değil — önemli olan doğru bilgiyi paylaşılabilir ve incelenebilir bir şekilde sunmak.

Spec'ler İş Akışında Nerede Duruyor?

Spec'lerin en güzel yanlarından biri esneklikleri. İşinizi yavaşlatacak ayrı belgeler olmak zorunda değiller. Bir spec şu yerlerde yaşayabilir:

• Açık kabul kriterleri içeren bir GitHub issue
• Değiştirilen davranışı belirten bir PR açıklaması
• Feature dosyalarınızdaki bir BDD senaryosu
• Implementasyondan önce hafif bir tasarım notu
• OpenSpec veya GitHub Spec Kit gibi bu kalıbı resmileştiren araçlar

Anahtar nokta şu: bağlam ve inceleme kriterleri görünür ve kalıcı olmalı. Spec'iniz sohbet oturumu bittiğinde kaybolmamalı. İşinizle birlikte yolculuk etmeli ve takım arkadaşlarınıza somut bir değerlendirme noktası sunmalı.

Atama Katmanı: Niyeti Uygulamadan Ayırmak

İşler burada gerçekten ilginç hale geliyor.

En güçlü spec'ler küçük davranış sözleşmeleri gibi çalışır. Üç farklı soruyu ayırır:

1. Hangi davranış değişmeli? (Gereksinim)
2. Doğruluğu tanımlayan kısıtlamalar veya örnekler neler? (Kabul kriterleri)
3. Şu an için uygun görünen implementasyon yolu hangisi? (Teknik yaklaşım)

Bu sorular bağlantılı, ama tek bir instruction yığınına dönüşmemeli.

Bu neden AI kodlama asistanları için önemli? Çünkü niyeti ve implementasyonu çok erken karıştırdığınızda, asistan yanlış şeye optimize edebilir. Önerilen bir implementasyon detayına sadık kalırken aslında ihtiyacınız olan davranışı kaçırabilir. Ya da teknik olarak ilginç ama belirtilen problemi çözmeyen kod üretebilir.

Bir atama katmanı, gereksinimi sabit tutarken implementasyonun evrimleşmesine izin verir. Asistan kod tabanını okur, komplikasyonlar keşfeder ve yaklaşımını hassaslaştırırken, spec referans noktası olarak kalır: "Bu iş belirtilen gereksinimi karşıladı mı?"

Bu, mevcut kod tabanları için özellikle değerli. Çoğu mühendislik çalışması sıfırdan başlamaz — zaten var olan bir davranışı değiştirirsiniz. İyi bir spec der ki: mevcut davranış şu, değişmesi gereken de bu. İnceleyicilerin niyetinizi implementasyon detaylarından çıkarması gerekmez.

Bu Değişimi Yapmak

AI kodlama asistanlarını gelişmiş arama motorları gibi kullanmaya alışkınsanız, bu yaklaşım gereksiz detay gibi gelebilir. Ama alternatifini düşünün: paylaşılan kod üzerinde kontrolsüz değişiklikler, incelenmesi zor PR'lar ve hayal ettiğinizle tam uyumlu olmayan işler.

Spec odaklı AI işbirliğine geçiş, bürokrasi meselesi değil. Hem insanlara hem makinelere birlikte etkili çalışabilecekleri netliği sağlama meselesi.

Küçük başlayın. Bir sonraki sefere bir AI kodlama asistanını repository'nize göndermeden önce, beş dakika ayırıp bağlamı, davranış değişikliğini ve başarı kriterlerini yazın. Görünür bir yere koyun — PR açıklaması bile olsa yeter.

Gelecekteki siz ve takım arkadaşlarınız size teşekkür edecek.

Sonuç: AI kodlama asistantları güçlü işbirlikçiler. Onları işbirlikçi gibi davranın. Uygun bir brief verin, karşılığında incelemeye değer iş alın.