# CLAUDE.md nasıl yazılır? AGENTS.md ve GEMINI.md rehberi

Adres: https://agentvera.dev/blog/claude-md-nasil-yazilir/ · Yayın: 2026-10-22

CLAUDE.md nasıl yazılır: dosya nerede durur, içine ne yazılır, neler dışarıda kalır, importlar ve tek AGENTS.md ile Claude, Codex ve Gemini’yi ortaklaştırmak.

**Kısaca:**

- İyi bir CLAUDE.md 200 satırın altında kalır; build ve test komutlarını, koddan anlaşılmayan kuralları ve ajanın daha önce yaptığı hataları içerir.
- Klasör turu, uzun prosedürler, gizli anahtarlar ve genel tavsiyeler bu dosyaya girmez; asla olmaması gereken şeyler cümleyle değil hook ya da izin ayarıyla engellenir.
- Kuralları tüm CLI’larla paylaşmak için AGENTS.md’ye yaz, CLAUDE.md’de @AGENTS.md ile import et ve Gemini CLI ayarlarında context.fileName listesine AGENTS.md’yi ekle.

İyi bir CLAUDE.md kısa (200 satırın epey altında), net ve kontrol edilebilir olur: build ve test komutları, ajanın koda bakarak tahmin edemeyeceği kurallar ve daha önce bir kez yaptığı hatalar. Klasör ağacı turu, uzun prosedürler ya da “temiz kod yaz” gibi genel tavsiyeler ya başka bir yere aittir ya da hiç yazılmamalıdır.

Bu yazıda CLAUDE.md, AGENTS.md ve GEMINI.md’nin ne olduğunu, her ajanın bunları nerede aradığını, içine ne yazıp neyi dışarıda bırakman gerektiğini, importların nasıl çalıştığını ve projedeki tüm ajanların okuduğu tek bir dosyayı nasıl kuracağını anlatıyorum.

## Bu dosyalar ne işe yarar?

Kodlama ajanları her oturuma projen hakkında hiçbir şey hatırlamadan başlar. Talimat dosyası, onlara bıraktığın nottur: CLI’ın açılışta okuyup ilk mesajından önce modelin [bağlam penceresine](/sozluk/baglam-penceresi/ "Bağlam penceresi") eklediği düz bir Markdown dosyası.

| Dosya | Kim okur | Not |
| --- | --- | --- |
| `CLAUDE.md` | Claude Code | `@yol` importlarını ve klasöre özel kuralları destekler |
| `AGENTS.md` | Codex, Cursor, Copilot, opencode, Aider, goose, Amp, Gemini CLI (ayarlanırsa) ve diğerleri | Açık format, “ajanlar için README” diye anılıyor |
| `GEMINI.md` | Gemini CLI | `@dosya.md` importlarını destekler, dosya adı değiştirilebilir |

AGENTS.md; OpenAI Codex, Amp, Google Jules, Cursor ve Factory’nin ortak çalışmasından çıktı, şu an Linux Foundation bünyesindeki Agentic AI Foundation’ın çatısı altında. Ortak bir standarda en yakın şey bu. Claude Code kendi dosya adını korudu ama yeni sürümleri (v2.1.277 ve sonrası), çalışma klasöründe ya da üstünde CLAUDE.md veya CLAUDE.local.md yoksa AGENTS.md’yi doğrudan okuyor.

## Dosyalar nerede durur?

Üç ajan da aynı mantığı kullanır: sana ait genel bir dosya, ekibe ait proje dosyası ve kodun bir bölümü için daha derindeki isteğe bağlı dosyalar.

### Claude Code

| Kapsam | Konum | Kim görür |
| --- | --- | --- |
| Yönetilen politika | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) | Yönetici herkes için koyar |
| Kullanıcı | `~/.claude/CLAUDE.md` | Sadece sen, tüm projelerde |
| Proje | `./CLAUDE.md` ya da `./.claude/CLAUDE.md` | Commit’lenir, tüm ekip |
| Yerel | `./CLAUDE.local.md` | Sadece sen; `.gitignore`’a ekle |
| İç içe | `src/payments/CLAUDE.md` gibi | Claude o klasördeki dosyaları okuyunca ya da düzenleyince yüklenir |

Çalışma klasöründeki ve üst klasörlerdeki dosyalar açılışta yüklenir ve birbirini ezmez, art arda eklenir. Alt klasörlerdeki dosyalar ise Claude o klasöre ilk dokunduğunda yüklenir. Hangi dosyaların gerçekten yüklendiğini görmek için `/context`, birini düzenlemek için `/memory` komutunu kullan.

### Codex

Codex önce genel `~/.codex/AGENTS.md` (ya da `AGENTS.override.md`) dosyasını okur, sonra git kökünden bulunduğun klasöre kadar iner ve her klasörden bir dosya alır: varsa `AGENTS.override.md`, yoksa `AGENTS.md`. Daha derindeki dosyalar metinde sonra gelir, yani iki kural çatışırsa onlar kazanır. Toplam boyut `project_doc_max_bytes` ile sınırlı, varsayılanı 32 KiB; zincir de oturum başına bir kez kurulur. CLI’ın kendisi için [Codex sayfasına](/ajanlar/codex/ "Codex CLI") bakabilirsin.

### Gemini CLI

Gemini CLI `~/.gemini/GEMINI.md`’yi, ardından çalışma alanı klasörlerindeki ve üstlerindeki dosyaları yükler; araçları başka klasörlere girdikçe oradakileri de toplar. Hepsi birleştirilip her prompt’la birlikte gönderilir. `/memory show` birleşik metni gösterir, dosyayı düzenledikten sonra `/memory reload` yeniden okutur.

## İçine ne yazmalı?

Repoyu hiç görmemiş, soru da sormayacak yetenekli yeni bir ekip arkadaşına yazıyormuş gibi düşün. Her satır ajanın uygulayabileceği, senin de kontrol edebileceğin bir şey olmalı.

- **Komutlar.** Kurulum, build, tek test, tüm testler, lint ve tip kontrolü nasıl çalıştırılır. En faydalı bölüm bu; yoksa ajan tahmin eder.
- **Koddan anlaşılmayan kurallar.** “npm değil pnpm kullan.” “Yeni API route’ları `withAuth()` içinden geçer.” “Tarihler UTC saklanır.”
- **Sınırlar.** “`generated/` altındaki dosyalara dokunma.” “Migration klasörünü sormadan değiştirme.”
- **İş nasıl bitirilir.** “Bitti demeden önce `pnpm test` ve `pnpm typecheck` çalıştır.” “Commit mesajları Conventional Commits biçiminde.”
- **Bilinen tuzaklar.** Ajanın geçen hafta iki kez yaptığı hata, bir kural olarak.

İyi kural somuttur. “2 boşlukla girinti yap” işe yarar; “kodu düzgün biçimlendir” yaramaz. “Commit’ten önce `npm test` çalıştır” işe yarar; “her şeyin çalıştığından emin ol” yaramaz.

### Kısa bir örnek

```markdown
# Proje notları

## Komutlar
- Kurulum: `pnpm install`
- Geliştirme sunucusu: `pnpm dev` (port 5173)
- Tek test: `pnpm vitest run path/to/file.test.ts`
- Bitirmeden önce: `pnpm lint && pnpm typecheck && pnpm test`

## Kurallar
- TypeScript strict; yeni kodda `any` yok.
- Sunucu kodu `src/server`, arayüz `src/ui` altında; arayüzden sunucu kodu import edilmez.
- Veritabanına sadece `src/server/db.ts` üzerinden erişilir.

## Yapma
- `src/generated/` klasörünü düzenleme (yerine `pnpm codegen` çalıştır).
- Gerekçesini özette yazmadan bağımlılık ekleme.

## Acı tecrübeyle öğrenilenler
- Ödeme testleri `STRIPE_KEY=test` ister; yoksa sessizce düşer.
```

Yaklaşık 20 satır ve bir ajanın ilk gün ihtiyaç duyduğu şeylerin çoğunu karşılıyor.

## Neleri dışarıda bırakmalı?

| Dışarıda bırak | Neden | Yerine |
| --- | --- | --- |
| Reponun dosya dosya turu | Ajan klasörleri kendisi listeleyebilir, tur da zamanla eskir | Hiçbir şey ya da bir kod haritası aracı |
| Uzun adım adım prosedürler (release, migration) | Kullanılmasa bile her turda yüklenir | Bir [skill](/sozluk/ajan-becerileri/ "Ajan becerileri") ya da dosyanın işaret ettiği bir doküman |
| Tek bir klasörü ilgilendiren kurallar | Her yerde bağlam harcar | İç içe CLAUDE.md / AGENTS.md ya da `paths:` içeren `.claude/rules/` |
| Genel tavsiyeler (“temiz kod yaz”) | Davranışa etkisi yok | Sil |
| Gizli anahtarlar, token’lar, iç adresler | Dosya commit’lenir ve modele gider | Ortam değişkenleri |
| Asla olmaması gerekenler | Talimat bağlamdır, zorlama değildir | Bir [hook](/sozluk/claude-code-hooks/ "Claude Code hook’ları") ya da izin kuralı |

## Kısa tut

CLAUDE.md’deki her satır her oturumun başında gönderilir ve konuşma boyunca bağlamda kalır. Anthropic’in kendi dokümanı dosya başına 200 satırın altını öneriyor ve uzun dosyaların Claude’un kurallara uyumunu düşürdüğünü söylüyor. Tanıdık bir durum: kural sayısı arttıkça her biri biraz daha sulanıyor.

İşe yarayan birkaç alışkanlık:

- **Kuralı ihtiyaç doğunca ekle.** Ajan aynı hatayı iki kez yaptıysa, bir inceleme bir şey yakaladıysa ya da aynı düzeltmeyi tekrar tekrar yazıyorsan sinyal budur.
- **Eklerken buda.** Bir aydır işe yaramayan kuralı sil.
- **Yapıştırmak yerine işaret et.** “Release süreci `docs/release.md` içinde” bir satır tutar; süreci yapıştırmak elli satır.
- **İnsanlara notları HTML yorumuyla yaz.** Claude Code blok düzeyindeki `<!-- -->` yorumlarını göndermeden önce siler.

Token maliyetini düşünüyorsan [Claude Code token tasarrufu](/blog/claude-code-token-tasarrufu/ "Claude Code token tasarrufu") yazısı bağlamı başka nelerin doldurduğunu anlatıyor.

## Importlar ve klasöre özel kurallar

Claude Code’da bir CLAUDE.md, `@yol` ile başka dosyaları içeri alabilir:

```markdown
Genel bakış için @README.md dosyasına bak.
Kod kuralları: @docs/conventions.md
@~/.claude/my-preferences.md
```

Yollar import’u içeren dosyaya göre çözülür, importlar en fazla dört adım iç içe gidebilir, kod bloklarının ya da satır içi kodun içindeki `@` yok sayılır. Bir proje ilk kez repo dışından dosya import ettiğinde Claude Code senden onay ister.

Bir incelik var: importlar metni düzenler ama token kazandırmaz. Import edilen dosya da açılışta ana dosya gibi tamamen yüklenir. Sadece ağacın bir bölümünde geçerli kurallar için frontmatter’ında `paths:` glob’u olan `.claude/rules/*.md` dosyalarını kullan; Claude yalnızca eşleşen dosyalarda çalışırken yüklenirler:

```markdown
---
paths: ["src/api/**/*.ts"]
---
- Her handler veritabanına dokunmadan önce girdiyi zod ile doğrular.
```

Gemini CLI de GEMINI.md içinde aynı `@dosya.md` import sözdizimini destekliyor.

## Tüm ajanlar için tek dosya

Ekip birden fazla CLI kullanıyorsa aynı kuralları üç dosyada tutmak, bir süre sonra birbirinden kopmaları demek. Yaygın kurulum şöyle:

1. Ortak kuralları **AGENTS.md**’ye yaz. Codex, Cursor, Copilot, opencode ve çoğu araç onu doğrudan okur.
2. Onu import eden ve Claude’a özel notları ekleyen bir **CLAUDE.md** oluştur:

   ```markdown
   @AGENTS.md

   ## Sadece Claude Code
   - PR açmadan önce projedeki /review skill’ini çalıştır.
   ```

3. **Gemini CLI**’da `.gemini/settings.json` içinde aradığı dosya adlarına AGENTS.md’yi ekle:

   ```json
   { "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }
   ```

macOS ve Linux’ta sembolik bağlantı (`ln -s AGENTS.md CLAUDE.md`) da çalışır ama import yöntemi daha anlaşılır ve Windows’un bağlantılara nasıl davrandığına bağlı değil. Claude Code’un `/config` içinde “Project instructions” ayarı da var; CLAUDE.md ile AGENTS.md’yi birlikte okumasını istersen oradan seçebilirsin.

## İlk sürümü yazmak

Boş sayfadan başlamak zorunda değilsin. Claude Code’da `/init` repoyu okuyup bir CLAUDE.md taslağı çıkarır. Bu taslağı ham malzeme gibi gör: komutları tut, klasör turunu sil, yeni bir ekip arkadaşına ilk sabahında söylemeyeceğin her şeyi çıkar.

Sonra dosyanın gerçek işle büyümesine izin ver. Ajanı her düzelttiğinde kendine sor: bu düzeltme gelecek hafta da geçerli olur mu? Cevap evetse elinde bir kural adayı var.

## AgentVera ile

[AgentVera](/indir/ "AgentVera’yı indir"), Claude Code, Codex, Gemini CLI ve diğer CLI’ları gerçek terminallerde yan yana çalıştırır. Her ajan kendi CLAUDE.md, AGENTS.md ya da GEMINI.md dosyasını yukarıda anlattığım gibi okumaya devam eder; AgentVera bu dosyaların yerini almaz. Yanlarında çalışan birkaç özellik var:

- **Düzeltmelerinden kural önerileri.** Bir ajanın işini [inceleme kutusundan](/ozellikler/inceleme-kutusu/ "İnceleme kutusu") bir notla geri gönderdiğinde ya da Verify bir kriteri başarısız bulduğunda, küçük bir Claude modeli bu düzeltmeyi tek satırlık bir kurala çevirir. Kural **Kural önerileri** altında görünür; **Talimatlara ekle** onu projedeki CLAUDE.md ve AGENTS.md’ye (hangisi varsa) ekler, dosyada zaten olan kurallar atlanır. İkisi de yoksa AGENTS.md’yi ve onu `@AGENTS.md` ile import eden bir CLAUDE.md’yi oluşturur.
- **Şişkin ortak dosya yerine ajana özel rol.** Ajan penceresindeki “Rol ve talimatlar” alanı sadece o ajana verilir (Claude’da sistem prompt’una eklenir, Codex’e developer instructions olarak gider). Böylece ajana özel roller ortak dosyaya karışmaz. Cursor, Gemini CLI ve Amp bu alanı kullanmaz; onlarda projedeki AGENTS.md ya da kural dosyaları geçerlidir.
- **Klasör turu yerine kod haritası.** [Proje haritası](/ozellikler/proje-haritasi/ "Proje haritası") yerelde oluşturulur ve ajanlara MCP araçları olarak sunulur (`map_related`, `map_outline`, `map_usages` ve diğerleri); yeni ajanlar da modüllerin, giriş noktalarının ve test komutunun kısa bir özetini alır. İnsanların CLAUDE.md’ye elle yapıştırdığı kısım tam olarak bu.
- **Proje hafızası.** [AgentVera Brain](/ozellikler/brain/ "AgentVera Brain"), CLAUDE.md ve AGENTS.md dahil git’te takip edilen dokümanlarını, commit’leri, PR’ları ve geçmiş konuşmaları okur; hangi kararların güncel, hangilerinin eskimiş olduğunu izler. İsteğe bağlı bağlam paketi (varsayılan olarak kapalı) yeni ajanların talimatlarına eklenebilir.
- **Prosedürler skill olarak.** [Skill galerisi](/ozellikler/skill-galerisi/ "Skill galerisi") Claude Code ve Codex için SKILL.md klasörlerini yönetir; uzun prosedürlerin yeri de burası.
- **Her seferinde çalışması gereken kurallar.** CLAUDE.md bir tavsiyedir; her seferinde yapılması gereken kontroller için [Claude Code hooks](/blog/claude-code-hooks-rehberi/ "Claude Code hooks rehberi") kullan, dar yan işleri [alt ajanlara](/blog/claude-code-alt-ajanlar/ "Claude Code alt ajanlar") ver.

## Kontrol listesi

- [ ] 200 satırın altında; mümkünse 100’ün altında.
- [ ] Build, test, lint ve tip kontrolü komutları yazılı ve doğru.
- [ ] Her kural kontrol edilebilecek kadar net.
- [ ] Klasör turu, gizli anahtar, genel tavsiye yok.
- [ ] Klasöre özel kurallar iç içe dosyalarda ya da `paths:` kurallarında.
- [ ] Uzun prosedürler skill’lerde ya da dokümanlarda, tek satırla işaret ediliyor.
- [ ] Kesin sınırlar cümleyle değil, hook ya da izinle uygulanıyor.
- [ ] Ortak kurallar AGENTS.md’de; CLAUDE.md onu import ediyor.
- [ ] Kişisel tercihler `~/.claude/CLAUDE.md` ya da CLAUDE.local.md’de.

## Toparlarsak

Talimat dosyası, bir ajanın projende daha önce çalışmış gibi davranmasının en ucuz yolu. Kısa tut, somut tut ve sadece gerçekten gördüğün hatalardan büyüsün. Ortak kuralları AGENTS.md’ye koy ki her CLI aynı şeyi okusun, prosedürleri skill’lere taşı, gerçekten önemli olanları da cümleyle değil hook’la uygula.

## Sık sorulanlar

**CLAUDE.md dosyası ne kadar uzun olmalı?** Anthropic dosya başına 200 satırın altında kalmayı öneriyor. Dosya her oturumun başında bağlama yüklenir; uzadıkça hem daha çok token harcar hem de ajan kurallara daha az sadık kalır.

**CLAUDE.md ile AGENTS.md arasındaki fark ne?** İkisi aynı işi görür. CLAUDE.md’yi Claude Code okur; AGENTS.md ise Codex, Cursor, Copilot, opencode, Aider, goose ve daha birçok aracın okuduğu açık bir formattır. Claude Code’un yeni sürümleri, CLAUDE.md yoksa AGENTS.md’yi de okuyor.

**Claude Code, Codex ve Gemini CLI için tek talimat dosyası kullanabilir miyim?** Evet. Ortak kuralları AGENTS.md’ye yaz, yanına içinde @AGENTS.md satırı olan bir CLAUDE.md koy, Gemini CLI ayarlarında da context.fileName listesine AGENTS.md’yi ekle.

**CLAUDE.md git’e eklenmeli mi?** Proje CLAUDE.md’si evet, çünkü ekibin ortak bilgisi. Kişisel tercihlerin ~/.claude/CLAUDE.md’ye ya da .gitignore’a eklediğin CLAUDE.local.md’ye gider.

**CLAUDE.md’ye yazdığım kurala ajan kesin uyar mı?** Hayır. Bu dosya bağlamdır, zorlama değildir. Net kurallara genelde uyulur ama bir şeyin asla olmaması gerekiyorsa onu CLAUDE.md’deki bir cümleyle değil, hook ya da izin ayarıyla engelle.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/