AGENTS.md ile özel talimatlar

Codex herhangi bir işe başlamadan önce AGENTS.md dosyalarını okur. Genel yönergeleri projeye özgü geçersiz kılmalarla katmanlandırarak hangi depoyu açarsanız açın her göreve tutarlı beklentilerle başlayabilirsiniz.

Codex yönergeleri nasıl keşfeder

Codex başlatıldığında bir talimat zinciri oluşturur (çalıştırma başına bir kez; TUI'de bu genellikle başlatılan oturum başına bir kez anlamına gelir). Keşif şu öncelik sırasını izler:

1. Genel kapsam: Codex ana dizininizde (CODEX_HOME ayarlanmadığı sürece varsayılan olarak ~/.codex), mevcutsa Codex AGENTS.override.md dosyasını okur. Aksi takdirde Codex AGENTS.md dosyasını okur. Codex bu düzeyde yalnızca boş olmayan ilk dosyayı kullanır.
2. Proje kapsamı: Codex, proje kökünden (genellikle Git kökü) başlayarak geçerli çalışma dizininize doğru ilerler. Codex bir proje kökü bulamazsa yalnızca geçerli dizini denetler. Yol üzerindeki her dizinde sırasıyla AGENTS.override.md, AGENTS.md ve ardından project_doc_fallback_filenames içindeki alternatif adları denetler. Codex her dizinden en fazla bir dosyayı dahil eder.
3. Birleştirme sırası: Codex dosyaları kökten aşağıya doğru, aralarına boş satırlar ekleyerek birleştirir. Geçerli dizininize daha yakın dosyalar, birleştirilmiş istemde daha sonra yer aldıkları için önceki yönergeleri geçersiz kılar.

Codex boş dosyaları atlar ve birleşik boyut project_doc_max_bytes ile tanımlanan sınıra (varsayılan olarak 32 KiB) ulaştığında dosya eklemeyi bırakır. Bu ayarlar hakkında ayrıntılı bilgi için Proje talimatlarını keşfetme bölümüne bakın. Sınıra ulaştığınızda limiti yükseltin veya talimatları iç içe dizinlere bölün.

Genel yönergeler oluşturma

Her deponun çalışma kurallarınızı devralması için Codex ana dizininizde kalıcı varsayılanlar oluşturun.

1. Dizinin mevcut olduğundan emin olun:

   mkdir -p ~/.codex

2. Yeniden kullanılabilir tercihlerle bir ~/.codex/AGENTS.md oluşturun:

   # ~/.codex/AGENTS.md
   
   ## Working agreements
   
   - Always run `npm test` after modifying JavaScript files.
   - Prefer `pnpm` when installing dependencies.
   - Ask for confirmation before adding new production dependencies.

3. Dosyanın yüklendiğini doğrulamak için Codex'i herhangi bir yerde çalıştırın:

   codex --ask-for-approval never "Summarize the current instructions."

   Beklenen: Codex, çalışma önermeden önce ~/.codex/AGENTS.md içindeki maddeleri aktarır.

Temel dosyayı silmeden geçici bir genel geçersiz kılmaya ihtiyaç duyduğunuzda ~/.codex/AGENTS.override.md kullanın. Paylaşılan yönergeleri geri yüklemek için geçersiz kılma dosyasını kaldırın.

Proje talimatlarını katmanlandırma

Depo düzeyindeki dosyalar, genel varsayılanlarınızı devralmaya devam ederken Codex'in proje kurallarından haberdar olmasını sağlar.

1. Deponuzun köküne temel kurulumu kapsayan bir AGENTS.md ekleyin:

   # AGENTS.md
   
   ## Repository expectations
   
   - Run `npm run lint` before opening a pull request.
   - Document public utilities in `docs/` when you change behavior.

2. Belirli ekipler farklı kurallara ihtiyaç duyduğunda iç içe dizinlere geçersiz kılmalar ekleyin. Örneğin services/payments/ içinde AGENTS.override.md oluşturun:

   # services/payments/AGENTS.override.md
   
   ## Payments service rules
   
   - Use `make test-payments` instead of `npm test`.
   - Never rotate API keys without notifying the security channel.

3. Codex'i payments dizininden başlatın:

   codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

   Beklenen: Codex önce genel dosyayı, ikinci olarak depo kökündeki AGENTS.md dosyasını ve son olarak payments geçersiz kılmasını bildirir.

Codex geçerli dizininize ulaştığında aramayı durdurur; bu nedenle geçersiz kılmaları uzmanlık gerektiren çalışmaya mümkün olduğunca yakın yerleştirin.

Genel bir dosya ve payments'e özgü bir geçersiz kılma ekledikten sonra örnek depo şöyle görünür:

<FileTree class="mt-4" tree={[ { name: "AGENTS.md", comment: "Depo beklentileri", highlight: true, }, { name: "services/", open: true, children: [ { name: "payments/", open: true, children: [ { name: "AGENTS.md", comment: "Bir geçersiz kılma mevcut olduğu için yok sayılır", }, { name: "AGENTS.override.md", comment: "Payments hizmeti kuralları", highlight: true, }, { name: "README.md" }, ], }, { name: "search/", children: [{ name: "AGENTS.md" }, { name: "…", placeholder: true }], }, ], }, ]} />

Kod inceleme kuralları ekleme

GitHub'da Codex kod incelemesi için, kuralların geçerli olduğu koda en yakın AGENTS.md dosyasına bir ## Code Review Rules bölümü ekleyin. Depo genelindeki denetimleri köke, hizmete özgü denetimleri ise iç içe bir dosyaya yerleştirin.

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

Kuralları kısa tutun, işaretlenecek davranışı ve güvenli yolları veya istisnaları açıklayın; biçimlendirme ve lint denetimlerini CI'a bırakın. Kurulum ve kural yazma yönergeleri için Codex'in neleri incelediğini özelleştirme bölümüne bakın.

Alternatif dosya adlarını özelleştirme

Deponuz zaten farklı bir dosya adı kullanıyorsa (örneğin TEAM_GUIDE.md), Codex'in bunu bir talimat dosyası olarak değerlendirmesi için alternatifler listesine ekleyin.

1. Codex yapılandırmanızı düzenleyin:

   # ~/.codex/config.toml
   project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
   project_doc_max_bytes = 65536

2. Güncellenen yapılandırmanın yüklenmesi için Codex'i yeniden başlatın veya yeni bir komut çalıştırın.

Codex artık her dizini şu sırayla denetler: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Bu listede olmayan dosya adları, talimat keşfi sırasında yok sayılır. Daha yüksek bayt sınırı, kırpılmadan önce daha fazla birleşik yönergeye izin verir.

Alternatifler listesi hazır olduğunda Codex alternatif dosyaları talimat olarak değerlendirir:

<FileTree class="mt-4" tree={[ { name: "TEAM_GUIDE.md", comment: "Alternatifler listesi aracılığıyla algılandı", highlight: true, }, { name: ".agents.md", comment: "Kökteki alternatif dosya", }, { name: "support/", open: true, children: [ { name: "AGENTS.override.md", comment: "Alternatif yönergeleri geçersiz kılar", highlight: true, }, { name: "playbooks/", children: [{ name: "…", placeholder: true }], }, ], }, ]} />

Projeye özgü bir otomasyon kullanıcısı gibi farklı bir profil istediğinizde CODEX_HOME ortam değişkenini ayarlayın:

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

Beklenen: Çıktı, özel .codex dizinine göreli dosyaları listeler.

Kurulumunuzu doğrulama

• Bir depo kökünden codex --ask-for-approval never "Summarize the current instructions." çalıştırın. Codex, genel ve proje dosyalarındaki yönergeleri öncelik sırasıyla yansıtmalıdır.
• İç içe geçersiz kılmaların daha genel kuralların yerini aldığını doğrulamak için codex --cd subdir --ask-for-approval never "Show which instruction files are active." kullanın.
• Codex'in hangi talimat dosyalarını yüklediğini denetlemek için codex -c log_dir=./.codex-log ile düz metin TUI günlüğünü etkinleştirip ./.codex-log/codex-tui.log dosyasını kontrol edin veya oturum günlüğünü etkinleştirdiyseniz en yeni session-*.jsonl dosyasını inceleyin.
• Talimatlar eski görünüyorsa Codex'i hedef dizinde yeniden başlatın. Codex talimat zincirini her çalıştırmada (ve her TUI oturumunun başında) yeniden oluşturur; dolayısıyla elle temizlenecek bir önbellek yoktur.

Keşif sorunlarını giderme

• Hiçbir şey yüklenmiyor: Amaçlanan depoda olduğunuzu ve codex status çıktısının beklediğiniz çalışma alanı kökünü bildirdiğini doğrulayın. Talimat dosyalarının içerik barındırdığından emin olun; Codex boş dosyaları yok sayar.
• Yanlış yönergeler görünüyor: Dizin ağacının daha üstünde veya Codex ana dizininizin altında bir AGENTS.override.md olup olmadığını kontrol edin. Normal dosyaya geri dönmek için geçersiz kılmayı yeniden adlandırın veya kaldırın.
• Codex alternatif adları yok sayıyor: Adları project_doc_fallback_filenames içinde yazım hatası olmadan listelediğinizi doğrulayın, ardından güncellenen yapılandırmanın geçerli olması için Codex'i yeniden başlatın.
• Talimatlar kırpılıyor: Kritik yönergeleri korumak için project_doc_max_bytes değerini yükseltin veya büyük dosyaları iç içe dizinlere bölün.
• Profil karışıklığı: Codex'i başlatmadan önce echo $CODEX_HOME çalıştırın. Varsayılan olmayan bir değer, Codex'i düzenlediğinizden farklı bir ana dizine yönlendirir.

Sonraki adımlar

• Daha fazla bilgi için resmî AGENTS.md web sitesini ziyaret edin.
• Kalıcı yönergelerle iyi çalışan konuşma kalıpları için Codex'e istem yazma bölümünü inceleyin.