Sorun: AI Neden Kod Yazarken Hep Aynı Yerden Tökezliyor

Cursor, Windsurf veya Claude Code ile proje geliştiren hemen herkes aynı çöküşü yaşıyor: AI bir paragraf kod üretiyor, kopyalayıp yapıştırıyorsun — derleme hata veriyor, testler kırmızı yanıyor, bağımlılıklar yanlış klasöre kuruluyor. Sorun AI’ın zekâsında değil; senin projenin “görgü kurallarını” bilmemesinde.

AGENTS.md, proje kök dizinine konan ve AI’a nasıl derleyeceğini, nasıl test edeceğini, hangi kurallara uyacağını söyleyen bir Markdown dosyası. README.md insanlar için yazılır: proje tanıtımı, katkı rehberi, marka hikâyesiyle doludur. AI bu içeriği okuduğunda, tıpkı işe yeni başlayan birine şirket broşürünü tutuşturup “hemen kod yaz” demek gibi oluyor — şirketin ne yaptığını biliyor ama derleme komutunu, testin nasıl çalıştığını, ESLint kurallarını bilmiyor. Sonuç: her seferinde sohbette aynı düzeltmeleri tekrarlıyorsun: “pnpm kullan, npm değil”, “testler packages/web altında”, “lint çalıştırmayı unutma”. Bu düzeltmeleri yüz kere tekrarlasan da proje yine dağınık kalıyor.

Freelance senaryosundaki kayıp daha da somut: Next.js + Prisma ile bir dış kaynak iş aldın, Cursor ile hızlandırmaya çalışıyorsun, ama AI npm install ile bağımlılıkları kuruyor, pnpm’in workspace ayarı çöp oluyor; veritabanı şemasının hangi dizinde olduğunu bilmiyor, ürettiği migration dosyası doğrudan hata veriyor. Müşteri teslimat için baskı yapıyor, sen AI’ın ürettiği kodu debug etmek için üç saat harcıyorsun — kazandığın para boğazına düğümleniyor.

AI’ın proje kurallarını bilememesinin 3 klasik çöküş senaryosu: ① Yanlış paket yöneticisi (proje pnpm kullanıyor, AI varsayılan olarak npm install çalıştırıyor), bağımlılıklar yanlış yere kuruluyor, workspace ayarı bozuluyor; ② Test girişi bulunamıyor (proje testleri packages/web altında, AI kök dizinde pnpm test çalıştırıyor, “test dosyası bulunamadı” hatası alıyor); ③ Tutarsız kod stili (proje ESLint + Prettier kullanıyor, AI’ın ürettiği kodda girintiler ve tırnaklar yanlış, CI doğrudan kırılıyor).

Fırsat: AGENTS.md “İnsan Dokümanı” ile “Makine Dokümanını” Birbirinden Ayırıyor

GitHub’daki açık kaynak proje AGENTS.md (depo adresi github.com/agentsmd/agents.md, 26 Ağustos 2026 itibarıyla yaklaşık 24.000 yıldız) tam olarak bu sorunu çözüyor. Çekirdek fikri son derece basit: proje kök dizinine, AI’a nasıl derleyeceğini, nasıl test edeceğini, hangi kod stilini izleyeceğini söyleyen bir Markdown dosyası koy.

Bu dosya README’nin yerine geçmiyor, onu tamamlıyor. README insan katkıcılara hizmet eder, AGENTS.md yapay zekâ ajanlarına. İkisinin görev alanı net, birbirine karışmıyor.

Kaynak gönderiye göre AGENTS.md on binlerce açık kaynak proje tarafından benimsenmiş (kesin rakam doğrulanmadı); VS Code, Cursor, Windsurf, Aider ve GitHub Copilot gibi başlıca AI kodlama araçlarının tümü destekliyor (doğrulandı); topluluk geri bildirimlerine göre OpenAI Codex ve Google Jules da destek sunuyor (⚠️ doğrulanmadı). Şimdi öğrenmezsen, AI ile lehçe lehçe konuşmaya devam edersin.

Yol Bir: Elle, Minimal Kullanılabilir Bir AGENTS.md Yaz

Maliyet çok düşük. Yeni dosya aç, üç paragraf yaz, yeter.

Ön bilgi: Aşağıdaki örneklerde pnpm (npm’den daha az disk yer kaplar, monorepo workspace destekler), turbo (monorepo görev orkestrasyon aracı) ve --filter parametresi (yalnızca belirli bir alt pakete etki eder, tüm depoya dokunmaz) kullanılıyor.

Birinci paragraf “Dev environment tips”: AI’a hangi paket yöneticisinin kullanıldığını, alt paketlere nasıl geçileceğini, yeni modülün nasıl oluşturulacağını söyle. Resmi örnekteki gibi:

• pnpm dlx turbo run where <project_name> — ls ile tek tek aramadan doğrudan ilgili alt paketin dizinine atla
• pnpm install --filter <project_name> — Yalnızca bir alt paketin bağımlılıklarını kur, tüm monorepo’ya dokunma
• pnpm create vite@latest <project_name> -- --template react-ts — TypeScript denetimli yeni bir React + Vite alt paketi oluştur

Bu komutları AI kendi başına tahmin edemez, ama sen yazdığında harfiyen uygular.

İkinci paragraf “Testing instructions”: AI’a testlerin nasıl çalıştırılacağını, CI planının nerede olduğunu, commit öncesi hangi kontrollerin zorunlu olduğunu söyle. Resmi örnek şunları içeriyor:

• pnpm turbo run test --filter <project_name> — Belirtilen alt paketin tüm kontrollerini çalıştır
• pnpm vitest run -t "<test name>" — Yalnızca adı eşleşen tek bir testi çalıştır
• “Fix any test or type errors until the whole suite is green” — Tüm suite yeşil olana kadar durma
• “Add or update tests for the code you change, even if nobody asked” — Bu son cümle kritik; yazmazsan AI sık sık test yazmadan geçer

Üçüncü paragraf “PR instructions”: Commit başlığı formatını standartlaştır, lint ve test çalıştırmayı zorunlu kıl. Resmi örnek: Title format: [<project_name>] <Title> ve “Always run pnpm lint and pnpm test before committing”.

Bu üç paragraf toplam 50 satırı bulmuyor, ama AI’ın ürettiği kodun ilk seferde geçme oranını ciddi şekilde yukarı çekiyor (topluluk geri bildirimine göre, kesin rakam doğrulanmadı).

Yol İki: Büyük Monorepo’larda İç İçe Kullanım

Eğer kurumsal düzeyde bir proje üzerinde çalışıyorsan ve kod tabanı monorepo yapısındaysa (örneğin ön yüz, arka yüz ve paylaşılan kod için her biri ayrı alt dizinde olmak üzere birden fazla ilgili proje tek bir Git deposunda yönetiliyorsa), tek bir AGENTS.md yetmez. AGENTS.md iç içe kullanımı destekliyor: her alt dizine kendi AGENTS.md dosyasını koyarsın, AI otomatik olarak “en yakın olanı” okur.

Pratik uygulama: Kök dizindeki AGENTS.md’ye genel kuralları yaz (paket yöneticisi, CI akışı, güvenlik notları), ardından packages/web/, packages/api/, packages/shared/ altına her biri için ayrı dosya koy; her birine o alt pakete özgü derleme komutlarını, test girişini, özel bağımlılıkları yaz. Örneğin ön yüz paketinde “bileşen kütüphanesi shadcn, stil Tailwind, ikonlar lucide-react” yazılmalı; arka yüz paketinde “veritabanı migration’ları Prisma ile, API rotaları src/routes altında, kimlik doğrulama JWT ile” yazılmalı.

AI alt dizinde çalışırken otomatik olarak en yakın AGENTS.md’yi yükler, kök dizindekinden daha yüksek önceliğe sahiptir. Bu, aynı projede ön yüz AI asistanı ile arka yüz AI asistanının tamamen farklı talimatlar alması, birbirine karışmaması demek.

Yol Üç: Bunu Freelance İşlerinde Farklılaşma Satış Noktasına Dönüştür

AI ile freelance iş piyasası artık kırmızı okyanus — herkes Cursor kullanıyor ama teslimat kalitesi çok değişken. Teklifine “Bu projede AGENTS.md standart dokümanı yapılandırıldı, AI destekli geliştirme proje kurallarına uygun ilerliyor” diye tek bir cümle yazarsan, kazanma oranın “ben AI ile kod yazıyorum” diyen rakiplerden belirgin şekilde yüksek olur.

Somut taktik: İşi aldıktan sonra ilk 30 dakikayı müşterinin proje yapısını okumaya ayır, ardından özelleştirilmiş bir AGENTS.md yaz. Bu dokümanın kendisi teslimatın bir parçası — müşteri ileride kendi AI’ıyla kodu sürdürürken de işine yarar.

AGENTS.md yapılandırma hizmetini ayrı bir kalem olarak fiyatlandır (referans fiyat, yerel pazara göre ayarlanmalı): Temel paket 500 TL (tek dosya yapılandırma + bir README açıklaması), Kurumsal paket 3.000 TL (monorepo iç içe yapı + güvenlik kuralları + ekip eğitimi). Teslimat kapsamı: ① Özelleştirilmiş AGENTS.md dosyası ② 30 gün WhatsApp/Telegram üzerinden soru-cevap desteği ③ 10 dakikalık bir ekran kaydı eğitimi. Uygun senaryo: Müşterinin Cursor/Windsurf aboneliği var ama verim alamıyor. Uygun değil: Müşteri hâlâ tamamen elle geliştirme yapıyor, AI aracı henüz devreye almamış.

Vaka: AGENTS.md’nin Uyumluluk Hendeği

AGENTS.md MIT lisansıyla yayımlanıyor (kaynak doğrulandı), topluluk tarafından sürdürülüyor (kesin yönetişim yapısı doğrulanmadı), resmi sitesi agents.md.

Uyumluluk, en büyük hendeği: VS Code, Cursor, Windsurf, Aider ve GitHub Copilot’un AGENTS.md okumayı desteklediği doğrulandı; topluluk geri bildirimine göre OpenAI Codex, Claude Code, Gemini CLI ve Google Jules da destek sunuyor (⚠️ doğrulanmadı). Bu, tek bir dosya yazıp tüm yaygın AI asistanlarında kullanabileceğin anlamına geliyor — her araç için ayrı ayrı yapılandırma yazmana gerek yok.

Diğer çözümlerle kısa bir karşılaştırma: Cursor’ın .cursorrules dosyası yalnızca Cursor’da çalışır, Windsurf’a geçtiğinde geçersiz olur; Claude Code’un CLAUDE.md‘si yalnızca Claude’a hizmet eder; GitHub Copilot’ın talimat sistemi ise bambaşka bir yapı. AGENTS.md’nin “bir kere yaz, her yerde çalıştır” özelliği, kısa vadede bu kadar yaygın benimsenmesinin asıl sebebi.

Araç geçiş maliyeti sıfır. Bugün Cursor kullanıyorsun, yarın Windsurf’a geçtin, AGENTS.md doğrudan taşınıyor, kuralları yeniden yazmana gerek yok.

Harekete Geç: Bu Akşam Projene Bir Makine Kılavuzu Ekle

5 dakikalık aksiyon listesi: ① Proje kök dizinini aç ② AGENTS.md adında yeni dosya oluştur ③ Resmi şablonu kopyala (github.com/agentsmd/agents.md) ④ Üç komutu yaz (derleme, test, lint) ⑤ Bir sonraki AI kod yazdırma görevinde sonucu gözlemle.

Monorepo kullanıyorsan bu akşam ekstra 20 dakika ayırıp her alt pakete iç içe bir yapılandırma ekle. Yarın işe başladığında AI’ın ürettiği kodun artık seni sürekli düzeltmene gerek kalmadığını fark edeceksin.

AGENTS.md şu an en yüksek getiriyi sunan AI kodlama yapılandırması — 30 dakikalık yatırım, ayda birkaç saatlik debug süresini geri getiriyor.