AGENTS.md nedir?

Kısaca

AGENTS.md, depoda duran ve yapay zekâ kodlama ajanlarına projede nasıl çalışacaklarını anlatan açık, düz bir Markdown dosyasıdır: projenin nasıl derlenip test edileceği, hangi kurallara uyulacağı, nelerden kaçınılacağı. Ajanlar için yazılmış, birçok farklı aracın okuduğu bir README gibi düşünebilirsin.

Hangi ajanlar okuyor?

Biçim agents.md adresinde anlatılıyor; orada destekleyen 20’den fazla araç listeleniyor. Ayrıntılar araçtan araca değiştiği için kendi ajanının dokümanına da bak.

Codex, Cursor, GitHub Copilot’un kodlama ajanı, opencode, Amp, Aider, goose, Zed, Warp, Junie ve Jules gibi araçlar okuyor.
Gemini CLI varsayılan olarak GEMINI.md okur; settings.json’daki context.fileName ayarına AGENTS.md’yi eklersen onu da okur.
Claude Code CLAUDE.md okur; 2.1.277 sürümünden beri depoda CLAUDE.md yoksa AGENTS.md’yi okur. AGENTS.md’yi CLAUDE.md içine @AGENTS.md ile de aktarabilirsin.

AGENTS.md, CLAUDE.md ve GEMINI.md

CLAUDE.md ve GEMINI.md, Claude Code ile Gemini CLI’ın araca özel dosyaları; AGENTS.md ise ortak olanı. Üçü de aynı türden içerik taşır. Yaygın düzen, ortak kuralları AGENTS.md’de tutmak ve araç dosyalarını ona yönlendirip yalnızca o araca özel olanı eklemektir; böylece talimatlar birbirinden kopmaz. İkisi birden varsa Claude Code varsayılan olarak yalnızca CLAUDE.md’yi okur; bu yüzden AGENTS.md’yi oradan aktar ya da Project instructions ayarını değiştir.

İçine ne yazılır?

Yeni bir ekip arkadaşının ilk gün bilmesi gerekenleri ve her prompt’ta tekrarlayacağın şeyleri yaz. Kısa tut: ajanlar bu dosyayı oturumun başında bağlamlarına yükler.

Kurulum, derleme ve test komutları, tam çalıştırıldığı hâliyle.
Linter’ın denetlemediği kod stili ve kurallar.
Proje düzeni: neyin nerede durduğu, hangi klasörlerin üretildiği.
Commit ve pull request kuralları.
Asla yapılmaması gerekenler: üretilmiş dosyaları düzenlemek, gizli bilgileri commit’lemek gibi.

Kısa bir örnek

Bir TypeScript projesi için küçük bir AGENTS.md şöyle olabilir. Monorepo’da her paketin kendi AGENTS.md’si olabilir; ajanlar düzenledikleri dosyaya en yakın olanı kullanır.

## Komutlar: pnpm install; her commit’ten önce pnpm test, dosya taşıdıktan sonra pnpm lint çalıştır.
## Stil: TypeScript strict modu, tek tırnak, noktalı virgül yok.
## Düzen: uygulama kodu src/ altında; src/gen/ içindeki API istemcisi üretilir, elle düzenleme.
## Pull request: başlık “[paket] Kısa özet” biçiminde; lint ve testler geçmeli.

AgentVera nerede duruyor?

AgentVera her ajanın kendi CLI’ını proje klasöründe başlatır, bu yüzden AGENTS.md ve araç dosyaları her zamanki gibi geçerlidir; ajanın rol ve talimatlar alanı bunların üstüne kalıcı talimat ekler, ek talimat bayrağı olmayan CLI’lar (örneğin Cursor, Gemini CLI ve Amp) ise projenin AGENTS.md’sine ya da kural dosyalarına dayanır.

Sık sorulanlar

AGENTS.md resmî bir standart mı?

Zorunlu alanı ya da şeması olmayan açık bir biçim: işine yarayan başlıklarla yazılmış düz Markdown. Adresi agents.md.

Hem CLAUDE.md hem AGENTS.md gerekir mi?

Şart değil. Yeni Claude Code sürümleri CLAUDE.md yoksa AGENTS.md’yi okur. Claude’a özel kuralların varsa, AGENTS.md’yi @AGENTS.md ile aktaran kısa bir CLAUDE.md tut.

Dosya nereye konur?

Deponun köküne. Büyük depolarda alt klasörlere de eklenebilir; düzenlenen koda en yakın dosya önceliklidir, sohbette verilen doğrudan talimat ise hepsinin önüne geçer.

Ne kadar uzun olmalı?

İşe yarar kaldığı sürece olabildiğince kısa. Her oturumda bağlamda yer kaplar ve uzun bir dosyaya gömülmüş bir kural ajanın gözünden daha kolay kaçar.