AGENTS.md: Her Kodlama Ajanı İçin Tek Bir Bağlam Dosyası (Codex, Gemini, Claude)

Temiz bir CLAUDE.md yazmak için bir öğleden sonranı harcadın. Ajanın sonunda stack'ini tahmin etmeyi bıraktı ve doğru test komutunu çalıştırmaya başladı. Derken bir takım arkadaşın aynı repoyu Codex ile açıyor, sen bir yan dalda Gemini CLI'yi deniyorsun ve o zar zor kazandığın bağlamın hiçbiri taşınmıyor. Her araç kendi dosyasını, kendi yerinde istiyor.

AGENTS.md işte bu karmaşanın cevabı: reponun kökünde duran, herhangi bir kodlama ajanının koda dokunmadan önce okuduğu tek bir düz Markdown dosyası.

AGENTS.md tam olarak nedir

Sihir yok. Genellikle deponun kökünde duran, AGENTS.md adında bir Markdown dosyasıdır ve ajan işe başlamadan önce onu kalıcı talimatlar olarak yükler. Onu, insan takım arkadaşların yerine yapay zeka takım arkadaşların için yazdığın README gibi düşün: proje nedir, nasıl build ve test edilir, hangi kurallara uyulur ve hangi tuzaklardan kaçınılır.

Açık bir konvansiyon: Codex ve giderek büyüyen bir ajan araçları listesi tarafından okunuyor, üstelik araçlar arası taşınabilir olma amacıyla tasarlanmış. Her araç için ayrı bir özel dosya yerine tek dosya, birçok ajan.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Şu an manzara araca göre bölünmüş durumda:

• CLAUDE.md, Claude Code'un aradığı dosya.
• GEMINI.md, Gemini CLI'nin konvansiyonu.
• AGENTS.md, araçlar arası standart: Codex ve diğerleri tarafından okunuyor, tarafsız olan dosya olmak üzere tasarlandı.

İçerik üçünde de neredeyse aynı: proje bağlamı, komutlar, kurallar. Tek gerçek fark, her aracın varsayılan olarak okuduğu dosya adı. Aynı kuralları elle üç dosyaya kopyalamanın baştan kaybedilmiş bir savaş olmasının sebebi tam da bu (senkron tutma konusuna aşağıda döneceğiz).

Çoğunlukla Claude Code içinde çalışıyorsan, CLAUDE.md rehberimiz Claude'a özgü yapıyı derinlemesine ele alıyor. AGENTS.md ise bu dosyanın provider'dan bağımsız, tarafsız kardeşi.

İçine ne koymalı

Kısa ve yüksek sinyalli tut. Ajan bunu her görevde okur, yani her satır dikkat çekmek için yarışır. Olmazsa olmazlar:

• Stack, tek nefeste. "Next.js 16, TypeScript, Prisma, MariaDB." Tarih yok, pazarlama yok.
• Önemli olan komutlar. Nasıl kurulur, çalıştırılır, build, test ve lint edilir. Tam komutlar: npm test, "testleri çalıştır" değil.
• Kurallar. İsimlendirme, dosya düzeni, hata yönetimi, review'da gerçekten uyguladığın desenler.
• Bir klasör haritası. Neyin nerede olduğuna dair iki satır, ki ajan körlemesine grep yapmayı bıraksın.
• "Dokunmadan önce oku" kuralları. "billing/ altında herhangi bir şeyi düzenlemeden önce docs/payments.md'yi oku." Bu tek alışkanlık birçok hasarı önler.
• Kesin yasaklar. "İstenmeden asla branch oluşturma." "Commit edilen dosyalarda makineye özgü mutlak yol yok."

Ajanların bu dosyayı görmezden gelmesine yol açan hatalar

Bir bağlam dosyası sessizce başarısız olur. Ajan hata fırlatmaz, sadece kayar gider. Olağan sebepler:

1. Çok uzun. 600 satırlık bir dosya, önemli olan beş kuralı gömer. Ajanın koddan kendisinin çıkarabileceği her şeyi sil.
2. Çelişkiler. Bir bölümde "Her zaman test yaz", başka bir bölümde "prototipler için testleri atla". Ajan rastgele birini seçer.
3. Makineye özgü yollar. Commit edilen bir dosyadaki /Users/you/project/... her takım arkadaşı için ve her diğer makinedeki her ajan için bozulur. Yolları göreli tut.
4. Eskimiş komutlar. Test komutu altı ay önce değişti, dosya değişmedi. Artık ajan yanlış şeyi tam bir özgüvenle çalıştırıyor.
5. Öncelik yok. Her şey "önemli", dolayısıyla hiçbir şey önemli değil. Tartışmaya kapalı maddeleri en başa koy ve etiketle.
6. Dokümantasyon boşaltma. Bunlar talimat, wiki değil. Dokümanlarına link ver, içeri yapıştırma.

Provider'lar arasında tek bir bağlam korumak

İşte çoğu rehberin atladığı pratik kısım. Sen ya da ekibin birden fazla ajan CLI'si çalıştırıyorsanız, aynı kuralların birbirinden sapan üç kopyasını istemezsin.

İki temiz yaklaşım:

• Tek kanonik dosya, ince işaretçiler. Her şeyi AGENTS.md içinde tut, CLAUDE.md ve GEMINI.md'yi "AGENTS.md'ye bak" diyen tek satırlık dosyalar yap ya da onları symlink ile bağla. Tek bir doğruluk kaynağı, beslenen her araç.
• Tek dosya, konvansiyonla paylaşılan. Araçların özel bir yola yönlendirilebiliyorsa hepsini AGENTS.md'ye çevir ve gerisini sil.

Her iki durumda da kural aynı: bağlamı bir kez yaz, provider başına bir kez değil. Bu aynı zamanda dosyanın doğru kalmasının tek yolu, çünkü insanların gerçekten bakımını yaptığı tek dosya, tek bir dosyadır.

Aynı anda birkaç ajan çalıştırdığında

Repo seviyesindeki bir AGENTS.md, "bu proje nedir" sorusunu yanıtlar. "Bu ajan kim" sorusunu yanıtlamaz. Aynı kod üzerinde paralel olarak bir Backend ajanı, bir Frontend ajanı ve bir QA ajanı çalıştırdığında, her biri paylaşılan proje bağlamına ek olarak kendi rolüne ihtiyaç duyar.

İşte AgentsRoom'un AGENTS.md'nin üzerine eklediği katman bu. Her ajan kendi sistem prompt'una sahip özel bir rol alır (DevOps, Frontend, Güvenlik ve daha fazlası), böylece paylaşılan dosya yalın kalırken her ajan yine de işinin ne olduğunu bilir. Tasarım gereği provider'dan bağımsızdır, yani aynı kurulum Claude, Codex veya Gemini'yi yan yana çalıştırır ve tekrar kullanılabilir talimatların her oturumda yeniden yazılmak yerine bir Prompt Kütüphanesi içinde yaşar.

O noktaya geldiğinde, birden fazla ajanı işin ipini kaçırmadan paralel çalıştırma yöntemi doğal olarak sıradaki okuman.

Özetle

Tek bir AGENTS.md yaz. Kısa tut, güncel tut, taşınabilir tut. Ajan başına bir dosya bakımı yapmak yerine her aracı ona yönlendir. Bağlamın artık hangi CLI ile başladığına bağlı kalmaz ve ajanların, hangilerini çalıştırırsan çalıştır, hepsi aynı sayfadan başlar.

Her ajanı tek bir ekranda, her biri kendi rolü ve paylaşılan bağlamınla görmek ister misin? AgentsRoom'u indir, provider'ını bağla ve filonu işe koş.