Bağlam Mühendisliği Rehberi: AGENTS.md, .cursorrules, CLAUDE.md

🎯 Giriş: Prompt Mühendisliği Yeterli Değil, Bağlam Mühendisliği Zamanı

Hazırsan başlayalım 🚀

Ben de yaşadım: her yeni özellik için yüzlerce token harcayıp, aynı açıklamaları tekrar tekrar yazdım.

Prompt yazıyorsun, model cevap veriyor.
Sonra bir hata çıkıyor, tekrar prompt düzeltiyorsun.
Halüsinasyonlar geliyor, token faturası artıyor ❗️

Prompt mühendisliği güzel bir başlangıç ama sınırları var:

Her istekte baştan başlıyorsun.
Projeye özel bilgiler (mimari, kod standartları, domain kuralları) her seferinde tekrar ediliyor.
Uzun konuşmalarda model “unutuyor” ve tutarsız cevaplar veriyor.

İşte tam burada Bağlam Mühendisliği (Context Engineering) devreye giriyor 🎯

Peki ya kod asistanına projenin kalbini bir kez anlatıp, her seferinde tekrarlamamak mümkün olsaydı?

Kısa cevap: Evet, mümkün.
Uzun cevap: Bu bölümde birlikte keşfedeceğiz 👇

🔁 Bağlam Mühendisliği Nedir ve Neden Farklı?

Hazırsan başlayalım. Bağlam Mühendisliği (Context Engineering), kısaca: AI'ya projeye özel bilgiyi — mimari, kod standartları, domain kuralları, hatta "nasıl düşündüğümüz" — kalıcı, yapılandırılmış ve sürdürülebilir bir şekilde vermenin sistematik yolu 🎯

Prompt mühendisliğiyle karıştırma. İkisi benzer gözükse de aradaki fark geçici vs kalıcı meselesi.

🆚 Prompt Mühendisliği vs Bağlam Mühendisliği

Özellik	Prompt Mühendisliği	Bağlam Mühendisliği
Ömür	Anlık, o sohbet için	Kalıcı, proje yaşam boyu
Tekrar	Her sohbette yeniden yazılır	Bir kez tanımlanır, her yerde kullanılır
Merkezileşme	Dağınık, herkes kendi promptunu yazar	Merkezi repo/dosya, ekibi ortak payda
Sürüklenebilirlik	Zor, kopyala-yapıştır loopu	Kolay, dosya referansı yeterli
Bakım	Yok denecek kadar	Versiyonlanabilir, review edilebilir

Ne oluyor burada? Prompt mühendisliği "şu an ne söylemeli?" sorusunu cevaplar. Bağlam mühendisliği ise "AI her zaman ne biliyor olmalı?" sorusunu cevaplar 🛠

🪟 Context Window (Bağlam Penceresi) Kısıtlaması

LLM'lerin bir context window'u var — bir seferde işleyebileceği token limiti. Büyük projelerde:

Tüm kodu, dokümanları, kuralları her mesajda göndermek mümkün değil ❌
Hatta mümkün olsa da maliyetli ve yavaş ❌

İşte Bağlam Mühendisliği bu noktada devreye girer: sıkıştırılmış, yüksek yoğunlukta bilgi hazırlarsın. AI "her şeyi" bilmek zorunda kalmaz; doğru şeyi bilir ✅

Örnek: 5000 satırlık bir mimari doküman yerine; "Mimari: Clean Architecture, Domain-driven, Event-driven async iletişim" satırı yeterli olabilir. Bu bilgi yoğunluğu kazandırırsın.

💡 Neden Şimdi?

Çünkü artık kod yazan AI değil, projeyi anlayan AI istiyoruz. Prompt ile "senior dev gibi davran" demek yetmez; ona senin senior dev'ının bildiği her şeyi sistematik vermelisin.

Hadi bir sonraki bölümde bunu nasıl dosyalara döktüğümüze bakalım 🚀

❗️ Sorun: Token Maliyeti, Halüsinasyon ve Tutarsız Kod Stili

Arkadaşlar, hadi dürüst olalım. AI asistanları harika, ama günlük hayatta bizi deli eden üç acı nokta var. Ben de bu yüzden kod review sırasında birden fazla kez sinir oldum, kabul ediyorum 😅

1️⃣ Token Maliyeti: Her Sohbette Tekrar Tekrar Anlatmak

Yeni bir chat başlattığınızda, AI'ın projenizi tanıması için şunu yazıyorsunuz:

"Bizim projede FastAPI kullanıyoruz, PostgreSQL var, SQLAlchemy ORM, Pydantic v2 modelleri, pytest testleri, ruff linting..."

Ve bunu her yeni sohbette tekrar ediyorsunuz. Bir proje için günde 10-15 sohbet açarsanız, sadece context için binlerce token yakıyorsunuz. Para para değil, zaman ve odak kaybı.

Ne oluyor burada?

Context penceresi doluyor, asıl soru için yer kalmıyor 😤
Küçük bir değişiklik için bile "projeyi tanı" macerasına girmek zorunda kalıyorsunuz

2️⃣ Halüsinasyon: Olmayan Servisleri Uydurma

AI, projenizdeki UserService sınıfını bilmiyorsa ne yapar? Uydurur. 🎭

# AI'ın uydurduğu kod — projenizde BÖYLE BİR ŞEY YOK
class UserService:
    def __init__(self, db: AsyncSession):
        self.db = db
    
    async def get_user_with_posts(self, user_id: int):
        # Bu metot hiç yok, AI hayal etti
        return await self.db.execute(
            select(User).options(selectinload(User.posts)).where(User.id == user_id)
        )

Siz bunu kopyalayıp yapıştırıyorsunuz, testler kırmızı dönüyor, sonra "yok böyle bir metot" diyerek tekrar soruyorsunuz. Döngü bozulmuyor.

Neden oluyor?
AI, projenizin gerçek şemasını, modüllerini, naming convention'larını bilmiyor. Sadece genel Python/FastAPI bilgisiyle "mantıklı gelen" kodu üretiyor.

3️⃣ Stil Tutarsızlığı: Her PR Farklı Bir Dil Gibi

Bu da benim en çok sinir olduğum kısım ⛔

PR #1	PR #2
`snake_case` fonksiyonlar	`camelCase` fonksiyonlar
Type hint'ler yok	Type hint'ler her yerde
`async def` kullanılmış	`def` + `run_in_executor` karışık
Docstring Google style	Docstring NumPy style

Hepsini aynı AI asistanı yazdı. Ama her seferinde context farklı, prompt farklı, çıktı farklı.

Sonuç?
Code review'de şu cümleleri kuruyorsunuz:

"Burada neden camelCase kullanılmış, proje standardı snake_case"
"Type hint nerede?"
"Bu docstring formatı yanlış"

Ve siz kod mantığını değil, stil hatalarını review ediyorsunuz. İşin asli kısmı kaçırıyorsunuz 😞

Özetle: Bu Üç Sorun Birbirini Besliyor

Sorun	Etkisi
Token maliyeti	Her chat'te context anlatmak → yavaş, pahalı
Halüsinasyon	Projeyi bilmemek → yanlış kod → debug zamanı
Stil tutarsızlığı	Her output farklı → review yükü → standart sapma

Ben de bu döngüden sıkıldım. "AI'a projemizi bir kere anlatsam, o da her seferinde hatırlasa, bizim stilimize uygun kod üretsin" diye düşündüm.

Hadi çözüme geçelim 🛠️

🛠 Çözüm: Yapılandırılmış Bağlam Dosyaları (AGENTS.md, .cursorrules, CLAUDE.md)

Hazırsan şimdi asıl çözüme geçelim 🎯

Yukarıdaki sorunları çözmek için üç popüler standart çıktı önümüze. Hepsi aynı fikirle çalışıyor: projenin kök dizinine bir Markdown dosyası koyuyorsun, araç o dosyayı okuyup bağlamını (context) anlıyor.

Hadi tek tek tanıyalım:

1. `AGENTS.md` — Araçtan bağımsız, açık standart 🌐

Kim okur? Cursor, Windsurf, Cline, Roo Code, VS Code eklentileri… kısaca çoğu modern AI kod asistanı
Ne için? Proje genelinde geçerli kuralları, mimari kararları, kod stilini, test stratejisini, hatta "nasıl PR açılır" bilgisini tek yerde toplar
Avantajı: Bir kez yazarsın, her yerde çalışır. Takım arkadaşın Cursor kullanıyor, sen Windsurf — ikiniz de aynı AGENTS.md'i okursunuz ✅

2. `.cursorrules` — Cursor IDE'ye özel 🎯

Kim okur? Sadece Cursor (ve Cursor tabanlı forklar)
Ne için? Cursor'a "benim projemde şu kurallar geçerli" diyorsun. Özellikle Cursor'un Composer ve Chat modları bu dosyayı baz alıyor
Farkı: Cursor'a özel komutlar, kısayollar, cmd+ tetikleyicileri gibi detayları da burada tutabilirsin

3. `CLAUDE.md` — Claude Code'a özel 🤖

Kim okur? Claude Code (Anthropic'in terminal tabanlı coding agent'ı)
Ne için? Claude Code başlarken proje kökündeki CLAUDE.md'yi otomatik okur. Proje yapısı, build/test komutları, kod standartları, hatta "hang dosyayı değiştirmeden önce bana sor" talimatları verirsin
İpucu: claude init komutu sana bir şablon CLAUDE.md bile üretiyor 🛠

"Peki, hangisini seçmeliyim?" diye sorarsan… 🤔

Hepsini de kullan! ❗️

Dosyalar birbirini ezmez, uyumlu çalışırlar. Düşün şöyle:

Dosya	Kapsam	Örnek İçerik
`AGENTS.md`	Genel, takım çapında	Mimari, naming convention, PR süreci
`.cursorrules`	Cursor'a özel	Composer shortcut'ları, Cursor-specific talimatlar
`CLAUDE.md`	Claude Code'a özel	Terminal komutları, test nasıl çalıştırılır, hook'lar

Pratik strateji:

Ortak kuralları → AGENTS.md'ye yaz (herkes faydalanır)
Cursor'a özel detayları → .cursorrules'a ekle
Claude Code için terminal odaklı talimatları → CLAUDE.md'ye koy

Böylece:

Takım arkadaşın Cursor açıp .cursorrules sayesinde anında üretken oluyor 🚀
Sen terminalde claude yazıyorsun, CLAUDE.md sayesinde context'in tam 🎯
Yeni gelen bir üye Windsurf/Cline/VS Code açıyor, AGENTS.md ile anında onboard oluyor ✅

Küçük bir pro tip 💡

AGENTS.md'ni tek kaynak (single source of truth) yap, diğer iki dosyadan ona referans ver:

# .cursorrules
@AGENTS.md dosyasındaki genel kurallar geçerlidir.
Ek olarak Cursor için şu shortcut'lar...

# CLAUDE.md
Proje standartları için AGENTS.md bakınız.
Claude Code için özel talimatlar:
- Test: `pnpm test:unit`
- Lint: `pnpm lint`

Bu sayede bakım tek yerden, her araç kendi ihtiyacını karşılıyor 🛠

Hadi şimdi bunlardan birini (veya hepsini) projenize ekleyelim mi? 👇

🔁 Derinlemesine: AGENTS.md Yapısı ve Örnek

Hazırsan AGENTS.md’nin nasıl bir iskelet oluşturması gerektiğini tek tek görelim.
Her proje farklı ama bu beş temel bölüm hemen hemen her yerde işinizi görür 🎯

Önerilen Bölümler

Proje Özeti – Ne yaptığınızı, kimler için, hangi hedeflerle geliştirdiğinizi 2‑3 cümleyle anlatın.
Mimari Kararlar – Monolitik mi, mikro‑servis mi? Veri tabanı seçimi, iletişim protokolleri (REST, gRPC, message queue) gibi büyük resim kararları.
Kod Standartları – Naming convention, lint/kontrol araçları, import sıralaması, dosya yapısı.
Test Stratejisi – Unit, integration, e2e test türleri; hangi araçlar (Jest, PyTest, Cypress…) ve CI/CD’de nasıl çalıştırılacak.
Yaygın Hatalar & İpuçları – Takıldığınız yerler, “bu hatayı yapma” listesi, performans püf noktaları.

Şimdi gelin bir gerçek proje için nasıl yazılır ona bakalım 👇

Aşağıdaki şablonu kopyalayıp projenize göre düzenleyin.
Kendi teknoloji yığınına, modül yapısına ve takım alışkanlıklarına göre alanları doldurun ✅

# AGENTS.md – Proje Şablonu

## 📌 Proje Özeti
**Proje Adı:** MyShop – E‑ticaret Mikro‑Servis Platformu  
**Amaç:** Kullanıcıların ürün keşfi, sepet yönetimi ve ödeme akışını sağlayan, ölçeklenebilir bir backend sunmak.  
**Hedef Kitle:** B2C müşteriler, mobil ve web frontend takımları.  

## 🏗 Mimari Kararlar
- **Mimari:** Mikro‑servis (Domain‑Driven Design)  
- **İletişim:** REST API (sync) + RabbitMQ (async eventler)  
- **Veri Depolama:** PostgreSQL (transactional), Redis (cache), Elasticsearch (arama)  
- **Orkestrasyon:** Kubernetes (Helm chart’lar)  
- **Güvenlik:** OAuth2 + JWT, mTLS arası servis iletişimi  

## 🧱 Kod Standartları
- **Dil:** Go 1.22, TypeScript 5 (frontend)  
- **Lint/Format:** `golangci-lint`, `eslint + prettier` (pre‑commit hook ile)  
- **Naming Convention:**  
  - Paketler: `snake_case`  
  - Dosyalar: `kebab-case`  
  - Interface’ler: `PascalCase` + `I` öneki (`IUserService`)  
- **Import Sıralaması:** Std‑lib → 3rd‑party → internal → relative  
- **Modül Yapısı:**

cmd/ # entry points internal/ domain/ # entity, repository interfaces usecase/ # business logic adapter/ # http, grpc, message handlers pkg/ # shared utilities


## 🧪 Test Stratejisi
| Test Türü | Araç | Çalıştırma Komutu | Kapsam |
|-----------|------|-------------------|--------|
| Unit      | `go test ./...` / `jest` | `make test-unit` | Her usecase & adapter |
| Integration | `go test -tags=integration` / `cypress run` | `make test-int` | DB, MQ, external API mock’ları |
| E2E       | `cypress` | `make test-e2e` | Critical user flows (checkout, login) |
| Contract  | `pact` | `make test-contract` | Servis arası sözleşmeler |

**CI/CD:** GitHub Actions → `test` job → `build` → `deploy` (ArgoCD)

## ⚠️ Yaygın Hatalar & İpuçları
- **❌** `context.Background()` üretimde kullanmayın – her request için `r.Context()` geçirin.  
- **❌** Global `sync.Mutex` yerine **channel** tabanlı koordinasyon tercih edin.  
- **✅** Redis cache key’lerine **prefix** ekleyin (`myshop:product:{id}`) – namespace kirliliğini önler.  
- **✅** Migration dosyalarını **numaralandırın** (`001_init_schema.up.sql`) ve **down** script’ini mutlaka yazın.  
- **💡** Loglarda `trace_id` ekleyin (OpenTelemetry) – dağıtık tracing kolaylaşır.  

---

> **Not:** Bu dosya **canlı bir belge** olmalı. Yeni bir servis eklendiğinde, bir kural değiştiğinde veya bir hata tekrarlandığında hemen güncelleyin. Böylece yeni gelen her takım arkadaşı “**nereden başlasam?**” diye sormak zorunda kalmaz 🚀

---

##  🔁 Derinlemesine: Cursor IDE İçin .cursorrules Dosyası

Hazırsan Cursor'ın **Rules for AI** özelliğinin kalbi olan `.cursorrules` dosyasına dalalım 🎯

### Ne İşe Yarar Bu Dosya?

Kısaca: **Cursor'ın kod yazarken hangi kurallara uymasını istiyorsan**, onları merkezi bir yerde tanımlarsın. Artık her sohbette "TypeScript kullan, functional component yaz" demek zorunda kalmıyorsun.

### 🔍 Glob Pattern Mantığı

Dosya eşleşme (glob pattern) sayesinde **hangi dosyalara hangi kural uygulanacak** çok hassas ayarlıyorsun:

- `*.tsx` → Sadece React bileşen dosyaları
- `**/*.test.ts` → Sadece test dosyaları
- `src/components/**/*.tsx` → Sadece components klasöründeki bileşenler

### ⚙️ Kural Tipleri: Always vs Agent Requested

| Tip | Ne Zaman Çalışır? |
|-----|-------------------|
| **Always** | Dosya her açıldığında / editlendiğinde **otomatik** |
| **Agent Requested** | Sadece AI'dan **"bu dosyaya kural uygula"** denildiğinde |

**Pratik tavsiye:** Proje geneli standartlar için `Always`, özel durumlar için `Agent Requested` kullan.

---

### 🛠 Örnek `.cursorrules` Dosyası

Hadi pratik bir TypeScript/React projesi için örnek yazalım. Bunu **Cursor Ayarları → Rules** sekmesine yapıştırman yeterli ✅

```yaml
rules:
  - name: "React Bileşen Standartları"
    glob: "*.tsx"
    type: "always"
    description: "Tüm .tsx dosyaları için zorunlu React kuralları"
    rules:
      - "Sadece **functional component** kullan (class component yazma)"
      - "Props için **interface** tanımla, type alias kullanma"
      - "**Default export yapma**, named export kullan: `export const Button = ...`"
      - "Component adı dosya adıyla birebir eşleşsin (PascalCase)"
      - "Children prop'u varsa `React.ReactNode` tipinde tanımla"

  - name: "Import Sıralaması"
    glob: "*.tsx"
    type: "always"
    rules:
      - "1. React ve next/router gibi framework importları"
      - "2. Üçüncü parti kütüphaneler (lodash, date-fns...)"
      - "3. Dahili modüller (@/components, @/lib...)"
      - "4. Relative importlar (./Button, ../utils...)"
      - "Her grup arasına boş satır koy"

  - name: "State Yönetimi Tercihleri"
    glob: "*.tsx"
    type: "agent_requested"
    description: "State konusunda danışıldığında uygulanacak kurallar"
    rules:
      - "Basit local state için **useState**"
      - "Complex form state için **react-hook-form** + zod"
      - "Global/shared state için **Zustand** (Redux Toolkit kullanma)"
      - "Server state için **TanStack Query** (eski adıyla React Query)"
      - "Derived state için **useMemo** / **useCallback** eksikliği olmasın"

  - name: "Test Dosyası Kuralları"
    glob: "*.test.tsx"
    type: "always"
    rules:
      - "Test dosyası adı: `ComponentName.test.tsx`"
      - "Kütüphane: **Vitest** + **React Testing Library**"
      - "Her component için en az: render, prop değişimi, event handler testleri"
      - "Snapshot test yazma, brittle olur"

💡 Nasıl Çalışır Bu Yapı?

Cursor ayarlarını aç (Cmd/Ctrl + Shift + J → Settings)
Sol menüden Rules'e tıkla
"Add Rule" de veya doğrudan YAML/JSON yapıştır
Kaydet — artık Cursor bu kurallara otomasyonla uyar 🔁

❗️ Küçük İpuçları

YAML yazmak JSON'dan daha okunaklı (yukarıdaki gibi)
type: "always" kuralı performans etkileyebilir — sadece gerçekten her zaman gereken kurallara koy
Kural sayısı arttıkça description alanını doldur, sonradan hangi kural ne işe yarar hatırlamak zorlaşır
Takımda çalışıyorsan .cursorrules dosyasını repo'ya commit'le — herkes aynı standartta kod üretir

Özetle: .cursorrules = "Kod yazarken benim yerime kuralları hatırla" demenin en temiz yolu. Bir kez yazarsın, her sohbette sessizce uygulanır 🎯

🔁 Derinlemesine: Claude Code İçin CLAUDE.md

Hadi gelin CLAUDE.md dosyasına yakından bakalım — bu aslında AGENTS.md'nin Claude Code'a özel versiyonu. Temel mantık aynı: proje kök dizininde bir markdown dosyası koyuyorsun, claude yazıyorsun, o da başlarken bunu otomatik yüklüyor 🎯

Ne Farkı Var AGENTS.md'den?

✅ bash commands bölümü: projeye özel komutları (test, build, lint) tanımlıyorsun
✅ tool permissions: hangi dizinlerde ne yapabilir/ne yapamaz belirtiyorsun
✅ Claude Code CLI'ye özel ayarlar (model, timeout, vs.)

Örnek Bir CLAUDE.md

Şöyle bir dosya koyduk diyelim proje köküne:

# CLAUDE.md — Proje Talimatları (Claude Code)

## 🛠 Build & Test Komutları
- `npm run build` — Production build alır
- `npm run test` — Jest ile testleri çalıştırır
- `npm run lint` — ESLint + Prettier kontrolü
- `npm run typecheck` — TypeScript derleme hatalarını yakalar

## 📝 Kod Stili Kuralları
- **TypeScript strict mode** açık, `any` yasak
- Import sıralaması: external → internal → relative
- Component'ler **PascalCase**, hook'lar **useCamelCase**
- Test dosyaları: `*.test.ts` veya `*.spec.ts`

## 🔐 İzin Verilen / Yasaklı Dizinler
| Dizin | İzin | Not |
|-------|------|-----|
| `src/` | ✅ Okuma/Yazma | Ana kaynak kod |
| `tests/` | ✅ Okuma/Yazma | Test dosyaları |
| `dist/` | ❌ Yazma | Build çıktısı, elle değiştirme |
| `node_modules/` | ❌ Her şey | Dokunma |
| `.env*` | ⚠️ Sadece okuma | Secret'lar burada |

## 🛠 Yaygın Hata Çözümleri
- **TypeScript hata**: `npm run typecheck` çalıştır, hatayı oku, ilgili dosyayı düzelt
- **Test fails**: `npm run test -- --verbose` ile detaylı log al
- **Lint hatası**: `npm run lint -- --fix` ile auto-fix dene
- **Build hata**: `dist/` silip `npm run build` tekrar dene

## 🎯 Projeye Özel Komutlar
- `npm run dev:api` — Backend dev server (port 3001)
- `npm run db:migrate` — Prisma migration çalıştırır
- `npm run storybook` — Component kütüphanesi görselleştirme

Ne Oluyor Arkada Planda?

claude yazıyorsun terminalde
CLI proje kökündeki CLAUDE.md'yi bulur, okur, context'e yükler
Artık "testleri çalıştır" dersen npm run test biliyor, "build al" dersen npm run build biliyor
Dosya yazma denediğinde tabloya bakıyor: dist/ yazma → ⛔ engeller, src/ yazma → ✅ izin verir
Hata alırsan "yaygın çözümler" bölümüne atıfta bulunuyor, sana doğru komutu öneriyor

Küçük İpucu 💡

CLAUDE.md'yi repo'ya commit'le — takım arkadaşların da claude yazdığında aynı context'i alsın. Ben genelde README.md yanına koyuyorum, .gitignore'a eklemiyorum.

Özetle: AGENTS.md'nin "Claude Code editions"ı. Bash komutları + tool permissions + proje özel kuralları = sadece claude yazıyorsun, gerisi geliyor ✨

🛠 Pratik İş Akışı: Bağlam Dosyalarını Oluşturmak, Test Etmek ve Güncellemek

Hazırsan başlayalım — benim takımdaki gerçek workflow şöyle işliyor 👇

1️⃣ İlk taslağı çıkart (AI schwere işi yapsın)

Kod bazını elle taramanın anlamı yok. AI asistanı (Claude, Cursor, vs.) projeyi analiz etsin, AGENTS.md veya CLAUDE.md taslağını yazsın.

claude "Projeyi analiz et ve AGENTS.md taslağı yaz: mimari, kod stilleri, test stratejisi, yaygın hatalar ve 'yapılmaması gerekenler' listesi içersin"

Ne oluyor burada?
AI projeyi tarıyor → dosya yapısını, bağımlılıkları, pattern'leri anlıyor → senin için bir başlangıç context dosyası üretiyor. Mükemmel olmayacak, ama boş sayfadan başlamakla uğraşmazsın.

2️⃣ Dosyayı repoya ekle (commit et, unutma)

git add AGENTS.md
git commit -m "chore: add initial AGENTS.md context file"

✅ Neden?
Artık versiyon kontrolünde. Değişiklikler takip edilebilir, code review'dan geçebilir, ekip arkadaşların da görebilir.

3️⃣ Küçük bir görevle test et 🎯

Şimdi AI asistanına gerçek bir iş ver. Örn:

"Yeni bir /api/health endpoint'i ekle. Mevcut pattern'lere uy, test yaz, dokümantasyon güncelle."

Ne oluyor?
AI, yeni yazdığın AGENTS.md'yi bağlam olarak kullanıyor. Çıktıyı görüyorsun — halüsinasyon var mı?, stil projeye uyuyor mu?, testler geçiyor mu?

4️⃣ Çıktıyı değerlendir (kritik adım ❗️)

Soru	Evetse Ne Yapmalı?
Yanlış import/yol kullanıldı mı?	Dosyaya "Import yolları: `src/` kökünden mutlak yol" kuralı ekle
Eski bir pattern mi takip etti?	"Yeni kodda her zaman `Repository` pattern kullan, `Service` katmanına doğrudan DB erişme" yaz
Test eksik mi?	"Her public fonksiyon için en az 1 unit test zorunlu" kuralı ekle
Naming convention bozuldu mu?	"Dosya isimleri: `kebab-case`, fonksiyonlar: `camelCase`" belirt

Özetle: AI'nin hata yaptığı her yer → context dosyasına yeni bir kural eklenir.

5️⃣ Dosyayı düzelt, tekrar dene 🔁

Düzeltilmiş AGENTS.md ile aynı görevi tekrar sor. Çıktı iyileşti mi?
Hayır mı? Tekrar 4. adıma dön.
Evet mi? 🎉 Context dosyası artık işe yarıyor.

6️⃣ (Opsiyonel) CI/CD veya pre-commit'e entegre et 🛠

İstersen bu süreci otomatik hale getirebilirsin:

.pre-commit-config.yaml örneği:

- repo: local
  hooks:
    - id: check-agents-md
      name: "AGENTS.md güncel mi?"
      entry: bash -c 'git diff --name-only HEAD | grep -q AGENTS.md || echo "⚠️  AGENTS.md değişmedi, güncelleme unutuldu mu?"'
      language: system
      stages: [commit]

CI'de de kontrol edebilirsin:

- name: Validate context file
  run: |
    if ! grep -q "yeni eklenen kural" AGENTS.md; then
      echo "❌ AGENTS.md güncel değil"
      exit 1
    fi

💡 Benim takımdan bir ipucu

İlk hafta her gün AGENTS.md güncellendi.
İkinci hafta haftada 1-2 kez.
Artık ayda bir bakıyoruz — dosya ölmüş bir belge değil, yaşayan bir sözleşme hale geldi.

Basit kural: AI hata yaptığında, seni suçlama, dosyayı düzelt. 😉

🎯 Etkileri Ölçmek: Token Tasarrufu ve Çıktı Kalitesi

Hazırsan başlayalım — teorik konuşmak yetmez, elimizde somut sayı olmalı 🎯

Token Tasarrufu: Ne Kadar Kazanıyorsunuz?

Benim deneyimimde token kullanımı %40-60 arası düştü (yaklaşık sayı, garanti değil ❗️). Her proje farklı ama trend net:

Context dosyası olmadan: Her prompt'ta tekrar tekrar aynı bilgileri veriyorsunuz
Context dosyası ile: Model zaten biliyor, sadece "yeni şey" gönderiyorsunuz
Fark: Özellikle uzun süren sohbetlerde büyüyor 🔁

💡 İpucu: Kendi projenizde ölçün. input_tokens vs output_tokens loglayın, 2 hafta karşılaştırın.

Kalite Metrikleri: Sayılar Yalan Söylemez 📊

Token tasarrufu güzel ama çıktil kalitesi ne oluyor? Takip ettiğim 3 metrik:

Metrik	Ne Anlama Gelir?	Nasıl Ölçülür?
Halüsinasyon sayısı	Model var olmayan API'leri, fonksiyonları uyduruyor mu?	Code review'da yakalanan "sahte" çağrılar
Stil ihlali sayısı	Proje standartlarına uygun mu?	Lint/Prettier hatası sayısı (CI'de otomatik)
Onboarding süresi	Yeni üye ne kadar hızlı katkı sağlıyor?	İlk PR merge'ine geçen gün sayısı

Benim gözlemim: Context dosyası varken halüsinasyon %50+ azaldı, lint hatası %30 düştü, yeni üyeler 2-3 gün önce kod üretmeye başladı ✅

Siz de Deneyin: A/B Test Meydan Okuma ⚔️

Okumak yetmez, kendi verinizi üretin. Bu hafta şu deneyi yapın:

Hafta 1: Context dosyası yok — normal çalışın, her PR'ı not alın
Hafta 2: Context dosyası var — aynı süreç, aynı takım
Karşılaştırın: PR kalitesi, review turu sayısı, merge süresi

Not: Takımınıza "test yapıyoruz" deyin, bias olmasın 🛠

Özet: Ne Kazandık? 🎯

Token: ~%40-60 tasarruf (paranız cebinizde)
Kalite: Daha az halüsinasyon, daha temiz kod, daha hızlı onboarding
Risk: Sıfır — sadece bir .md dosya ekliyorsunuz

Şimdi sırada sizin projenizde denemek var. Hazır mısınız? 🚀

❗️ Yaygın Hatalar ve En İyi Uygulamalar

🎯 Sık Yapılan Tuzaklar

Her şeye karışmak – Dosya 500 satırı geçince AI de boğulur ⛔
Güncellememek – Eski kural kalır, AI yanlış yazar 🔁
Çelişkili kurallar yazmak – Karşıt talimatlar modeli karmaşa verir ❗️

✅ En İyi Uygulamalar

Küçük başla, ihtiyaç oldukça büyüt 🌱
Dosyayı kodun yanında tut (repo içinde) 📁
Takımla birlikte review et 🤝
Versiyon kontrolü yap 🛠

Bunları yazarken kendi yanlışlarımdan öğrendim 😊

🎯 Bonus Tavsiye: Bağlam Mühendisliğini Ekip Kültürüne Dönüştürmek

Harika, şimdi sen de bağlam mühendisliği nin gücünü hissediyorsun. Ama işin aslı şu: bu beceri sadece senin için bir "hobi" kalmamalı 🎯

Ekip standardı haline getir. İşte nasıl:

📄 Yeni gelen geliştiriciye "Önce AGENTS.md dosyasını oku, sonra kodlara bak" de. Ne kadar güçlü bir cümle, değil mi?
🗂 Shared context repo kur. Herkesin erişebileceği, güncellenen tek bir kaynak.
✅ Onboarding checklist'ine bağlam dosyalarını ekle: AGENTS.md, CONTEXT.md, PROMPT_LIBRARY.md...
🔁 PR şablonuna "Bağlam dosyaları güncellendi mi?" maddesini koy. Unutulmaz hale gelsin.

Ne oluyor böylece?
Ekipte kimse "Bu task için hangi promptu kullanayım?" diye vakit kaybetmez. Herkes odaklı, hızlı ve tutarlı çalışır.

Artık prompt yazmakla vakit kaybetmiyorum, özellik yapıyorum 🚀

Sence hangi dosyayı ilk deneyeceksin?
AGENTS.md mi, CONTEXT.md mi, yoksa kendi PROMPT_LIBRARY.md nin mi?
Yorumda paylaş bakalım 👇

Bu içerik tamamen yapay zeka destekli otomasyon sistemi ile üretilmiştir.