Monafy’yi AI ajanlarıyla geliştirirken aynı kuralın farklı repolarda farklı sürümleriyle karşılaştım. Bir dosya güncelleniyor, başka bir kopyası eski davranışı istemeye devam ediyordu. Ajan bütün bu metinleri bağlam olarak okuyabildiği için sorun yalnız doküman düzeni değildi; geliştirme sırasında verilen kararları da etkiliyordu.
Çözüm olarak ortak çalışma kurallarını tek bir kök dosyada topladım. Repo dosyalarında ise yalnız ilgili servise özgü komutlar ve sınırlar kaldı. Diğer dokümanlar kuralları yeniden yazmak yerine bu kaynağa yönlendiriyor.
Aynı talimatın farklı sürümleri
Bir repoda kök dosyanın uzun bir kopyası bulunuyordu. Bu kopya kendisini ortak çalışma alanının yetkili kaynağı olarak tanıtıyor, ancak kökte değiştirilmiş kuralları eski biçimleriyle taşıyordu. Yeni bir oturum iki sürümü birlikte okuduğunda hangisinin güncel olduğunu metnin kendisinden anlayamıyordu.
Benzer çelişkiler tasarım notlarında ve kalıcı hafıza kayıtlarında da vardı. Bir araç, tek oturumluk tercihi genel kural gibi kaydetmişti. Başka bir dosyada ise paralel çalışmanın nasıl yürütüleceğine ilişkin birbirine ters iki öneri duruyordu.
Ortak bağlam ile yerel ayrıntıyı ayırmak
Köke, bütün repolar için geçerli kararları koydum: kaynak önceliği, kanıt beklentisi ve bağlamın nasıl korunacağı. Bir servisin test komutu veya o repoya özgü geliştirme ayrıntısı ise kendi dosyasında kaldı.
Bu ayrımın amacı her şeyi tek dosyaya taşımak değildi. Ortak kuralı tek yerde tanımlarken yerel bilginin ait olduğu yerde okunmasını sağlamak gerekiyordu. Kök dosyanın yazım yaklaşımını CLAUDE.md ve proje bağlamı yazısında ayrıca anlatıyorum.
Kural değiştiğinde eski metni de aramak
Yalnız doğru dosyayı değiştirmek yeterli olmuyor. Bir kural yenilendiğinde önceki ifadesini de ilgili dokümanlarda arıyorum. Eşleşen metnin çevresini okumak önemli; aynı anlam farklı satırlara bölünmüş veya başka bir cümlenin içine taşınmış olabiliyor.
Yönlendirmelerin de gerçek çalışma dizininden çözüldüğünü kontrol ediyorum. Normal checkout’ta çalışan göreli bir yol, ayrı worktree içinde başka yere işaret edebiliyor. Kuralın doğru olması, ajanın doğru dosyayı bulabildiğini tek başına göstermiyor.
Bağlam maliyetini yönetmek
Ortak dosyaya eklenen her paragraf tekrar tekrar okunuyor. Bu yüzden olay anlatımlarını ve geçmiş tartışmaları kural metninden ayırıyorum. Dosyada davranışı değiştiren kural ile gerekçesi kalıyor; olayın ayrıntısı ilgili raporda tutuluyor. Böylece ajan güncel kararı bulurken geçmiş metinler arasında seçim yapmak zorunda kalmıyor.