AGENTS.md ve CLAUDE.md nasıl yazılır? 100 depo ne yapıyor

AGENTS.md ve CLAUDE.md ne işe yarar?

Bir kodlama ajanı her oturuma projeyi bilmeden başlar. Kural dosyası, her seferinde yeniden anlatacağınız şeyleri bir kez yazdığınız yerdir: derleme ve test komutları, kod kuralları, dizin yapısı, “bunu asla yapma” dediğiniz şeyler. Bu yazıda o dosyayı nasıl yazacağınızı anlatıyoruz: hangi adı vermeli, içine ne yazmalı, ne kadar uzun tutmalı.

AGENTS.md tek bir araca ait değil. Linux Foundation bünyesindeki Agentic AI Foundation’ın yürüttüğü açık bir format; kendi sitesine göre 60.000’den fazla açık kaynak proje onu kullanıyor. Düz bir Markdown dosyası, zorunlu bir alanı yok. CLAUDE.md ise Claude Code’un her oturumun başında okuduğu dosya. O da düz Markdown, ama kendine özgü birkaç özelliği var: başka dosyaları içe aktarabilir (@yol), kullanıcıya ya da kuruluşa özel katmanları olabilir.

Biz bu dosyaları her gün okuyan bir araç yapıyoruz: diffox, bir pull request’i incelerken deponun kural dosyasını da okur (nasıl çalıştığı ayrı bir yazıda). Aşağıdaki ölçümler o işin yan ürünü.

Hangi araç hangi dosyayı okur?

Aşağıdaki tabloyu beş aracın kendi belgelerinden, 13 Ekim 2026 günü derledik. Yeni sürümlerle değişebilir; her aracın adı kaynağına bağlantı veriyor.

Kaynak: her aracın kendi belgesi, 13 Ekim 2026. Claude Code satırı 2.1.277 ve sonraki sürümler için geçerli.

Tablodan iki şey çıkıyor. Birincisi, beş araç da AGENTS.md’yi okuyabiliyor: Gemini CLI bir ayarla, Claude Code ise yanında CLAUDE.md yoksa. İkincisi, alt klasörlerdeki dosyaları her araç başka türlü okuyor. Codex kökten aşağı hepsini birleştirir, Copilot en yakın dosyayı alır, Claude Code ise alt klasördeki dosyayı ancak o klasörde bir dosya açtığınızda yükler.

Google, 18 Haziran 2026’da ücretsiz kullanıcılar ile Google AI Pro ve Ultra aboneleri için Gemini CLI’ın hizmetini durdurup onları Antigravity CLI’a yönlendirdi; ücretli API anahtarıyla ya da şirket lisansıyla Gemini CLI’ı kullanmaya devam edebilirsiniz. Antigravity’nin kural belgesini 28 Ekim 2026 günü okuduk. AGENTS.md ya da GEMINI.md adlı dosyayı hiçbir ayar gerekmeden okuyor. Alt klasördeki dosyayı, ajan o klasörde bir dosyayı okuyunca ya da düzenleyince yüklüyor. Bulduğu dosyaları birleştiriyor; kurallar çelişirse alt klasördeki geçerli oluyor. Dosya başına sınır 24 KB. Belgenin saydığı dosyalar arasında CLAUDE.md yok; kurallarınız AGENTS.md’deyse Antigravity de okur.

AGENTS.md, CLAUDE.md’den daha yaygın

Hangi dosyanın daha yaygın olduğunu görmek için depoları tek bir ölçüte göre seçtik: 13 Ekim 2026 günü GitHub’da en çok yıldızı olan 100 depo. Listenin önemli bir kısmı derlenen bir yazılım değil; kaynak listeleri, kitaplar, eğitimler. Depoları kural dosyası olup olmadığına bakmadan seçtiğimiz için listeye dokunmadık.

100 deponun 47’sinde kök dizinde bu iki dosyadan en az biri var. 42 depoda AGENTS.md, 24 depoda CLAUDE.md var; yalnızca CLAUDE.md kullanan depo sayısı 5. Öteki araçların dosyaları daha seyrek: Copilot’unki 11 depoda, Cursor’ın kural klasörü 4 depoda, GEMINI.md 3 depoda. Eski .cursorrules dosyası 1 depoda hâlâ duruyor; .windsurfrules ve .clinerules hiçbirinde yok.

Alt klasörlerdeki dosyaları ve öteki araçların dosyalarını da sayınca, bunlardan en az birini kullanan depo sayısı 55 oluyor.

İki dosya da varsa Claude Code yalnızca CLAUDE.md’yi okur

En sık yanlış bilinen nokta burası. Claude Code uzun süre AGENTS.md’yi hiç okumadı; bugün hâlâ öyle yazan çok kaynak var. 2.1.277 sürümünden beri okuyor, ama bir şartla: çalışma dizininde ya da üstündeki dizinlerde CLAUDE.md (ya da CLAUDE.local.md) olmamalı. İkisi de varsa varsayılan olarak yalnızca CLAUDE.md’yi okur.

Pratikte bunun anlamı şu: yanında bir CLAUDE.md varsa, AGENTS.md’ye eklediğiniz kural Claude Code’a ulaşmaz. Codex ise varsayılan olarak yalnızca AGENTS.md’yi okur. Bu durumda iki dosyayı elle aynı tutmanız gerekir.

Kişisel notlarınız için eklediğiniz CLAUDE.local.md de aynı sonucu doğurur: o dosya varken Claude Code AGENTS.md’yi okumaz. İkisini de okutmak için /config içindeki “Project instructions” ayarını claude-md-and-agents-md yapın.

100 deponun 19’unda iki dosya da kökte duruyor. Bu depolarda iki dosyanın birbirine nasıl bağlandığına tek tek baktık.

8 depo, CLAUDE.md’yi doğrudan AGENTS.md’ye bağlamış: 5’i CLAUDE.md’ye @AGENTS.md yazarak, 3’ü sembolik linkle. n8n, AutoGPT, RustDesk ve Clash Verge Rev depolarında CLAUDE.md tek satırdan ibaret. 2 depoda CLAUDE.md, düz bir cümleyle AGENTS.md’ye yönlendiriyor; Claude Code’un belgesine göre ajan o dosyayı ancak açmaya karar verirse görür. 3 depo aynı metni iki dosyada ayrı ayrı tutuyor; 1 tanesinde iki kopyadaki kural sayısı artık aynı değil. Kalan 6 depoda ise iki dosyaya ayrı metinler yazılmış: bu depolarda Claude Code ile Codex aynı projede farklı talimatlar okuyor.

CLAUDE.md’yi AGENTS.md’ye bağlamanın iki yolu

Verinin de gösterdiği yol şu: kuralları tek dosyada tutun, öteki dosyayı ona yönlendirin. Asıl metin AGENTS.md’de dursun, çünkü onu okuyan araç daha çok. Yanına şu CLAUDE.md’yi koyun:

@AGENTS.md

## Claude Code
Yalnızca Claude Code’a özel notlarınız buraya.

İçe aktarma satırı sayesinde AGENTS.md, CLAUDE.md’nin bir parçası olarak yüklenir. Altına yalnızca Claude Code’a özel notları yazarsınız. Böyle bir notunuz yoksa sembolik link de iş görür: ln -s AGENTS.md CLAUDE.md.

Sembolik linkin iki eksiği var. Depoyu Windows’ta klonlayan biri, link yerine tek satırlık bir metin dosyası görebilir. Claude Code da linkin üzerinden yazmayı reddeder; onun yerine asıl dosyayı düzenler. Ekipte Windows kullanan varsa içe aktarma satırı daha güvenli.

Yalnızca AGENTS.md tutmak da artık bir seçenek, çünkü Claude Code’un güncel sürümleri onu doğrudan okuyor. Eski sürümler için tek satırlık CLAUDE.md’yi bırakmanın zararı yok: Claude Code aynı dosyayı iki kez yüklemez.

Popüler depolar dosyaya ne yazıyor?

Dosyalara ne yazıldığını görmek için okuduğumuz 47 dosyanın başlıklarına baktık. Bir dosya bir konuya ayrı bir başlık açmışsa, o konuyu anlattığını kabul ettik.

En sık konu commit ve pull request kuralları (29 dosya). Ardından kurulum ve çalıştırma komutları (26), kod stili (26), dizin yapısı (21), testler (16) ve güvenlik (7) geliyor. Başlıklardan bağımsız olarak, 47 dosyanın 36’sında kod bloğunda ya da satır içinde yazılmış bir komut var. Bu sayım yalnızca başlıklardaki kelimelere bakıyor, yani kaba bir ölçü. Yine de sıra açık: ajan önce neyi nasıl çalıştıracağını ve değişikliği nasıl teslim edeceğini bilmek istiyor.

Kubernetes ve AutoGPT’den iki iyi örnek

İki örnek de bu sayımda okuduğumuz dosyalardan. Kubernetes’in AGENTS.md’si 38 satır. Her kural neyin yapılmayacağını ve yerine ne yapılacağını söylüyor; her komutun yanında ne işe yaradığı yazıyor:

## Constraints

- **Generated files are read-only.** Never hand-edit `zz_generated.*` or `generated.pb.go`. Run `make update`.
- **go.mod/go.work are generated.** Use `hack/pin-dependency.sh` + `hack/update-vendor.sh`. Never `go mod tidy`.
…
## Commands

Run `make help` for all available targets. Common workflows:

```
make test WHAT=./pkg/kubelet GOFLAGS=-v     # Unit tests (one package)
make test-integration WHAT=./test/integration/scheduler
make verify                                 # All verification checks
make update                                 # ALL generators and formatters
```

AutoGPT’nin AGENTS.md’si 92 satır; dizin yapısını, her parçanın test komutunu ve ölçülebilir pull request kurallarını yazıyor. CLAUDE.md’si ise yalnızca @AGENTS.md satırından ibaret: yukarıda önerdiğimiz yöntem.

## Testing

- Backend: `poetry run test` (runs pytest with a docker based postgres + prisma).
- Frontend integration tests: `pnpm test:unit` (Vitest + RTL + MSW, primary testing approach).
…
## Pull requests

…
- Keep out-of-scope changes under 20% of the PR.

İki dosyanın ortak yanı, cümlelerini hem bir ajanın hem bir insanın kontrol edebileceği biçimde kurması: “üretilen dosyayı elle düzenleme, make update çalıştır” ya da “kapsam dışı değişiklik pull request’in beşte birini geçmesin”. Alıntılar sayımda okuduğumuz commit’ten; “…” atlanan satırları gösteriyor.

Başlamak için bir AGENTS.md şablonu

Aşağıdaki kısa AGENTS.md iskeletini, popüler depoların en sık açtığı başlıklardan ve yukarıdaki iki örnekten çıkardık. Bu yalnızca bir örnek. İngilizce yazdık, çünkü bu dosyaları okuyan ajanlar da çoğu ekip de İngilizce çalışıyor. Komutları ve yolları kendi projenizinkilerle değiştirin:

# Project name

## Commands
- Install: `pnpm install`
- Test one package: `pnpm test --filter api`
- Lint and format: `pnpm lint && pnpm format`

## Project structure
- `apps/web` - Next.js front end
- `packages/api` - API service

## Code style
- TypeScript strict mode. Never use `any`; use `unknown`.

## Testing
- Add or update the test that covers your change.

## Commits and pull requests
- Conventional commits: `feat(api): ...`
- Keep unrelated changes out of the pull request.

## Never
- Never hand-edit files under `generated/`. Run `pnpm generate`.
- Never commit secrets; read them from the environment.

Claude Code kullanıyorsanız yanına tek satırlık CLAUDE.md’yi koyun: @AGENTS.md. Şablondaki her satır bir komut ya da kontrol edilebilir bir kural; projenin ne yaptığını anlatmak README’nin işi.

İyi bir kural nasıl yazılır?

Dosyaya ne yazılacağına dair en işe yarar ölçüt Claude Code’un belgesinde: talimat, doğrulanabilecek kadar somut olmalı. “Kodu düzgün biçimlendir” yerine “2 boşluk girinti kullan”, “değişikliklerini test et” yerine “commit’ten önce npm test çalıştır” yazın. Aşağıdaki altı madde bu ölçütü, kendi dosyamızı yazarken öğrendiklerimizle birleştiriyor:

• Ne yapılması gerektiğini yazın. “Şunu yap” ya da “şunu asla yapma” diyen bir cümle kontrol edilebilir; projeyi tanıtan bir paragraf edilemez. Okuduğumuz 47 dosyanın 3’ünde böyle tek bir cümle bile yok; medyan dosyada 10 tane var.
• Komutu olduğu gibi yazın. Ajan “testleri çalıştır” cümlesinden hangi komutu kastettiğinizi çıkaramaz; pnpm test --filter api yazarsanız onu çalıştırır.
• Kuralın nedenini yanına yazın. Kendi dosyamızda her kuralın yanında, o kuralı yazmamıza yol açan hata duruyor. Nedeni yazılmamış kuralı, ondan ilk rahatsız olan siler.
• Araçların zaten kontrol ettiği şeyleri yazmayın. Formatter’ın ya da linter’ın kontrol ettiği bir kuralı dosyaya eklemek boşuna satır harcar; dosya uzadıkça ajan talimatlara daha az uyar.
• Her kuralı tek yerde yazın. Aynı kural iki dosyadaysa biri eskir; eskiyen de en az okunan dosya olur.
• Hata tekrarlanınca ekleyin, gereği kalmayınca silin. Ajan aynı hatayı ikinci kez yaptığında kuralı yazın. Claude Code’da /doctor prompt-audit eskimiş ve çelişen talimatları listeler.

Bu maddelerin ilki diffox için doğrudan önemli. diffox bir pull request’i incelerken deponun kökündeki kural dosyasını okur: önce AGENTS.md’yi, o yoksa CLAUDE.md’yi. Sembolik linki ve @AGENTS.md satırını da izler. Dosyadaki “şunu yap, şunu yapma” diyen cümleleri uzman ajanlara inceleme kuralı olarak verir. Yani kontrol edilebilir bir kural, incelemede de işe yarar.

Kural dosyalarının çoğu 200 satırın altında

Uzunluk konusunda üç aracın belgesi üç ayrı sınır veriyor. Claude Code’un hedefi dosya başına 200 satırın altında kalmak, çünkü uzun dosya daha çok bağlam harcar ve ajan talimatlara daha az uyar. Cursor, kural başına 500 satırın altında kalmayı önerir. Codex ise birleştirdiği dosyaların toplamı 32 KiB’a ulaşınca yenilerini eklemez.

Okuduğumuz 47 dosyanın medyanı 92 satır; en kısası 4, en uzunu 1.017 satır. 14’ü 200 satırı, 2’si 500 satırı aşıyor. Codex’in 32 KiB sınırını tek başına aşan dosya sayısı 1.

Monorepoda alt klasörün kendi kural dosyası olur

Büyük depolar kuralları tek dosyaya sığdırmıyor. Dosya ağacının tamamını okuyabildiğimiz 98 deponun 27’sinde, kökten başka bir klasörde de AGENTS.md ya da CLAUDE.md var: toplam 278 dosya.

Alt klasördeki dosya, o klasörde yapılan değişiklikler için yazılır: frontend kuralları frontend klasöründe, backend kuralları backend klasöründe durur. Böylece kök dosya kısa kalır, ajan da yalnızca çalıştığı yerin kurallarını yükler.

Bunun ne kadar sık işe yaradığını Eylül 2026 tarihli bir ölçümümüzde gördük: alt klasöründe kural dosyası olan 17 depoda, en son merge edilen 417 pull request’in 202’si böyle bir klasördeki en az bir dosyayı değiştiriyordu.

Yalnız şuna dikkat edin: her araç alt klasörlerdeki dosyaları farklı okuyor. Aynı konuyu iki düzeyde farklı biçimde yazarsanız, hangisinin geçerli olacağı araca göre değişir. Birbiriyle çelişen cümle bırakmayın.