Efektif AGENTS.md oluşturma prompt

A developer shared a detailed prompt for creating an effective AGENTS.md file, emphasizing evidence-based documentation over generic rules. The prompt outlines a three-stage process: gathering repository evidence, asking targeted questions, and writing a concise guide with specific sections like non-negotiables, pitfalls, and verification steps.

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.