AGENTS.md

​

Ne işe yarar

• Konum: Repo kökü. Bu, agentsmd/agents.md açık formatının tanımlı yeridir.
• Ne zaman okunur: Her yeni oturumun başında, ajan tarafından otomatik olarak.
• Rol: Yönlendirici (router). Genel bakış, hızlı başlangıç, sıkı kısıtlar (hard constraints) ve konu dokümanları haritası burada durur. Detay, docs/ altındaki dosyalara dağılır (Ders 04).
• Boy bütçesi: 50–200 satır. HumanLayer’ın saha kılavuzunun çizdiği üst sınır 300 satırdır; “daha kısası daha iyidir.”

​

Şablon

# AGENTS.md — <Proje adı>

> Bu dosya bir router'dır. Detay konu dokümanlarındadır.
> Üst sınır: 200 satır. Şu an: <satır sayısı>.

## Proje

<Bir cümle: ne, kimin için, hangi yığın.>
Örnek: "B2B fatura kesme servisi. Python 3.11 + FastAPI + PostgreSQL 15."

İlgili dosyalar: `ARCHITECTURE.md`, `CONTRIBUTING.md`, `examples/reference-endpoint/`.

---

## Sıkı kısıtlar (ihlal edilemez)

1. Tüm DB sorguları parametreli; ham string concat yasak.
2. Tüm endpoint'ler OAuth 2.0 ile kimlik doğrular.
3. Secret'lar yalnız `.env` ve `vault://` üzerinden; repoya commit edilmez.
4. Her PR `make check` yeşilken açılır.
5. 300 satırdan büyük yeni dosya kabul edilmez (ratchet kuralı).

---

## Dev Environment Tips

- Kurulum: `make setup`
- Yerel geliştirme: `make dev`
- Python sürümü: `.python-version` dosyasında sabit.
- Node sürümü: `.nvmrc` dosyasında sabit.
- Bağımlılık ekleme: `uv add <paket>` (pip değil).
- Yeni modül: `examples/reference-endpoint/` örneğini kopyala, üzerine yaz.

## Testing Instructions

- Tüm testler: `make test`
- Tek bir dosya: `pytest tests/test_<isim>.py -x`
- Tip denetimi: `mypy src/ --strict`
- Lint: `ruff check src/`
- Tam doğrulama (CI'nin de koştuğu): `make check`

Ajan teslim etmeden önce `make check` koşar ve çıktısını PR açıklamasına yapıştırır. Yeşil olmayan diff teslim edilmez.

## PR Instructions

- Commit mesajı: `[<modül>] <tek mantıksal değişim>`
- Bir PR = bir mantıksal değişim. Karışık PR reddedilir.
- `PROGRESS.md` ve `DECISIONS.md` değişiklikle birlikte güncellenir.
- İlgili konu dokümanı değişti mi? Checkbox işaretle.
- `make check` çıktısı PR gövdesinde.

---

## Konu dokümanları

Aşağıdaki haritayı oku; ilgili görev geldiğinde **yalnız ilgili dosyayı** aç.

| Görev | Dosya |
| --- | --- |
| API uçları eklerken / değiştirirken | `docs/api-patterns.md` |
| DB şema, migration, sorgu | `docs/database-rules.md` |
| Yeni test yazarken | `docs/testing-standards.md` |
| Auth, secrets, input validation | `docs/security.md` |
| Sürüm çıkışı | `docs/release.md` |

## Durum ve karar

- Aktif iş: `PROGRESS.md`
- Karar günlüğü (neden, alternatif, sonuç): `DECISIONS.md`
- Yeni özellikler: `features.json`

​

Konvansiyon

• Ad: AGENTS.md (büyük harf, tek dosya). agentsmd/agents.md açık formatı bu adı standartlaştırır; Claude Code projelerinde CLAUDE.md ile bire bir aynı role sahiptir. İkisini birden tutuyorsan biri diğerini referans etsin, içerik çatallanmasın.
• Konum: Yalnızca repo kökü. Alt dizinlerdeki AGENTS.md dosyaları desteklenir ama opsiyoneldir; köktekiyle çelişmemelidir.
• Sahip: Kod sahibiyle aynı ekip. CODEOWNERS içine /AGENTS.md @platform-team satırı koyulur. Doküman çürümesinin en yaygın sebebi sahipsizliktir.
• Yapı: Üç ana bölüm — Dev Environment Tips, Testing Instructions, PR Instructions — agentsmd/agents.md referans şablonunun çekirdeğidir. Sıkı kısıtlar ve konu dokümanları haritası yerel ekleme olarak üstte/altta durur.
• Konum disiplini: Liu et al. 2023’ün “Lost in the Middle” sonucu nedeniyle sıkı kısıtlar dosyanın başında veya sonunda yer alır, asla ortada değil.

​

Özelleştirme

• Monorepo: Kökte ince bir AGENTS.md; her paket altında 30–80 satırlık yerel AGENTS.md. Kök dosya paket haritasını tutar; paketler kendi sıkı kısıtlarını yazar.
• Brownfield: 600 satırlık şişmiş bir dosya geldiyse, doğrudan kısaltma. Önce her bölümü ilgili docs/<konu>.md dosyasına taşı, sonra kökten link bırak. Ratchet: her commit sonrası satır sayısı yalnızca düşebilir.
• Çoklu ajan: Cursor, Claude Code ve Codex aynı repoda çalışacaksa tek AGENTS.md ve aracın yerel dosyası (örn. .cursor/rules) için sembolik link kur. İçerik tek yerde yaşasın.
• Gotcha — stil kuralları: “snake_case kullan” gibi maddeleri AGENTS.md içinde tutma; linter’a taşı. HumanLayer’ın tavsiyesi net: bütçeni stil için harcama.
• Gotcha — kopyala yapıştır şişmesi: Bir hata olduğunda refleksle kural ekleme. Önce sor: “Bu kural konu dokümanına ait mi?” Cevap genellikle evettir.

​

Otomasyona bağlama

.PHONY: check-agents
check-agents:
	@lines=$$(wc -l < AGENTS.md); \
	if [ $$lines -gt 200 ]; then \
	  echo "AGENTS.md $$lines satır — üst sınır 200"; exit 1; \
	fi

• PR template: “AGENTS.md veya ilgili docs/<konu>.md güncellendi mi?” checkbox’ı zorunlu alan olarak.
• CODEOWNERS: /AGENTS.md için review zorunlu.
• Pre-commit: AGENTS.md değişirse PROGRESS.md üzerinde bir satır değişikliği bekleyen basit bir hook — kararın gerekçesi yazılı kalsın.
• Soğuk başlangıç testi: Ayda bir, yeni bir oturum aç ve Ders 03 testindeki beş soruyu yalnız repoya bakarak cevapla. Birine bile cevap veremiyorsan AGENTS.md veya bağladığı konu dokümanı eksiktir.

​

İlgili dersler

• Ders 02 — Düzeneğin Anatomisi
• Ders 03 — Repo: Hakikat Kaynağı
• Ders 04 — Şişmiş Talimat Sendromu
• Kütüphane — PROGRESS.md / DECISIONS.md
• Kütüphane — Bootstrap
• Kütüphane — features.json