Codex'e Projenizi Öğretmek: AGENTS.md Zinciri, config.toml, Skills ve MCP

Sürüm notu: Bu yazı Codex CLI 0.169.0'ı (13 Kasım 2026) anlatır; talimat keşfi, configuration katmanları ve skill ayrıntıları 15 Kasım 2026'da learn.chatgpt.com/docs'taki Custom instructions with AGENTS.md, Config basics, Advanced Configuration, Configuration Reference, Build skills, Model Context Protocol ve Import from another agent sayfalarından, alt dizinlerdeki dosyalarla ilgili davranış aynı gün github.com/openai/codex'teki base instructions dosyasından kontrol edilmiştir. Bu yazıda resmî belgelerden yararlanılmıştır. Örnek config.toml dosyaları yerelde ayrıştırılıp Codex'in resmî JSON şemasıyla doğrulanmış, skill dosyalarının YAML (insan tarafından okunabilir veri formatı) frontmatter'ı ayrıştırılmıştır.

Önce Tahmin Et

Emre, sitedeki serilerin ortak örnek uygulaması Bookstore'da (bir online kitapçı) Codex'e bir hafta boyunca aynı şeyleri tekrar tekrar anlatmaktan yoruldu ve hepsini dosyalara yazdı. Kendi ~/.codex/AGENTS.md'sine "paket kurarken pnpm kullan" yazdı. Repo kökündeki AGENTS.md'ye build komutlarını, katman kurallarını ve mimari dokümanın tamamını yapıştırdı; dosya 40 KB'ı geçti. Angular kurallarını da web/bookstore-web/AGENTS.md'ye koydu ve Codex'i her zamanki gibi repo kökünde başlattı.

Tahminin ne? Repo npm kullanıyorken Codex hangi paket yöneticisini seçer? 40 KB'lık dosyanın hangi kısmı modele ulaşır? Ve kökte başlatılan bir session'da Angular kuralları otomatik olarak yüklenir mi? Cevaplar zincir bölümünde ve Bookstore bölümünde.

Talimat dosyalarının araçtan bağımsız tarafını, yani bir AGENTS.md'ye ne yazılır, ne yazılmaz sorusunu AI Destekli Geliştirme serisinin ikinci yazısında (/blog/agentsmd-copilot-instructions-context-dosyalari) anlatmıştık. Bu yazı Codex'in mekaniğine odaklanıyor: hangi dosya hangi sırayla okunur, configuration hangi katmandan gelir, tekrar eden iş nasıl skill olur ve MCP (Model Context Protocol; agent'ların dış tool ve veri kaynaklarına bağlandığı açık protokol) server'ı nereye tanımlanır.

AGENTS.md Zinciri Nasıl Kuruluyor?

Codex bir session başlarken bir talimat zinciri kuruyor ve bunu her çalıştırmada yeniden yapıyor; temizlenmesi gereken bir cache yok. Belgelerdeki sıra üç adım:

• Global: Codex home klasöründe (varsayılan ~/.codex, Windows'ta %USERPROFILE%\.codex) önce AGENTS.override.md'ye, yoksa AGENTS.md'ye bakar ve bu seviyede yalnız ilk dolu dosyayı alır.
• Proje: proje kökünden (genelde Git kökü) çalışma dizinine kadar her dizinde sırayla AGENTS.override.md, AGENTS.md ve project_doc_fallback_filenames'teki adlara bakar; her dizinden en fazla bir dosya alır.
• Birleştirme: dosyalar kökten aşağıya doğru, aralarında boş satırla art arda eklenir. Çalışma dizinine yakın olan dosya prompt'ta daha sonra geldiği için öncekini ezer.

Tahmindeki ilk sorunun cevabı bu sırada. Global dosya zincirin başında, repo kökündeki dosya ondan sonra geliyor. Kök AGENTS.md açıkça "npm kullan" diyorsa o kural daha geç geldiği için kazanıyor; repo bu konuda hiçbir şey demiyorsa Codex'in global tercihi uygulaması beklenir. Proje kuralını global dosyaya yazmak bu yüzden hem başka repo'ları etkiliyor hem de projede neyin geçerli olduğunu belirsizleştiriyor.

Boş dosyalar atlanıyor ve birleşik içerik project_doc_max_bytes sınırına (varsayılan 32 KiB, yani 32.768 byte) ulaşınca Codex dosya eklemeyi bırakıyor. İkinci sorunun cevabı da burada: Emre'nin 40 KB'lık dosyasının ilk 32 KiB'tan sonrası modele hiç ulaşmıyor, üstelik belgelere göre sınıra gelindikten sonra alt dizinlerdeki dosyalar da eklenmiyor. Sınırı yükseltmek mümkün ama belgelerin asıl önerisi talimatları iç içe dizinlere bölmek. Pricing sayfası da kullanım limitini uzatmak için AGENTS.md'yi küçük tutmayı ve iç içe dizinlere bölmeyi öneriyor; dosyanın içeriği context'e ekleniyor.

Üçüncü soru biraz daha ince. Zincir yalnız proje kökünden çalışma dizinine giden yolu kapsıyor; Codex'i kökte başlattıysan web/bookstore-web/AGENTS.md başlangıçta prompt'a eklenmiyor. Codex'in GitHub'daki açık kaynak base instructions dosyası modele, çalışma dizininin altındaki bir klasörde iş yaparken orada geçerli olabilecek AGENTS.md dosyalarını kontrol etmesini ve bir dosyanın kapsamının bulunduğu klasörün tamamı olduğunu söylüyor. Yani alt dizindeki kurallar model tarafından okunuyor, ama bu Codex'in garanti ettiği bir yükleme değil, modelin izlediği bir talimat. Angular'da yoğun çalışacağın bir session'ı codex -C web/bookstore-web ile başlatmak kuralların kesin olarak zincire girmesini sağlıyor.

Bookstore: Kökte Tek Kaynak, Alt Klasörde Ayrıntı

Bookstore'un kök AGENTS.md'si kısa tutuldu: komutlar, yerleşim ve kurallar. Mimari doküman dosyaya kopyalanmıyor; gerekirse Codex onu repo'dan kendisi okuyabilir.

# Bookstore

Online bookstore: ASP.NET Core 10 API, Angular 22 client, SQL Server.
See README.md for local setup.

## Build and test
- Build: `dotnet build Bookstore.slnx`
- API tests: `dotnet test` (needs SQL Server; the connection string `ConnectionStrings:BookstoreDb` is in user-secrets)
- Client: run `npm test` and `npm run build` in `web/bookstore-web`
- Run the relevant tests before you say a change is done, and show the test summary.

## Layout
- `src/Bookstore.Api`: endpoints, EF Core `BookstoreContext`, migrations in `src/Bookstore.Api/Data/Migrations`
- `src/Bookstore.Contracts`: DTOs shared with the client; no reference to EF Core
- `tests/Bookstore.Api.Tests`: API tests
- `web/bookstore-web`: Angular client with its own `AGENTS.md`

## Rules
- Money is `decimal` with currency `TRY`; times are stored in UTC.
- Endpoints return `ProblemDetails` on errors.
- Read-only EF Core queries use `AsNoTracking()` and pass the `CancellationToken` through.
- Never edit an existing migration; add a new migration instead (see the `add-migration` skill).
- Never put secrets in code or appsettings files; use user-secrets locally.
- Ask before adding a NuGet or npm package.

Alana özel kurallar o alanın klasöründe duruyor. Angular kuralları web/bookstore-web/AGENTS.md'de, migration kuralları da src/Bookstore.Api/Data/Migrations/AGENTS.md'de:

# Migrations

- Files in this folder are generated by `dotnet ef migrations add`. Never edit or delete a migration that is already committed.
- To change the schema, add a new migration with the `add-migration` skill and review the generated SQL.
- Never run `dotnet ef database update` against any database; the developer applies migrations.

Üç dosyanın toplamı yaklaşık 2 KB; 32 KiB sınırının çok altında. AGENTS.override.md ise ekip dosyası değil. Belgelerde geçici bir global ya da dizin bazlı geçersiz kılma olarak anlatılıyor; aynı dizinde bir override varsa o dizinin AGENTS.md'si hiç okunmuyor. Bu yüzden Bookstore'da .gitignore'a eklendi; kişisel bir deneme yapan geliştirici kendi override'ını yazıp sonra silebiliyor. Belgelere göre Codex, git'in yok saydığı bir AGENTS.override.md'yi kendi yönettiği worktree'lere de kopyalıyor. Zincirin doğru kurulduğunu görmenin en kısa yolu belgelerdeki kontrol:

codex -a never "Summarize the current instructions."
codex --cd web/bookstore-web -a never "Show which instruction files are active."

İki Araçta Ortak Talimat: Claude Code ve Codex

Bookstore ekibi Claude Code'u da kullanıyor. Claude Code serisinin ikinci yazısında (/blog/claude-code-claude-md-memory-rules) gördüğümüz gibi Claude Code, CLAUDE.md yoksa AGENTS.md'yi okuyabiliyor; Windows için en taşınabilir yol da @AGENTS.md satırıyla başlayan kısa bir CLAUDE.md. İki seçenek var:

• Kaynak AGENTS.md, CLAUDE.md onu import ediyor: Codex kendi dosyasını doğal yoldan okuyor, Claude Code'a özgü birkaç satır CLAUDE.md'de kalıyor. Bedeli, Claude Code'a özgü ayrıntıların (path'e özel kurallar gibi) ayrı dosyalarda kalması.
• Kaynak CLAUDE.md, Codex onu project_doc_fallback_filenames = ["CLAUDE.md"] ile okuyor: Claude Code tarafı hiç değişmiyor. Bedeli, Claude Code'a özgü talimatların Codex'e de gitmesi; Codex belgelerinde @ ile import diye bir mekanizma yok, o satırlar düz metin olarak okunuyor.

Bookstore ilk yolu seçti, çünkü ekipteki üçüncü araçlar da AGENTS.md'yi okuyor. Mevcut bir Claude Code kurulumunu taşıyacak olan için Codex'in bir kısayolu da var: CLI'da /import, desktop app'te Settings > Import. Belgelere göre talimat dosyaları AGENTS.md'ye, settings.json config.toml'a, slash command'lar skill'lere, MCP ve hook tanımları da Codex karşılıklarına aktarılıyor ve Claude Code tarafındaki kurulum değişmiyor. Aktarılanı commit'lemeden önce diff olarak okumak gerekiyor; iki aracın izin modeli birebir aynı değil (üçüncü yazı).

config.toml: Katmanlar ve Güven

Codex'in ayarları TOML (Tom's Obvious, Minimal Language; anahtar-değer tabanlı configuration dosya formatı) formatında ve birden çok katmandan geliyor. Belgelerdeki öncelik sırası, en güçlüden başlayarak şöyle: komut satırı bayrakları ve -c ile verilen değerler; projedeki .codex/config.toml dosyaları (kökten çalışma dizinine, yakın olan kazanır); --profile ile seçilen profil dosyası; kullanıcı dosyası ~/.codex/config.toml; workspace için cloud'dan gelen varsayılanlar; sistem dosyası; yerleşik varsayılanlar. Desktop app, CLI ve IDE extension bu katmanları paylaşıyor.

Proje katmanının bir koşulu var: Codex proje .codex/ klasörünü yalnız proje güvenilir olarak işaretlendiğinde yüklüyor. Güvenilmeyen bir projede proje configuration'ı, proje hook'ları ve proje rules dosyaları atlanıyor; kullanıcı ve sistem katmanları yine yükleniyor. Ayrıca belgelere göre proje dosyası kimlik bilgisini başka yere yönlendiren ya da makineye özel komut çalıştıran anahtarları değiştiremiyor: model_provider, openai_base_url, notify, profile ve otel gibi anahtarlar proje dosyasında yok sayılıyor ve açılışta uyarı veriliyor. Bir repo'yu klonlamak, o repo'nun senin kimliğini başka bir sunucuya göndermesine izin vermek anlamına gelmiyor.

Emre'nin kişisel dosyası model ve reasoning effort varsayılanını ve giriş bilgisinin işletim sisteminin credential store'unda tutulmasını belirliyor. Projeye güvendiğinde Codex'in kaydettiği satır da burada duruyor:

#:schema https://developers.openai.com/codex/config-schema.json
# Kişisel varsayılanlar: Windows'ta %USERPROFILE%\.codex\config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
cli_auth_credentials_store = "keyring"

# Klasöre güvendiğinde Codex bu satırı yazar
[projects.'C:\src\bookstore']
trust_level = "trusted"

İlk satırdaki #:schema yorumu belgelerin önerisi: Even Better TOML extension'ı bu şemayla Visual Studio Code (VS Code) ve Cursor'da otomatik tamamlama ve hata işaretleme yapıyor. Aynı şema additionalProperties: false ile tanımlı, yani yanlış yazılmış bir anahtarı da yakalıyor; bu yazıdaki dosyalar onunla doğrulandı. Komut satırında da --strict-config bayrağı, Codex'in tanımadığı bir alan gördüğünde hata vermesini sağlıyor.

Profiller 0.134'ten beri ayrı dosyalar. codex --profile deep-review, önce kullanıcı dosyasını, sonra yanındaki deep-review.config.toml'u yüklüyor; profil dosyasına yalnız farklı olan değerleri yazıyorsun. Eski [profiles.x] tabloları ve profile = "x" seçicisi artık okunmuyor. Hangi değerin hangi katmandan geldiğini session içinde /debug-config gösteriyor.

# %USERPROFILE%\.codex\deep-review.config.toml; kullanım: codex --profile deep-review
model = "gpt-6-astra"
model_reasoning_effort = "high"

Skills: Tekrar Eden İşi Paketlemek

Bir iş akışını her seferinde prompt'a yazmak yerine skill olarak paketleyebilirsin. Skill, içinde SKILL.md bulunan bir klasör; frontmatter'da name ve description zorunlu, yanına script'ler, referans dokümanlar ve şablonlar eklenebiliyor. Codex açık agent skills standardını kullanıyor. Repo skill'leri çalışma dizininden repo köküne kadar her dizindeki .agents/skills klasöründen, kişisel skill'ler $HOME/.agents/skills'ten okunuyor. Codex skill-creator ve skill-installer adlı iki skill'i de kendisiyle birlikte getiriyor.

Context'i korumak için Codex başta yalnız skill'lerin adını, açıklamasını ve dosya yolunu görüyor; bu liste varsayılan olarak context window'un en fazla yüzde 2'sini kaplıyor. Bir skill'i kullanmaya karar verdiğinde SKILL.md'nin tamamını okuyor. Skill iki yoldan devreye giriyor: açıkça (/skills ya da prompt'ta $add-migration) veya örtük olarak, iş açıklamaya uyduğunda. Migration gibi riskli bir işin kendiliğinden başlamasını istemiyoruz; bu yüzden Bookstore'un skill'i örtük çağrıyı agents/openai.yaml'da kapatıyor:

---
name: add-migration
description: Create a new EF Core migration in src/Bookstore.Api, review the generated SQL and write rollback notes. Use only when the user explicitly asks for $add-migration with a migration name.
---

# Add an EF Core migration

The user gives the migration name in the prompt, for example `$add-migration AddLowStockAlerts`.

1. If the name is missing or not PascalCase, ask for a name and stop.
2. Build the solution: `dotnet build Bookstore.slnx`. Stop and report if the build fails.
3. Find the latest existing migration: `dotnet ef migrations list --project src/Bookstore.Api`.
4. Create the migration:
   `dotnet ef migrations add <Name> --project src/Bookstore.Api --output-dir Data/Migrations`
5. Generate the SQL from the previous migration to the new one:
   `dotnet ef migrations script <Previous> <Name> --project src/Bookstore.Api --output artifacts/migrations/<Name>.sql`
6. Read the migration and the SQL, then report:
   - tables and columns that are added, changed or dropped
   - anything that can lose data: dropped columns, narrowed types, NOT NULL without a default
   - indexes the new queries need that the migration does not create
7. Write `artifacts/migrations/<Name>.rollback.md` with the previous migration name and the command
   `dotnet ef database update <Previous> --project src/Bookstore.Api`.

Never apply the migration to a database and never edit an existing migration.

interface:
  display_name: "Add EF Core migration"
  short_description: "Create a migration, review its SQL and write rollback notes"

policy:
  allow_implicit_invocation: false

Eski blog yazılarında gördüğün ~/.codex/prompts/ altındaki custom prompt'lar deprecated. Yalnız açık çağrıyla çalışıyorlar ve kişisel klasörde durdukları için repo ile paylaşılmıyorlar; belgeler yerlerine skill önermesinin sebebi bu. Bir skill'i başka ekiplere dağıtmak istersen onu bir plugin'e koyuyorsun; plugin birden çok skill'i ve MCP bağlantılarını tek paket olarak taşıyabiliyor.

MCP Server Tanımı

MCP server'lar da config.toml'da, [mcp_servers.<name>] tablolarıyla tanımlanıyor; kişisel olanlar kullanıcı dosyasında, ekibin ortak kullandıkları güvenilir projenin .codex/config.toml'unda. Desktop app, CLI ve IDE extension aynı makinede bu tanımları paylaştığı için bir kez kurmak yetiyor. Bookstore'un Angular arayüzünü tarayıcıda test etmek için proje dosyasına Playwright MCP server'ı eklendi:

#:schema https://developers.openai.com/codex/config-schema.json
# Bookstore proje ayarları. Codex bu dosyayı yalnız proje güvenilirse yükler.

[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@0.0.85"]
startup_timeout_sec = 30
default_tools_approval_mode = "prompt"

Paket sürümü bilinçli olarak sabitlendi; @latest her açılışta başka bir kodun çalışması demek. startup_timeout_sec varsayılan 10 saniye; ilk açılışta npx'in paketi indirmesi bundan uzun sürebiliyor. default_tools_approval_mode = "prompt" server'ın tool'larını her çağrıda onaya bağlıyor; writes yalnız read-only olarak işaretlenmemiş tool'ları sorduruyor. Belirli tool'ları enabled_tools ve disabled_tools ile açıp kapatabiliyorsun. Komut satırında aynı işi codex mcp add, codex mcp list ve OAuth isteyen server'lar için codex mcp login yapıyor; session içinde aktif server'ları /mcp listeliyor.

MCP server yazmanın kendisi AI Agent'ları ve MCP serisinde anlatıldı; Claude Code tarafındaki karşılığı da "Claude Code'a MCP Server Bağlamak: Bookstore MCP Server'ı, Veritabanı ve Tarayıcı" yazısında (/blog/claude-code-mcp-server-baglamak). Codex'te dikkat edilecek bir maliyet noktası var: Pricing sayfasına göre her MCP server mesajlara context ekliyor ve kullanım limitini tüketiyor; ihtiyacın olmayan server'ı enabled = false ile kapat.

Üretimde Dikkat

AGENTS.md'yi kod gibi review et. Kök dosyaya eklenen tek bir satır ekipteki herkesin her session'ına giriyor. Kısa tut, komutları güncel tut ve bir kural iki kez yanlış uygulandığında metni netleştir; kural sayısını artırmak çoğu zaman çözüm değil.

Proje .codex/ klasörü de review gerektiriyor. Güvendiğin bir repo'nun config.toml'u senin makinende komut başlatan MCP server'ları, hook'ları ve rules dosyalarını devreye sokuyor. Yabancı bir repo'yu klonladığında önce bu klasöre bak, sonra güven.

Secret'ları configuration'a yazma. Belgeler, gizli bir OAuth client'ı için codex mcp add'in client secret'ı config.toml'a kaydettiğini ve o dosyanın gizli tutulması gerektiğini söylüyor; böyle bir değer hiçbir zaman projenin commit'lenen dosyasına girmemeli. Token gereken HTTP server'larında bearer_token_env_var ile ortam değişkeni adını vermek daha güvenli.

Sık Düşülen Tuzaklar

32 KiB'ı aşmak. Sınırdan sonrası sessizce düşüyor. Dosyayı böl, mimari dokümanı kopyalamak yerine yolunu yaz.

Çelişen iç içe dosyalar. Kök "npm" derken alt klasör "pnpm" diyorsa yakın olan kazanır ama okuyan herkes kafası karışık kalır. Çelişkiyi kaldır, istisnayı açıkça yaz.

Proje kuralını global dosyaya yazmak. ~/.codex/AGENTS.md kişisel çalışma tercihleri içindir; başka repo'larda da geçerli olur.

Eski profil syntax'ı. [profiles.x] tabloları 0.134'ten beri okunmuyor; profil ayrı bir x.config.toml dosyası.

Güvenilmeyen projede .codex/'in çalışmasını beklemek. Proje güvenilmediyse MCP server'ı, hook ve rules dosyaları hiç yüklenmez; /debug-config bunu gösterir.

Küçük Bir Deneme

★☆☆ Kendi repo'nda /init ile bir AGENTS.md iskeleti üret, içinden gereksiz satırları sil ve byte boyutunu not et. Sonra "Summarize the current instructions." prompt'unu çalıştırıp hangi kuralların geri geldiğine bak.

★★☆ Bir alt klasöre AGENTS.md koy ve Codex'i bir kez kökte, bir kez --cd ile o klasörde başlat. "Show which instruction files are active." cevabı iki durumda nasıl farklı?

★★★ Ekibinde tekrar eden bir işi (migration, release notu, yeni endpoint iskeleti) skill olarak yaz, örtük çağrıyı kapat ve iki hafta boyunca $skill ile kullan. Hangi adımlar en çok düzeltme gerektirdi?

Codex artık Bookstore'un kurallarını biliyor; ama bir kuralı bilmek onu uygulayacağının garantisi değil. Üçüncü yazıda kurala değil teknik sınıra bakacağız: sandbox modları, approval policy, auto-review, Windows sandbox ve rules dosyaları.