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

İ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 eklediği düz bir Markdown dosyası.

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

Ç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 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

# 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ı?

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 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:

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:

---
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:

   @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:

   { "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, 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 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ı 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, 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 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 kullan, dar yan işleri alt ajanlara 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.