Hepsine Hükmeden Tek Kurulum: Model-Bağımsız AI Kodlama Yapılandırması

Özet#

Ekipler nadiren tek bir AI kodlama aracında uzlaşır; yalnızca Claude Code, Codex, Copilot, Cursor ya da OpenCode'dan biriyle çalışan bir repo, farklı bir araç seçen her katkı sağlayıcıyı dışarıda bırakır. Bu yazı, AGENTS.md dosyasını tek kaynak olarak kullanan somut bir düzen gösterir: diğer araçların beklediği her dosya adı için symlink ya da @-import, araçlar arası tool katmanı için MCP. Aynı zamanda hayalin kırıldığı yerleri de işaretler: skill'ler, slash komutları ve Windows symlink tuzakları.

Problem#

Bir ekip Claude Code benimser. Yeni bir geliştirici Cursor'u tercih eder. Repo kökündeki CLAUDE.md sessiz sessiz durur; Cursor ise .cursor/rules/ klasörünü okur. Biri kuralları elle kopyalar. Bir ay sonra aynı kural AGENTS.md dosyasında biraz farklı bir ifadeyle yer alır. Üç dosya birbirinden uzaklaşır. Senkronizasyonun sahibi yoktur.

Gerçek repolarda karşımıza çıkan birkaç sorun daha:

• Paket bazlı kuralları olan bir monorepo. Claude Code ağaç boyunca yukarı yürür ve iç içe CLAUDE.md dosyalarını birleştirir. OpenCode en yakın AGENTS.md dosyasını okur. Copilot yalnızca kökteki .github/copilot-instructions.md dosyasını okur. Aynı kod, farklı davranış.
• MCP sunucuları (GitHub, veritabanı, dosya sistemi) .mcp.json (proje kökü, Claude Code), .codex/config.toml, .vscode/mcp.json ve .cursor/mcp.json dosyalarında yaşamak zorunda. Aynı URL, aynı kimlik doğrulama, dört farklı format.
• Skill'ler ve slash komutları .claude/skills/ ve .claude/commands/ içinde durur. Codex, Copilot veya Cursor'a otomatik taşınmazlar.
• Windows katkıcıları repoyu klonlar. Symlink'ler düz metin dosyaları olarak gelir ve içinde yalnızca AGENTS.md yazar. AI aracı sessizce hiçbir şey yüklemez.

Bu yazının amacı: kanonik bir dosya seçmek, her aracın onu okumasını sağlamak ve en düşük ortak payda duvarının gerçekte nerede olduğu konusunda dürüst olmak.

Her Aracın Okuduğu Dosya (Nisan 2026)#

Bir düzen seçmeden önce, her aracın açılışta gerçekten neye baktığını bilmek gerekir. Aşağıdaki tabloyu her aracın Nisan 2026 dokümantasyonuyla karşılaştırdım (bağlantılar sonda).

Not: Anthropic'in Nisan 2026 memory dokümanı, AGENTS.md dosyasını CLAUDE.md yoksa devreye giren bir yedek olarak tanımlıyor, eşit bir eş olarak değil. İki dosya da varsa, Claude Code CLAUDE.md dosyasını okur ve AGENTS.md dosyasını görmezden gelir. Bu, farklı topluluk rehberlerinin farklı ifade ettiği tek nokta; yayına girmeden önce resmi dokümandan doğrulayın.

Tablo basit bir seçimi dayatıyor: en çok aracın doğrudan okuduğu bir dosyayı seç ve diğer araçların onu bulabilmesini sağla.

Kanonik Düzen#

AGENTS.md dosyasını seçin. 2026'da en geniş kabul gören isim; OpenAI, Copilot, OpenCode, Cursor ve diğerleri onu kanonik kabul ediyor.

repo-koku/  AGENTS.md  # tek kaynak, commit'lenir  CLAUDE.md  # symlink -> AGENTS.md  .mcp.json  # MCP sunucuları (Claude Code, proje kökü)  .github/    copilot-instructions.md  # symlink -> ../AGENTS.md    instructions/  # dosya yoluna özel kurallar (yalnız Copilot)  .cursor/    rules/      main.mdc  # symlink -> ../../AGENTS.md veya ince bir shim  .claude/    commands/  # Claude'a özel slash komutları    skills/  # Claude'a özel skill'ler  .codex/    config.toml  # MCP sunucuları (Codex formatı)  .vscode/    mcp.json  # MCP sunucuları (Copilot formatı)  GEMINI.md  # symlink -> AGENTS.md (isteğe bağlı)

Tek bir dosya kuralları taşır. Symlink'ler her aracın beklediği diğer dosya adlarına köprü kurar. Araç dizinleri araca özel kalır.

Tek Kaynağı Korumanın Üç Yolu#

Seçenek A: Symlink#

Unix yerlisi yaklaşım. Git symlink'leri takip eder. Her editör ve CLI aracı onları izler.

ln -sfn AGENTS.md CLAUDE.mdln -sfn ../AGENTS.md .github/copilot-instructions.mdmkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc

Windows'taki ekip arkadaşları için klonlamadan önce git config --global core.symlinks true komutunu çalıştırın. Bu ayar olmazsa git, symlink'i içeriği yalnızca AGENTS.md olan düz bir metin dosyası olarak çeker. Araç o tek satırı tüm proje kural kitabı sanır.

Seçenek B: @-import#

Claude Code ve OpenCode, bir dosyayı @ öneki ile gördüğünde içeriğini satır içi yerleştirir. Ortak bir tabanın üstüne birkaç araca özel satır eklemek istiyorsanız en temiz seçenek budur.

# CLAUDE.md@AGENTS.md
## Yalnızca Claude için eklentiler- Testlerden önce `.claude/hooks` betiklerini kullan.

Copilot ve Cursor @-import'u anlamaz. Metni olduğu gibi okur. Bu yolu seçerseniz Copilot ve Cursor'ı symlink veya işaretçi dosya ile çözün.

Seçenek C: İşaretçi dosyalar#

En kaba ama en taşınabilir seçenek. Tek satırlık bir CLAUDE.md:

ÖNCE AGENTS.md DOSYASINI OKU. Tüm proje kuralları orada.

LLM'in bu satıra uyması olasılıksaldır. İşaretçi belki yüzde beş oranında görmezden gelinir. Tek kişilik bir repo için yeter; uyumluluk gerektiren bir repo için yetmez.

Strateji Seçimi#

Symlink ne zaman kazanır: saf unix ekibi, Windows katkıcısı yok, sıfır tekrar istiyorsunuz.

@-import ne zaman kazanır: ortak tabanın üzerine araca özel eklentiler istiyorsunuz ve ekibiniz Claude Code veya OpenCode kullanıyor.

İkisi de değmediğinde: bugün tek araç var, değiştirme planı yok. Tek başına CLAUDE.md veya AGENTS.md yeterli. Erken birleştirme sadece yeni bir drift kaynağıdır.

MCP Katmanı#

MCP (Model Context Protocol), araçlar için tek gerçek araçlar arası sözleşmedir; kurallar için değil. Her ciddi asistan MCP sunucu tanımlarını okur. Ama her biri farklı bir yol ve formattan:

• Claude Code: proje kökünde .mcp.json (.claude/mcp.json değil, yaygın bir tuzak)
• Codex CLI: proje bazında .codex/config.toml veya global ~/.codex/config.toml — çoğu ekip global dosyayı kullanır
• Copilot (VS Code): .vscode/mcp.json (servers anahtarını kullanır, mcpServers değil)
• Cursor: .cursor/mcp.json (mcpServers anahtarını kullanır)

Dört dosya. Aynı URL, aynı kimlik token'ı, dört format. Topluluk araçları (chezmoi tarifleri, 2026 başında Hacker News'te paylaşılan YAML-to-çoklu üreticiler) dördünü tek kaynaktan üretebilir. Bilmekte fayda var. Bir yaklaşım net kazanana kadar bağımlılık kurmaya değmez. Şimdilik reponuz gerçek MCP sunucuları çalıştırıyorsa dört config dosyasına bütçe ayırın.

Buradaki ödünleşim çirkin ama dürüst: kurallar tek dosya ile taşınır, araçlar MCP ile taşınır ve MCP yapılandırmasının kendisi taşınmaz. Ya buna katlanırsınız ya tek araç seçersiniz.

Kurulumu Otomatize Etmek (projen ve benzerleri)#

Üç symlink ve bir .mcp.json kurmak bir saat sürer. Bir yıl sonra biri bir dosyayı yeniden adlandırır, Windows symlink'leri bozulur, dört MCP config'i birbirinden uzaklaşır. Otomasyon, CI'yi iyi niyet yerine zorlayıcı katman yapar.

Seçenekler ekibinizin zaten neyi kullandığına göre ayrılır.

projen — TypeScript synth#

projen proje dosyalarını kod olarak ele alır. Bir project sınıfını extend edersiniz, üretilmesini istediğiniz dosyaları tanımlarsınız, npx projen onları yeniden üretir. Herhangi bir drift synth kontrolünde başarısız olur.

// .projenrc.tsimport { Project, TextFile, JsonFile, Component } from 'projen';import { readFileSync, existsSync, unlinkSync, symlinkSync } from 'fs';import { dirname, relative } from 'path';
class AgentSymlinks extends Component {  constructor(project: Project, private aliases: string[], private target: string) {    super(project);  }  synthesize() {    for (const alias of this.aliases) {      if (existsSync(alias)) unlinkSync(alias);      symlinkSync(relative(dirname(alias), this.target), alias);    }  }}
const project = new Project({ name: 'my-repo' });
new TextFile(project, 'AGENTS.md', {  lines: readFileSync('.rules/agents-source.md', 'utf8').split('\n'),});
new AgentSymlinks(project, [  'CLAUDE.md',  '.github/copilot-instructions.md',  '.cursor/rules/main.mdc',], 'AGENTS.md');
// Tek YAML kaynağı, dört MCP config formatınew JsonFile(project, '.mcp.json',  { obj: mcpFrom('mcp-servers.yml', 'claude') });new JsonFile(project, '.vscode/mcp.json', { obj: mcpFrom('mcp-servers.yml', 'vscode') });new JsonFile(project, '.cursor/mcp.json', { obj: mcpFrom('mcp-servers.yml', 'cursor') });
project.synth();

Trade-off: projen AWS CDK bölgesi. Ekibiniz zaten package.json, tsconfig ve GitHub Actions'ı projen ile sentezlemiyorsa, sadece AI config için benimseme maliyet olarak fazla. Kazanç tek-araçla-tüm-config'ten geliyor, tek-araçla-AI-config'ten değil.

chezmoi — şablonlar, geliştirici bazlı#

chezmoi Go text/template destekli bir dotfile yöneticisi. AI config'inizin çoğu $HOME içinde yaşıyorsa (kullanıcı bazlı Claude, Cursor, Codex globaller), chezmoi repo-bazlı synth'ten daha iyi uyar. Tek bir .chezmoitemplates/AGENTS.md, sonrasında chezmoi apply onu her aracın beklediği yola yerleştirir. Geliştirici bazlı override'lar aynı template sistemini kullanır.

Amaca özel araçlar ve düz scriptler#

Başka otomasyon bulunmayan tek bir repo için küçük bir amaca özel CLI ya da pre-commit hook'lu otuz satırlık bir shell script yeter. Başka yerde kullanmadığınız bir framework'ü benimsemeyin.

Araç seçimi:

• Zaten projen kullanıyor musunuz (AWS CDK ekibi)? Bir AgentConfig component'i ekleyin. Yeni tooling yok.
• Dotfile için zaten chezmoi kullanıyor musunuz? .chezmoitemplates/AGENTS.md ekleyin. Yeni tooling yok.
• Hiçbiri değil mi? Shell script + CI kontrolü çıtayı geçer. Acı baş gösterirse sonra yükseltirsiniz.

Çıta: "kural drift'i CI'da fail eder." Üçü de bu çıtayı geçer.

En Düşük Ortak Payda Duvarı#

Her şey birleşmez. Birkaç şey araca özel kalır ve aksini iddia etmek ekibinizi yanıltır.

Slash komutları. .claude/commands/ Claude'a özel slash komutları barındırır. Codex, Copilot ve Cursor onları okumaz. Ekibiniz Claude slash komutu olarak /deploy üzerine bel bağlıyorsa o akış taşınmaz.

Skill'ler. Anthropic, SKILL.md spesifikasyonunu Aralık 2025'te açık standart olarak yayımladı. Nisan 2026 itibarıyla benimseme geniş: VS Code yerleşik Skills desteğiyle geliyor, GitHub Copilot'un sürümü hâlâ deneysel olarak işaretli, Cursor, Codex CLI, OpenCode ve Goose aynı SKILL.md formatını okuyor. Claude Code için yazılan bir skill, diğerlerinde çoğunlukla değişiklik gerektirmeden çalışır. Hâlâ farklı olan şey, her aracın nereye baktığı: .claude/skills/ Claude'a özel, Copilot, Cursor ve diğerleri kendi keşif yollarını tanımlıyor. Format taşınır, yerleşim henüz değil.

Yol bazlı talimatlar. Copilot glob desenli .github/instructions/*.instructions.md destekler. Cursor'da .mdc dosyalarında globs: frontmatter vardır. Claude'un kendi yol kapsamlandırması vardır. Bunlar taşınmaz. Kökteki AGENTS.md dosyasını genel tutun. Her araç kendi yol kapsamlandırmasını kullansın.

Duvar budur. Kabul edin, AGENTS.md dosyanızda belgeleyin ve yolunuza devam edin. Tam taşınabilirlik olduğunu sanan bir ekip, bunu zorlamaya çalışırken bir hafta kaybeder.

Bu Yazıyı Uygulamama Sebepleri#

Post'un dürüst versiyonu kendi hedef kitlesinin sınırlarını da kabul eder. Aşağıdakilerden biri durumunuzu tanımlıyorsa okumayı bırakın, tek bir araç seçin.

Tek-satıcı bir enterprise organizasyonsunuz. Procurement Copilot'u seçti. Güvenlik tek satıcıyı onayladı. Onboarding dokümanı tek bir install script'i gösteriyor. Bu dünyada symlink ve @-import size maintenance yükünden başka bir şey kazandırmaz. Tek bir copilot-instructions.md dosyası tüm işi görür.

Regulated bir ortamdasınız ve AI erişimi denetleniyor. SOC 2, ISO 27001 ve HIPAA denetçileri AI destekli kod üretimi için tek-satıcı iz ister — kim, ne zaman, hangi system prompt'uyla hangi koda baktı. Multi-vendor AI-at-code-time bu izi karmaşıklaştırır. Bir tane seçin, belgeleyin, devam edin.

Tek kişisiniz. Tek kişilik bir repoda drift problemi yoktur. Tek başına CLAUDE.md veya AGENTS.md yeter. İkinci katkıcı geldiğinde tekrar bakarsınız.

AI kodlama aracınızı henüz yeni benimsediniz. Sahip olmadığınız bir araç filosu için altyapı kurmayın. Bir araçla başlayın. Symlink'ler, ekibinizden birinin Cursor açtığı gün ilginç hale gelir.

Post'un hakkını verdiği yerler: açık kaynak repoları (maintainer'lar katkıcılara araç dayatamaz), ajanslar ve consultancy'ler (her müşteri reposu farklı bir araç stack'i dayatır), adoption'ın organik büyüdüğü mid-stage takımlar (standartlaşma artık retroaktif politika işi olur) ve araç-seçim özerkliğine bilinçli değer veren her takım.

Tek-satıcı standartlaşması geçerli bir cevap. Bu post, o cevabın geçerli olmadığı ekipler için.

Sık Karşılaşılan Tuzaklar#

Kişisel override'ları commit'lemek. CLAUDE.local.md ve .claude/settings.local.json kişisel override içindir. İlk gün .gitignore dosyasına ekleyin. Commit'lenmiş bir CLAUDE.local.md, birinin özel denemeleriyle tüm takımı kafasından karıştırır.

Copilot'un yalnızca AGENTS.md okuduğunu varsaymak. Copilot, AGENTS.md ve .github/copilot-instructions.md dosyalarını birleştirir. Tüm kuralları yalnızca AGENTS.md dosyasına koyar ve copilot-instructions.md dosyasını boş bırakırsanız, Copilot'un web PR incelemesi bağlamı kaçırabilir. Symlink çözümü bunu halleder.

Monorepo'larda iç içe AGENTS.md. OpenCode ve Copilot en yakın dosyayı okur. Claude Code ağaç boyunca birleştirir. Aynı repo, farklı kural bileşimi. Güvendiğiniz iç içe davranışı belgeleyin.

Windows'ta core.symlinks=true olmadan symlink. Hata modu sessizdir. Dosya görünür. İçeriği AGENTS.md yazan düz bir metin olarak okunur. AI aracı o tek satırı tüm kural kitabı sanır. Çözüm: herhangi bir symlink metin dosyasına dönüşmüşse başarısız olan bir CI kontrolü ekleyin (test -L CLAUDE.md).

Üçüncü aydan sonra drift. Kontrol olmadan, biri Windows'ta bozuk bir symlink'i gerçek bir AGENTS.md kopyasıyla "düzeltecektir". İki hafta sonra kopya değişir. Symlink'i zorlayan bir pre-commit hook'u veya CI job'ı ekleyin.

İzlemeye Değer Metrikler#

Her ekip burada dashboard'a ihtiyaç duymaz, ama birkaç basit kontrol çoğu drift'i yakalar:

• Bir kural değişikliği başına güncellenmesi gereken talimat dosyası sayısı. Hedef: bir.
• İlk klonlamada tercih ettiği aracı kanonik dosyayı okuyan geliştirici yüzdesi. Hedef: yüzde 100.
• Çeyrek başına drift olayları. A aracı ile B aracının aynı repoda farklı davrandığı durumlar.
• Yeni bir AI aracını repoya eklemek için gereken süre. Hedef: otuz dakikanın altı (symlink ekle, MCP config ekle, bitti).

Bu sayılar sağlıklı kaldıkça, "hepsine hükmeden tek kurulum" gerçekten hükmediyor demektir.

Sahadan İlkeler#

Mekanikler (symlink, @-import, araç-özel dizinler) depolama problemini çözer. Her gün kodlama ajanlarıyla çalışan uygulayıcıların ise içerik problemine (yani AGENTS.md dosyasında ne olmalı ve şişmesini nasıl engelleriz) dair daha net duruşları var.

Addy Osmani, spec-önce-kod disiplini savunuyor: AGENTS.md sabit kuralları ve konvansiyonları tutar, feature başına yazılan spec.md ise niyeti taşır. "Curse of Instructions" bulgusuna atıfta bulunuyor — tek bir prompt'a daha fazla gereklilik yığdıkça her bir kuralın takip oranı düşüyor, frontier modeller bile düzinelerce eş zamanlı kuralı karşılamakta zorlanıyor. Pratik üst sınır: AGENTS.md dosyasını ~200 satır altında tutun, yol-bazlı kuralları .github/instructions/*.instructions.md veya .cursor/rules/*.mdc dosyalarına taşıyın.

Simon Willison işi "yapmayı bildiğin şeyleri istiflemek" olarak çerçeveliyor — ajanın tekrar birleştirdiği bir pattern kütüphanesi, itaat ettiği bir kural kitabı değil. AGENTS.md hak ettiği değeri bilinen pattern'ları işaret ederken kazanır, aşikârı yeniden tarif ederken değil.

Geoffrey Huntley (Sourcegraph Amp) iki noktaya vuruyor: aynı anda aktif olan çok sayıda MCP aracı context window'u kirletiyor ve araç açıklamaları standart değil. Çözümü: araçları sadece onlara ihtiyaç duyulan aşamalarda devreye al — Jira MCP planlamada, GitHub MCP incelemede, diğer zamanlarda kapalı. Aynı disiplin kurallara da uygulanır: her zaman yüklü olan kök dosya küçük kalsın, yol-bazlı kurallar ağırlığı taşısın.

ruler (intellectronica/ruler, "her kodlama ajanına aynı kuralları uygular"), tek bir kural kaynağını her aracın yerli dosyasına basan küçük bir CLI. projen ve chezmoi'nin yanında, ikisinden de hafif ve amaca özel bir araç arıyorsanız iyi oturur.

Bir güvenlik notu. Kural dosyaları hem insanlar hem de ajan tarafından okunur ama ajan her karakteri okur. "Rules File Backdoor" tekniği (SC Media, 2026) kural dosyalarına görünmez Unicode enjekte ederek ajanı yönlendirir. AGENTS.md dosyasına executable code gibi davranın — kural-dosyası diff'lerinde non-ASCII veya yazdırılamayan karakterleri flag'leyen bir CI kontrolü ekleyin.

Kapanış#

2026 AI kodlama ekosistemi sessizce ortak bir örüntüye yaklaştı: kökte tek bir markdown dosyası, araca özel bir dizin ve araçlar arası katman olarak MCP. AGENTS.md en geniş kabul gören kanonik isim. Symlink ve @-import'lar diğer beklenen her dosya adına köprü kurar.

Örüntünün dürüst versiyonu duvarı kabul eder. Kurallar taşınır. MCP sunucuları (format dönüşümüyle) taşınır. Slash komutları, skill'ler ve yol bazlı talimatlar taşınmaz. AI-araç stratejinizi taşınanlar etrafında kurun ve taşınmayan parçaları belgeleyip kapsamını daraltın.

Ekibiniz hâlâ CLAUDE.md ile .cursor/rules/main.mdc arasında kural kopyalıyorsa, çözüm bir saatlik bir öğleden sonra işi. AGENTS.md dosyasını seçin, üç ln komutu çalıştırın, bir CI kontrolü ekleyin ve daha zor problemlere geçin.

Kaynaklar#

• AGENTS.md resmi spesifikasyonu - Açık standart sitesi; güncel benimseme listesi (Codex, Cursor, Copilot, Gemini CLI, Aider, OpenCode, Zed, Warp, VS Code, Devin ve daha fazlası).
• Codex AGENTS.md rehberi (OpenAI) - Codex'in AGENTS.md dosyasını nasıl okuduğuna dair OpenAI'nın resmi dokümantasyonu.
• GitHub blog: Harika bir agents.md nasıl yazılır - 2.500 repo analizinden çıkan ampirik örüntüler ve çalışan altı çekirdek bölüm.
• Claude Code memory dokümanı - CLAUDE.md hiyerarşisi, @-import, AGENTS.md yedek davranışı ve 200 satır önerisi.
• OpenCode rules dokümanı - sst/opencode'un AGENTS.md işleyişi, Claude Code uyumluluk yedeği, proje ve global kapsamlar.
• GitHub Docs: Copilot için repo özel talimatları ekleme - Resmi yol, AGENTS.md ile birleşme davranışı ve yol bazlı .github/instructions/*.instructions.md.
• Cursor Rules dokümanı - .cursor/rules/*.mdc formatı, frontmatter (description, alwaysApply, globs) ve eski .cursorrules kullanımdan kaldırma notu.
• Gemini CLI GEMINI.md dokümanı - Hiyerarşik yükleme, @file.md import sözdizimi ve /memory komutları.
• Aider conventions dokümanı - Aider'ın .aider.conf.yml üzerinden CONVENTIONS.md veya AGENTS.md yükleme şekli.
• Claude Code, Codex ve Cursor hafızasını senkron tutmak - Üç yaklaşım (symlink, @-import, işaretçi dosya) ve Windows notları.
• One AGENTS.md to Rule Them All (Kaushik Gopal) - Tek kaynak örüntüsünün uygulayıcı bakışlı özeti.
• Symlink ile AI Agent Config Paylaşmak (Rushi) - Cursor ve Claude için somut bir symlink tarifi.
• Codex, Claude, Cursor ve Copilot için Tek MCP Yapılandırması - MCP config drift'ine chezmoi ile pratik bir yaklaşım.
• projen — kod olarak config - AWS CDK ekibinin TypeScript tabanlı proje synthesizer'ı; custom Component alt sınıfları dosya üretir ve her npx projen çağrısında synthesize() çalışır.
• ruler — her kodlama ajanına aynı kuralları uygula - Tek bir kural kaynağını her ajanın yerli dosya formatına yazan küçük bir CLI; bu özel problem için projen veya chezmoi'ye daha hafif bir alternatif.
• Agents.md: AI kodlama ajanları için açık standart (Tessl) - Linux Foundation ve Agentic AI Foundation'ın standart üzerindeki gözetimine dair bağlam.