Claude Code, Cursor, Copilot, Codex için Tek Yapılandırma

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. Aşağıdaki düzen tek bir dosyayı yetkili kılar: kaynak olarak AGENTS.md, diğer araçların beklediği her dosya adı için symlink ya da @-import, araçlar arası tool katmanı için MCP. Düzen üç yerde kırılır: skill’ler, slash komutları ve Windows symlink tuzakları.

Problem#

Bir ekip Claude Code benimser, sonra yeni bir geliştirici Cursor’u tercih eder. Repo kökündeki CLAUDE.md sessiz durur, Cursor ise .cursor/rules/ klasörünü okur; biri kuralları elle kopyalar. Sonra aynı kural AGENTS.md dosyasında biraz farklı bir ifadeyle yer alır. Üç dosya birbirinden uzaklaşır ve 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.

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).

Araç	Kanonik dosya	Yedek	Araç dizini
OpenAI Codex CLI	AGENTS.md	yok	.codex/config.toml
GitHub Copilot	.github/copilot-instructions.md + AGENTS.md (birleşik)	yok	.github/instructions/*.instructions.md
Claude Code	CLAUDE.md	AGENTS.md (yalnızca CLAUDE.md yoksa)	.claude/{commands,skills} + proje kökünde .mcp.json
OpenCode (sst)	AGENTS.md	CLAUDE.md (eski uyumluluk)	~/.config/opencode/*
Cursor	.cursor/rules/*.mdc	eski .cursorrules (kullanımdan kaldırıldı)	.cursor/
Gemini CLI	GEMINI.md (hiyerarşik, .git köküne kadar yukarı yürür)	yok	~/.gemini/
Aider	CONVENTIONS.md veya AGENTS.md (config ile)	yok	.aider.conf.yml

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ı)

Symlink, @-Import veya İşaretçi Dosyalar#

Seçenek A: Symlink#

Unix’in doğal yaklaşımı. Git symlink’leri sürüm kontrolünde tutar, her editör ve CLI aracı da onları takip eder.

ln -sfn AGENTS.md CLAUDE.md
ln -sfn ../AGENTS.md .github/copilot-instructions.md
mkdir -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 yüzden bu iki aracı symlink veya işaretçi dosyaya yönlendirin.

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

En kaba ama en taşınabilir seçenek: LLM’in bu satıra uyması olasılıksaldır, işaretçi zaman zaman görmezden gelinir ve bunu size haber veren bir şey yoktur. Tek kişilik bir repo için yeter; uyumluluk gerektiren bir repo için yetmez. Tek satırlık bir CLAUDE.md:

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

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.

MCP Katmanı#

MCP (Model Context Protocol), araç katmanındaki tek gerçek araçlar arası sözleşmedir. Kurallar bu katmanın dışında kalır. Her ciddi asistan MCP sunucu tanımlarını okur ama her biri farklı bir yoldan ve farklı bir formatta:

• 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. Şimdilik reponuz gerçek MCP sunucuları çalıştırıyorsa dört config dosyasına bütçe ayırın.

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, kuralın uygulanmasını iyi niyete değil CI’ya bağlar.

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

projen: TypeScript synth#

projen (yeni sekmede açılır) 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.ts
import { 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 dünyasının aracı. Ekibiniz zaten package.json, tsconfig ve GitHub Actions’ı projen ile sentezlemiyorsa, sadece AI config için benimseme maliyet olarak fazla. Kazanç tüm config’i tek yerden sentezlemekten geliyor; AI dosyaları bunun küçük bir dilimi.

Kullanıcı Bazlı Config için chezmoi#

chezmoi (yeni sekmede açılır) 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. İhtiyaç doğarsa sonra yükseltirsiniz.

Taşınabilirliğin Bittiği Yer#

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; bu yüzden format taşınıyor, yerleşim konvansiyonu henüz taşınmıyor.

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.

Bu Kurulumu Gerektirmeyen Durumlar#

Her repo bu düzene ihtiyaç duymaz. Aşağıdakilerden biri durumunuzu tanımlıyorsa tek bir araç seçin ve düzeni atlayın.

Tek satıcılı kurumsal ekipler bütün bunu atlar. Satın alma birimi Copilot’u seçti, güvenlik tek satıcıyı onayladı, onboarding dokümanı tek bir kurulum script’ini gösteriyor. Symlink ve @-import burada bakım yükünden başka bir şey kazandırmaz: tek bir copilot-instructions.md dosyası tüm işi görür.

Denetime tabi ortamlar farklı bir gerekçeyle aynı cevaba varır. SOC 2, ISO 27001 ve HIPAA denetçileri AI destekli kod üretimi için tek satıcılı bir iz ister: kim, ne zaman, hangi system prompt’uyla hangi koda baktı. Kod yazma anında birden fazla satıcı kullanmak bu izi karmaşıklaştırır, bu yüzden tek satıcı seçip belgelemek işin tamamıdır.

Tek kişilik repolar ve ilk kez araç benimseyen ekipler aynı mantığa tabidir. Tek kişilik bir repoda henüz drift problemi yoktur: tek başına CLAUDE.md veya AGENTS.md yeter, ikinci katkıcı gelene kadar kurulacak bir şey de yoktur. İlk AI kodlama aracını benimseyen bir ekip de aynı noktadadır: sahip olmadığınız bir araç filosu için altyapı kurmayın. Symlink’ler, ekibinizden biri Cursor açarken geri kalanı Claude Code kullanırken ilginç hale gelir.

Düzenin hakkını verdiği yerler: açık kaynak repoları (maintainer’lar katkıcılara araç dayatamaz), ajanslar ve danışmanlık şirketleri (her müşteri reposu farklı bir araç setiyle gelir), benimsemenin organik büyüdüğü orta ölçekli ekipler (standartlaşma artık geriye dönük bir politika işi olur) ve araç seçim özerkliğine bilinçli değer veren her ekip.

Drift’in Geri Sızdığı Yerler#

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 ekibin kafasını 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 yerinde görünür, içeriği AGENTS.md yazan düz bir metin olarak okunur ve 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.
• Tercih ettiği araç ilk klonlamada kanonik dosyayı okuyan geliştiricilerin 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).

Sahadan Notlar#

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 disiplinini (yeni sekmede açılır) 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” (yeni sekmede açılır) 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 ederek kazanır; aşikârı yeniden tarif etmek yalnızca satır sayısını artırır.

Geoffrey Huntley (Sourcegraph Amp (yeni sekmede açılır)) iki noktanın altını çiziyor: 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 (yeni sekmede açılır)), 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 (yeni sekmede açılır)) kural dosyalarına görünmez Unicode enjekte ederek ajanı yönlendirir. AGENTS.md dosyasına çalıştırılabilir kod gibi davranın; kural dosyası diff’lerinde non-ASCII veya yazdırılamayan karakterleri işaretleyen bir CI kontrolü ekleyin.

Kapanış#

Düzen, birden fazla AI aracı aynı kuralları okumak zorunda kaldığı sürece kurulumuna değer. Politika tek satıcıyı belirlediği an düzeni bırakın; hiçbir zaman taşınmayan parçaları (slash komutları, skill’ler, yol bazlı talimatlar) her araç için ayrı ayrı belgeleyip kapsamını daraltın.

Ekibiniz hâlâ CLAUDE.md ile .cursor/rules/main.mdc arasında kural kopyalıyorsa, çözüm yaklaşık bir saat sürer: AGENTS.md dosyasını seçin, üç symlink’i ekleyin ve drift olduğunda başarısız olan bir CI kontrolü ekleyin.

Kaynaklar#

• AGENTS.md resmi spesifikasyonu (yeni sekmede açılır) - 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) (yeni sekmede açılır) - 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 (yeni sekmede açılır) - 2.500 repo analizinden çıkan ampirik örüntüler ve çalışan altı çekirdek bölüm.
• Claude Code memory dokümanı (yeni sekmede açılır) - CLAUDE.md hiyerarşisi, @-import, AGENTS.md yedek davranışı ve 200 satır önerisi.
• OpenCode rules dokümanı (yeni sekmede açılır) - 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 (yeni sekmede açılır) - Resmi yol, AGENTS.md ile birleşme davranışı ve yol bazlı .github/instructions/*.instructions.md.
• Cursor Rules dokümanı (yeni sekmede açılır) - .cursor/rules/*.mdc formatı, frontmatter (description, alwaysApply, globs) ve eski .cursorrules kullanımdan kaldırma notu.
• Gemini CLI GEMINI.md dokümanı (yeni sekmede açılır) - Hiyerarşik yükleme, @file.md import sözdizimi ve /memory komutları.
• Aider conventions dokümanı (yeni sekmede açılır) - Aider’ın .aider.conf.yml üzerinden CONVENTIONS.md veya AGENTS.md yükleme şekli.
• Claude Code, Codex ve Cursor hafızasını senkron tutmak (yeni sekmede açılır) - Üç yaklaşım (symlink, @-import, işaretçi dosya) ve Windows notları.
• One AGENTS.md to Rule Them All (Kaushik Gopal) (yeni sekmede açılır) - Tek kaynak örüntüsünün uygulayıcı bakışlı özeti.
• Symlink ile AI Agent Config Paylaşmak (Rushi) (yeni sekmede açılır) - Cursor ve Claude için somut bir symlink tarifi.
• Codex, Claude, Cursor ve Copilot için Tek MCP Yapılandırması (yeni sekmede açılır) - MCP config drift’ine chezmoi ile pratik bir yaklaşım.
• projen: kod olarak config (yeni sekmede açılır) - 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 (yeni sekmede açılır) - 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) (yeni sekmede açılır) - Linux Foundation ve Agentic AI Foundation’ın standart üzerindeki gözetimine dair bağlam.