Bir AI coding agent güçlü bir model kullansa bile projenizin özel kurallarını kendiliğinden bilemez. Hangi komutla test çalıştırıldığını, hangi klasörün değiştirilmemesi gerektiğini, yeni bağımlılık eklerken onay istenip istenmediğini veya belirli bir modülde hangi mimari kalıbın kullanıldığını repository içinden tahmin etmeye çalışabilir. AGENTS.md, bu tür kalıcı proje bilgilerini coding agentlara daha düzenli ve tekrar kullanılabilir biçimde vermek için kullanılan açık bir Markdown formatıdır.
15 Temmuz 2026 itibarıyla AGENTS.md resmî sitesi dosyayı “agentlar için README” yaklaşımıyla tanımlar: README insan geliştiricilere proje hakkında genel bilgi verirken AGENTS.md, coding agentların etkili çalışması için gerekli build, test, kod stili, güvenlik ve çalışma kurallarını ayrı bir yerde tutmayı amaçlar AGENTS.md. OpenAI Codex, GitHub Copilot agent instructions ve Cursor gibi güncel coding araçları AGENTS.md yaklaşımını destekleyen ekosistemin parçalarıdır OpenAI Codex AGENTS.md GitHub Copilot Repository Instructions.
AGENTS.md nedir?
AGENTS.md, coding agentlara repository hakkında kalıcı talimat ve bağlam vermek için kullanılan standart Markdown dosyasıdır. Dosyanın zorunlu bir şeması veya belirli alan listesi yoktur. Resmî AGENTS.md sitesine göre standart Markdown kullanılır ve ekip ihtiyaç duyduğu başlıkları kendisi belirler AGENTS.md.
Dosyanın amacı, her yeni görevde aynı açıklamaları tekrar tekrar prompt içine yazma ihtiyacını azaltmaktır. Örneğin proje hangi runtime sürümünü kullanıyor, testler hangi sırayla çalıştırılıyor, hangi klasör generated code içeriyor veya yeni production dependency eklenmeden önce ne yapılmalı gibi kalıcı bilgiler AGENTS.md içinde tutulabilir.
Bu yaklaşım özellikle büyük yazılım geliştirme projelerinde değerlidir. Çünkü agent yalnız kodu görmekle projenin bütün çalışma kurallarını doğru çıkaramayabilir. Repository yapısı teknik gerçeğin bir bölümünü gösterirken ekip kararları, operasyonel sınırlar ve doğrulama adımları çoğu zaman yazılı talimat gerektirir.
AGENTS.md neden gerekli olabilir?
Coding agentlar repository’yi araştırabilir ancak araştırma ile açık talimat aynı şey değildir. Agent package.json veya CI dosyalarını okuyarak test komutunu bulabilir; fakat ekibin “önce hızlı unit testleri, sonra yalnız değişen modülün integration testlerini çalıştır” gibi tercihlerini her görevde yeniden keşfetmesi gerekebilir.
OpenAI Codex best practices dokümantasyonu, tekrar eden çalışma kalıplarını her promptta yeniden yazmak yerine AGENTS.md içinde kalıcı hale getirmeyi önerir. Dokümantasyon; build ve test komutları, review beklentileri, repository’ye özgü kurallar ve klasör bazlı talimatları uygun içerikler arasında gösterir OpenAI Codex Best Practices.
İyi bir AGENTS.md üç temel maliyeti azaltabilir:
- Keşif maliyeti: Agentın her görevde aynı proje bilgisini yeniden araması azalır.
- Hata maliyeti: Yanlış test, yanlış klasör veya ekip standardına aykırı değişiklik olasılığı düşebilir.
- Prompt tekrarı: Kalıcı kurallar her görev açıklamasına tekrar eklenmek zorunda kalmaz.
Ancak AGENTS.md tek başına doğru davranışı garanti etmez. Talimatlar yanlış, eski veya birbiriyle çelişkiliyse agent da yanlış yönlendirilebilir. Bu nedenle dosya yaşayan proje dokümantasyonu olarak yönetilmelidir.
AGENTS.md ile README.md arasındaki fark nedir?
README.md genellikle insan okuyucu için hazırlanır. Projenin amacı, kurulum özeti, kullanım biçimi ve katkı süreçleri gibi bilgileri açıklar. AGENTS.md ise aynı bilgilerin bir kısmını tekrar edebilse de odağı coding agentın görev yürütürken ihtiyaç duyduğu operasyonel talimatlardır.
Resmî AGENTS.md sitesi iki dosyanın birbirini tamamlamasını önerir. Amaç README’yi agenta özel ayrıntılarla doldurmak yerine coding agentların ihtiyaç duyduğu test, build ve proje kurallarını ayrı ve tahmin edilebilir bir yerde tutmaktır AGENTS.md.
| Konu | README.md | AGENTS.md |
|---|---|---|
| Temel hedef kitle | İnsan geliştiriciler ve kullanıcılar | AI coding agentlar |
| Proje tanımı | Genellikle önemli | Agentın işini anlaması kadar gerekli |
| Build ve test ayrıntıları | Özet olabilir | Görev yürütmeye yetecek kadar açık olabilir |
| Kod stili ve mimari sınırlar | Başka dokümana yönlendirebilir | Agent davranışını yönlendirmek için açıkça yazılabilir |
| Klasör bazlı özel kurallar | Genellikle merkezi | Nested AGENTS.md ile yerelleştirilebilir |
AGENTS.md içine hangi bilgiler yazılmalı?
Dosyaya her proje bilgisini eklemek yerine agentın kararlarını gerçekten etkileyen kalıcı bilgiler yazılmalıdır. Resmî AGENTS.md rehberi proje özeti, build ve test komutları, kod stili, test talimatları, güvenlik konuları, commit ve pull request kuralları gibi başlıkları yaygın kullanım alanları arasında gösterir AGENTS.md.
Proje ve repository özeti
Agentın kod tabanını anlamasını kolaylaştıracak kısa bir harita verilebilir. Ana uygulama nerede, backend ve frontend hangi klasörlerde, generated code hangi dizinde, hangi servis hangi sorumluluğu taşıyor gibi bilgiler yararlıdır.
Buradaki amaç bütün mimari dokümantasyonu AGENTS.md içine kopyalamak değildir. Agentın göreve başlarken yanlış klasörde uzun keşif yapmasını önleyecek kadar yön göstermek yeterlidir.
Kurulum, build ve test komutları
Çalışan ve doğrulanmış komutlar AGENTS.md’nin en değerli bölümlerinden biri olabilir. Agentın hangi package managerı kullanacağı, bağımlılıkların nasıl kurulacağı, unit test, lint, type-check ve build komutlarının ne olduğu açıkça yazılabilir.
Komutların gerçekte çalıştığı doğrulanmalıdır. GitHub’ın repository custom instructions rehberi de agent talimatlarına build ve validation adımlarını eklerken komutların çalıştırılarak doğrulanmasını önerir GitHub Copilot Repository Instructions.
Kod stili ve mimari kurallar
“Temiz kod yaz” gibi soyut talimatlar yerine projeye özel ve gözlemlenebilir kurallar daha yararlıdır. Örneğin domain katmanının HTTP frameworküne bağımlı olmaması, yeni endpointlerin belirli validation katmanını kullanması veya generated dosyaların elle düzenlenmemesi gibi kurallar yazılabilir.
Bir özel yazılım projesinde bu bölüm, yıllar içinde oluşan ekip kararlarını agente taşımak için önemlidir. Ancak AGENTS.md kötü mimarinin yerine geçmez; yalnız mevcut kararları görünür kılar.
Güvenlik ve izin sınırları
Yeni production dependency eklemeden önce onay istemek, secret dosyalarını değiştirmemek, migration çalıştırmamak veya belirli deployment komutlarını otomatik yürütmemek gibi sınırlar açıkça yazılabilir.
Burada önemli ayrım şudur: Talimat dosyası güvenlik mekanizmasının yerine geçmez. “Production’a deploy etme” yazmak yararlı olsa da gerçek sistemde agentın production credentialına hiç erişmemesi daha güçlü bir kontroldür. Yazılı kural ile teknik yetkilendirme birlikte kullanılmalıdır.
İyi bir AGENTS.md nasıl yazılır?
İyi AGENTS.md uzun olan değil, agentın kararlarını değiştiren net bilgiyi taşıyan dosyadır. OpenAI Codex customization dokümantasyonu da AGENTS.md için kalıcı proje rehberini kısa tutmayı ve her görevde uygulanması gereken kurallara odaklanmayı önerir OpenAI Codex Customization.
Aşağıdaki yapı gerçek bir proje dosyası değil, hangi bilgi türlerinin bulunabileceğini göstermek için hazırlanmış genel bir şablondur:
# Repository guidance
## Project structure
- Ana uygulamanın ve önemli modüllerin konumunu açıklayın.
- Generated veya değiştirilmemesi gereken klasörleri belirtin.
## Validation
- <unit-test-command>
- <lint-command>
- <type-check-command>
## Coding rules
- Projeye özgü mimari ve stil kurallarını yazın.
- Yeni bağımlılık eklenmesi için gereken onayı belirtin.
## Safety
- Geri döndürülemez işlemleri otomatik çalıştırmayın.
- Secret veya production credential dosyalarını değiştirmeyin.
## Completion criteria
- İlgili kontrolleri çalıştırın.
- Değişen dosyaları ve doğrulama sonuçlarını özetleyin.
Şablondaki placeholder komutlar gerçek komutlarla değiştirilmeden kullanılmamalıdır. Agenta çalışmayan veya varsayımsal komut vermek, hiç talimat vermemekten daha kötü sonuç üretebilir.
AGENTS.md içinde hangi tür talimatlardan kaçınılmalı?
Bir talimat dosyası zamanla her şeyin toplandığı uzun bir bilgi deposuna dönüşebilir. Bu durumda kritik kurallar gürültü içinde kaybolur ve çelişki ihtimali artar.
- Belirsiz ifadeler: “Her zaman en iyi çözümü kullan” gibi ölçülemeyen talimatlar.
- Göreve özel geçici bilgiler: Yalnız tek issue için geçerli ayrıntılar.
- Eski komutlar: Artık çalışmayan test veya build adımları.
- Çelişkili kurallar: Bir yerde “yeni dependency ekleme”, başka yerde “gerekirse otomatik ekle” gibi tutarsızlıklar.
- Gereksiz uzun dokümantasyon: Agentın her görevde ihtiyaç duymadığı ayrıntılar.
- Güvenlik kontrolü yerine metin: Teknik olarak engellenmesi gereken işlemleri yalnız talimata bırakmak.
AGENTS.md agent context’inin bir parçası olduğu için gereksiz içerik de maliyet yaratabilir. Kalıcı ve genel kurallar dosyada; görev özelindeki hedef ve kabul kriterleri ise doğrudan görev promptunda tutulmalıdır.
Kök klasör ve alt klasör AGENTS.md dosyaları nasıl çalışır?
AGENTS.md formatının önemli özelliklerinden biri büyük repository ve monorepolarda klasör bazlı talimatların kullanılabilmesidir. Resmî AGENTS.md sitesi, alt projelerde nested AGENTS.md dosyaları kullanılabileceğini ve düzenlenen dosyaya en yakın talimatın öncelik kazanabileceğini açıklar AGENTS.md.
OpenAI Codex’in discovery mekanizması daha ayrıntılı bir zincir kullanır. Codex global talimatlardan proje köküne ve mevcut çalışma dizinine doğru talimat dosyalarını toplar; daha yakın dizindeki rehber daha sonra geldiği için önceki genel rehberi geçersiz kılabilir. Codex ayrıca AGENTS.override.md mekanizmasını da destekler OpenAI Codex AGENTS.md.
GitHub Copilot agent instructions dokümantasyonu da repository içinde birden fazla AGENTS.md bulunabileceğini ve agent çalışırken dizin ağacındaki en yakın dosyanın öncelik kazanacağını belirtir GitHub Copilot Repository Instructions.
| Konum | Uygun içerik | Örnek kapsam |
|---|---|---|
| Repository kökü | Bütün projede geçerli temel kurallar | Genel test yaklaşımı, dependency politikası, ortak standartlar |
| Frontend klasörü | Frontend’e özel kurallar | UI yapısı, frontend testleri, component kuralları |
| Backend klasörü | Backend’e özel kurallar | API, veri erişimi ve backend validation kuralları |
| Kritik alt modül | Dar ve özel güvenlik veya çalışma sınırları | Ödeme veya authentication modülüne özel kontroller |
Bu tablo bir ürünün zorunlu klasör yapısı değildir; nested talimat mantığının nasıl bölünebileceğini gösteren genel bir karar çerçevesidir.
AGENTS.md ile görev promptu arasındaki fark nedir?
AGENTS.md kalıcı kuralları, görev promptu ise o an yapılacak işi taşımalıdır. Bu ayrım iyi yapılmazsa AGENTS.md tek issue’ya özel ayrıntılarla şişer veya her promptta aynı proje kuralları tekrar edilir.
Örneğin “her değişiklikten sonra ilgili unit testleri çalıştır” kalıcı bir repository kuralı olabilir. “Kullanıcı profilindeki belirli hatayı düzelt ve yalnız şu modüle dokun” ise görev özelidir ve doğrudan promptta bulunmalıdır.
Resmî AGENTS.md sitesine göre açık kullanıcı chat promptu, AGENTS.md talimatlarıyla çatıştığında daha yüksek önceliğe sahip olabilir AGENTS.md. Bununla birlikte gerçek öncelik ve discovery davranışı kullanılan coding agent ürününün dokümantasyonundan ayrıca kontrol edilmelidir.
AGENTS.md ile Skills ve özel agentlar aynı şey mi?
Hayır. AGENTS.md, repository içinde sürekli uygulanması beklenen proje rehberini taşır. Skills ise belirli bir görev veya uzmanlık için talimat, kaynak ve gerektiğinde script paketleri sunabilir. Özel agentlar ise belirli rol ve araçlarla yapılandırılmış daha geniş agent profilleri olabilir.
OpenAI Codex Skills dokümantasyonu, skill yapısını görev özelindeki uzmanlık ve tekrar kullanılabilir workflow paketleri için kullanır OpenAI Codex Skills. GitHub da agent skills ve custom agents yapılarını repository genelindeki custom instructions’tan ayrı kavramlar olarak sunar GitHub Agent Skills.
Basit ayrım şu şekilde düşünülebilir:
- AGENTS.md: Bu repository’de her zaman nasıl çalışmalısın?
- Skill: Belirli bir işi yaparken hangi özel bilgi ve workflow’u kullanmalısın?
- Özel agent: Hangi rol, araç ve uzmanlıkla çalışmalısın?
- Görev promptu: Şu anda tam olarak ne yapmalısın?
AGENTS.md agent performansını otomatik olarak artırır mı?
Hayır. Dosyanın varlığı tek başına kalite sağlamaz. Yanlış talimatlar agentı yanlış yöne götürebilir; aşırı uzun dosya önemli kuralları görünmez hale getirebilir; güncelliğini kaybetmiş komutlar gereksiz başarısızlık oluşturabilir.
AGENTS.md’nin gerçek değerini ölçmek için aynı tür görevlerde tekrar eden hatalara bakılabilir. Agent sürekli yanlış package manager kullanıyorsa, belirli testleri atlıyorsa veya generated dosyayı değiştiriyorsa bu tür sorunlar kalıcı talimat gerektirebilir. Buna karşılık bir kez yaşanan ve tekrar etmeyen her ayrıntıyı dosyaya eklemek doğru değildir.
Bir iş süreci otomasyonu gibi düşünmek yararlıdır: kural yalnız yazıldığı için değer üretmez; doğru davranışı tekrar edilebilir hale getiriyorsa değerlidir.
AGENTS.md dosyası nasıl yönetilmeli?
- Repository ile birlikte versiyonlayın: Kod değiştikçe kurallar da aynı geçmiş içinde güncellenebilir.
- Çalışmayan komutları temizleyin: Build ve test talimatlarını dönemsel olarak doğrulayın.
- Tekrarlanan agent hatalarından öğrenin: Gerçekten tekrar eden sorunları kalıcı kurala dönüştürün.
- Kritik kuralları kısa ve görünür tutun: Uzun açıklamalar arasında kaybetmeyin.
- Monorepoda kapsamı daraltın: Her alt projenin özel kuralını kök dosyaya yığmayın.
- Güvenliği teknik kontrollerle destekleyin: Talimatı erişim kontrolünün yerine kullanmayın.
AGENTS.md yaşayan bir dokümandır. Resmî site de dosyanın zaman içinde güncellenmesini önerir AGENTS.md. Proje yapısı değişirken talimat dosyası değişmiyorsa agent eski çalışma modeline göre hareket edebilir.
AGENTS.md hazırlarken pratik kontrol listesi
- Agent projenin ne yaptığını birkaç cümlede anlayabiliyor mu?
- Kurulum, test, lint ve build komutları gerçek ortamda doğrulandı mı?
- Değiştirilmemesi gereken dosya ve klasörler açık mı?
- Projeye özel mimari kurallar somut biçimde yazıldı mı?
- Yeni dependency, migration ve deployment gibi riskli işlemler için sınırlar var mı?
- Göreve özel geçici bilgiler kalıcı dosyadan çıkarıldı mı?
- Monorepo ise alt klasörler için ayrı talimat gerekip gerekmediği değerlendirildi mi?
- Talimatlar birbirleriyle ve mevcut CI süreciyle çelişiyor mu?
Sonuç: AGENTS.md, coding agent için proje hafızası değil çalışma sözleşmesidir
AGENTS.md, AI coding agentlara repository içinde nasıl çalışmaları gerektiğini anlatan açık ve basit bir Markdown formatıdır. En değerli kullanım alanı; her görevde tekrar eden build, test, kod standardı, güvenlik ve klasör kurallarını kalıcı hale getirmektir.
Dosyanın amacı bütün proje bilgisini modele yüklemek değildir. İyi AGENTS.md, agentın gerçekten karar verirken ihtiyaç duyduğu kalıcı bilgiyi kısa, güncel ve doğrulanabilir biçimde sunar. Büyük repository’lerde nested dosyalarla kapsam daraltılabilir; görev özelindeki hedefler ise AGENTS.md yerine doğrudan görev promptunda tutulmalıdır.
En güçlü coding agent bile yanlış proje talimatıyla güvenilir çalışamaz. Bu nedenle AI destekli geliştirmede model seçimi kadar, modele hangi proje kurallarının nasıl verildiği de mühendislik sisteminin bir parçasıdır.
Sıkça Sorulan Sorular
AGENTS.md nedir?
AGENTS.md, AI coding agentlara repository içinde nasıl çalışmaları gerektiğini anlatmak için kullanılan açık bir Markdown formatıdır. Build ve test komutları, kod standartları, proje yapısı, güvenlik sınırları ve review beklentileri gibi kalıcı talimatlar burada tutulabilir. Zorunlu alanları olan katı bir şema değildir; standart Markdown kullanılır ve ekip ihtiyacına göre başlıklar oluşturur.
AGENTS.md ile README.md arasındaki fark nedir?
README.md çoğunlukla insan geliştiriciler ve kullanıcılar için proje tanımı, kurulum ve kullanım bilgisi sunar. AGENTS.md ise coding agentların görev yürütürken ihtiyaç duyduğu operasyonel talimatlara odaklanır. Test komutları, değiştirilmemesi gereken klasörler, proje standartları ve agenta özel çalışma sınırları AGENTS.md içinde daha uygun olabilir. İki dosya birbirinin yerine değil, birbirini tamamlayacak şekilde kullanılabilir.
AGENTS.md içine hangi bilgiler yazılmalı?
Agentın kararlarını tekrar tekrar etkileyen kalıcı bilgiler yazılmalıdır. Proje ve klasör özeti, doğrulanmış kurulum, test, lint ve build komutları, kod stili, mimari sınırlar, dependency politikası, güvenlik kuralları ve tamamlanma kriterleri uygun örneklerdir. Yalnız tek görev için geçerli geçici ayrıntılar ise AGENTS.md yerine doğrudan görev promptunda tutulmalıdır.
Bir repository’de birden fazla AGENTS.md olabilir mi?
Evet. Büyük repository ve monorepolarda alt klasörlere ayrı AGENTS.md dosyaları yerleştirilebilir. Genel yaklaşımda düzenlenen dosyaya daha yakın talimat daha özel kabul edilir. OpenAI Codex ve GitHub Copilot gibi araçlar nested talimatları destekler ancak discovery ve öncelik ayrıntıları ürüne göre değişebilir. Bu nedenle kullanılan coding agentın güncel dokümantasyonu ayrıca kontrol edilmelidir.
AGENTS.md coding agentın daha iyi çalışmasını garanti eder mi?
Hayır. Dosya yalnız doğru, güncel ve uygulanabilir bilgi taşıyorsa yarar sağlar. Eski test komutları, belirsiz kurallar veya çelişkili talimatlar agent performansını kötüleştirebilir. En iyi yaklaşım, tekrar eden gerçek agent hatalarını gözlemlemek ve yalnız sürekli ihtiyaç duyulan proje kurallarını dosyada tutmaktır. Talimatların etkisi gerçek görev sonuçlarıyla değerlendirilmelidir.
AGENTS.md güvenlik kontrolünün yerini alır mı?
Hayır. AGENTS.md içinde production deployment yapmama, secret dosyalarını değiştirmeme veya riskli işlemlerde onay isteme gibi kurallar yazılabilir; ancak bunlar teknik erişim kontrolünün yerine geçmez. Agentın ihtiyaç duymadığı credential ve sistemlere erişimi baştan sınırlandırılmalıdır. Yazılı talimat, sandbox, izin modeli ve en düşük yetki yaklaşımıyla birlikte kullanılmalıdır.
