Bir projede aynı bilgileri her görevde yeniden anlatmak yorucudur. Testlerin hangi komutla çalıştığı, ortak bileşenlerin nerede bulunduğu veya üretilen dosyaların elle değiştirilmemesi gibi bilgiler kalıcıdır. AGENTS.md, bu tür proje talimatlarını görev açıklamasından ayırmak için kullanılabilir. Değeri uzunluğundan değil, günlük çalışmada doğru yön göstermesinden gelir.
Kalıcı bilgiyle tek seferlik isteği ayırın
“Bu görevde düğmeyi sarı yap” geçici bir istektir. “Renkler ortak tema değişkenlerinden alınır” ise sonraki görevlerde de geçerli olabilecek bir proje kuralıdır. İkisini aynı dosyada biriktirmek, talimatların zamanla geçmiş işlerin dökümüne dönüşmesine neden olur.
Resmî doküman, Codex’in genel ve proje düzeyindeki talimatları katmanlı biçimde bulduğunu açıklar. Daha özel klasörlerdeki talimatlar da çalışma bağlamını etkileyebilir. Bu nedenle düzenleme yapmadan önce hangi AGENTS.md dosyalarının geçerli olduğunu bilmek önemlidir. Birden fazla yerde aynı konuyu farklı cümlelerle yönetmek, gereksiz çelişki yaratabilir.
Bir blog deposunda kök dosya genel geliştirme kurallarını taşıyabilir. Yalnızca içerik üretimi klasörüne özgü yazım kuralları ise o alanın yakınında tutulabilir. Burada amaç karmaşık bir talimat ağacı kurmak değildir; farklı sorumlulukların birbirini gölgelemesini önlemektir.
İlk dosyaya neler yazılmalı?
Önce doğrulanmış, kısa bilgilerle başlayın: uygulamanın giriş noktaları, geliştirme komutu, anlamlı test komutu ve proje için önemli iki üç kural. Komutların gerçekten depoda çalıştığını kontrol edin. Kopyalanmış fakat artık kullanılmayan bir komut, hiç bilgi olmamasından daha fazla zaman kaybettirebilir.
Örnek bir bölüm şöyle olabilir:
## Proje yapısı
- Ortak gezinme bileşenleri src/components/navigation altında.
- Tema renkleri src/styles/tokens.css içinde tanımlı.
## Çalışma kuralları
- Mevcut bileşenleri kullan; aynı iş için paralel sistem kurma.
- Davranış değişikliğinde ilgili kontrolü çalıştır ve sonucunu bildir.
- Üretilen dist dosyalarını doğrudan düzenleme.
Bu örnekteki yollar temsilidir; kendi deponuzdan doğrulanmadan kullanılmamalıdır. Aynı şekilde “her değişiklikte bütün testleri çalıştır” gibi geniş bir kuralın maliyetini değerlendirin. Amaç gerekli doğrulamayı tarif etmek, küçük bir metin değişikliğini saatler süren bir sürece çevirmek değildir.
Talimatları ekipte yeni başlayan birinin gözünden okuyun. “Standart biçimi kullan” cümlesi ancak standardın nerede bulunduğu biliniyorsa işe yarar. Bunun yerine doğru örnek dosyaya kısa bir yönlendirme eklemek daha açıklayıcıdır. Kuralları mümkün olduğunca uygulanabilir fiillerle yazın; hangi davranışın beklendiği anlaşılmıyorsa maddenin kısa olması tek başına avantaj sağlamaz ve yorum farkları zamanla büyüyebilir.
Codex ile dosyayı birlikte iyileştirin
Şu görev başlangıç için uygundur:
Depodaki mevcut talimat dosyalarını ve paket komutlarını incele. AGENTS.md için yalnızca doğrulanmış proje yapısını, geliştirme komutlarını ve tekrar eden bakım kurallarını içeren kısa bir taslak hazırla. Gizli bilgi ekleme. Bulamadığın komutları tahmin etme; açık soru olarak belirt.
Taslağı değerlendirirken her maddeye “Bunu bilmemek sonraki görevi gerçekten zorlaştırır mı?” diye sorun. Cevap hayırsa maddenin yeri başka bir belge olabilir. Mimari gerekçeler uzunsa kısa bir yönlendirme bağlantısı kullanmak, ana talimat dosyasını okunabilir tutar.
Dosya zamanla güncellenmelidir. Aynı hatanın tekrarlanması, yeni bir kuralın işe yarayabileceğini gösterir; tek seferlik yanlış anlaşılma her zaman kalıcı talimat gerektirmez. Kaldırılan bir yapılandırmanın talimatını da silin. Güncel kalan on satır, geçmiş kararlarla dolu yüz satırdan daha değerlidir.
Kaynak: AGENTS.md ile özel talimatlar.
