Kodlama aracıları, kod yazmadan önce deponuzu okur ve ilk okudukları dosya AGENTS.md'dir. Bu, Codex CLI, Cursor, Aider, OpenHands ve giderek artan diğer araçların üzerinde anlaştığı açık bir kuraldır, böylece tek bir bağlam dosyası her aracıda çalışır. API geliştirme ekipleri için bu dosya, gerçek bir yerel sunucuya karşı doğru testleri çalıştıran bir aracı ile uç noktaları yanıltan ve bozuk bir istemci gönderen bir aracı arasındaki farkı yaratır.
Bu rehber, AGENTS.md'nin ne olduğunu, API ekiplerinin onu neden üretim kodu olarak ele alması gerektiğini, OpenAPI öncelikli depolarda önemli olan bölümleri, somut örnekleri ve API geliştikçe nasıl güncel tutulacağını kapsar. Sonunda onu Apidog ile eşleştiriyoruz, böylece aracının sözleşme testi akışı gerçek bir spesifikasyona dayanır.
Düğme
ÖZET
AGENTS.md, depo kökünde bulunan, kodlama aracılarına projenizde kodda nasıl gezineceklerini, derleyeceklerini, test edeceklerini ve göndereceklerini anlatan düz bir Markdown dosyasıdır.- Bu kural açık olup Codex CLI, Cursor, OpenHands, Aider, Claude Code ve diğer aracı araçlarında desteklenmektedir.
- API ekipleri için en çok karşılık veren bölümler derleme komutları, OpenAPI spesifikasyon yolu, mock sunucu uç noktaları, sözleşme testi komutları, kimlik doğrulama kurulumu ve “dokunulmaması gereken” alanlardır.
- Kısa tutun. 200 ila 400 satır yeterlidir. Daha uzun olursa, aracı önemli kısımları atlayacaktır.
- Onu bir Apidog koleksiyonuyla eşleştirin, böylece aracı hem bağlama (
AGENTS.md) hem de çalıştırılabilir bir sözleşmeye (OpenAPI spesifikasyonu) sahip olur.
AGENTS.md Gerçekte Nedir
AGENTS.md, bir deponun köküne işlediğiniz bir Markdown dosyasıdır. Kodlama aracıları kod tabanıyla ilk temasta onu arar ve içeriğini projenin nasıl çalıştığına dair yetkili bir bilgilendirme olarak kabul eder. Bu kural, OpenAI'nin Codex CLI içinde başladı ve diğer araçların aynı dosyayı okuyabilmesi için açık bir standart olarak yayınlandı. Bu yıl itibarıyla Codex CLI, Cursor, Aider, Claude Code, OpenHands, Sourcegraph Cody ve daha küçük birkaç aracı onu okumaktadır.
Üç şey onu kullanışlı kılar:
- Tek dosya, her aracı. Bağlamı bir kez yazarsınız ve ekibin araç setindeki her aracı onu alır. Araca özel yapılandırma kayması olmaz.
- Düz Markdown. DSL yok, şema yok, derleme adımı yok. Mühendisler onu diğer belgeler gibi düzenler.
- Tanımladığı kodun yanında yaşar. Derleme betiği değiştiğinde, dosya aynı PR'da değişir. Fark, değişikliği inceleyenlere ve aracıya görünür kılar.
En yakın akrabası, Anthropic'in Claude Code'unun okuduğu CLAUDE.md'dir. İki format büyük ölçüde örtüşmektedir; birçok proje, her iki aracın da ek yapılandırma olmadan çalışması için AGENTS.md dosyasını CLAUDE.md'ye sembolik bağ olarak tutar. Codex ekibi ve Anthropic, formatları gelecekte de uyumlu tutma konusunda kamuoyuna açıkça mutabık kalmışlardır.
API Geliştirme Ekiplerinin Buna Neden Çoğundan Daha Çok İhtiyacı Var
API ekipleri garip bir kavşakta yer alır: kod küçüktür, sözleşmeler büyüktür ve herhangi birinde hata yapmanın sonuçları her alt akım istemcisi tarafından görülür. openapi.yaml adresinde spesifikasyonun yaşadığını bilmeyen bir aracı, eğitim verilerinden hatırladığı yanıt şeklinden türleri yeniden yazacaktır. Sözleşme testi komutunu bilmeyen bir aracı, derlenen ancak istemci SDK hattını bozan kod işleyecektir.
Bir API deposu için iyi yazılmış bir AGENTS.md dört şey yapar:
- Spesifikasyonu doğruluk kaynağı olarak sabitler. Her değişiklik OpenAPI veya GraphQL şemasıyla başlar ve biter. Aracı önce spesifikasyonu güncellemeyi, sonra türleri yeniden oluşturmayı öğrenir.
- Yerel sunucuları adlandırır. Yerel bir mock veya canlı sunucuyu başlatan aracılar, testler için doğru URL'yi seçer, bir Stack Overflow kod parçacığını değil.
- Test komutlarını amacına göre listeler. “Birim testlerini çalıştır” ile “sözleşme testlerini çalıştır” veya “hazırlık ortamına karşı entegrasyon testlerini çalıştır” aynı değildir.
- Yasak yolları belirtir. Oluşturulmuş SDK kodu, üçüncü taraf istemci sarmalayıcıları ve geçiş dosyaları genellikle düzenlenebilir gibi görünse de değildir.
Dosya bu dört şeyi yaptığında, aracı çıktısı README'yi atlamış bir junior geliştirici gibi görünmeyi bırakır ve bir takım arkadaşı gibi görünmeye başlar.
API Depoları İçin Çalışan Yapı
AGENTS.md'nin zorunlu bir şeması yoktur. Topluluk, neredeyse her iyi ayarlanmış dosyada görünen birkaç bölüm üzerinde mutabık kalmıştır. Bir API ekibi için aşağıdaki sıra güçlü bir varsayılan olarak kabul edilebilir.
1. Proje Özeti (3-5 satır)
API'nin ne yaptığını, tüketicilerin kim olduğunu ve sunucunun hangi dil ve çerçevede çalıştığını belirtin. Gerçeklere dayalı olsun.
# Project: Payments API
Internal payments service for the Acme product line. Customers are
mobile, web, and partner backends. Server is Go 1.23 on Echo, Postgres
17 for storage, and a Redis-backed idempotency layer.
Bu blok, aracıya hangi dili varsayılan olarak kullanacağını, hangi deyimleri takip edeceğini ve yanlış yanıt şekli gönderirseniz hangi istemcilerin bozulacağını söyler.
2. Hızlı Başlangıç Komutları
Aracının sürekli çalıştıracağı beş ila on komut. Komutu her zaman dahil edin, asla bir wiki'ye bağlantı vermeyin.
## Commands
| Amaç | Komut |
|--------|---------|
| Bağımlılıkları Kur | `make deps` |
| Sunucuyu Yerel Olarak Çalıştır | `make dev` (binds 127.0.0.1:8080) |
| Birim Testlerini Çalıştır | `make test` |
| Yerel Mock'a Karşı Sözleşme Testlerini Çalıştır | `make contract` |
| Lintle | `make lint` |
| Spesifikasyondan İstemcileri Yeniden Oluştur | `make codegen` |
| Geçişleri Uygula | `make migrate` |
Bir komutun çalışması için bir ortam değişkenine ihtiyacı varsa, ortam değişkeninin adını yanına koyun. Aracılar değişkenleri dışa aktarmada iyidir; tahminde kötüdürler.
3. OpenAPI / GraphQL Spesifikasyon Bölümü
Bu, bir API deposundaki en değerli bölümdür. Aracıya spesifikasyonun nerede olduğunu, spesifikasyonun oluşturulan kodla nasıl ilişkili olduğunu ve düzenlemelerin hangi yönde aktığını söyleyin.
## Source of truth
- The spec is at `apis/payments/openapi.yaml`.
- Generated clients live in `gen/clients/{go,ts,python}` and MUST NOT be hand-edited.
- The generation pipeline is `make codegen`. Run it after every spec change
and commit the regenerated clients in the same PR.
- Spec changes flow: spec -> `make codegen` -> server handler updates ->
contract tests -> ship.
Yalnızca bu blok, aracıların bir tür uyumsuzluğunu “düzeltmek” için oluşturulan istemciyi düzenlediği, sonraki kod üretimi çalıştırmasının değişikliği sildiği ve derlemenin iki gün sonra gizemli bir şekilde bozulduğu bir hata sınıfını ortadan kaldırır.
4. Mock Sunucu ve Apidog Bağlantısı
Mock sunucuları çalıştırıyorsanız (ki çalıştırmalısınız), onları adlandırın. URL'leri, okudukları spesifikasyonu ve nasıl başlatılacaklarını listeleyin.
## Local servers
- Real server: `make dev` -> `http://127.0.0.1:8080`
- Apidog mock server: `make mock` -> `http://127.0.0.1:4010`
- The mock reads from the same `openapi.yaml` and replays saved examples
from the Apidog collection at `apis/payments/apidog/`.
Apidog'un dosyada yerini kazandığı yer burasıdır. Mock sunucu, spesifikasyon ve kaydedilmiş istek örnekleri, aracının gerçek arka uçta çağrıları harcamadan çalıştırabileceği bir sözleşme oluşturur. Temel iş akışı için onu Postman olmadan API testi rehberi ile eşleştirin.
5. Kimlik Doğrulama ve Sırlar
Aracıya API'nin nasıl kimlik doğruladığını ve hangi ortam değişkenlerinin neyi tuttuğunu söyleyin. Gerçek sırları asla dosyaya koymayın.
## Auth
- Production uses OAuth 2 client credentials issued by Auth0.
- Local dev uses a static dev token; export `DEV_TOKEN` from `.env.local`.
- The Apidog collection uses the same env var names so the mock and the
real client behave identically.
- Tokens MUST NOT be committed; `.env.local` is in `.gitignore`.
6. Test Stratejisi
Test katmanlarını sıralayın. Aracılar onları listelediğiniz sırada çalıştıracaktır.
## Test Etme
1. Birim testleri için `make test`. Hızlıdır, her değişiklikte çalışır.
2. Mock'a karşı OpenAPI sözleşme testleri için `make contract`. Herhangi bir spesifikasyon değişikliği birleştirilmeden önce çalıştırın.
3. Gerçek bir Postgres ile yerel bir sunucuya karşı uçtan uca testler için `make integration`. Ana dala birleştirmeden önce çalıştırın.
4. Hazırlık ortamı dayanıklılık testleri GitHub Actions aracılığıyla her gece çalışır; yerel bir komut değildir.
7. Dokunulmaması Gerekenler Listesi
Oluşturulan kod, bağımlılıklar ve geçişler neredeyse her zaman buraya aittir.
## Do not edit by hand
- `gen/**` (regenerated by `make codegen`)
- `vendor/**` (managed by `go mod vendor`)
- `migrations/*.up.sql` past the first unapplied migration
- `apis/payments/openapi.yaml` schema field names without owner sign-off
8. Kurumsal Stil
Üç ila beş kural. Daha fazlası olursa aracı yanlış olanı seçecektir.
## Conventions
- Errors return RFC 7807 problem JSON; never bare strings.
- Use snake_case in JSON, camelCase in Go, PascalCase in TS clients.
Codegen handles the mapping.
- Idempotency keys are required on all POST endpoints that create resources.
- New endpoints require a contract test that exercises both 200 and 4xx paths.
Somut Örnek: İşi Yapan 90 Satırlık Bir Dosya
Ayartıcı olan 800 satır yazmaktır. Direnin. Aşağıdaki dosya, 90 satırlık Markdown ile gerçek bir API hizmetini kapsar ve herhangi bir büyük aracının verimli çalışması için yeterlidir.
# Project: Payments API
Internal payments service for the Acme product line. Go 1.23, Echo,
Postgres 17, Redis for idempotency. Consumers are mobile, web,
and partner backends.
## Commands
| Intent | Command |
|--------|---------|
| Install | `make deps` |
| Run server | `make dev` |
| Unit tests | `make test` |
| Contract tests | `make contract` |
| Lint | `make lint` |
| Regen clients | `make codegen` |
| Migrate DB | `make migrate` |
## Source of truth
- Spec: `apis/payments/openapi.yaml`
- Generated clients: `gen/clients/{go,ts,python}` (do not edit)
- Edit flow: spec -> `make codegen` -> handler -> contract tests -> ship
## Local servers
- Real server: `make dev` (`http://127.0.0.1:8080`)
- Apidog mock: `make mock` (`http://127.0.0.1:4010`)
- Apidog collection: `apis/payments/apidog/`
## Auth
- Production: Auth0 OAuth 2 client credentials.
- Local dev: static `DEV_TOKEN` from `.env.local`.
## Testing order
1. `make test`
2. `make contract`
3. `make integration`
## Do not edit by hand
- `gen/**`, `vendor/**`
- Applied migrations in `migrations/`
- Spec field names without owner approval
## Conventions
- RFC 7807 problem JSON for errors
- snake_case JSON, codegen handles language mapping
- Idempotency keys required on POST creates
- Every new endpoint ships with a contract test
Bu yeterli. Bölümleri yalnızca bir aracı aynı yanlış seçimi iki kez yaptığında ekleyin.
Dosyayı Güncel Tutmak
Eski bir AGENTS.md hiç olmamasından daha kötüdür. Aracı buna inanacak ve artık çalışmayan bir derleme komutuna dayalı kod gönderecektir.
Üç alışkanlık onu güncel tutar:
- Üretim kodu olarak ele alın. Değişiklikler diğer tüm PR'lar gibi aynı incelemeden geçer. İnceleyiciler komut listelerinin gerçek
Makefileile eşleştiğini kontrol eder. - CI'ya bağlayın. Komut tablosunu ayrıştıran ve her komutu yeni bir çekimde çalıştıran kısa bir betik, kaymayı hızlıca yakalar. Çoğu ekip bunu 30 satırlık Bash kodunda yazar.
- Aynı PR'da güncelleyin. Yeni bir test komutu eklediğinizde,
AGENTS.md'yi daha sonra güncelleyeceğinizi vaat etmeyin. Şimdi güncelleyin. Maliyeti iki dakikadır; atlamanın maliyeti ise iki haftalık aracı karışıklığıdır.
AGENTS.md'niz İçin Çalışma Zamanı Sözleşmesi Olarak Apidog
AGENTS.md aracıya bağlam sağlar. OpenAPI spesifikasyonu ona sözleşmeyi verir. Apidog ikisini birleştirir: spesifikasyonu okur, AGENTS.md'de listelenen URL'de yerel bir mock çalıştırır, testler için kaydedilmiş istek örneklerini tekrar oynatır ve aracının canlı arka uçta kredileri yakmadan gerçek yanıtları görmesini sağlar.
İşe yarayan desen:
apis/<service>/openapi.yamlveapis/<service>/apidog/(dışa aktarılan koleksiyon) dosyalarını commit'leyin.AGENTS.md'de mock URL'sini vemake mockkomutunu listeleyin.- Aracılar, kaydedilmiş örneklere karşı hızlı testler için
make contractkomutunu çalıştırır. - Spesifikasyon değiştiğinde, aracı istemcileri yeniden oluşturur, sözleşme paketini çalıştırır ve ancak o zaman canlı sunucuya dokunur.
Gerçek bir API ile Apidog mock iş akışının daha derinlemesine bir incelemesi için, DeepSeek V4 API rehberi, bir servis API'si yerine bir model API'ye uygulanan aynı deseni kapsar.
API Ekiplerinin Yaptığı Yaygın Hatalar
Bu dosyalardan onlarcasını inceledikten sonra, aynı beş sorun ortaya çıkıyor:
- Listelemek yerine bağlantı vermek. “Derleme komutları için wiki'ye bakın.” Aracı wiki'ye göz atmaz. Komutları satır içine ekleyin.
- Pazarlama odaklı yazı. “Dünya standartlarındaki API platformumuz güç verir…” Aracının bir tanıtıma ihtiyacı yok. Gerçekleri belirtin.
- Eski komutlar. Mart ayında bozulan bir komut Nisan ayında hala dosyada duruyor. Bunu yakalamak için CI'yı bağlayın.
- Spesifikasyon bölümünü eksik bırakmak. En kullanışlı blok. Her zaman dahil edin.
- Dokunulmaması gerekenler listesi yok. Aracı oluşturulan kodu düzenler. Sonraki kod üretimi çalıştırması düzenlemeyi siler. Derleme bozulur. Tekrar.
Başlamak için bir temel istiyorsanız, yukarıdaki örneği deponuza kopyalayın, proje özetini düzenleyin ve komut tablosunu ayarlayın. Kullanılabilir bir dosyayı 20 dakikada gönderebilirsiniz.
Sıkça Sorulan Sorular
AGENTS.md, CLAUDE.md ile aynı mı? Formatlar uyumludur. Çoğu ekip birini doğruluk kaynağı olarak tutar ve diğerini sembolik bağlar. Anthropic ve OpenAI, kuralları birlikte çalışabilir tutma konusunda kamuoyuna açıkça mutabık kalmışlardır.
Dosyayı nereye koymalıyım? Her zaman depo köküne. Bazı aracılar, monorepolar için faydalı olan alt dizinlerdeki iç içe AGENTS.md dosyalarını da okur. Tek bir kök seviye dosyayla başlayın ve yalnızca tek bir kök dosyası çok uzun hale geldiğinde alt dizin dosyalarını ekleyin.
Ne kadar uzun olmalı? 200 ila 400 satır idealdir. Bunun ötesinde, aracılar bölümleri atlamaya başlar. Daha fazla derinliğe ihtiyacınız varsa, satır içinde tek satırlık bir özetle ayrı bir belgeye bağlantı verin.
Kod örnekleri dahil etmeli miyim? Kısa olanları evet. Uzun olanları hayır. Tam örnekleri testler için saklayın; aracılar testleri de okur. GPT-5.5 ücretsiz Codex rehberi, Codex'in örnek testleri ek sinyal olarak nasıl kullandığını özellikle ele alır.
Aracı dosyayı her seferinde yeniden okur mu? Çoğu aracı oturum başlangıcında okur ve önbelleğe alır. Bazıları büyük dosya değişikliklerinden sonra yeniden okur. Büyük bir düzenleme yaparsanız, aracı oturumunu yeniden başlatmak en güvenli harekettir.
Dosyamın çalıştığını nasıl test ederim? Başka hiçbir bağlam olmadan yeni bir aracı oturumu başlatın, ona küçük bir görev verin (“POST /payments'a 422 yanıtı ekle”) ve ne yaptığını izleyin. Spesifikasyonu okur, make codegen komutunu çalıştırır ve bir sözleşme testi yazarsa, dosya işini yapıyor demektir.