AGENTS.md - AI kodlama ajanları için açık format

 (agents.md)
35 puan yazan GN⁺ 2025-08-21 | 1 yorum | WhatsApp'ta paylaş
  • AGENTS.md, README'yi tamamlayıcı bir rol üstlenir ve AI kodlama ajanlarının projede çalışırken ihtiyaç duyduğu bağlamı ve yönergeleri içeren özel bir dosyadır
  • 20.000'den fazla açık kaynak proje tarafından kullanılıyor; derleme/test/kod stili gibi insanlar için gereksiz ama ajanlar için önemli bilgileri düzenler
  • Ajanlara özel yönergeleri net ve öngörülebilir bir konumda sunarak README'yi sade tutarken işbirliği verimliliğini artırır
  • Tek bir AGENTS.md ile çeşitli ajanlar ve araçlarla uyumludur; büyük monorepo'larda alt projelere özel ayrı AGENTS.md dosyaları kullanılabilir
  • OpenAI Codex, Cursor, Google Jules gibi birçok ekosistemin işbirliğiyle oluşturulmuş açık bir standarttır

Why AGENTS.md?

  • README.md insanlar için hazırlanmış bir dokümandır; hızlı başlangıç, proje açıklaması ve katkı yönergeleri sunar
  • AGENTS.md, ajanlar için yardımcı bir dokümandır; derleme/test/kod kuralları gibi ayrıntılı bağlamı içererek README'yi karmaşık hale getirmez
  • Ayrı bir dosya olmasının nedenleri
    • Ajanların başvuracağı öngörülebilir bir yönerge konumu sağlar
    • README, insan katkıcıları merkeze alarak sade kalır
    • Mevcut dokümanları tamamlayan daha hassas, ajana özel yönergeler sunar
  • Sahipli bir format yerine herkesin kullanabileceği açık standart adlandırması benimsenmiştir
  • Tek bir AGENTS.md ile birden fazla AI kodlama ajanı ve araçla uyumluluk sağlanabilir

How to use AGENTS.md?

  • 1. AGENTS.md dosyasını oluşturun
    • Depo köküne yerleştirin (birçok ajan otomatik oluşturmayı destekler)
  • 2. Temel bölümleri yazın
    • Proje özeti
    • Derleme ve test komutları
    • Kod stili yönergeleri
    • Test yöntemi
    • Güvenlik değerlendirmeleri
  • 3. Ek yönergeler ekleyin
    • Commit/PR kuralları, güvenlik uyarıları, büyük veri kümeleri, dağıtım adımları gibi ekip üyelerine iletilmek istenen içerikler
  • 4. Monorepo desteği
    • Her paket için ayrı AGENTS.md yerleştirilebilir
    • Ajanlar en yakın dosyayı okuyarak ilgili alt projeye uygun yönergeleri izler
    • Örnek: OpenAI deposunda 88 adet AGENTS.md bulunuyor

FAQ

  • Zorunlu alanlar: Yok; genel Markdown biçimi serbestçe kullanılabilir
  • Çakışma durumunda: En yakın AGENTS.md önceliklidir, kullanıcı tarafından açıkça verilen prompt son olarak uygulanır
  • Otomatik çalıştırma: Dosyada belirtilen test komutları ajan tarafından çalıştırılarak hataları düzeltme girişiminde bulunulabilir
  • Güncellenebilirlik: İstenildiği zaman değiştirilebilir, canlı bir doküman olarak yönetilir
  • Mevcut dokümanların taşınması: Dosya adı değiştirildikten sonra sembolik bağlantıyla uyumluluk korunabilir
    • mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

İlgili okumalar

1 yorum

 
GN⁺ 2025-08-21
Hacker News görüşü

  • Küçük projelerde tek bir .md dosyası yeterli olsa da, karmaşık projelerde hiyerarşik klasör yapısı ve index.md çok daha etkili oluyor
    index.md ve onun altında auth.md, performance.md gibi dosyalardan oluşan yapı hem bakım açısından kolay, hem de LLM ya da ajanların gereksiz token harcamadan yalnızca ilgili bağlamı çekebilmesini sağlıyor
    .docs dosyaları hem insanlar hem de LLM’ler için uygun hale geliyor ve index.md içinde her dosya için kısa yönlendirmelerle organizasyon rehberi de yer alabiliyor
    Yalnız, ".agents" yerine .codebots veya .context gibi daha sezgisel bir isim daha iyi olurdu

    • Önemli dosya ve dizinleri özellikle gizlemeye gerek olmadığını düşünüyorum
      Özellikle dokümantasyon gizlenince daha da opak hale geliyor; gelenekten geliyor olabilir ama bu iyi bir kalıp değil
      robot_docs gibi bir isim nasıl olur diye düşünüyorum

    • Aslında bu tür bilgiler, katkıda bulunanların merak ettiği şeylerle çakıştığı için, esasen CONTRIBUTING.md içinde yer almalı diye düşünüyorum

    • Bu yapı, hem insanlar hem de robotlar için yazılmış bir yazılım tasarımı/kodlama stili rehberi dokümanı gibi duruyor
      Ben bu tür .md dosyalarını docs/ klasörüne koyuyorum; Claude Code da bunu doğrudan yazıyor
      AGENTS.md ve CLAUDE.md sadece robotlara yönelik olmalı; ister tek büyük dosyada h2 başlıklarla bölümlere ayırın, ister birden çok dosyaya bölün, ikisinin de artıları ve eksileri var
      Arc42 gibi ikisini de destekleyen mimari dokümantasyon formatları da var
      Büyük bir Markdown içinde belirli bir bölüme referans vermek yerine, bunu ayrı dosya yapıp @ ile anmak daha kolay ve hata olasılığını azaltıyor
      Belirli bir bölüme odaklanmak gerektiğinde küçük dosyalara bölmek kod ajanları için de daha iyi
      Küçük dosyalar diff/PR incelemesinde de daha kullanışlı

    • Kod tabanının içinde birden fazla AGENTS.md dosyası da bulundurabilirsiniz
      Tooling, mevcut dizindeki ve kök dizindeki AGENTS.md dosyalarını birlikte okuyacak şekilde tasarlanırsa, bilgi kodun yakınında kalabilir ve bu da istenen yaklaşımla birlikte kullanılabilir

    • Ben de benzer bir yapı kullanıyorum; index.md içine her dosya için kısa açıklamalar ekleyerek oldukça iyi sonuçlar aldım
      Ayrıca rules.md gibi, dizin bazında istenen davranış kurallarını tanımlayan dosya yöntemini de deniyorum
      Örneğin realtime-service.ts ve queue-service.ts gibi farklı servislerin bulunduğu bir dizinde yanına bir rules.md koymak gibi
      Prompt içinde bu kural dosyasını belirterek yeni şeyler üretmek kolaylaşıyor; ama isim konusu hâlâ biraz daha düşünülmeli

  • Şu an, ajanların kod tabanını anlayabilmesi için, insanların ihtiyaç duyduğundan daha fazla özel rehber yazmak zorunda kaldığımız bir geçiş dönemindeyiz
    Yakında buna gerek kalmayacağını düşünüyorum
    Proje dokümantasyonumuz baştan yeterince dolu ve düzgün olsaydı, AGENTS.md içindeki her şey zaten onun içinde yer alabilirdi
    Her zaman insanlar için doküman yazmalıyız; LLM’lerin avantajı da insanların yazdığı metni okuyabilmeleri
    Bence tasarım da bu bakış açısıyla yapılmalı

    • Bu sadece kod tabanını anlamakla ilgili değil; belirli stilleri zorunlu kılmak için de çok işe yarıyor (örneğin testlerde hangi assert kütüphanesinin kullanılacağı, yorum yazmama kuralı, yapısal logging kullanımı vb.)
      Hatta neredeyse hiç kodu olmayan yeni projelerde daha da faydalı olabilir

    • Makinenin okuyabildiği kuralların toplumun birçok alanında daha yaygın hale geleceğini tahmin ediyorum
      Örneğin otonom sürüş ve trafik kuralları: insanların bile bağlamı anlamakta zorlandığı tabelalar var ("Kırmızı ışıkta sağa dönüş yasaktır, eğitim döneminde 7-9 arası" gibi); makineler için bu daha da zor
      Sonunda kamu kurumları ya daha az bağlam gerektiren kurallara geçecek ya da makine tarafından okunabilirlik (QR kod vb.) içeren sinyallere yönelecek
      Böyle bir değişim olmazsa makineler kuralları daha sık ihlal edecek

    • İş mantığı gibi alanlarda ise, ajanlar için özel yönlendirmelerin gelecekte de kesinlikle gerekli olacağını düşünüyorum
      Ne inşa edildiği, niyetin ne olduğu, projenin nihai amacı gibi şeyleri insanlar açıkça anlatmadıkça makineler anlayamaz
      Mimari gibi konularda da herkesin ölçütü farklı; zihinde bir yapı olması, gerçek değişikliklere bakarken anlamayı kolaylaştırıyor, yani gerçek darboğaz aslında burada

    • Genel olarak katılıyorum ama bazı bilgileri (örneğin her seferinde bağlama mutlaka eklemek istediklerimizi) ayrı bir dosya olarak zorla dahil etme isteği de doğabiliyor

    • Zımnen düşündüğümüz kuralları ve varsayımları dokümante etmezsek LLM bunları bilemez
      Koddan bir kısmını çıkarım yoluyla anlayabilir belki ama %100 mümkün değil; bu yüzden gereksinimleri açıkça yazmak önemli

  • AGENTS.md, sonuçta README.md ile aynı rolü oynarken biraz da hype yarattığı için, insanların gerçekten içini dolduruyor olması ilginç
    İnsanlar başkaları için doküman yazmaya üşeniyor ama robotlar için gayet hevesle yazıyorlar; bu ilginç
    Bu durum, başta azınlık için ergonomik düşünülüp sonunda herkes için daha iyi hale gelen bir sap tasarımına benziyor

    • Aslında tam tersi: insanlar doküman okumadığı için kimsenin yazma motivasyonu oluşmuyordu
      Ajanlar için yazılan CLAUDE.md, bir kez yazıldığında kısa süre içinde 1000 ajan tarafından okunacak; bu da yazma isteği doğuruyor

    • Sonuçta README.md içine minimum gerekeni yazmak yeterli değil mi diye düşünüyorum

    • Gerçekte ajanların kendisi bile bu dokümanları okumuyor ya da birkaç talimat daha verilince her şeyi unutuyor olacak

    • Şu anki durum, insanların insan geliştiricileri (kendileri dahil) geliştirme sürecinden aktif biçimde çıkarmaya çalışması ve bu yüzden ajanların mutlaka uygun yönlendirmelere ihtiyaç duyması
      Çünkü insanların yazılım geliştirmeye katılımını tamamen kaldırma arzusu güçlenmiş durumda

build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors. Bunları ayırmayı önermek bana gerçekten dünyanın nereye gittiğini anlamıyormuşum gibi hissettiriyor

  • Güncel atmosferin zaten vibe coding olduğu yönünde şaka yapıyor
    Botlar için doküman yazmanın sonuçta iyi yazılmış dokümandan pek farklı olmadığı görüşü de daha önce dile getirilmişti sanırım

  • Sonuçta his şu: "AGENTS.md dosyası oluşturun ve içine sihri doldurun" deyip asıl olarak bir siteye link vermişler

  • Benim durumumda, 5.000’den fazla repo yöneten bir kodlama ajanı geliştiriyorum
    Ajanın durumu gizli .agent dizininde tutuluyor; her ajan rolü için yapılandırma klasörleri ve rol bazlı açık talimatlar içeriyor
    Proje klasöründe agents adlı bir klasör tutup, çeşitli dosyaları rollere göre ayırarak <Rol> <talimat> biçiminde yönetiyorum
    Ajan yalnızca rolü tanımlı dosyaları okuyor, durum ise dot<coding agent name> klasöründe saklanıyor
    Başlatma /init ile yapılıyor ve tüm repo kodunu basitçe indekslemek yerine, tüm mimariyi ve mantığı özetleyen bir high-level summary üretiliyor
    Bu özet, editör içinde açılıp kapatılabilen ghost comments olarak sunuluyor ve gerçek koda commit edilmeyen metadata niteliğinde
    Gelişmiş bir eşleme sistemi sayesinde her özet ilgili kod satırlarıyla tam olarak bağlanıyor
    Başta RAG’i doğrudan koda uyguladığımda istediğim sonucu alamadım; bu yüzden şu anki yapıya geçtim
    Şu anda AST tabanlı hızlı sözdizimsel arama ile, özetlere dayalı anlamsal keşfi (RAG) birleştiren hibrit bir arama modeli kullanıyorum
    Örneğin "Bu uygulamadaki kimlik doğrulama nasıl çalışıyor?" diye sorulduğunda, sözdizimsel arama yalnızca login gibi kelimeler içeren fonksiyonları bulurken, anlamsal arama özetler üzerinden tüm kimlik doğrulama akışını anlatısal biçimde kavrayıp farklı dosyalara dağılmış parçaları birbirine bağladığı için adeta sihir gibi çalışıyor

    • Buna ek olarak, özetlerin hiyerarşik bir yapısını (B-tree veya genel ağaç biçiminde) kurabilirsiniz
      Yani yöntem/sınıf/modül başına bir summary olur ve her katman daha alt katmanlara işaret eder
      RAG, anlamsal sorguya göre gerektiği kadar derine inebilir; her aşama alt katmanı özetleyerek bilgi miktarını azaltır ama gerekli anlamı korur
      Bu yaklaşım, kodun soyutlamasının iyi yapıldığı durumlarda özellikle etkili
      Örneğin add(n1, n2) gibi adı zaten yeterince anlam taşıyan bir fonksiyonda gerçek implementasyonu bilmek gerekmez; ama gerçek dünyadaki fonksiyonlar logging veya cache gibi birden fazla işleve sahip olduğundan, bağlama göre gerçek kodu da eklemek gerekebilir

    • Bunun daha ayrıntılı açıklamasını duymak isterim

  • Sanki insanlar yavaş yavaş proje dokümantasyonunu düzgün yazmaya şartlandırılıyor

    • Şaka gibi ama aslında bunu ekibe anlatıyorum
      LLM’ler gerçekten üretkenliği dramatik biçimde artırmasa bile, sonuçta çok daha iyi dokümantasyon yapmamıza yol açıyor

    • "Mission. Fucking. Accomplished." xkcd 810

  • README.md ile AGENTS.md dosyalarını gerçekten ayırmak gerekip gerekmediğinden hâlâ emin değilim

    • Ben de bunu düşünmeye devam ediyorum
      İlgili derleme’ye göre,
      ayırma nedenleri şunlar:
  1. yazım stili sorunu (ajan dokümanındaki TAMAMI BÜYÜK HARFLE vurgular, insan odaklı dokümanda rahatsız edici olabilir)
  2. özlülük ile eksiksizlik farkı (ajan dokümanı yalnızca temel bilgiyi taşımalı, insan dokümanı ise mümkün olduğunca her şeyi belgelemeli)
  3. gereken bilginin farklı olması (LMM için gereken bilgiyle insanlar için önemli bilgi aynı değil)
    ayırmama nedeniyse
  4. tekrarlı yönetim (özünde aynı şeyi iki yerde ayrı ayrı yazma yükü)

  • README.md artık biraz pazarlama/landing page gibi; AGENTS.md ve CLAUDE.md ise kod, mimari ve kullanım gibi gerçek içeriğe gidilen yerler gibi hissettiriyor

  • Örnekleri okurken ben de aynı şeyi düşündüm; aslında her şeyi kapsayan iyi bir README.md yeterli olmaz mı diye aklımdan geçti

  • README insanlar içindir, AGENTS.md vb. ise LLM’ler için
    Kullanım/kurulum yöntemi readme’de, derleme/test yöntemi, mimari kararlar, kodlama standartları, repo yapısı gibi konular ise ajan dokümanlarında yer alıyor

  • LLM’de context olarak kullanılan kapasite sorununu da düşünmek gerekiyor
    README.md uzun olduğu için tamamını context’e koymak zor
    AGENT.md içinde LLM’in gerçekten ihtiyaç duyduğu testler, build komutları gibi temel komutlar kısa ve öz tutuluyor
    README ile örtüşen kısımlar olabilir ama gereksiz içeriğin context’e tekrar tekrar gönderilmesini istemiyorum

  • Yapay zekanın vaadi, bizim ille de kesin bir formata takılmadan istediğimiz gibi yazıp makinenin bunu kendi başına uyarlaması değil miydi?

    • Aslında doğru seçim, yalnızca dosya adını standartlaştırıp içeriği herhangi bir biçime zorlamamak olmuş
      AGENTS.md standart Markdown olduğu için istediğiniz başlıkları kullanabilirsiniz ve ajan metni parse eder

    • Yine de belli ölçüde yapı ve biçim önemli
      Tabii bunu tam anlamıyla kod sözdizimi düzeyinde söylemiyorum

    • Sonuçta varılan yer, içeriğin açık biçimde yazılması gerektiği
      Doküman uzadıkça yapısal yaklaşım, insanlar açısından bakım için daha avantajlı oluyor

  • Kullanılan her ajan (Claude Code, Gemini, Aider) için dosya adı farklı
    Standartlaşsa iyi olurdu ama şimdilik ruler ile birden fazla formatı otomatik üretme zahmetine katlanıyorum
    Özellikle ajanların MCP yapılandırma dosyalarını tüketme biçimleri de farklı olduğu için, standartlaşmanın hemen gerçekleşeceğini sanmıyorum
    ruler

    • Biraz sinik bakarsak bunun nedeninin vendor lock-in yaratma eğilimi olduğunu düşünüyorum
      Standartlaşma emtialaşmaya yol açabileceği için şirketler bundan kaçınıyor olabilir

    • Jules, AGENTS.md kullanıyor; bu da Google’ın bu standarda katıldığını gösteriyor
      Gemini Code Assist varlığını sürdürürse muhtemelen AGENTS.md desteği de ekler
      Aider dokümanlarında belirli bir dosya adına rastlamadım; elinde link varsa paylaşmanı isterim
      Görünen o ki standart dosya adını henüz desteklemeyen tek şirket Anthropic

    • ruler gibi bir araca gerçekten ihtiyaç duyulması biraz üzücü

  • Tuhaf hissettiren bir web sitesi
    OpenAI tarafından yapılmış olabileceğini, ziyaretçi çekme ve pazarlama konumlandırması amacı taşıyıp taşımadığını düşündüm
    Gerçekte ise bir format tanımlamıyor, sadece dosya adını belirliyor
    Anthropic/Claude’un eksik olması da dikkat çekici; CLAUDE.md’yi AGENTS.md’ye sembolik link ile bağlamak gibi bir yöntem de mümkün

    • Aslında bunu sourcegraph yaptı ve mayıstan beri vardı
      Daha önce agent.md idi, şimdi agents.md’ye 301 yönlendirmesi yapılıyor
      Eski bağlantı
      Açıklama yazısı da var
      Görünüşe göre yakın zamanda OpenAI ile ortaklık yapmışlar
      İlginç olan, başlangıçta agent.md iken şimdi agents.md olmuş olması

    • Claude’un listede olmamasının nedeni, yalnızca Claude’un hâlâ standart dosya adı kuralını desteklememesi