Kodlama ajanıyla ürün geliştirirken işin önemli bir kısmı, ajanın hangi bilgiye göre karar vereceğini tasarlamak. Monafy’de bunu çalışma alanının kökündeki CLAUDE.md dosyası ve repolara özgü kısa talimatlarla yapıyorum. Dosya, geliştirme sürecinde tekrar tekrar ihtiyaç duyulan kararları görünür tutuyor.
Ürünün ne yapacağını, teknik sınırları ve kabul kriterlerini başta belirliyorum. Ajan bu çerçevede uygulamayı geliştiriyor. Kullanışlı bir talimat dosyası da bu sorumluluk paylaşımını, bir işin nasıl doğrulanacağını ve belirsizlikte hangi kaynağa dönüleceğini açıklıyor.
Önce hangi bilginin geçerli olduğunu söylemek
Çok repolu bir üründe ajanın karşısına kaynak kod, tasarım notları, eski planlar ve önceki oturumların özetleri çıkıyor. Bunların aynı ağırlıkta değerlendirilmesi yanlış bir varsayımı kalıcı karara dönüştürebilir. Bu nedenle dosyanın başında kaynakların önceliğini tanımlıyorum.
Oturumda verdiğim güncel istek ile tarihsel bir plan çelişiyorsa eski plan otomatik olarak uygulanmıyor. Üçüncü taraf ve üretilmiş dosyalar da çalışma talimatı sayılmıyor. Ajan bir metnin içinde emir kipi görmüş olmasını o emrin yetkili olduğu şeklinde yorumlamamalı.
Kabul kriterini kontrol edilebilir yazmak
“Doğru çalışsın” gibi bir ifade uygulama kararı vermek için yetersiz. Hangi girişin hangi sonucu üretmesi gerektiğini, hangi hata durumunda işlemin duracağını ve sonucun nereden okunacağını yazıyorum. Bu ölçütler hem geliştiren ajan hem inceleyen kişi için aynı kontrol noktasını oluşturuyor.
Eksik veri davranışı bunun basit bir örneği. Finansal bir değer gelmediğinde sıfır göstermek, kullanıcıya gerçekte olmayan bir ölçüm sunabilir. Kural bu nedenle yalnız “eksik veriyi ele al” demiyor; hangi görünümün kullanılacağını ve varsayılan sıfır üretiminin nerede aranacağını açıklıyor.
Bağlamı görev boyunca güncel tutmak
Uzun bir oturumda başlangıçta okunan dosya değişmiş olabilir. Özetlenmiş bir konuşma da kararın gerekçesini veya sınırını kaybedebilir. Bu yüzden önemli düzenlemelerden önce güncel dosyanın ve görevin yeniden okunmasını istiyorum.
Bu yaklaşımın context engineering tarafı, yalnız daha uzun bir prompt yazmak değil. Doğru kaynağın doğru anda erişilebilir olmasını sağlamak. Görevin amacı, mevcut kararlar ve yapılmamış kontroller kısa bir ilerleme kaydında tutulabiliyor; geçmişteki her ayrıntının her adımda okunması gerekmiyor.
Ortak kuralları kopyalamamak
Ortak dosya bütün repoları ilgilendiren kuralları taşıyor. Yerel dosyalarda ilgili servisin komutları ve özel sınırları bulunuyor. Aynı kuralın uzun kopyalarını her repoya taşımak, zamanla farklı sürümlerin okunmasına yol açıyor. Bu sorunu talimat tutarlılığı vaka incelemesinde anlattım.
Yeni bir kural eklerken eski ifadeyi de arıyorum. Bir dosyanın güncellenmiş olması, başka bir rehberin aynı kararı eski biçimiyle anlatmadığını göstermiyor. Yönlendirme yollarının normal checkout ve worktree içinde çözüldüğünü de ayrıca kontrol ediyorum.
Paralel oturumları bağımsız işlere ayırmak
Bir oturum veri sözleşmesini incelerken diğeri arayüz üzerinde çalışabilir. İkisine de aynı uzun konuşmayı vermek yerine, görevini, dokunacağı alanı ve beklenen çıktıyı belirtiyorum. Paylaşılan dosyalar varsa kimin değiştireceği baştan netleşiyor. İki iş aynı karara bağımlıysa o karar sonuçlanana kadar paralel ilerlemeyi zorlamıyorum.
Aynı repoda bağımsız değişiklikler için ayrı Git worktree’leri kullanılabiliyor. Git worktree ayrı bir çalışma dizini sağlar; veritabanını ve dış servisleri kendiliğinden ayırmaz. Bu yüzden kodun ayrı klasörde bulunmasıyla çalışma ortamının bağımsız olması farklı kontroller gerektiriyor.
- Sınırı belirleGörev, dosyalar ve kabul ölçütü
- Bağımsız çalışGerekli bağlam ve ayrı değişiklikler
- Birlikte doğrulaBirleşen değişikliklerin davranışı
Sonuç döndüğünde yalnız oturumun “tamamlandı” demesine bakmıyorum. Değişikliği ve doğrulama çıktısını okuyorum; parçalar bir araya geldikten sonra ortak davranışı da kontrol ediyorum. Claude Code’un paralel çalışma rehberi araçların kullanımını açıklıyor; görev sınırını tanımlamak ise geliştirme kararımız.
Kısa bir talimat örneği
Aşağıdaki sadeleştirilmiş örnek, görevin sınırını ve tamamlanma ölçütünü aynı yerde tutuyor. Kullanılan teknolojiye göre komutlar değişebilir; kararın gözlenebilir olması beklentisi değişmiyor.
1## Kapsam
2Yalnız istenen davranışı değiştir.
3
4## Doğrulama
5Girdi, beklenen sonuç ve hata durumunu tanımla.
6Çalıştırılmayan kontrolü açıkça belirt.Kuralın yanına gerekçesini koymak
Bir kural yalnız yapılacak işi değil, nedenini de açıklarsa ajan benzer ama listelenmemiş bir durumda daha doğru değerlendirme yapabiliyor. Örneğin yoğun bir veri akışında her olay için log yazmanın maliyetini bilmek, yalnız belirli bir log satırını yasaklamaktan daha kullanışlı.
Olayın bütün hikâyesini talimat dosyasında tutmuyorum. Hikâye raporda kalıyor; burada davranışı değiştiren karar ve gerekçesi bulunuyor. Dosya her oturumda okunduğu için, eklenen her paragrafın gerçekten bir kararı iyileştirmesi gerekiyor.