Agent’a Hazır Repo Yapısı (2026)

Prompt ince ayarını bırakın. Repo’nuzu AI agent’lar için paketlemeye başlayın.

AI agent’lar model kalitesinden çok daha sık repo belirsizliği yüzünden başarısız olur.
2026’da kazanan ekipler daha uzun prompt yazanlar değil; agent’a hazır repository’ler çıkaranlar.

Bu yazı, sizi tek bir araca ya da sağlayıcıya bağlamadan, bunun pratikte gerçekte ne anlama geldiğini anlatıyor.

Asıl sorun (prompt’lar değil)

Bir agent’ın şunları yaptığını hiç izlediyseniz:

• yanlış dosyaları düzenlemek
• kurulum adımlarında döngüye girmek
• testlerin nasıl çalıştırılacağını sormak
• ya da niyet etmediğiniz altyapıya dokunmak

…asıl sorunu görmüşsünüz demektir.

Agent’lar projenizi bir insan ekip arkadaşı gibi “anlamaz”.
Yalnızca yapıyı, konvansiyonları ve açık kuralları görürler.

Bunlar eksik olduğunda agent tahmin yürütür.
Ve işler tam da tahminin başladığı yerde bozulur.

Gerçekten işe yarayan sıralama

Çoğu ekip buradan başlar:

Prompt → Model → Hope

Pratikte işe yarayan ise:

Structure → Prompt → Model

Yapı belirsizliği azaltır.
Prompt’lar kısalır.
Model, sandığınızdan daha az önemlidir.

README yeterli değil

README dosyaları insanlar için yazılır:

• üst düzey açıklama
• kurulum rehberleri
• oryantasyon bağlamı

Agent’ların ihtiyacı ise bambaşka.

İhtiyaç duydukları şeyler:

• standart komutlar
• net giriş noktaları
• açık sınırlar
• bir “dokunma” listesi

İşte AGENTS.md tam burada devreye giriyor.

AGENTS.md: eksik parça

AGENTS.md’yi bir dokümantasyon değil, bir brifing belgesi olarak düşünün.

İyi bir AGENTS.md yalnızca tek bir soruyu yanıtlar:

“Hiç bağlamı olmayan yeni bir mühendis olsaydım, küçük bir değişikliği nasıl güvenle yapardım?”

Minimal AGENTS.md şablonu

# AGENTS.md

## Goal
You help ship small, reviewable changes.

## Canonical commands (don’t guess)
- Install: ./scripts/dev.sh install
- Dev:     ./scripts/dev.sh start
- Test:    ./scripts/test.sh
- Lint:    ./scripts/lint.sh

## Entry points
- Web app: src/entrypoints/web.ts
- Worker:  src/entrypoints/worker.ts

## Boundaries
- Do not change generated files or lockfiles unless asked.
- No infra, migrations, or prod config edits without confirmation.
- Prefer the smallest possible diff.

## Where to look for answers
- Architecture: docs/architecture.md
- Runbook:      docs/runbook.md
- API contract: api/openapi.yaml

Hepsi bu.
Prompt şiiri yok. Rol yapma yok.
Sadece netlik.

Pratik, agent’a hazır bir repo düzeni

Araçlar ve ekosistemler arasında çalışan temel bir yapı:

repo/
  AGENTS.md
  README.md

  docs/
    architecture.md
    runbook.md

  scripts/
    dev.sh
    test.sh
    lint.sh

  api/
    openapi.yaml

  src/
    entrypoints/
      web.ts
      worker.ts

  .github/
    workflows/ci.yml

Neden işe yarıyor:

• Bir şeyi çalıştırmanın tek bir yolu → tahmin yok
• Açık giriş noktaları → daha az yanlış düzenleme
• Yazıya dökülmüş sınırlar → daha güvenli değişiklikler

Araç uyumluluğu (bağımlılık olmadan)

Bu yapı araçtan bağımsız olduğu için işe yarıyor.

Farklı ekosistemler onu farklı şekillerde okur:

• GitHub Copilot agent’ları
• Claude Code
• Cursor / VS Code agent modları
• gelecekteki agent çalıştırıcıları

Temel fikir aynı kalır:

Repo düzeyindeki talimatlar, prompt düzeyindeki numaraları yener.

Araca özel klasörler ya da config’ler olabilir, ancak bunlar projeyi anlamak için zorunlu değil, isteğe bağlı olmalıdır.

Bu neden 2026’da ölçekleniyor

Agent’lar “sohbet asistanları” olmaktan iş akışının katılımcıları olmaya geçtikçe belirsizlik pahalı hale geliyor.

Yapıya yatırım yapan ekipler şunları kazanır:

• daha hızlı agent iterasyonu
• daha güvenli diff’ler
• daha az insan müdahalesi
• insanlar ve agent’lar arasında daha temiz devir teslimler

Bu bir AI numarası değil.
Sadece iyi mühendislik disiplini — nihayet zorunlu hale gelmiş haliyle.

Küçük başlayın

Bunu okuduktan sonra tek bir adım atacaksanız:

Repo’nuza AGENTS.md ekleyin.

Mükemmel bir yapıya ihtiyacınız yok.
Net bir yapıya ihtiyacınız var.

Bir repo’yu agent’a hazır yapan şey budur.

Bu yazı işinize yaradıysa, agentic iş akışları ve repo tasarımı üzerine gerçek dünyadan daha fazla pattern paylaşıyorum.
Takipte kalın ya da bana ulaşın — notlarımızı karşılaştırmaktan memnuniyet duyarım.