AI Kod Ajanına Proje Bağlamı: CLAUDE.md ve AGENTS.md

Yeni bir AI kod ajanını mevcut bir repoda çalıştırdığında ilk izlenim genelde hayal kırıklığı olur: ajan proje adını doğru bilir ama hangi paket yöneticisini kullandığını, test komutunun ne olduğunu, hangi klasöre dokunulmayacağını bilmez. CLAUDE.md AGENTS.md nasıl yazılır sorusunun cevabı aslında tam burada başlıyor — ajan aptal değil, sadece bağlamsız. Bu yazıda iki dosyanın (CLAUDE.md ve AGENTS.md) ne işe yaradığını, hangi sırayla okunduğunu ve neyin yazılıp neyin yazılmaması gerektiğini elindeki en güncel (Kasım 2025 dönemi) mekanizmalarla anlatıyorum.

💡 Pro Tip: Bağlam dosyasını "dokümantasyon" gibi değil, her oturumda otomatik context'e giren ve tokeni tüketen bir kaynak gibi düşün — ne kadar uzunsa o kadar pahalı.

İçindekiler

• Ajan neden sizin projenizde aptallaşıyor — eksik olan bağlam
• AGENTS.md: araç-bağımsız sözleşme
• CLAUDE.md: oturum başında otomatik yüklenen proje hafızası
• Öncelik sırası: global kural, proje kuralı, alt klasör kuralı
• Ne yazılmalı: komutlar, mimari sınırlar, yasaklar, kanıt beklentisi
• Ne YAZILMAMALI: dokümantasyon kopyası, sürüm notu, şişmiş liste
• Bağlam maliyetini ölçmek: neden kısa tutmalısın
• Şablon: 30 satırlık minimum çekirdek
• Hızlı düzenleme: `#` kısayolu ve `/memory` komutu
• SSS
• CLAUDE.md ile AGENTS.md arasındaki fark nedir?
• İyi bir proje bağlam dosyası neleri içermeli, ne kadar uzun olmalı?
• Kurallar hangi sırayla geçerli olur (global, proje, alt klasör)?
• Bağlam dosyası her oturumda token yakıyor mu?
• Güncelleme (Eylül 2026)
• Sonuç
• Kaynaklar

Ajan neden sizin projenizde aptallaşıyor — eksik olan bağlam

Bir kod ajanı yeni bir konuşma başlattığında elinde yalnızca modelin genel eğitimi ve sizin o an yazdığınız istek vardır; sizin repo'nuzun tarihini, ekip konvansiyonlarını, "neden böyle yaptık" kararlarını bilmez. Claude Code bu boşluğu doldurmak için CLAUDE.md adında özel bir dosya kullanır: bu dosya, bir konuşma başlarken Claude'un otomatik olarak context'e çektiği bir dosyadır ve bash komutları, dosya yapısı, kod stili, test talimatları gibi bilgiler için ideal bir yerdir (Anthropic, "Claude Code: Best practices for agentic coding", Nisan 2025'te yayımlandı; web.archive.org 2025-11-08 anlık görüntüsü). Yani ajanın "aptallaşması" aslında model sınırlaması değil, eksik bağlam sorunudur — ve bu sorunun çözümü, doğru dosyayı doğru yere koymaktır.

AGENTS.md: araç-bağımsız sözleşme

AGENTS.md, farklı bir sorunu çözmek için ortaya çıktı: her kod ajanı aracının kendi bağlam dosyası formatı varsa (Claude Code için CLAUDE.md, başka bir araç için farklı bir isim), aynı projeyi birden fazla ajanla çalıştıran ekipler bilgiyi tekrar tekrar yazmak zorunda kalıyordu. AGENTS.md bunun yerine araç-bağımsız, düz Markdown bir "ajanlar için README" öneriyor. 18 Kasım 2025 tarihli haliyle agents.md, 20.000'den fazla açık kaynak projede kullanıldığını belirtiyordu (agents.md, web.archive.org 2025-11-18 anlık görüntüsü). O tarihte agents.md'nin desteklediği araçlar listesinde Codex, Jules, Factory, Aider, Kilo Code, Phoenix, Semgrep, GitHub Copilot Coding Agent, Ona, UiPath, Amp, Cursor, RooCode, Gemini CLI, opencode, Zed, Warp, VS Code ve Devin vardı — Claude Code o listede henüz yer almıyordu.

Bunun anlamı şu: Claude Code o tarihte AGENTS.md'yi kendiliğinden okumuyordu; dosyayı yazmana engel bir şey yoktu, kök CLAUDE.md'ye tek satır @AGENTS.md yazarak aynı dosyayı Claude Code'a da yükletebiliyordun (import mekanizması 0.2.107, 9 Mayıs 2025). İki dosya aynı amaca (proje bağlamı) hizmet eder, farklı ekosistemlerde farklı isimlerle.

CLAUDE.md: oturum başında otomatik yüklenen proje hafızası

Claude Code, dört katmanlı bir hafıza hiyerarşisi sunar: Enterprise policy (kurum genelinde, IT tarafından yönetilir), Project memory (ekiple paylaşılan, repo köküne commit edilen ./CLAUDE.md), User memory (~/.claude/CLAUDE.md, tüm projelerde geçerli kişisel tercihler) ve Project memory (local) — ./CLAUDE.local.md (code.claude.com/docs/en/memory, web.archive.org 2025-11-13 anlık görüntüsü). Bu dördüncü katman o tarihte zaten kullanımdan kaldırılmıştı: CLAUDE.local.md benzer bir amaca hizmet ediyordu ama artık import mekanizması lehine deprecated durumdaydı — çünkü import'lar birden fazla git worktree arasında daha iyi çalışıyor (aynı kaynak). Yani pratikte proje bağlamı için iki dosya kalıyordu: ekiple paylaşılan CLAUDE.md ve kişisel ~/.claude/CLAUDE.md.

Enterprise policy dosyasının yolu işletim sistemine göre sabitti: macOS'te /Library/Application Support/ClaudeCode/CLAUDE.md, Linux'te /etc/claude-code/CLAUDE.md, Windows'ta C:\ProgramData\ClaudeCode\CLAUDE.md (aynı kaynak, 2025-11-13 anlık görüntüsü) — bu dosyaya kullanıcı erişemez, IT tarafından merkezi olarak dağıtılır ve en üst öncelikle yüklenir.

Dört katmanı bir arada görmek, hangisinin git'e gireceğini ve hangisinin kişisel kalacağını netleştiriyor:

Pratikte bu tablo şu soruyu cevaplıyor: "bu kuralı nereye yazmalıyım?" Ekiple paylaşılacak her şey ./CLAUDE.md'ye ve PR ile gider; "ben şahsen böyle çalışmayı tercih ediyorum" türünden bir tercih ise ~/.claude/CLAUDE.md'ye gider ve hiçbir zaman repoya karışmaz.

1# Proje kökünde hiyerarşinin nerede olduğunu gör
2ls -la CLAUDE.md CLAUDE.local.md ~/.claude/CLAUDE.md 2>/dev/null

Öncelik sırası: global kural, proje kuralı, alt klasör kuralı

Hiyerarşideki kural basit: yukarıda olan dosyalar önceliklidir ve önce yüklenir, daha genel bir temel oluşturur, altındakiler bu temeli daha spesifik hale getirir (code.claude.com/docs/en/memory, 2025-11-13). Yani sıra şöyle işler: önce Enterprise policy okunur (kurum standardı), sonra Project memory (ekip kararı, CLAUDE.md), sonra User memory (kişisel tercih, ~/.claude/CLAUDE.md). Çakışma olduğunda daha spesifik/daha alt katman değil, hiyerarşideki konum belirleyicidir — bu nedenle "proje kuralı global kuralın önüne geçer mi" sorusunun cevabı dosyaya değil, o dosyanın hiyerarşideki konumuna bakar.

Dosyalar arasında bilgi paylaşmanın bir yolu da import mekanizmasıdır: CLAUDE.md dosyaları @path/to/file.md söz dizimiyle başka dosyaları içeri alabilir — bu özellik 9 Mayıs 2025'te 0.2.107 sürümüyle eklendi ("CLAUDE.md files can now import other files. Add @path/to/file.md to ./CLAUDE.md to load additional files on launch", code.claude.com/docs/en/changelog). Pratikte bu, kök CLAUDE.md'yi kısa tutup detayları alt klasörlere bölmenin standart yoludur:

1# CLAUDE.md (proje kökü)
2 
3Bu proje bir Next.js monorepo'dur. Paket yöneticisi pnpm.
4 
5@docs/testing-conventions.md
6@docs/api-error-handling.md

Böylece kök dosya kısa kalır, ama alt klasörlerdeki detaylı kurallar ihtiyaç anında yine context'e girer.

Ne yazılmalı: komutlar, mimari sınırlar, yasaklar, kanıt beklentisi

Anthropic'in Nisan 2025 tarihli rehberi, CLAUDE.md'ye yazılması önerilen içerik türlerini net bir listeyle veriyordu; listenin başlıca maddeleri şunlardı: sık kullanılan bash komutları, temel dosyalar ve yardımcı fonksiyonlar, kod stili kuralları, test talimatları, repo görgü kuralları (branch adlandırma, merge veya rebase tercihi), geliştirici ortamı kurulumu (örneğin belirli bir derleyici sürümü) ve projeye özgü beklenmedik davranışlar veya uyarılar ("Claude Code: Best practices for agentic coding", web.archive.org 2025-11-08 anlık görüntüsü). Bu liste aslında bir ajanın "sorup öğrenmek yerine bilerek başlamasını" istediğiniz her şeyi kapsar.

1# CLAUDE.md içine yazılabilecek tipik bir komut bloğu
2pnpm dev          # yerel geliştirme sunucusu
3pnpm test         # vitest unit testler
4pnpm test:e2e     # playwright, önce `pnpm dev` gerekir
5pnpm lint --fix   # eslint + prettier otomatik düzeltme

• Bash komutları: ajanın tahmin etmek yerine kopyalayıp çalıştırabileceği tam komutlar.
• Kod stili: girinti, import sırası, isimlendirme — "düzgün formatla" değil, somut kural.
• Test talimatları: hangi komut, hangi dizinden, hangi ön koşulla çalıştırılır.
• Repo görgü kuralı: branch adlandırma, commit mesaj formatı, rebase mi merge mi.
• Beklenmedik davranışlar: "bu modül aslında X yapıyor ama ismi Y" türünden tuzaklar.

Bu listeye bakınca ortak bir örüntü fark edilir: hepsi "ajanın sorup öğrenebileceği ama sormadan bilmesi daha ucuz olan" bilgilerdir. Bir ajan hangi test komutunu çalıştıracağını dosyadan okumak yerine repo'yu tarayarak da bulabilir, ama bu hem zaman hem token harcar; CLAUDE.md'ye yazılan her satır, ajanın bu tür keşif adımlarını atlamasını sağlar. Kanıt beklentisi de aynı mantıkla yazılabilir — örneğin "bir değişiklik yaptıktan sonra pnpm test ve pnpm build ikisi de geçmeden tamamlandı deme" gibi bir kural, ajanın kendi kendine "bitti" demesini engelleyen somut bir kapıdır.

Ne YAZILMAMALI: dokümantasyon kopyası, sürüm notu, şişmiş liste

CLAUDE.md'nin zorunlu bir formatı yoktur; Anthropic bunu kısa ve insan-okunur tutmayı öneriyordu ("There's no required format for CLAUDE.md files. We recommend keeping them concise and human-readable", aynı kaynak, 2025-11-08 anlık görüntüsü). Hafıza dosyaları için üç ilke veriliyordu: spesifik ol ("2 boşlukla girintile" ifadesi "kodu düzgün formatla" ifadesinden daha iyidir), yapı kullanarak organize et, ve düzenli aralıklarla gözden geçir (code.claude.com/docs/en/memory, 2025-11-13). Bu üç ilkeden çıkan pratik sonuç şu: CLAUDE.md bir README kopyası, bir CHANGELOG ya da "yapılacaklar" listesi değildir — ajanın her oturumda tekrar okuyacağı, çalışırken gerçekten kullanacağı bilgi olmalı.

Bağlam maliyetini ölçmek: neden kısa tutmalısın

CLAUDE.md, hiyerarşideki her katmanla birlikte konuşma başlarken otomatik olarak context'e yüklenir — bu, dosyanın büyüklüğünün doğrudan her oturumun token bütçesinden pay aldığı anlamına gelir. Dört katmanın (enterprise, proje, kullanıcı, ve o dönemde hâlâ desteklenen local) hepsi aynı anda yükleniyorsa, uzun ve gevşek yazılmış bir dosya, ajanın asıl işe başlamadan önce tükettiği tokeni büyütür. Bu yüzden yukarıdaki üç ilke (spesifik, yapılı, düzenli gözden geçirilen) sadece okunabilirlik için değil, doğrudan maliyet için de geçerlidir: gereksiz cümle, tekrar eden açıklama veya kod tabanından zaten çıkarılabilecek bilgi (dosya ağacı, bağımlılık listesi gibi) CLAUDE.md'de yer kaplamamalıdır. Pratik bir ölçüm yöntemi, dosyayı periyodik olarak yeniden okumak ve "bu satır ajanın gerçek bir kararını değiştirdi mi" sorusunu sormaktır — cevap hayırsa, o satır silinmeye adaydır.

Şablon: 30 satırlık minimum çekirdek

Biçim zorunluluğu olmadığı için başlangıç noktası küçük tutulabilir. Aşağıdaki iskelet, yeni bir projede CLAUDE.md'ye ilk günden eklenebilecek minimum çekirdeği gösteriyor — büyüdükçe alt bölümler @path importlarıyla ayrılabilir (yukarıdaki bölüme bakın):

1# Proje Adı
2 
3**Komutlar**
4 
5- Dev: pnpm dev
6- Test: pnpm test
7- Lint: pnpm lint --fix
8 
9**Mimari**
10 
11- src/api/ — REST endpoint'leri, her biri kendi dosyasında
12- src/lib/db.ts — tek DB bağlantı noktası, başka yerden import etme
13 
14**Kod stili**
15 
16- TypeScript strict, any yasak
17- Import sırası: external -> internal -> relative
18 
19**Yasaklar**
20 
21- main branch'e doğrudan push yok
22- .env dosyasını asla commit etme
23 
24**Test talimatı**
25 
26- pnpm test önce pnpm db:seed ister

Bu çekirdek 30 satırın altındadır ama beş temel soruyu (nasıl çalıştırılır, nereye dokunulur, nasıl yazılır, ne yasak, nasıl doğrulanır) baştan cevaplar. Proje büyüdükçe her bölüm kendi @docs/...md dosyasına taşınabilir; kök dosya böylece küçük kalmaya devam eder.

Hızlı düzenleme: `#` kısayolu ve `/memory` komutu

2025-11-19 itibarıyla Claude Code'da bir hafıza dosyasına hızlıca not eklemenin iki yolu vardı: konuşma sırasında mesajını # ile başlatarak (bu, Claude'a "bunu hatırla" demenin kısa yoluydu) ya da /memory komutuyla ilgili dosyayı doğrudan açıp düzenleyerek. Katman seçimi her iki yolda da vardı; kısayolla not eklerken de bunun hangi hafıza dosyasında saklanacağı sana sorulup seçtiriliyordu. Asıl fark kapsamdı: /memory dosyayı kendi editöründe açtığı için tek satırlık not yerine uzun eklemeler ve yeniden düzenleme yapabiliyordun. Pratikte önerilen akış şuydu: küçük, anlık bir kural eklerken hızlı kısayolu kullan; dosyayı yeniden yapılandırırken ya da uzun bir bölüm eklerken /memory ile açıp elle düzenle.

1claude
2# ardından Claude istemine yaz: /memory

SSS

CLAUDE.md ile AGENTS.md arasındaki fark nedir?

İkisi de aynı amaca hizmet eder: bir kod ajanına proje bağlamı vermek. Fark, kimin okuduğudur. CLAUDE.md, Claude Code'a özel bir dosyadır ve konuşma başlarken otomatik olarak context'e çekilir. AGENTS.md ise araç-bağımsız bir standarttır; Codex, Cursor, Aider, Gemini CLI, Zed, Warp gibi birçok farklı ajan tarafından okunur. 2025-11-19 döneminde Claude Code, AGENTS.md'yi kendiliğinden okumuyordu; ama içeriği kopyalamana gerek yoktu — kök CLAUDE.md'ye tek satır @AGENTS.md yazarak aynı dosyayı yükletebiliyordun (import 0.2.107, 9 Mayıs 2025).

İyi bir proje bağlam dosyası neleri içermeli, ne kadar uzun olmalı?

Bash komutları, temel dosyalar ve yardımcı fonksiyonlar, kod stili kuralları, test talimatları, repo görgü kuralları, geliştirici ortamı kurulumu ve projeye özgü beklenmedik davranışları içermeli. Uzunluk için zorunlu bir format ya da sayısal sınır yoktu; Anthropic'in önerisi dosyayı kısa ve insan-okunur tutmak, spesifik olmak, yapı kullanmak ve düzenli aralıklarla gözden geçirmekti.

Kurallar hangi sırayla geçerli olur (global, proje, alt klasör)?

Claude Code dört katmanlı bir hiyerarşi kullanır: Enterprise policy en üstte (kurum tarafından merkezi yönetilir), altında Project memory (ekiple paylaşılan CLAUDE.md), altında User memory (~/.claude/CLAUDE.md, tüm projelerde geçerli kişisel tercihler). Hiyerarşide yukarıda olan dosyalar önceliklidir ve önce yüklenir; daha spesifik katmanlar bu temelin üzerine eklenir. Alt klasör kuralları ise @path import mekanizmasıyla kök dosyaya bağlanır ve aynı hiyerarşinin bir parçası olarak yüklenir.

Bağlam dosyası her oturumda token yakıyor mu?

Evet — CLAUDE.md hiyerarşideki tüm katmanlarıyla birlikte konuşma başlarken otomatik olarak context'e yüklenir, yani dosyanın uzunluğu doğrudan her oturumun başlangıç token maliyetine eklenir. Bu yüzden dosyayı kısa, spesifik ve düzenli gözden geçirilmiş tutmak sadece okunabilirlik değil, doğrudan maliyet meselesidir.

Güncelleme (Eylül 2026)

Bu yazının gövdesi 2025-11-19 tarihindeki mekanizmalarla yazıldı. O tarihten sonra Claude Code'un bağlam dosyası davranışında gerçek değişiklikler oldu:

• AGENTS.md artık doğrudan okunuyor. 18 Eylül 2026'da yayınlanan v2.1.277 ile Claude Code, proje kökünde CLAUDE.md yoksa AGENTS.md'yi doğrudan okumaya başladı — artık @AGENTS.md importu ya da symlink workaround'una gerek yok (code.claude.com/docs/en/changelog). Bu davranış /config menüsündeki "Project instructions" ayarıyla (claude-md-or-agents-md varsayılan, claude-md-and-agents-md, claude-md, managed-only seçenekleriyle) ya da settings.json'daki pluginConfigs["agents-md@builtin"].options.instructionFiles anahtarıyla değiştirilebiliyor. Destek henüz Bedrock, Vertex ve Foundry'de yok.
• /memory ve /context artık AGENTS.md'yi de listeliyor. 22 Eylül 2026'da yayınlanan v2.1.280 öncesinde, doğrudan okunan bir AGENTS.md bu komutların çıktısında listelenmiyordu (code.claude.com/docs/en/memory).
• .claude/rules/ yol-bazlı kurallarda üç ayrı düzeltme geldi: v2.1.198 symlink üzerinden erişilen dosyalarda paths eşleşmesini düzeltti, v2.1.207 geçersiz bir glob deseninin artık tüm kuralı değil sadece o deseni bozmasını sağladı, v2.1.217 çok sayıda brace-expansion içeren listelerin CLI'ı donduran davranışını 1.000 genişletilmiş desen ve 4 MiB'lik ortak bütçeyle sınırladı (code.claude.com/docs/en/memory).
• # kısayolu kaldırıldı. 15 Aralık 2025'te v2.0.70 ile hızlı hafıza ekleme kısayolunun kendisi kaldırıldı: "Removed # shortcut for quick memory entry (tell Claude to edit your CLAUDE.md instead)" (code.claude.com/docs/en/changelog).
• Best practices sayfası baştan yazıldı. Gövdede alıntılanan anthropic.com/engineering/claude-code-best-practices adresi bugün code.claude.com/docs/en/best-practices'e yönleniyor ve sayfa "Best practices for Claude Code" başlığıyla yeniden yazıldı; bu yazıdaki alıntılar 2025-11-08 arşiv anlık görüntüsünden alınmıştır.

Sonuç

CLAUDE.md AGENTS.md nasıl yazılır sorusunun kısa cevabı: az yaz, spesifik yaz, hiyerarşiyi anla. Ajanı "aptal" gösteren şey çoğu zaman eksik ya da şişmiş bağlam dosyasıdır — komutlar somut değilse, yasaklar cümlenin ortasında kayboluyorsa ya da dosya kod tabanından zaten çıkarılabilecek bilgiyle doluysa, ajan her oturumda aynı hataları tekrar eder. Claude Code'un dört katmanlı hiyerarşisini ve @path import mekanizmasını doğru kullanmak, tek bir kök dosyayı küçük tutup detayları ihtiyaç anında yüklemek anlamına gelir.

Bu konuyu bağlam yönetiminin başka katmanlarıyla birlikte okumak istersen Claude Projects ve Memory: Bağlam Yönetimi yazısı tüketici tarafındaki (Claude.ai) bağlam mekanizmalarını anlatıyor — bu yazı ise repo kökündeki ajan sözleşme dosyalarını ele alıyor, ikisi birbirini tamamlıyor. Planlama aşamasında ajanı yönlendirmek için Claude Code Plan Mode: AI ile Yazılım Mimarisi Planlama yazısına, birden fazla ajanı orkestre etmek için Claude Code Multi-Agent Teams: Paralel AI Agentlar yazısına, hangi ajan aracını (Skill, Subagent, Hook, MCP) ne zaman kullanacağına karar vermek için Claude Code'da Skill, Subagent, Hook, MCP: Hangisi? yazısına, delegasyon maliyetini kontrol altında tutmak için de Claude Code Subagent Model Ataması ve Orkestrasyon yazısına bakabilirsin.

Kaynaklar

• Claude Code memory dokümantasyonu — hiyerarşi, import sözdizimi ve hafıza yönetimi
• Claude Code changelog — sürüm bazlı değişiklik kayıtları (import, AGENTS.md desteği, # kısayolu)
• Claude Code: Best practices for agentic coding (2025-11-08 arşiv anlık görüntüsü) — CLAUDE.md içeriği için orijinal öneriler; canlı adres bugün code.claude.com/docs/en/best-practices'e yönleniyor ve yeniden yazıldı
• AGENTS.md — araç-bağımsız proje bağlam dosyası standardı
• AGENTS.md desteği — Claude Code memory dokümantasyonu — doğrudan okuma davranışı ve sınırları
• @anthropic-ai/claude-code npm paketi — sürüm/tarih doğrulaması için paket kayıt verisi