Yapay zekâ programlama ajanlarına yönelik talimat dosyaları sınırsız biçimde genişletilmek yerine sürekli gözden geçirilmelidir. Model her hata yaptığında yeni bir kural eklenir, bir araç her değiştiğinde bir geçici çözüm yöntemi eklenir; daha yeni modeller ortaya çıktıktan sonra da önceki model yönergeleri dosyada kalmaya devam eder. Sonuçta dosya; geliştirici kurulum kılavuzu, stil kılavuzu, hata ayıklama günlüğü ve eski istem yazma tekniklerinin birleşiminden oluşabilir.
Makalenin belirttiğine göre bu birikim, programlama ajanını daha az etkili hâle getirebilir. Modern modeller depoları keşfetme, yaygın çerçeveleri tanıma, mevcut kalıpları izleme ve olağan hatalarla başa çıkma konusunda giderek daha yetenekli. Ancak ekibin kendine özgü kararlarını, gizli kısıtlamalarını veya ekip içinde birikmiş operasyonel deneyimleri bilemezler. Bu nedenle amaç, talimat dosyasını mümkün olduğunca kısaltmak değil, sonucu gerçekten değiştiren yüksek sinyalli bilgilerin en küçük kümesini korumaktır.
Bağlamı sınırlı bir kaynak olarak ele alın
Talimat dosyası, geçerli olduğu her istekte modelin kullanabileceği bağlama eklenir ve dosyanın satırları; geliştiricinin görevi, ilgili kod, araç çıktıları, sohbet geçmişi ve diğer talimatlarla modelin dikkati için yarışır. Bağlam penceresinin geniş olması, eklenen her simgenin maliyetsiz olduğu anlamına gelmez.
Pratik soru şu değildir: Modele depo hakkında neler anlatılabilir? Asıl soru şudur: Modelin bilmesi gereken, ancak güvenilir biçimde keşfedemediği, çıkaramadığı veya geri getiremediği bilgiler nelerdir? Makale, belirli, etkili ve çıkarılması zor bilgilere odaklanılmasını öneriyor.
Dosyada neler kalmalı?
En değerli bilgiler arasında, sistem hakkında açıkça anlaşılmayan gerçekler bulunur. Örneğin depo bileşenleri arasındaki sahiplik sınırları, eski bir klasörün hâlâ üretimde kullanılıyor olması veya belirli dosyaların oluşturulmuş olması ve elle değiştirilmemesi gerektiği. Bir arayüzün genel HTTP sözleşmesine sahip olduğunu ya da alan kurallarının belirli bir katmana ait olduğunu açıkça belirtmek, modelin bu sınırları klasör adlarından çıkarmasını beklemekten daha faydalıdır.
Yalnızca test edilmiş komutlarla sınırlı olmak kaydıyla, derleme ve doğrulama için en kısa güvenilir yol da belgelenmelidir. Makalede verilen örnekler arasında ilk derleme işleminden önce dotnet restore App.slnx komutunun çalıştırılması, ardından dotnet build App.slnx --no-restore komutunun kullanılması, API’ler değiştirildiğinde belirli testlerin çalıştırılması veya sözleşmeler değiştirildikten sonra oluşturulmuş dosyaları doğrulama aracının kullanılması yer alıyor. Docker gerektiren ve paralel çalıştırılmaması gereken entegrasyon testleri gibi özel gereksinimler de açıklanmalıdır; çünkü yanlış bir komutun güvenle tekrarlanması, komutun hiç olmamasından daha kötüdür.
Kodun sürekli olarak kesinleştiremeyeceği yerel seçimleri kaydetmek de faydalıdır: kullanılan test çerçevesi, controller’lar yerine Minimal APIs tercihi, beklenen alan hatalarını ele almak için Result<T> kalıbı veya sistem saatini doğrudan çağırmak yerine TimeProvider kullanımı. Bunlar genel programlama kuralları değil, kod tabanına özgü kararlardır; bu nedenle talimat dosyası için uygundurlar.
Katı kısıtlamalara gelince, “her zaman”, “asla” ve “-meli/-malı” gibi ifadeler yalnızca gerçekten mutlak olan kurallar için kullanılmalıdır. Örneğin genel JSON sözleşmesinin korunması, müşteri verilerinin günlüklerde tutulmaması, veritabanı geçişlerinin önceki sürümle uyumlu olması veya açık bir dağıtım görevi olmadan üretim ortamı dosyalarının değiştirilmemesi. Ayrıca içerikleri kopyalamak yerine arayüz tasarım yönergeleri dosyaları, çalışma zamanı sürüm tanımları, dağıtım belgeleri ve mimari kararları gibi doğruluk kaynaklarına işaret edilebilir.
Neler silinebilir veya taşınabilir?
Makale; temiz kod yazmak, en iyi uygulamaları izlemek, anlamlı adlar kullanmak ve hataları uygun biçimde ele almak gibi genel tavsiyelerin silinmesini öneriyor. Bu ifadeler pratik bir kararı belirlemez. Buna karşılık, mevcut ProblemDetails araçlarını kullanarak doğrulama hatalarını 400 yanıtına, bulunamayan kaynakları 404 yanıtına ve eşzamanlılık çakışmalarını 409 yanıtına bağlamak gibi belirli yerel kurallar daha faydalıdır.
Dosyaların genellikle kapsamlı klasör envanterlerine ihtiyacı yoktur; model depo yapısını hızla okuyabilir. Araçların dayattığı biçimlendirme kurallarını tekrarlamaya da gerek yoktur; dotnet format --verify-no-changes gibi uygun doğrulama komutunu belirtmek yeterlidir. Bakım maliyetinin yükselmemesi veya belgeler arasında çelişkiler ortaya çıkmaması için README dosyaları, mimari ve katkı kılavuzları bütünüyle kopyalanmamalıdır.
Makale ayrıca, modele derin bir nefes almasını söylemek, üst düzey bir mühendis gibi davranmasını istemek veya herhangi bir değişiklik yapmadan önce her dosyayı okumasını emretmek gibi eski “istem mitlerine” karşı uyarıyor. Bu ifadeler projeye ilişkin bilgi eklemez ve gereksiz keşfe yol açabilir. Bunun yerine sonuç, kısıtlamalar ve gerekli doğrulama açıklanmalıdır: kök nedeni ele alan en küçük değişikliği yapmak, genel davranışı korumak ve hedeflenen testleri çalıştırmak.
Geçici çözümler, onları gerektiren sorun düzeltildikten sonra silinmelidir. Aksi hâlde ajan, artık bozuk olmayan bir yolu kullanmaktan kaçınmaya devam eder. Talimatlar ayrıca belirli bir sürüme değil, model ailesine uygun yazılmalıdır; her modele özel yollara ayrılan talimatlar, modeller ve davranışları değiştikçe kırılgan hâle gelir.
Talimatların kapsamını seçme ve gözden geçirme
Her yönlendirme genel depo dosyasına uygun değildir. GitHub Copilot, .github/copilot-instructions.md içinde genel talimatları, .github/instructions/ altında yollara özel dosyaları ve AGENTS.md gibi ajan talimatlarını destekler. Her ikisi de mevcut olduğunda genel talimat dosyası, eşleşen yola özel dosyayla birlikte kullanılır.
Sistem yapısı, ortak komutlar ve genel kısıtlamalar genel kapsama yerleştirilmelidir. Çerçeve kuralları, test kalıpları ve belirli bir bölüme özgü oluşturulmuş dosyalarla ilgili kurallar ise yola özel bir dosyaya taşınmalıdır. Ayrıntılı açıklamalar, kararların geçmişi ve nadir prosedürler ise bağlantılı belgelerde tutulmalıdır. Böylece React bileşenlerinin testlerine ilişkin bir kural, modelin veritabanı geçişiyle ilgili bir görev sırasında dikkatini tüketmez.
Makale her yönlendirmenin dört sonuçtan biriyle değerlendirilmesini öneriyor: doğru, etkili ve çıkarılması zor ise koru; model bunu biliyorsa, bir araç bunu dayatıyorsa ya da bilgi belirsiz veya güncelliğini yitirmişse sil; yararlı olmakla birlikte başka bir yola veya belgeye aitse taşı; bir komuttan, geçici çözümden veya değişmiş olabilecek bir sürümden söz ediyorsa doğrula.
Gözden geçirme zamanları arasında daha yetenekli bir modelin benimsenmesi, derleme sisteminin değiştirilmesi, deponun yeniden düzenlenmesi veya ajanların talimatları görmezden geldiğinin ya da yanlış uyguladığının fark edilmesi bulunur. Ardından daha küçük dosya belirli bir görev üzerinde test edilir, gerçek hata durumları izlenir, bunların tekrarlanmasını önleyecek en az sayıda talimat eklenir ve başka bir görev üzerinde yeniden test yapılır.
Proje bakımının bir parçası
Makale, talimat dosyalarındaki değişikliklerin olağan çekme isteklerinde gözden geçirilmesini, inceleyen kişilere kuralın yeniden kullanılabilir olup olmadığının veya yalnızca tek bir görevi ele alıp almadığının sorulmasını ve operasyonel komutlarla ortam gereksinimleri için bir sahip atanmasını öneriyor. Geçici çözümler, sorunun nedenini ele alan çekme isteğinin içinde silinmeli; SDK paketleri, çerçeveler, test araçları veya derleme yolu güncellendikten sonra komutlar yeniden incelenmelidir.
Dosyanın kalitesi satır sayısıyla ölçülmemelidir. 30 satırlık ve hatalı talimatlar içeren bir dosya, çok projeli bir deponun sınırlarını ve modelin çıkaramayacağı bilgileri açıklayan 100 satırlık bir dosyadan daha kötü olabilir. Daha iyi ölçüt, dosyanın yetkin bir modelin çalışmaya hızla başlamasını sağlamasıdır; bunun için ekibin yalnızca kendisinin bildiği şu bilgileri sunmalıdır: sistemin ne olduğu, önemli sınırlar, yerel tercihler, derleme ve doğrulama yöntemi, bozulmaması gerekenler ve daha derin ayrıntıların nerede bulunacağı.