Claude Code AGENTS.md Desteği: CLAUDE.md ile Nasıl Kullanılır?

Claude Code'un AGENTS.md desteği v2.1.277 ile geldi: CLAUDE.md bulunmayan bir projede Claude Code artık AGENTS.md dosyanızı proje talimatları olarak okuyor. İçe aktarma, sembolik bağlantı veya ayar gerekmiyor. Deponuzda her iki dosya da varsa Claude yalnızca CLAUDE.md'i okur; /config içindeki Project instructions ayarını değiştirip ikisini birden yüklemesini sağlamadıkça.

Ekibiniz birden fazla kodlama ajanı kullanıyorsa, Codex ve Cursor'ın zaten okuduğu AGENTS.md dosyası artık Claude Code'u da yönlendiriyor. Bu rehber; öncelik sırasını, geçişi ve herhangi bir ajana Apidog CLI ile API'lerinizi test etmeyi öğreten bir AGENTS.md örneğini kapsıyor.

Claude Code'da AGENTS.md nedir?

AGENTS.md, kodlama ajanları için talimatlar içeren düz bir Markdown dosyasıdır: derleme komutları, test komutları, kod stili ve proje kuralları. v2.1.277'den itibaren Claude Code bunu yerleşik bir eklenti üzerinden okur; böylece diğer ajanlar için hazırlanmış bir depo, ek dosyaya gerek kalmadan Claude Code ile çalışır. Zorunlu alan veya özel sözdizimi gerektirmez.

Formatın kendisi açıktır. AGENTS.md sitesi, bunu "kodlama ajanlarını yönlendirmek için basit ve açık bir format" olarak tanımlar; 60.000'den fazla açık kaynak projesi tarafından kullanılır ve artık Linux Foundation bünyesindeki Agentic AI Foundation tarafından yönetilmektedir. OpenAI Codex ve Cursor ikisi de AGENTS.md desteğini belgeliyordu ve bu sürüme kadar açıkça desteklemeyen tek taraf Claude Code'du.

Formatla yeni mi tanışıyorsunuz? API geliştirme ekipleri için AGENTS.md dosyaları nasıl yazılır makalesiyle başlayın.

Resmi Claude Code değişiklik günlüğünden sürüm izleri şöyle:

Bunlara güvenmeden önce claude --version komutunu çalıştırın. 2.1.277'den eski sürümlerde Claude Code yalnızca CLAUDE.md dosyalarını okur.

CLAUDE.md mi AGENTS.md mi: hangisi geçerli olur?

Varsayılan olarak CLAUDE.md önceliklidir. Claude Code, AGENTS.md'i yalnızca çalışma dizininizde veya üzerindeki herhangi bir dizinde CLAUDE.md yoksa okur. Claude Code bellek belgeleri üç durumu açıkça belirtir:

Her dosya bu kontrol için sayılmaz. Şu üçü AGENTS.md'i engeller:

• Çalışma dizininde veya üzerinde bir CLAUDE.md
• Çalışma dizininde veya üzerinde bir .claude/CLAUDE.md
• Çalışma dizininde veya üzerinde bir CLAUDE.local.md

Bunlar engellemez ve AGENTS.md ile birlikte yüklenmeye devam eder: ~/.claude/CLAUDE.md konumundaki kullanıcı dosyanız, kuruluşunuzun yönetilen CLAUDE.md'i ve .claude/rules/ altındaki dosyalar.

CLAUDE.local.md tuzağına dikkat: kişisel notlar için bir tane eklerseniz, Claude sizin için ekibin AGENTS.md dosyasını okumayı bırakır.

Claude Code neyi, ne zaman yükler?

Hiçbir şey engellemiyorsa Claude Code şunları okur:

1. Oturum başlangıcında: çalışma dizinindeki ve üzerindeki dizinlerdeki her AGENTS.md ve .claude/AGENTS.md dosyasını. Etkileşimli oturumlar no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md gibi bir satır yazdırır.
2. Alt dizinlerde: Claude, Read aracıyla orada bir dosya açtığında ve o klasörün kendisine ait bir CLAUDE.md'i olmadığında, alt dizinin AGENTS.md'ini okur.
3. İçe aktarmalar: AGENTS.md içindeki @path içe aktarmaları genişletilir ve claudeMdExcludes desenleri uygulanır.

Claude Code, AGENTS.local.md, AGENTS.override.md veya .agents/ altındaki hiçbir şeyi okumaz. AGENTS.override.md'i belgeleyen Codex ile bir depo paylaşıyorsanız bunu aklınızda tutun.

Claude Code'un hangi talimat dosyalarını yüklediğini değiştirme

Bir oturumda /config yazın ve Project instructions ayarını dört değerden birine getirin:

Karma ekiplerin çoğu için istediğiniz ayar claude-md-and-agents-md'dir. Kişisel CLAUDE.local.md dosyanızı korur ve yine de paylaşılan AGENTS.md'i yükler.

Bunu bir ayar dosyasıyla da yapabilirsiniz. Claude Code bu girdiyi ~/.claude/settings.json, bir --settings dosyası veya yönetilen ayarlardan okur; proje ve yerel ayar dosyalarında yok sayar:

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

v2.1.285 öncesinde eklenti kimliği agents-md@builtin'di. 2.1.285 ve sonrasındaki sürümler her iki kimliği de okur; dosyayı eski sürümler de kullanıyorsa eski kimliği tercih edin. Değişiklik bir sonraki mesajınızdan itibaren geçerli olur.

/config içinde Project instructions görünmüyorsa oturumunuz AGENTS.md'i yükleyemiyor demektir: 2.1.277 öncesi bir sürümde olabilirsiniz, yerleşik eklentiyi /plugin üzerinden devre dışı bırakmış olabilirsiniz ya da bu, güncellemeden sonraki ilk oturumunuzdur (bir sonrakinden itibaren çalışır).

Eski bir AGENTS.md geçici çözümünü taşıma

Bu sürümden önce birçok ekip AGENTS.md'i Claude Code'a elle bağlamıştı. Belgeler şunu önerir:

Ekibinizde hâlâ 2.1.277 öncesi bir sürüm kullanan varsa @AGENTS.md içe aktarmasını koruyun. Her sürümde çalışan tek kurulum budur.

İçe aktarma mı, sembolik bağlantı mı?

Paylaşılan dosyanın üzerine Claude'a özel kurallar eklemeniz gerekiyorsa içe aktarmayı kullanın. Claude önce içe aktarılan dosyayı, sonra geri kalanını okur:

@AGENTS.md

## Claude Code

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

Claude'a özel bir şeye ihtiyacınız yoksa sembolik bağlantı da iş görür:

ln -s AGENTS.md CLAUDE.md

İki püf noktası: Claude'un Edit ve Write araçları sembolik bağlantı üzerinden yazamaz; ayrıca Windows'ta Git, core.symlinks açık değilse commit edilmiş bir sembolik bağlantıyı tek satırlık bir metin dosyası olarak çeker. Ekibinizde Windows kullanan varsa içe aktarmayı seçin.

Hangisini seçerseniz seçin, bir sonraki oturumunuzda /context all komutunu çalıştırın ve CLAUDE.md'in Memory files altında göründüğünü doğrulayın.

Codex, Cursor ve Claude Code için tek bir AGENTS.md

Kazanç, tek bir doğruluk kaynağıdır. Derleme komutlarınızı, test komutlarınızı ve kurallarınızı depo kökündeki AGENTS.md'e koyun. Codex, Cursor ve Claude Code hepsi onu okur.

Pratikte işe yarayan bir düzen:

• Kök dizinde AGENTS.md: her ajanın ihtiyaç duyduğu her şey. Komutlar, klasör haritası, stil kuralları, dokunulmaması gerekenler.
• Büyük alt klasörlerde AGENTS.md: yalnızca orada geçerli olan kurallar; örneğin services/payments/AGENTS.md. Claude Code bunları, o klasördeki bir dosyayı okuduğunda talep üzerine yükler.
• İsteğe bağlı CLAUDE.md: yalnızca plan modu veya hook'lar gibi Claude'a özel bir davranışa ihtiyacınız varsa. @AGENTS.md ile başlatın.

Tek uyarı: ayar üzerinden yüklenen bir AGENTS.md, InstructionsLoaded hook'larını tetiklemez ve --add-dir dizinlerinden yüklenmez. Bunlardan birine güveniyorsanız @AGENTS.md içe aktarma yolunu kullanın.

Ajanınıza AGENTS.md içinde Apidog CLI ile API test etmeyi öğretin

API test kurallarınızı bir kez yazın; depoyu hangi ajan açarsa açsın testleri aynı şekilde çalıştırır. Apidog CLI, ajana okuyabileceği yapılandırılmış JSON çıktısı verir; böylece döngü terminalde kalır.

Makine başına bir kez kurun:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Kısa bir yol: ajanınıza "https://apidog.com/apidog-cli-installation-guide.md adresini oku ve Apidog CLI'ı kur" deyin. O rehber ajanlar için yazılmıştır ve kurulumu, girişi ve skill'i kapsar.

Ardından AGENTS.md dosyanıza şöyle bir bölüm ekleyin:

## API testing (Apidog CLI)

- Apidog project ID: 123456. Staging environment ID: 7890.
- Never build Apidog JSON payloads from memory. Run
  `apidog cli-schema get <key>` first, then
  `apidog cli-schema validate <key> --file <path>`, and write only after it passes.
- After changing any handler under `src/routes/`, find its endpoint with
  `apidog endpoint list --project 123456` and its cases with
  `apidog test-case list --project 123456 --endpoint <endpointId>`.
- If a route has no test case, create one with
  `apidog test-case create --project 123456 --file case.json`.
- Run cases with
  `apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json`
  and summarize every failure before you say the task is done.
- Do not edit or delete endpoints in Apidog unless the task asks for it.

Artık tek bir istem, Claude Code, Codex veya Cursor'da işi halleder:

I changed POST /orders to require a currency field. Update the Apidog test
case for it and run it against staging, following AGENTS.md.

Ajan kurallarınıza uyar ve şuna benzer komutları çalıştırır:

apidog endpoint list --project 123456
apidog test-case list --project 123456 --endpoint <endpointId>
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json

Yukarıdaki her bayrak, Apidog CLI 2.2.12'deki apidog <cmd> --help çıktısından alınmıştır. -r junit ile aynı apidog run satırı CI'a doğrudan girer; --upload-report ise çalışma özetini uygulamaya göndererek ekibinizin görmesini sağlar. Claude Code tarafının ayrıntıları için Claude Code'da Apidog CLI nasıl kullanılır makalesine; Codex kullanıcıları Codex'te Apidog CLI rehberine bakabilir. Apidog Free 4 kullanıcıya kadar kapsar; küçük bir ekip bunu bugün deneyebilir.

Sorun giderme: AGENTS.md dosyam yüklenmiyor

1. Yolda bir CLAUDE.md var mı bakın. Çalışma dizininizde veya üzerinde bir CLAUDE.md, .claude/CLAUDE.md ya da CLAUDE.local.md varsa varsayılan olarak o kazanır. ~/.claude/CLAUDE.md dosyanız sayılmaz.
2. Sürümünüzü kontrol edin. claude --version komutunu çalıştırın. 2.1.277 veya üstü; Bedrock, Vertex AI, Foundry, ağ geçitlerinde ya da telemetri kapalıyken 2.1.281 veya üstü gerekir.
3. Ayarı kontrol edin. /config'i açın ve Project instructions ayarının claude-md veya managed-only olmadığından emin olun.
4. Yüklendiğini doğrulayın. /memory komutunu çalıştırın ve listede AGENTS.md yolunu arayın.

SSS

Claude Code artık AGENTS.md'i okuyor mu? Evet, v2.1.277'den itibaren. Çalışma dizininizde veya üzerinde CLAUDE.md yoksa Claude Code, AGENTS.md'i otomatik olarak proje talimatları olarak okur.

Hem CLAUDE.md hem AGENTS.md varsa Claude Code hangisini kullanır? Varsayılan olarak yalnızca CLAUDE.md'i. İkisini birden, önce CLAUDE.md olmak üzere yüklemek için /config içinde Project instructions ayarını claude-md-and-agents-md yapın.

@AGENTS.md içe aktaran CLAUDE.md dosyamı silmeli miyim? Gerek yok. İçe aktarma AGENTS.md'i asla iki kez yüklemez ve 2.1.277 öncesi sürümlerdeki ekip arkadaşlarınız için hâlâ çalışır. Yalnızca içinde başka bir şey yoksa ve herkes güncelleme yaptıysa silin.

Claude Code, Codex gibi AGENTS.override.md'i okur mu? Hayır. Claude Code, AGENTS.override.md, AGENTS.local.md ve .agents/ altındaki hiçbir şeyi okumaz.

AGENTS.md Amazon Bedrock veya Google Vertex AI'da çalışıyor mu? Evet, v2.1.281'den itibaren. Bedrock, Vertex AI, Foundry, ağ geçitlerinde ya da telemetri kapalıyken önceki sürümler yalnızca CLAUDE.md okur; orada bir @AGENTS.md içe aktarması kullanın.