SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor · Güncellendi 2026-10-30

Monorepo yapısında iç içe AGENTS.md kullanımı

Monorepo projelerinde tek bir AGENTS.md dosyası güncelliğini yitirir ve gereksiz bağlam tüketir. İç içe dosya yapısı ile aracıların sadece ilgili dizine odaklanmasını sağlayın.

Monorepo yapısında iç içe AGENTS.md dosyalarının anlamı

Monorepo yapısında iç içe AGENTS.md dosyaları, depo kök dizininde bir adet küçük dosya ve her servis dizininin içinde birer adet daha dosya bulunması anlamına gelir. Kök dizindeki dosya, her yerde geçerli olan birkaç kuralı ve diğer dosyaların nerede bulunduğunu gösteren bir haritayı içerir. Her servis dosyası ise yalnızca o dizine özgü komutları ve kuralları barındırır. services/worker/queue.py dosyasını düzenleyen bir aracı, kök dosyayı ve ilgili servis dosyasını okur; böylece asla dokunmayacağı ön yüz (front end) için hiçbir bağlam (context) harcamaz.

Kurulacak herhangi bir şey yoktur. AGENTS.md bir gelenektir ve yukarı akış (upstream) projesi bunu açıkça belirtir:

AGENTS.md sadece standart Markdown dosyasıdır. İstediğiniz başlıkları kullanabilirsiniz; aracı, sağladığınız metni basitçe ayrıştırır.

Bu teknik, doğru şekilde öğrenilmeye değerdir. Format sizin üzerinizde değişmeyecektir. Bozulacak olan şey yerleşim ve bakımdır; bunların her ikisi de sizin sorumluluğunuzdadır.

Neden tek bir büyük kök dizin AGENTS.md dosyası çalışmayı durdurur?

Bir web uygulaması, bir arka plan işçisi ve bir Terraform dizini barındıran bir deponun kök dizinindeki 600 satırlık tek bir AGENTS.md dosyası, dört farklı şekilde başarısız olur.

Sahiplenilmediği için güncelliğini yitirir. apps/web altındaki bir test betiğini yeniden adlandıran mühendis, apps/web altındaki dosyaları düzenler. Kök dizindeki AGENTS.md bu fark (diff) içinde yer almadığından, hiçbir gözden geçiren kişi uyumsuzluğu görmez. Altı hafta sonra dosya artık var olmayan bir derleme adımını tarif eder ve onu bozan kişi değişikliği unutmuştur.

Her görevde bağlam maliyeti yaratır. Bu dosyalar, oturumun başında, ajan size ne soracağınızı bilmeden önce yüklenir. Claude Code belgeleri buna bir sınır koyar: "CLAUDE.md dosyası başına 200 satırın altını hedefleyin. Daha uzun dosyalar daha fazla bağlam tüketir ve uyumu azaltır." Codex, talimat dosyalarının toplam boyutu varsayılan project_doc_max_bytes olan 32 KiB değerine ulaştığında bunları birleştirmeyi durdurur. Dört servisi belgeleyen bir kök dosya, her görev için bu bütçeyi diğer üç servis için harcar.

Talimatlar birbiriyle çelişmeye başlar. Web dizini pnpm test ister. İşçi dizini pytest -q ister. Tek bir dosyaya yazıldığında, her kural sadece bazen doğrudur, bu yüzden ajan hangisinin geçerli olduğunu tahmin etmek zorunda kalır. Claude Code belgeleri sonucu şöyle tarif eder: "iki talimat birbiriyle çelişirse, Claude birini keyfi olarak seçebilir." Dosyayı bölmek, diğer kuralın bağlam dışında kalmasını sağlamaz. Claude Code, bir dosyayı diğeriyle değiştirmek yerine yüklediği tüm talimat dosyalarını birleştirir; bu nedenle kök dosya her zaman oradadır ve ajan hem apps/web hem de services/worker içindeki dosyaları açtığında, her iki dizin dosyası da bağlamda birlikte yer alır. Dizin bazlı bir dosyanın yaptığı şey, her kuralı yönettiği dizine bağlamaktır. Aşağıdaki # apps/web örneklerinde olduğu gibi, dosyanın en üstünde dizin adını belirtin; böylece birden fazla dosya yüklendiğinde her komut nerede geçerli olduğunu belirtmiş olur. Açıkça yazdığınızdan emin olduğunuz bir kural yine de atlandığında, bir talimatın neden asla uygulanmadığının nedenleri üzerinde çalışmak, ifadeyi dördüncü kez yeniden yazmaktan daha etkilidir.

Ajanın koddan okuyabileceği gerçeklerle dolar. Bir dizin ağacı, bağımlılık listesi, her paketin ne yaptığına dair bir özet. Claude Code'un /doctor denetimi tam olarak bunu ayıklamak için vardır. "Claude'un kod tabanından çıkarabileceği dizin yapıları, bağımlılık listeleri ve mimari genel bakışlar gibi içerikleri keser" ve "tuzakları, mantığı ve araç varsayımlarından farklı olan kuralları" tutar. Bu cümle, bir satırın dosyaya ait olup olmadığını anlamak için bildiğim en iyi testtir.

Ajan kök dizindeki dosyayı mı yoksa yalnızca en yakın olanı mı okur?

Çoğu kişinin modeli yanlış anladığı nokta burasıdır; bu nedenle konuyu kendi cümlelerimizle ifade etmek yerine yukarı akış (upstream) kuralını doğrudan alıntılamak daha doğrudur:

Her paketin içine bir AGENTS.md yerleştirin. Ajanlar dizin ağacındaki en yakın dosyayı otomatik olarak okur, bu sayede en yakındaki dosya öncelik kazanır ve her alt proje kendine özel talimatlar sunabilir.

Çakışmalar konusunda ise:

Düzenlenen dosyaya en yakın AGENTS.md geçerli olur; açık kullanıcı sohbet istemleri ise her şeyin üzerindedir.

"Öncelik kazanır" ifadesi birçok kişi tarafından "kök dizindeki dosya yok sayılır" şeklinde yorumlanır. Ancak durum böyle değildir. Kuralı uygulayan araçlarda, depo kökünden çalışma dizinine kadar olan yol üzerindeki her dosya okunur ve birleştirilir. En yakın dosya, yalnızca iki dosya aynı konu hakkında farklı şeyler söylediğinde geçerli olur.

Codex, mekanizma konusunda nettir: "Codex, dosyaları kökten başlayarak birleştirir ve aralarına boş satırlar ekler. Mevcut dizininize daha yakın olan dosyalar, önceki yönlendirmeleri geçersiz kılar." Claude Code da aynı yolu izler. Oturum başlangıcında çalışma dizininizdeki ve üzerindeki dizinlerde bulunan "her AGENTS.md ve .claude/AGENTS.md dosyasını" okur ve belgeleri yükleme modelini açıkça belirtir: "Bulunan tüm dosyalar birbirini geçersiz kılmak yerine bağlama eklenerek birleştirilir." Çalışma dizininin altındaki dizinler farklı davranır: Claude Code, bir alt dizinin AGENTS.md dosyasını talep üzerine, "Claude oradaki bir dosyayı Read aracıyla açtığında" yükler.

Bunun iki pratik sonucu vardır. Kök dizindeki dosya, depodaki her oturumun ön ekidir; bu nedenle oradaki her satırı haftada yüz kez ödediğiniz bir maliyet olarak görün. Dizin bazlı bir dosya ise ajan o dizinde bir dosya açana kadar hiçbir maliyet oluşturmaz; bu da ayrıntıların orada ucuz olduğu ve oraya ait olduğu anlamına gelir.

Bu davranış, 27 Ekim 2026 tarihinde Codex ve Claude Code belgeleri üzerinden kontrol edilmiştir. Araçlar kuralı biraz farklı uygular ve zamanla değişiklik gösterebilirler; bu nedenle ekibinizin kullandığı ajan için yükleme kurallarını teyit edin.

Üç servisli bir depo için çalışma düzeni

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

Kök dizindeki dosya bilinçli olarak kısa tutulmuştur. Hangi dizinlere bakılacağını belirtir ve yalnızca her dizin için geçerli olan kuralları içerir.

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

Dizin bazlı dosya, detayların yer aldığı yerdir ve dizinin gerektirdiği uzunlukta olabilir.

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

Worker dosyası, farklı içeriklerle aynı yapıya sahiptir: kurulum komutu, pytest -q, tüketicinin neden idempotent kalması gerektiği ve testlerin geçmesi için çalışması gereken migrasyon. Infra dosyası, bir ajanın zarar vermesini engelleyen kuralları yazdığınız yerdir. Asla terraform apply çalıştırmayın. terraform plan komutunu çalıştırıp orada durun ve ajanın yenisini başlatmaya çalışmaması için halihazırda yapılandırılmış olan state backend ismini belirtin.

Bu dosyaların hiçbirinde yer almayan şeye dikkat edin: her servisin ne işe yaradığına dair bir açıklama. Bu, insanların sorumluluğundadır. Upstream aynı ayrımı yaparak "README.md dosyaları insanlar içindir: hızlı başlangıçlar, proje açıklamaları ve katkı kılavuzları" derken, AGENTS.md dosyası "kodlama ajanlarının ihtiyaç duyduğu ek ve bazen detaylı bağlamı: derleme adımları, testler ve kurallar" içerir. AGENTS.md ile insan odaklı README arasındaki ayrım, bu sınırı cümle cümle ele alır ve kodun neden bu şekilde yapılandırıldığını kaydeden bir DESIGN.md, komutlardan ziyade kararları açıklayan üçüncü dosyayı kapsar.

Kod değiştiğinde dosyayı kim günceller?

Tek bir kural vardır ve bu kural kök dizindeki dosyada yer alır: Bir dizindeki kodu değiştiren kişi, aynı commit içerisinde o dizinin AGENTS.md dosyasını da günceller.

Bu yöntem kültürel bir nedenden değil, mekanik bir gereklilikten dolayı işler. Dizin bazlı dosya, kodla aynı diff içerisinde yer alır; bu sayede pull request incelemesini yapan kişi her ikisini de aynı anda görür. Kök dizindeki bir dosya herkese aitmiş gibi görünür, bu da aslında kimseye ait olmadığı anlamına gelir ve kimsenin okumakta olduğu diff içerisinde yer almaz.

Bu kuralı, pull request üzerinde bir denetim ile destekleyin. Bu denetim, değiştirilen her dosyanın üst dizinindeki en yakın AGENTS.md dosyasını bulur ve dosyanın güncellenmediği durumlarda rapor verir.

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

Dokümantasyona dokunmadan API istemcisini yeniden düzenleyen bir dalda çıktı şu şekilde görünür:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

Bunu bir hata (failure) yerine uyarı (warning) olarak tutun. Kesin bir engel, insanların CI sürecini yeşile döndürmek için dosyaya boş bir satır eklemesine neden olur; bir robotu tatmin etmek için düzenlenen bir dosyanın değeri, hiç olmamasından daha düşüktür. Uyarı, incelemeyi yapan kişiye sorması gereken soruyu hatırlatır; asıl işe yarayan kısım da budur.

Güncelliğini yitirmiş bir AGENTS.md dosyasını nasıl tespit ederim?

Bugün çalıştırabileceğiniz iki kontrol ve bir oturum sırasında karşılaşacağınız bir belirti bulunmaktadır.

Her dosyanın yaşını, tanımladığı kodun yaşıyla karşılaştırın. %cs, commit tarihini YYYY-MM-DD olarak yazdırır.

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done
apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

Kod tarihinden altı ay geride olan bir doküman tarihi, dosyanın yanlış olduğunu kanıtlamaz. Bu durum size yalnızca ilk olarak hangi dosyayı okumanız gerektiğini söyler; bir saniye süren bir kontrolden beklediğiniz tek şey de budur.

Artık mevcut olmayan yolları arayın. Dokümantasyon çok belirli bir şekilde eskir: silinmiş kodları tanımlamaya devam eder. Bu dosyalardaki her yol backtick işaretleri içinde yazılıdır, bu nedenle bunları ayıklamak ve test etmek kolaydır.

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

Bunu CI sürecine dahil etmek yerine çıktıyı kendiniz okuyun. Bu yöntem ayrıca src/**/*.ts gibi glob ifadelerini ve alıntıladığınız tüm URL'leri işaretler; çünkü her ikisi de eğik çizgi içerir ve diskte bir dosya değildir. Claude Code v2.1.283 veya sonraki sürümlerde, /doctor prompt-audit sizin için benzer bir tarama gerçekleştirir: "mevcut olmayan dosya veya komut referanslarını" ve birbiriyle çelişen dosyaları arar, AGENTS.md dosyalarınızı varsayılan olarak kapsar ve siz önerdiği düzenlemeleri uygulamasını isteyene kadar hiçbir şeyi değiştirmez.

Oturumdaki belirti. Ajan dosyayı okur, dosya talimat verdiği için src/api/client.ts dosyasını açmaya çalışır ve araç şu çıktıyı döndürür:

No such file or directory

Bu durumda ajan mantıklı olanı yapar ve kendi fetch sarmalayıcısını yazar. Güncelliğini yitirmiş bir dosyanın gerçek maliyeti budur. Ajan dokümantasyonunuzu görmezden gelmez. Dokümantasyonu takip eder, üç ay önce silinmiş bir yola ulaşır ve zaten sahip olduğunuz kodu yeniden oluşturur. Bir ajanı çalışan en küçük değişikliğe bağlı tutan Ponytail gibi bir yetenek, bu yeniden oluşturma içgüdüsünü nadir hale getirir ancak dosyanızın yanlış yere işaret ettiği bir yardımcıyı bulamaz.

Claude Code, AGENTS.md dosyalarını okur mu?

Evet, Claude Code v2.1.277 sürümünden itibaren okur. İç içe geçmiş dizin yapısı buna bağlı olduğundan, kuralın tam olarak uygulanması önemlidir. 27 Ekim 2026 tarihli belgelere göre: "Claude Code, AGENTS.md dosyasını proje talimatlarınız olarak okuyabilir; bu sayede diğer kodlama ajanları için yapılandırılmış bir depo, ek bir CLAUDE.md, içe aktarma veya ayar gerektirmeden çalışır." Varsayılan Project instructions değeri olan claude-md-or-agents-md, "çalışma dizininizde veya üst dizinlerinizde CLAUDE.md veya CLAUDE.local.md bulunmadığında AGENTS.md dosyalarınızı" okur. İç içe geçmiş dosyalar da kapsam dahilindedir: Claude, "o alt dizinde kendi CLAUDE.md dosyalarından hiçbiri bulunmadığı" sürece, "Claude o dizindeki bir dosyayı Read aracıyla açtığında" alt dizinin AGENTS.md dosyasını okur. Bu üç dosya CLAUDE.md, .claude/CLAUDE.md ve CLAUDE.local.md'tir; dolayısıyla apps/web içindeki kişisel bir CLAUDE.local.md, apps/web/AGENTS.md dosyasının yüklenmesini durdurmak için yeterlidir.

Bu durum, her AGENTS.md yanına bir CLAUDE.md koyma şeklindeki eski tavsiyeyi bir tuzağa dönüştürür. Çalışma dizininizde veya üstünde bir AGENTS.md ile bir CLAUDE.md veya CLAUDE.local.md varsa, belgeler Claude'un "yalnızca CLAUDE.md dosyalarınızı" okuduğunu belirtir. Bir .claude/CLAUDE.md de aynı şekilde sayılır. Kök dizinde Claude'a özel tek bir satır içeren bir eşlikçi dosya, yol üzerindeki her AGENTS.md dosyasını gizler; kişisel bir CLAUDE.local.md de aynı sonucu doğurur. Birini tutmak isterseniz, /config yazın ve Project instructions ayarını, her dizinin CLAUDE.md dosyasını önce, AGENTS.md dosyasını sonra okuyacak şekilde claude-md-and-agents-md olarak belirleyin.

Yalnızca sürüm numarası çalışıp çalışmadığını doğrulamak için yeterli değildir. v2.1.277 veya sonraki bir sürüm gerekir; ancak v2.1.281 öncesinde Amazon Bedrock üzerindeki veya telemetri devre dışı bırakılmış bazı oturumlar yalnızca CLAUDE.md dosyalarını okur. Bazı durumlarda v2.1.276 veya öncesinden v2.1.281'e yükseltme yaptıktan sonraki ilk oturum AGENTS.md dosyasını da atlar: belgeler "Claude, AGENTS.md dosyasını bir sonraki oturumunuzdan itibaren okur" der. Bu yüzden oturumu kontrol edin. Etkileşimli bir oturumda Claude Code, no CLAUDE.md found; AGENTS.md loaded: gibi bir satırı ve ardından dosya yolunu yazdırır; güncel sürümlerde /memory dosyayı listeler. v2.1.280 öncesinde /memory ve /context, Claude'un doğrudan okuduğu bir AGENTS.md dosyasını listelemiyordu; bu sürümlerde Claude'a proje talimatlarının ne olduğunu sorun.

İçe aktarma (import) yöntemi, Claude'un AGENTS.md dosyasını doğrudan okuyamadığı durumlarda hala geçerlidir: eski bir sürüm, Amazon Bedrock üzerinde veya telemetri devre dışıyken v2.1.281 öncesi bir oturum, dosyayı okuyan yerleşik eklentinin devre dışı olduğu bir oturum veya Project instructions ayarı claude-md olarak belirlenmiş bir CLAUDE.md dosyası içeren projeler. Bunu services/worker/CLAUDE.md içine ekleyin:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

Sembolik bağlantı (symlink) yöntemi, araca özel eklenecek bir şey olmadığında doğrudur.

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

ln başarılı olduğunda hiçbir şey yazdırmaz, bu yüzden listeyi kontrol edin: apps/web/CLAUDE.md -> AGENTS.md. Ardından bir oturum başlatın ve yüklenen dosyaların Memory files altında göründüğü /context komutunu çalıştırın. Windows üzerinde bir sembolik bağlantı için Yönetici hakları veya Geliştirici Modu gerekir. Git, core.symlinks etkinleştirilmediği sürece commit edilmiş bir sembolik bağlantıyı düz metin dosyası olarak dışa aktarır; bu da o kopyada talimatlarınız yerine tek satırlık bir CLAUDE.md bırakır. Depoyu kopyalayan herhangi biri Windows üzerinde çalışıyorsa, @AGENTS.md içe aktarma yöntemini kullanın. Claude Code AGENTS.md dosyasını kendi başına okumadan önce bu geçici çözümlerden birini kurduysanız, öyle bırakabilirsiniz: belgeler, içe aktarma işlemini tutmanın "Claude'un AGENTS.md dosyasını iki kez okumasına asla neden olmadığını" ve sembolik bağlantılı bir CLAUDE.md dosyasının bir kez okunduğunu belirtir.

Bununla ilgili bir tuzak vardır. /compact işleminden sonra, proje kök dizinindeki CLAUDE.md diskten yeniden okunur, ancak alt dizinlerdeki iç içe geçmiş dosyalar yeniden enjekte edilmez. Claude Code bunları, ajan o dizindeki bir dosyayla bir sonraki çalışmasında talep üzerine yeniden yükler. Belgeler bunu CLAUDE.md dosyaları için açıklar ve doğrudan okunan bir AGENTS.md için ayrı bir sıkıştırma (compaction) tanımlamaz; bu nedenle her iki isimdeki iç içe geçmiş dosyaların da bu şekilde davranmasını bekleyin. Eğer dizine özel bir kural uzun bir oturumun ortasında uygulanmayı durdurmuş gibi görünüyorsa, genellikle nedeni budur; dizindeki herhangi bir dosyayı okumak kuralı geri getirir.

Diğer ajanları AGENTS.md dosyasına yönlendiren ayarlar

Codex, AGENTS.md dosyasını yerel olarak okur. Her seviyede önce AGENTS.override.md dosyasını kontrol eder; bu, paylaşılan dosyayı düzenlemeden bir dizine yerel bir geçersiz kılma (override) sağlar. Birleştirilmiş boyut varsayılan project_doc_max_bytes olan 32 KiB'a ulaştığında birleştirmeyi durdurur; kök dizindeki dosyayı küçük tutmak için bir neden daha.

Aider, read: AGENTS.md satırı ile .aider.conf.yml üzerinden alır.

Gemini CLI, { "context": { "fileName": "AGENTS.md" } } ile .gemini/settings.json üzerinden alır.

Upstream, hala eski tekil ismi kullanan depolar için geriye dönük uyumlu bir yeniden adlandırma belgelemiştir: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

Çok büyük bir monorepo içinde, Claude Code'un claudeMdExcludes ayarı, başka bir ekibin dizini sizinkinin üzerinde olduğunda yararlı olan yol veya glob ile üst dizin dosyalarını atlar. Bu desenler, Claude Code'un okuduğu AGENTS.md dosyaları için de geçerlidir.

Bunun ajan belleğinden veya bir yetenekten farkı nedir?

Bu mekanizmalar birbirine benzer görünse de tamamen farklı şekillerde başarısız olurlar; bu nedenle hangisine ihtiyaç duyduğunuz konusunda kesin olmakta fayda vardır.

AGENTS.md dosyası sizin tarafınızdan yazılır, git'e commit edilir, bir pull request ile gözden geçirilir ve depoyu klonlayan herkes için aynıdır. Ajan belleği ise ajan tarafından yazılır, depo dışında saklanır ve tek bir makineye özeldir. Claude Code belgeleri de aynı ayrımı yapar: CLAUDE.md sizin yazdığınız "Talimatlar ve kurallar"ı içerir, otomatik bellek ise Claude'un yazdığı "Öğrenilenler ve kalıplar"ı tutar ve bellek dizini makineler arasında paylaşılmaz. Test basittir. Eğer bir bilginin yeni bir klon üzerinde çalışan bir iş arkadaşı için de geçerli olması gerekiyorsa, bu bilgi bellekte tutulamaz. Ajan belleğinin oturumlar arasında nasıl kalıcı hale geldiği konunun bu kısmını ele alır.

Yetenek ise üçüncü bir kavramdır. AGENTS.md her oturumda yüklenen bir bağlamdır; yetenek ise ihtiyaç duyulduğunda yüklenen bir prosedürdür. Claude Code belgeleri kullanışlı bir kural sunar: "Eğer bir girdi çok adımlı bir prosedürse veya kod tabanının yalnızca bir kısmı için önemliyse, onu bir yeteneğe veya yol kapsamlı bir kurala taşıyın." Bu cümlenin ikinci yarısı, iç içe geçmiş AGENTS.md dosyalarının tam olarak çözdüğü sorundur. İlk yarısı ise ajan yetenekleri içindir; aynı prosedür birden fazla depoda gerekiyorsa, aynı paragrafları on farklı AGENTS.md dosyasına yapıştırmak yerine yeteneği depolar arasında paylaşın.

Upstream, "bu yazının yazıldığı sırada ana OpenAI deposunda 88 adet AGENTS.md dosyası bulunduğunu" belirtir. Bu sayı, argümanın tamamını oluşturur. Büyük bir depo daha büyük bir dosyaya ihtiyaç duymaz. Daha fazla sayıda küçük dosyaya ihtiyaç duyar; her biri tanımladığı kodun yanında durur ve her biri o kodu en son değiştiren kişi tarafından sahiplenilir.

FAQ

İç içe yerleştirilmiş bir AGENTS.md dosyası kök dizindeki dosyanın yerini mi alır yoksa ona ekleme mi yapar?

Ekleme yapar. Upstream kaynaklar "en yakındaki önceliklidir" ifadesini kullanır; bu, bir çakışma durumunda ne olacağını açıklar, neyin yükleneceğini değil. Codex "dosyaları kökten aşağıya doğru boş satırlarla birleştirerek" okur; Claude Code ise dosyaları geçersiz kılmak yerine çalışma dizininden yukarıya doğru tarayarak bulduğu her dosyayı birleştirir. En yakın dosya, yalnızca iki dosya aynı konu hakkında farklı talimatlar verdiğinde geçerli olur. Paylaşılan kuralları kök dizinde bir kez yazın ve bunları her dizinde tekrarlamayın.

Kök dizindeki AGENTS.md dosyası ne kadar büyük olmalıdır?

O depoda yaptığınız her isteğin tepesine yapıştırıldığında sizi rahatsız etmeyecek kadar küçük olmalıdır, çünkü gerçekte olan budur. Claude Code belgeleri, dosya başına 200 satırın altında kalınmasını önerir ve daha uzun dosyaların "uyumu azalttığını" belirtir. Codex, varsayılan olarak 32 KiB birleşik boyuta ulaşıldığında talimat dosyalarını birleştirmeyi durdurur. Kök dosyanız dört farklı servisi belgeliyorsa, bu içeriğin büyük bir kısmı tek bir görev için gereksiz yük oluşturur. Detayları dizin bazlı dosyalara taşıyın ve kök dizinde bir harita bırakın.

Bu dosyaların güncelliğini yitirmesini nasıl engellerim?

Kök dosyaya şu kuralı ekleyin: Bir dizindeki kodu değiştiren kişi, aynı commit içerisinde o dizinin AGENTS.md dosyasını da günceller. Dosyayı kodun yanına yerleştirmek kuralın kalıcı olmasını sağlar; çünkü değişiklik, bir insanın zaten incelemekte olduğu pull request farkına yansır. Değişen her yolu üzerindeki en yakın AGENTS.md dosyasıyla eşleştiren bir CI uyarısı ekleyin ve belirli aralıklarla her dosya üzerindeki git log -1 --format=%cs komutunu, belgelendirdiği dizinde çalıştırılan aynı komutla karşılaştırın.

Claude Code, AGENTS.md dosyalarını okur mu?

Evet, v2.1.277 sürümünden itibaren. 27 Ekim 2026 tarihinde belgeler üzerinden doğrulandığı üzere, çalışma dizininizde veya üzerinde herhangi bir CLAUDE.md veya CLAUDE.local.md bulunmadığında Claude Code varsayılan olarak AGENTS.md dosyasını okur. Ayrıca, bir dosyayı Read aracıyla açtığında ve o alt dizinde kendi CLAUDE.md, .claude/CLAUDE.md veya CLAUDE.local.md dosyası bulunmadığında, alt dizinin AGENTS.md dosyasını okur. Her AGENTS.md yanına bir CLAUDE.md eklemeyin: Çalışma dizininde veya üzerinde bir tane olması durumunda Claude "Sadece CLAUDE.md dosyalarınızı" okur. Eğer bir CLAUDE.md dosyasına da ihtiyacınız varsa, /config içerisindeki Project instructions kısmını claude-md-and-agents-md olarak ayarlayın veya dosyanın ilk satırına @AGENTS.md ekleyin. Bir oturumda /memory komutunu çalıştırın ve AGENTS.md yolunun listede göründüğünü doğrulayın.

Sadece bazen geçerli olan bir kuralı nereye koymalıyım?

AGENTS.md dosyasına değil. Bu dosya her oturumda yüklendiği için, içindeki her satır yazdığınız asıl istekle dikkat çekmek için yarışır. Ara sıra ihtiyaç duyulan birkaç adımlı bir prosedür, talep üzerine yüklenen bir yeteneğe (skill) aittir. Tek bir dizin için geçerli olan bir kural, o dizinin AGENTS.md dosyasına aittir. Dizin ağacı veya bağımlılık listesi gibi ajanın doğrudan koddan okuyabileceği bir bilgi ise hiçbirine ait değildir.

Bu yazı işinize yaradı mı?