AGENTS.md: Her Kodlama Ajanı İçin Tek Bir Bağlam Dosyası (Codex, Antigravity, 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 Antigravity 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

Bu rehber ilk yazıldığında her araç kendi dosyasını arıyordu. O zamandan beri çoğu AGENTS.md üzerinde birleşti:

• Codex AGENTS.md okur, GitHub Copilot CLI, Cursor, Amp ve yeni ajan CLI'larının çoğu da öyle.
• Claude Code CLAUDE.md okur ve 2.1.277 sürümünden beri, çalışma dizininde ve üstündeki dizinlerde ne CLAUDE.md ne de CLAUDE.local.md yoksa AGENTS.md'yi de kendiliğinden okur. Bir CLAUDE.md varsa Claude yalnızca onu okur, /config içindeki Project instructions ayarını değiştirmediğin sürece.
• Antigravity CLI reponun kökünde veya herhangi bir alt dizinde AGENTS.md ya da GEMINI.md okur, ayrıca bir .agents/rules/ klasörünü ve ~/.gemini/ altındaki global kuralları da.

İçerik üçünde de neredeyse aynı: proje bağlamı, komutlar, kurallar. Hâlâ farklı olan şey, birden fazla dosya bulduğunda bir aracın hangisini seçtiği. 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). Bu davranışları 10 Ekim 2026'da Claude Code'un bellek dokümantasyonuna ve Antigravity'nin kurallar dokümantasyonuna göre kontrol ettik.

Ç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 bir AGENTS.md, başka hiçbir şey. Kimsenin yalnızca Claude'a özel kurallara ihtiyacı yoksa tek bir AGENTS.md tut: Codex, Antigravity CLI ve Claude Code 2.1.277 veya sonrası hepsi onu okur. Tuzak sessizdir: sonradan eklenen bir CLAUDE.md ya da kişisel bir CLAUDE.local.md, Claude Code'un AGENTS.md'yi okumayı bırakmasına yol açar.
• Tek kanonik dosya, tek içe aktarma. Her şeyi AGENTS.md içinde tut, CLAUDE.md'yi @AGENTS.md satırıyla başlat, ardından Claude'a özel kuralları onun altına yaz. Claude önce içe aktarılan dosyayı okur. Bizim kendi repomuz da böyle çalışıyor: CLAUDE.md dosyası sadece bu tek satırdan oluşuyor. Bir sembolik bağlantı (ln -s AGENTS.md CLAUDE.md) da işe yarar, ama Windows'ta pek iyi çalışmaz: orada bir sembolik bağlantı oluşturmak yönetici hakları ya da Geliştirici Modu gerektirir ve core.symlinks olmadan alınan bir klon, talimatların yerine tek satırlık bir metin dosyası alır.

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 Antigravity'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ş.

Sıkça sorulan sorular

AGENTS.md nedir?

Genellikle bir reponun kökünde duran ve kodlama ajanlarının işe başlamadan önce kalıcı talimatlar olarak yüklediği bir Markdown dosyası: proje nedir, nasıl build ve test edilir, hangi kurallara uyulur ve hangi tuzaklardan kaçınılır. Tek bir aracın dosyası değil, araçlar arasında paylaşılan açık bir konvansiyon. Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp ve 2.1.277 sürümünden beri Claude Code tarafından okunuyor.

Claude Code AGENTS.md'yi okur mu?

Evet, Claude Code 2.1.277'den beri, ama yalnızca çalışma dizininde veya üstündeki dizinlerde CLAUDE.md, .claude/CLAUDE.md ya da CLAUDE.local.md yoksa. Bu durumda çalışma dizininden yukarı doğru her AGENTS.md'yi yükler, bir alt dizindeki AGENTS.md'yi de orada bir dosya açtığında yükler. Bir CLAUDE.md varsa Claude yalnızca onu okur, /config içinde Project instructions ayarını claude-md-and-agents-md olarak değiştirmediğin sürece. Daha eski sürümlerde bir CLAUDE.md'nin en üstüne @AGENTS.md satırını koy.

Antigravity AGENTS.md mi kullanır, GEMINI.md mi?

İkisini de. Antigravity, reponun kökünde veya herhangi bir alt dizinde bir AGENTS.md, bir GEMINI.md ya da bir .agents/rules/ klasörü okur, ayrıca ~/.gemini/ altındaki global kuralları da okur. Kurallar birbirinin yerine geçmek yerine üst üste eklenir ve ikisi çeliştiğinde daha spesifik dizinin kuralı kazanır.

AGENTS.md mi tutmalıyım, CLAUDE.md mi?

Bakımını yaptığın tek dosya olarak AGENTS.md'yi tut. Yalnızca Claude için kurallara da ihtiyacın varsa, ilk satırı @AGENTS.md olan bir CLAUDE.md ekle ve bu kuralları onun altına yaz: Claude önce içe aktarılan dosyayı okur. Böyle kurallara ihtiyacın yoksa Claude Code 2.1.277 veya sonrası için tek başına AGENTS.md yeterli. Aynı kuralların iki tam kopyasından kaçın: kimsenin düzenlemediği kopya eskir.

AGENTS.md nereye konmalı?

Her yerde geçerli olan kurallar için reponun köküne. Claude Code ve Antigravity alt dizinlerdeki AGENTS.md dosyalarını da okur, böylece kendi komutları olan bir paket ya da servis, ajan o klasörde çalışırken okunan kendi dosyasını taşıyabilir.