Yapay zekâ ajanları için anlaşılır proje yapısı (2026)

Yapay zekâ ajanlarının doğru dosyada çalışabilmesi için net klasör yapısı, standart komutlar ve AGENTS.md ile yazılı çalışma kuralları.

Yapay zekâya verdiğiniz talimatı uzatmadan önce projenin dosyalarını ve çalışma kurallarını düzenleyin.

AI (yapay zekâ) agent’lar (araç kullanarak bir görevin adımlarını yürüten yapay zekâ ajanı) model kalitesinden çok daha sık repo (projenin dosyalarını ve değişiklik geçmişini tutan kod deposu) belirsizliği yüzünden başarısız olur.
2026’da kazanan ekipler daha uzun prompt (yapay zekâya verilen talimat veya soru) yazanlar değil; agent’a hazır repository’ler (projenin dosyalarını ve değişiklik geçmişini tutan kod deposu) çıkaranlar.

Bu yazı, sizi tek bir araca ya da sağlayıcıya bağlamadan, bunun pratikte 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.

Yapay zekâ ajanları projenizi bir insan ekip arkadaşı gibi “anlamaz”.
Yalnızca yapıyı, yerleşik çalışma kurallarını 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:

text
Prompt → Model → Hope

Pratikte işe yarayan ise:

text
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
  • projeye başlamak için genel bilgiler

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

text
# AGENTS.md
text
## Goal
          You help ship small, reviewable changes.
text
## Canonical commands (don’t guess)
          - Install: ./scripts/dev.sh install
          - Dev:     ./scripts/dev.sh start
          - Test:    ./scripts/test.sh
          - Lint:    ./scripts/lint.sh
text
## Entry points
          - Web app: src/entrypoints/web.ts
          - Worker:  src/entrypoints/worker.ts
text
## Boundaries
          - Do not change generated files or lockfiles unless asked.
          - No infra, migrations, or prod config edits without confirmation.
          - Prefer the smallest possible diff.
text
## 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ı:

text
repo/
            AGENTS.md
            README.md
text
  docs/
              architecture.md
              runbook.md
text
  scripts/
              dev.sh
              test.sh
              lint.sh
text
  api/
              openapi.yaml
text
  src/
              entrypoints/
                web.ts
                worker.ts
text
  .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 (uygulamanın davranışını belirleyen ayarlar) 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 (iki sürüm arasındaki değişiklikleri gösteren karşılaştırma)
  • 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 uygulama örneği paylaşıyorum.
Takipte kalın ya da bana ulaşın — notlarımızı karşılaştırmaktan memnuniyet duyarım.

Bu yazı İngilizce aslından Türkçeye çevrilmiştir.

İlk yayın: Medium ↗

Çözmeye değer bir problemin mi var?Birlikte çözelim

Konuşmaya başla

Full-stack ve uygulamalı AI rollerine açığım, uzaktan veya hibrit.

Rolü, ekibi ve problemi anlat.