Bu repo için AGENTS.md yaz. Amaç kural listesi değil: buraya yeni düşen bir kodlama ajanının (ve yeni ekip üyesinin) hangi hataları yapacağını önceden kesen bir harita.
AŞAMA 1 — Kanıt topla. Önce oku, sonra yaz. Uydurma yok.
- package.json / pyproject / go.mod / Gemfile: script'ler, paket yöneticisi, runtime sürümü pinlenmiş mi (.nvmrc, engines, volta gerçekten var mı?)
- Dizin ağacı (2 seviye). Aynı işi yapan iki klasör var mı? (api/ + apis/, navigations/ + routes/ gibi) — bunlar göç halinde, not al.
- CI dosyaları: gerçekte hangi komutlar çalışıyor, hangileri lokalde gereksiz.
- Test kurulumu: testler nerede duruyor, ortak helper/mock nerede, hangi komut tek dosya çalıştırıyor.
- README, varsa mevcut AGENTS.md / CLAUDE.md / .cursorrules.
- Son 50 commit: en çok dokunulan dosyalar, revert'ler, "fix:" desenleri.
- Ortam ve build: .env.*, config/, ios/, android/, patches/, Dockerfile. Yazdığın her komut, yol ve dosya adı gördüğün bir şey olsun. Doğrulayamadığını yazma; emin değilsen "bunu doğrulayamadım" de.
AŞAMA 2 — Bana 5 soru sor, cevaplarımı bekle. Bunlar kodda yok:
- Bu üründe asla bozulmaması gereken 3 şey ne?
- Yeni gelen biri ilk haftasında neyi kırar, nerede saat kaybeder?
- Repodaki hangi "garip" şey bilerek öyle? (kaldırılmasını istemediğin şey)
- Gelen hataların en sık tipi ne — değişiklikler genelde neyi ıskalıyor?
- Sormadan çalıştırmamam gereken komutlar? (pahalı, yıkıcı, ortama bağlı)
AŞAMA 3 — Şu iskeletle yaz, 150 satırı geçme:
- Bu repo tek paragrafta: ne, kim için, hangi teknoloji, prod'da ne riski var.
- Asla taviz verilmeyenler — 3-5 madde, her biri bir başlık + 2 cümle. Bunlar yasak değil değer: neden umursadığımızı anlat.
- Küçük sözlük — bu ekibin kendine has kelimeleri, koddaki karşılığıyla birlikte. Genel yazılım terimlerini tanımlama.
- Kendini yaralamanın yolları — 3 madde, bu repoya özel gerçek tuzaklar. Her biri: ne yapma + neden patlıyor + onun yerine ne yap.
- Her yüzeye dokun — buradaki en sık defect "test ettiğin yolda doğru, geri kalan her yerde eksik" olan değişiklik. Bir değişikliğin peşinden gitmesi gereken yerlerin kontrol listesi (platformlar, diller, katmanlar, ortamlar, ters durumlar: ileri yolu eklediysen geri yolunu da ekle).
- Komutlar — gerçekten çalışan en küçük komutlar. İzin almadan çalıştırılmaması gerekenleri ayrı yaz, sebebiyle.
- Doğrulama — "değişikliğin çalıştığının en küçük kanıtı" ne? Tüm suite'i çalıştırmak cevap değil.
- Nasıl çalışıyor — bir istek/veri sistemin içinde baştan sona nereden geçiyor, tek paragraf.
- Kod nerede yaşar — kısa dizin haritası + hiç açılmaması gereken klasörler.
- Zevk — bu kod tabanında iyi kodun neye benzediği. Tercihler, dogma değil.
- Bitirirken — bir görevin sonunda benden ne beklendiği.
KALİTE TESTİ — teslim etmeden önce her satır için sor: "Bu cümle başka bir repoya olduğu gibi kopyalanabilir mi?" Cevap evetse sil. "Küçük değişiklikler yap", "temiz kod yaz", "testleri geç" gibi cümleler yer kaplamaktan başka iş yapmaz; ajan zaten bunları biliyor. Bilmediği şey senin repondaki tuzaklar.
TON: kısa cümleler, düz anlatım. Yasak listesi yerine sebep. Bunlar kanun değil iyi varsayılanlar — geliştiricinin tercihi bu dosyayı ezer, bunu dosyada da yaz.