AGENTS.md nedir, nasıl oluşturulur? İyi örneklerle adım adım rehber

Claude Code artık AGENTS.md de okuyor. 18 Eylül 2026'da çıkan 2.1.277 sürümüyle, projende CLAUDE.md yoksa ajan doğrudan AGENTS.md'ye bakıyor.

Duyuruyu Claude Code ekibinden Thariq X'te paylaştı; davranışı /config altından açıp kapatabiliyorsun. Böylece Codex, Cursor, GitHub Copilot, Jules ve Devin gibi ajanların zaten desteklediği dosyayı Claude Code da okumaya başladı. Bu rehber o dosyayı anlatıyor: ne olduğunu, nasıl kurulduğunu ve iyi örneklerinin neye benzediğini.

AGENTS.md nedir?

AGENTS.md, kodlama ajanlarına bir projede nasıl çalışacaklarını anlatan, deponun kök dizinine konan düz bir Markdown dosyasıdır. Formatın kendi sitesi onu “ajanlar için README” diye tarif ediyor. README insanlar için yazılır; AGENTS.md ise ajanın ihtiyaç duyduğu ama README'yi kalabalıklaştıracak ayrıntılar için: kurulum komutları, testlerin nasıl koşulduğu, kod kuralları, dokunulmaması gereken yerler.

Zorunlu bir alanı yok. Başlıkları sen seçersin, ajan metni okur. OpenAI formatı Ağustos 2025'te Codex ile birlikte çıkardı; Amp, Jules, Cursor ve Factory de işin içindeydi. 9 Aralık 2025'ten beri format, Linux Foundation altında kurulan Agentic AI Foundation'da (AAIF), Anthropic'in MCP'siyle aynı çatı altında duruyor. Sitesindeki sayıya göre 60 binden fazla açık kaynak projede kullanılıyor.

Neden önemli?

Çünkü çoğu ekip artık tek bir ajanla çalışmıyor. Biri Cursor'da, biri Claude Code'da çalışıyor, pull request'lere de Copilot bakıyor. Her aracın kendi dosyası olunca aynı kural beş yere yazılıyor: CLAUDE.md, .cursorrules, copilot-instructions.md ve diğerleri. Birinde güncellenen kural ötekinde eskiyor, ajanlar aynı depoda farklı davranmaya başlıyor. AGENTS.md bu dağınıklığa ortak bir ad koyuyor ve Claude Code'un katılmasıyla büyük kodlama ajanlarının neredeyse hepsi aynı dosyayı okuyabiliyor.

AGENTS.md'nin dört dönüm noktası. Kaynak: agents.md, Linux Foundation, arXiv 2602.11988, Claude Code sürüm notları.

Kod yazmıyorsan da seni ilgilendirir

Dosyanın adı kod kokuyor ama içine yazılan şey bir ekibin yazılı olmayan kuralları. Bir tasarım sistemi deposunda token'ların nerede durduğu, bir ürün ekibinin doküman klasöründe hangi belgenin güncel olduğu, hangi dosyanın elle düzenlenmeyeceği. IBM'in Carbon tasarım sistemi AGENTS.md'sinde bir bölümü tamamen tema token'larına ayırıyor; aşağıda göreceksin. Tasarımcılar arasında yayılan bir ayrım da var: UX Planet'teki bir yazı CLAUDE.md'yi “çalışma kılavuzu”, DESIGN.md'yi ise “tasarımın doğruluk kaynağı” diye ayırıyor. Aynı ayrım AGENTS.md için de geçerli: ajana nasıl çalışacağını bir dosyada, ürünün nasıl görüneceğini başka bir dosyada anlatıyorsun (yazının tamamı Medium üyelerine açık).

CLAUDE.md ve diğer dosyalardan farkı

AGENTS.md nasıl oluşturulur?

Kurulumun kendisi tek bir dosya açmaktan ibaret. Zor kısım içine ne yazacağın ve dosyanın gerçekten okunduğundan emin olmak. Beş adımda gidelim.

1. Dosyayı deponun köküne koy

Deponun kök dizininde AGENTS.md adında bir dosya aç. Büyük bir monorepo'daysan her paketin içine ayrı bir AGENTS.md koyabilirsin. Formatın kuralı basit: düzenlenen dosyaya en yakın AGENTS.md geçerli olur, sohbette verdiğin açık talimat ise hepsinin üstündedir. agents.md sitesi, OpenAI'ın ana deposunda 88 ayrı AGENTS.md olduğunu yazıyor.

İlk sürümün kısa olabilir. Temporal'ın Java SDK'sındaki dosya 59 satır ve şu başlıklardan oluşuyor:

## Repository Layout
## General Guidance
## Building and Testing
## Tests
## Commit Messages and Pull Requests
## Review Checklist

Depo yapısı, genel kurallar, derleme ve test komutları, test kuralları, commit ve PR kuralları, inceleme listesi. Ekibe yeni katılan birine ilk gün anlatacağın her şey.

2. İçine ajanın tahmin edemeyeceğini yaz

GitHub, Copilot'un özel ajan dosyalarından 2.500'den fazlasını inceledi ve iyi çalışanların altı alanı kapsadığını gördü: komutlar, test, proje yapısı, kod stili, git akışı ve sınırlar. Komutları dosyanın başına koymayı, açıklama yerine gerçek kod örneği vermeyi ve teknoloji yığınını sürümüyle yazmayı öneriyor (“React projesi” değil, “React 18, TypeScript, Vite”). İnceleme kök dizindeki AGENTS.md üzerine değil, Copilot'un .github/agents/ altındaki dosyaları üzerine yapıldı; ama bulgular aynı mantıkla taşınıyor (GitHub'ın yazısı).

Neyi yazmayacağın da en az bunun kadar önemli. ETH Zürih'in çalışması, ajanların dosyadaki talimatlara iyi uyduğunu ama depoyu tanıtan genel bölümlerin işe yaramadığını gösterdi: ajan ilgili dosyayı o bölüm olmadan da aynı hızda buluyor. Yani ajanın kendi başına bulabileceğini yazma, bulamayacağını yaz.

Sınırları yazarken GitHub'ın analizindeki üç kademe işe yarıyor. Her kural bu üç kutudan birine düşmeli:

Bunun canlı hali için Builder.io'nun kurucusu Steve Sewell'in videosu iyi bir örnek. Bir Figma tasarımını AGENTS.md olmayan bir ajana veriyor: arayüz iyi görünüyor ama ajan MUI'nin farklı bir sürümünü varsayıyor, karanlık modda bazı token'ları atlıyor. Sonra dosyayı katman katman kuruyor. En öğretici kısım, bütün projeyi değil yalnızca düzenlenen dosyayı derleyen ve test eden komutları yazması. Demo Builder.io'nun kendi ajanında çekildi, Claude Code'da değil; dosyanın mantığı aynı.

3. Claude Code'da çalıştığını doğrula

Claude Code'da AGENTS.md'yi doğrudan okumak için 2.1.277 ya da sonrası gerekiyor; sürümünü claude --version ile görebilirsin. Güncellemeden sonraki ilk oturumda dosya henüz okunmuyor, bir sonraki oturumdan itibaren devreye giriyor. Varsayılan ayar tek bir kontrole dayanıyor:

Claude Code'un varsayılan ayarında hangi talimat dosyasının okunduğu. Kaynak: Claude Code dokümantasyonu, Eylül 2026.

Dosya okunduğunda oturumda “no CLAUDE.md found; AGENTS.md loaded” diye başlayan bir satır görürsün. Dikkat: doğrudan okunan AGENTS.md, /memory ve /context listelerinde görünmüyor. Emin olmak için o satıra bak ya da Claude'a proje talimatlarında ne yazdığını sor. Satırı görmüyorsan sırayla şunlara bak: çalıştığın klasörde ya da üstünde bir CLAUDE.md veya CLAUDE.local.md var mı, oturum Bedrock, Vertex ya da Foundry gibi bir sağlayıcıda mı açıldı, telemetri kapalı mı, /config içindeki Project instructions ayarı claude-md ya da managed-only olarak mı seçili.

4. CLAUDE.md ile birlikte yaşat

Claude'a özgü talimatların varsa (plan modunun hangi klasörde kullanılacağı gibi) CLAUDE.md'yi silmek zorunda değilsin. Dokümantasyonun önerdiği yol, CLAUDE.md'nin başında AGENTS.md'yi içeri çağırmak ve Claude'a özgü notları altına yazmak:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude önce içeri çağrılan dosyayı, sonra geri kalanı okur. Bu yöntem doğrudan okumanın çalışmadığı oturumlarda da iş görür. Claude'a özgü bir şeyin yoksa ln -s AGENTS.md CLAUDE.md ile bir symlink de yeter; ama ekipte Windows kullanan biri varsa import'u seç, çünkü Git orada symlink'i düz bir metin dosyası olarak çekebiliyor. Üçüncü yol ayar: iki dosyanın da her zaman okunmasını istiyorsan ~/.claude/settings.json içine şunu ekle:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Bu ayar proje ve yerel ayar dosyalarında yok sayılıyor; kullanıcı düzeyinde, bir --settings dosyasında ya da kurumsal ayarlarda çalışıyor. Aynı değeri /config içindeki Project instructions satırından da seçebilirsin.

5. Eski geçici çözümü temizle

Claude Code AGENTS.md okumadan önce birçok ekip bir ara çözüm kurmuştu. Duyurunun altındaki cevaplarda birkaç kişinin anlattığı kurgu şu: içinde tek cümle olan bir CLAUDE.md, “AGENTS.md'yi oku”. Dokümantasyon bu kurgunun zayıf olduğunu açıkça söylüyor, çünkü Claude dosyayı ancak açmaya karar verirse görüyor. O CLAUDE.md'yi sil ya da cümleyi @AGENTS.md import'uyla değiştir. AGENTS.md'yi ekrana basan bir SessionStart hook'u kurduysan onu da kaldır; artık bağlama ikinci bir kopya ekliyor. İçinde yalnızca @AGENTS.md olan bir CLAUDE.md ise zararsız, dosya iki kez okunmuyor.

İyi AGENTS.md örnekleri

Aşağıdaki dosyaların hepsi açık kaynak ve Apache 2.0 lisanslı; tamamını kendi depolarında okuyabilirsin. Uzunlukları 53 ile 320 satır arasında değişiyor. Ortak noktaları uzunluk değil, her birinin ajanın kendi başına çıkaramayacağı bir şeyi söylemesi.

Adobe React Spectrum: standart dışını söylüyor

## Toolchain guardrails

This repo does **not** use the conventional JS toolchain ...

- Format with `yarn format` (oxfmt), **not** Prettier. Lint with `yarn lint` (oxlint), **not** ESLint.
- **Don't run `yarn chromatic` / `yarn chromatic:forced-colors`** ...

Ajan bir JavaScript deposu gördüğünde Prettier ve ESLint'e uzanır, çünkü gördüğü depoların çoğu öyle. Spectrum bu varsayımı ilk satırda bozuyor. ETH çalışmasının bağlam dosyalarının asıl işe yaradığı yer dediği tam olarak bu: standart dışı pratiği açıkça yazmak. İkinci madde bir “asla” kuralı; görsel regresyon testlerini bakımcılar koşuyor, ajan değil.

IBM Carbon: tasarım token'larının adresini veriyor

<!--
HUMAN MAINTAINERS:
This file should be as short as possible. More length = more tokens used.
-->
...
## Theme token lookup

- All four theme token values and descriptions live in a single file:
  `packages/themes/src/dtcg/themes.json`. Component tokens are in
  `packages/themes/src/dtcg/components/`.
- Tokens use nested JSON keys (e.g. `layer-accent-active-03` is
  `layer.accent.active.03`), so search by key segments rather than flat token
  names.

İki şey öğretiyor. Birincisi en üstteki not: dosyayı düzenleyen insanlara “kısa tut, her satır token demek” hatırlatması. Claude Code bu tür blok HTML yorumlarını dosyayı bağlama koymadan önce siliyor; not insana görünüyor, ajana maliyet yazmıyor. İkincisi token bölümü: ajana token'ların nerede durduğunu ve nasıl aranacağını söylüyor. Sewell'in demosunda ajanın karanlık modda token atlaması, bu bölüm olmayınca ne olduğunu gösteriyordu.

OpenAI Codex: yasağı gerekçesiyle yazıyor

- Never add or modify any code related to `CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR` or `CODEX_SANDBOX_ENV_VAR`.
  - You operate in a sandbox where `CODEX_SANDBOX_NETWORK_DISABLED=1` will be set whenever you use the `shell` tool. ...

1. Do not run `cargo test` directly. Use `just test` so test execution follows the repo defaults.

Yasak tek başına bırakılmamış, nedeni yanında duruyor. Ajan bu değişkene bakan testleri neden “garip” bulduğunu anlıyor ve düzeltmeye kalkmıyor. İkinci satır klasik bir standart dışı komut: Rust'ta herkes cargo test yazar, bu depo just test istiyor. Dosya 320 satırla Claude Code dokümantasyonunun önerdiği 200 satır sınırının üstünde. ETH çalışması da uzunluğun başarıyla ilişkili olmadığını buldu; ölçüt satır sayısı değil, her satırın bir işi olması.

Apache Airflow: sınırı kademeli çiziyor

## Boundaries

- **Ask first**
  - Large cross-package refactors.
  - New dependencies with broad impact.
  - Destructive data or migration changes.
- **Never**
  - Commit secrets, credentials, or tokens.
  - Edit generated files by hand when a generation workflow exists.
  - Use destructive git operations unless explicitly requested.

Yukarıdaki üç kademenin ikisi, somut maddelerle. Airflow bir adım daha atıyor ve dosyanın en başına projenin kendi yazım kuralını koyuyor: düz yazıda her zaman “Dag”, kodda DAG. Ajanın dokümantasyon yazarken kendi başına tutturamayacağı türden bir ev kuralı.

Beş dosyanın ortak dersini tek cümleye indirirsek:

İyi bir AGENTS.md ajana projeyi anlatmaz, projenin tuhaflıklarını anlatır.

Yaygın hatalar

• Depo turu yazmak. Klasörleri tek tek tanıtan bölümler ajanı hızlandırmıyor; ETH çalışmasında ilgili dosyaya ulaşma süresini kısaltmadıkları görüldü. Yerine “bu klasörü örnek alma, eski” gibi yön veren tek satırlar yaz.
• /init çıktısını olduğu gibi bırakmak. Otomatik üretilen dosyalar çoğunlukla depodaki dokümantasyonu tekrar ediyor. Aynı çalışmada modelin ürettiği bağlam dosyaları başarıyı hafifçe düşürdü, geliştiricilerin yazdıkları hafifçe artırdı. /init iyi bir başlangıç; çıktıdan ajanın zaten bildiğini sil.
• Dosyayı kelimeyle çağırmak. CLAUDE.md'ye “AGENTS.md'yi oku” yazmak, ajanın dosyayı açmaya karar vermesine bel bağlamak demek. İçeri çağırmak için @AGENTS.md kullan.
• CLAUDE.local.md'yi unutmak. Kendi notların için bu dosyayı açtığın an Claude Code senin makinende AGENTS.md'yi okumayı bırakıyor. Depo herkes için doğru görünür, fark sadece sende oluşur.
• Dosyayı güvenlik duvarı sanmak. Claude Code bu dosyaları bağlam olarak okuyor, zorunlu ayar olarak değil. Bir eylemi kesin engellemek istiyorsan izin ayarlarını ya da bir PreToolUse hook'unu kullan; AGENTS.md'deki “asla” bir rica.
• Tanımadığın deponun dosyasına güvenmek. Klonladığın her deponun AGENTS.md'si ajana talimat olarak yüklenir. Başkasının deposunda çalışmaya başlamadan önce dosyayı bir kez kendin oku.
• Çelişen kurallar bırakmak. İki kural birbirini tutmazsa Claude Code dokümantasyonuna göre ajan birini keyfi seçebilir. Kök dosyayı, alt klasör dosyalarını ve kural klasörünü ara ara birlikte gözden geçir.

Brick'te ajanlarla kurduğumuz iş akışlarında da aynı dersi aldık. Talimat dosyalarımızda fark yaratan satırlar kim olduğumuzu anlatan uzun paragraflar olmadı; “uzun çizgi kullanma” gibi, ajanın kendi başına tahmin edemeyeceği tek satırlık ev kuralları oldu.

Kendi dosyanı yazmaya başlarken tek bir alışkanlık yeter.

Sen ekibinde kaç farklı ajan kullanıyorsun ve her biri için ayrı bir talimat dosyası mı tutuyorsun? Dosya ortaklaştığında asıl kazanç teknik değil: ekibin yazılı olmayan kurallarını ilk kez yazıya döküyorsun. 🧱