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:
Prompt → Model → HopePratikte işe yarayan ise:
Structure → Prompt → ModelYapı 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
# 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.yamlHepsi 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.ymlNeden 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.



Bu yazıya bırakılan notlar
Katıl
Bir yorum bırak.
Bu yazıya not eklemek için giriş yap.
Sadece adın ve avatarın kullanılır.