OpenAI GPT Codex CLI ve Bulut Ajanları: Hiyerarşik AGENTS.md Mimarisi, İzole Sandbox ve En Popüler 10 Mühendislik Skill’i

Terminalden Bulut Konteynerine: OpenAI Codex Mimarisi Nasıl Çalışır?

Otonom yazılım mühendisliğinde 2026 yılı itibarıyla en kritik mimari ayrım, geliştiricinin yerel terminalinde senkron çalışan ajanlar ile bulut üzerinde paralel MicroVM konteynerlerinde asenkron görev yürüten ajanların tek bir standart altında birleşmesidir. OpenAI GPT Codex CLI (Rust tabanlı yerel çalışma zamanı) ve Codex Cloud Agents (bulut tabanlı paralel görev yürütücüleri), bu birleşimi üç temel mühendislik katmanı üzerinde gerçekleştirir:

1. Hiyerarşik AGENTS.md İşletim Sözleşmesi: Depo kökünden alt modüllere kadar uzanan, ajana derleme/test komutlarını, mimari sınırları ve kabul kriterlerini bildiren açık standartlı talimat katmanı.
2. Çekirdek Seviyesinde Sandbox İzolasyonu (Landlock, Seatbelt ve Air-Gapped MicroVM): Her araç çağrısında kullanıcıdan manuel onay istemek yerine, ajanı varsayılan olarak dış ağ erişimi kapatılmış (network-disabled) ve yalnızca çalışma dizinine yazabilen (workspace-write) işletim sistemi kafeslerinde çalıştıran güvenlik mimarisi.
3. Modüler Yetenek Paketleri (.codex/skills/<ad>/SKILL.md ve config.toml): Tekrarlanan karmaşık mühendislik operasyonlarını (CI/CD onarımı, CVE yamama, monorepo sürüm göçü) deterministik doğrulama adımlarıyla standartlaştıran taşınabilir yetenekler.

Bu kapsamlı teknik rehberde, kurumsal ölçekte AGENTS.md ve .codex/config.toml kurgusu ile üretim ortamında en yoğun kullanılan 10 otonom Codex mühendislik yeteneği (skill) şablonları ve mimari karşılaştırma tablosuyla incelenmektedir.

1. Hiyerarşik AGENTS.md Standardı ve .codex/config.toml Kurgusu

OpenAI Codex hem yerel CLI oturumunda hem de bulut konteynerinde göreve başlarken dosya sistemini tarayarak üç katmanlı bir talimat zinciri (instruction chain) inşa eder:

• Küresel Katman (~/.codex/AGENTS.md ve ~/.codex/config.toml): Kuruluş genelindeki güvenlik politikaları, tercih edilen model profilleri, MCP (Model Context Protocol) sunucu bağlantıları ve genel kodlama disiplini.
• Depo Kök Katmanı (./AGENTS.md): Projenin mimari topolojisi, paket yöneticisi kuralları, zorunlu test ve linter komutları ile PR kabul şartları.
• Alt Dizin / Servis Katmanı (./packages/billing/AGENTS.md): Yalnızca ajan ilgili paketteki dosyalara dokunduğunda bağlama dahil edilen, alana özgü (domain-specific) veri ve iş mantığı değişmezleri.

Üretim Kalitesinde AGENTS.md ve .codex/config.toml Şablonu

Aşağıdaki yapılandırma, hem yerel Codex CLI hem de bulut ajanları için sıfır belirsizlik bırakan kurumsal bir AGENTS.md ve config.toml örneğini göstermektedir:

<!-- Dosya: ./AGENTS.md -->
# Kurumsal Mikroservis Monorepo — Ajan İşletim Sözleşmesi (AGENTS.md)

## 1. Derleme, Test ve Kalite Kapısı Komutları
- **Hızlı Birim Testi:** `pnpm --filter <paket-adi> test:unit`
- **Tam Tip ve Linter Doğrulaması:** `pnpm turbo run typecheck lint --affected`
- **Veritabanı Entegrasyon Testi:** `./scripts/run-isolated-pg-tests.sh`

## 2. Mimari Değişmezler (Invariants)
- **Katman İzolasyonu:** `domain/` sınıfları hiçbir koşulda `infrastructure/` veya HTTP çerçeve paketlerini içe aktaramaz.
- **Veritabanı Güvenliği:** Tüm yeni SQL migration dosyaları geriye dönük uyumlu (Expand-and-Contract) olmalı; indeks tanımları `CONCURRENTLY` içermelidir.
- **Hata Yönetimi:** Boş `catch` blokları yasaktır; tüm dış servis hataları yapılandırılmış `AppResult<T, E>` zarfıyla dönülmelidir.

## 3. Görev Tamamlama (Definition of Done) Protokolü
1. Değiştirilen her modül için ilgili birim ve regresyon testleri çalıştırılır.
2. `pnpm turbo run typecheck lint` çıktısında sıfır hata ve sıfır uyarı doğrulanır.
3. API uç noktası değiştiyse `pnpm run openapi:generate` çalıştırılarak şema senkronizasyonu kanıtlanır.

# Dosya: .codex/config.toml
model = "gpt-6-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false
writable_roots = [".", "/tmp/codex-build-cache"]

[profiles.ci_healer]
sandbox_mode = "workspace-write"
approval_policy = "never"

[mcp_servers.postgres_audit]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://auditor@localhost:5432/test_db"]

2. OpenAI Codex CLI ve Bulut Ajanları İçin En Popüler 10 Mühendislik Skill’i

Aşağıdaki 10 yetenek paketi, yazılım mühendisliği ekiplerinin Codex CLI ve Bulut Ajanlarını günlük geliştirme, güvenlik ve altyapı bakımında otonomlaştırmak için kullandığı en yüksek etkili iş akışlarıdır.

Yetenek 1: İzole Sandbox Container İçinde Otonom Test Koşumu (sandbox-test-runner)

Otonom ajanların test koşarken dış ağdaki gerçek ödeme geçitlerine istek atması veya yerel sistem dosyalarını bozması en büyük operasyonel risktir. Codex mimarisi bu sorunu iki aşamalı konteyner yaşam döngüsüyle çözer:

1. Kurulum Aşaması (setup.sh — Ağ Açık): Konteyner ayağa kalkarken yalnızca güvenilir paket kayıt defterlerinden (npm, Maven Central, PyPI) bağımlılıklar indirilir ve yerel önbelleğe yazılır.
2. Ajan Yürütme Aşaması (Ağ Kapalı / Air-Gapped): Ajan görevi devraldığı anda Linux çekirdeğinde Landlock + seccomp (macOS'ta Seatbelt) devreye girerek dış ağ soketlerini tamamen kapatır. Ajan yalnızca çalışma ağacına (workspace-write) yazabilir ve tüm testleri %100 izole ortamda çalıştırır.

#!/usr/bin/env bash
# Dosya: .codex/setup.sh (Ağ kapatılmadan önce çalışan deterministik hazırlık betiği)
set -euo pipefail

echo "[Codex Sandbox Setup] Bağımlılıklar çevrimdışı önbelleğe alınıyor..."
pnpm install --frozen-lockfile --prefer-offline
./mvnw dependency:go-offline -B -q

# Yerel bellek içi (in-memory) test veritabanı ve şemasını hazırla
pg_ctl -D /var/lib/postgresql/data -l /tmp/pg.log start
psql -U postgres -c "CREATE DATABASE codex_sandbox_test;"
pnpm --filter @core/db prisma migrate deploy

echo "[Codex Sandbox Setup] Hazır. Dış ağ erişimi kapatılarak ajan oturumu başlatılabilir."

Yetenek 2: Kırılan CI/CD Pipeline’larını Otomatik İyileştirme (self-healing-ci)

Büyük mühendislik organizasyonlarında mühendis zamanının önemli bir kısmı kırılan CI/CD hatlarını (bağımlılık uyuşmazlıkları, eksik tip tanımları, ortam yapılandırma kaymaları) incelemekle geçer. self-healing-ci yeteneği, başarısız bir GitHub Actions veya GitLab CI çalışmasının log çıktısını girdi olarak alır:

• Hata imzasını (derleyici hatası, başarısız test, linter ihlali veya Docker katman hatası) sınıflandırır.
• İzole sandbox içinde hatayı birebir yeniden üretir (reproduce).
• Minimum satır değişikliğiyle yamayı uygular, tüm pipeline adımlarını yerel konteynerde yeşile çevirir ve kanıt loglarıyla birlikte düzeltme PR'ını açar.

Yetenek 3: Çoklu Repo (Monorepo) Bağımlılık ve Sürüm Göçü (monorepo-migration)

Yüzlerce paketten oluşan bir monorepo'da temel bir kütüphanenin (örneğin React, Spring Boot, Zod veya iç SDK) ana sürümünü yükseltmek haftalar süren manuel refaktör gerektirir. Codex Bulut Ajanları bu süreci paralel konteynerlere bölerek yürütür:

• Önce AST (Soyut Sözdizimi Ağacı) tabanlı bir dönüşüm betiği (jscodeshift veya OpenRewrite kuralı) üretilir.
• Ardından etkilenen her alt paket için derleme grafiği (pnpm turbo run build --filter=...[HEAD^1]) çalıştırılarak kırılan uç noktalar otonom olarak yeni API imzalarına uyarlanır.

Yetenek 4: Eski Kod Tabanlarını (Legacy Code) Modernize Etme (legacy-modernizer)

Bankacılık, sigorta ve kamu sistemlerindeki eski kod tabanlarının (Java 8'den Java 25 sanal iş parçacıklarına ve record yapılarına geçiş veya eski COBOL/VB modüllerinin modern mikroservislere taşınması) modernizasyonunda en büyük tehlike gizli iş kurallarının kaybolmasıdır. legacy-modernizer yeteneği:

1. Önce mevcut eski modülün tüm girdi/çıktı kombinasyonlarını kaydeden bir Altın Standart (Golden Master / Characterization Test) paketi üretir.
2. Kodu hedef modern mimariye dönüştürür.
3. Hem eski hem yeni kodu aynı test vektörleriyle koşturarak %100 davranışsal eşdeğerliği kanıtlar.

Yetenek 5: Otomatik Güvenlik Yaması ve CVE Kapatma (cve-auto-patcher)

Güvenlik tarayıcıları (Trivy, Snyk, Dependabot, CodeQL) her gün yüzlerce güvenlik açığı (CVE) bildirir; ancak bunların hangisinin gerçekte sömürülebilir olduğu ve sistemi kırmadan nasıl yamalanacağı ciddi bir darboğazdır. cve-auto-patcher yeteneği:

• Bildirilen CVE veya CWE (ör. SQL Injection, Path Traversal, SSRF, Deserialization) için önce izole sandbox içinde zafiyeti tetikleyen bir Sömürü Kanıtı Testi (Proof-of-Concept Security Test) yazar.
• Testin mevcut kodda güvenlik ihlali oluşturduğunu doğruladıktan sonra savunmasız kod bloğunu veya geçişli (transitive) bağımlılığı yamalar.
• PoC testinin artık engellendiğini ve mevcut regresyon testlerinin tamamının geçtiğini kanıtlar.

Yetenek 6: Uçtan Uca (E2E) Regresyon Test Üretimi (e2e-regression-gen)

Yalnızca mutlu yolu (happy path) test eden birim testleri, servisler arası entegrasyon hatalarını yakalayamaz. e2e-regression-gen yeteneği, uygulama rotalarını ve durum geçişlerini analiz ederek Playwright veya Testcontainers tabanlı uçtan uca test senaryoları üretir:

• Rastgele bekleme süreleri (sleep) yerine deterministik ağ ve DOM durumu beklemeleri kullanarak kırılgan olmayan (non-flaky) testler inşa eder.
• Ağ zaman aşımı, çift tıklama (idempotency ihlali) ve yetkisiz rol erişimi gibi sınır durumlarını otomatik olarak kapsama ekler.

Yetenek 7: Veritabanı Sorgu Optimizasyonu (sql-query-optimizer)

Üretim veritabanlarında CPU ve G/Ç darboğazına yol açan yavaş sorgular için sql-query-optimizer yeteneği doğrudan PostgreSQL/MySQL yürütme planlarıyla çalışır:

• EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) çıktısını ayrıştırarak milyonlarca satırı tarayan Seq Scan ve yüksek maliyetli Nested Loop düğümlerini bulur.
• Sorguyu ortak tablo ifadeleri (CTE), pencere fonksiyonları veya birleşik kapsayıcı indeksler (CREATE INDEX CONCURRENTLY ... INCLUDE (...)) ile yeniden yazar ve tampon okuma (shared hit/read) sayısındaki düşüşü matematiksel olarak raporlar.

Yetenek 8: API Dokümantasyon ve OpenAPI 3.1 Senkronizasyonu (openapi-contract-sync)

Kod tabanı hızla değişirken API dokümantasyonunun geride kalması, entegrasyon ekiplerini ve dış müşterileri yanıltır. openapi-contract-sync yeteneği:

• Arka uç Controller/Handler sınıflarını, DTO doğrulama anotasyonlarını (@Valid, Zod şemaları) ve HTTP durum kodlarını kaynak koddan okur.
• openapi.yaml (OpenAPI 3.1) spesifikasyonunu, örnek istek/yanıt gövdelerini ve istemci SDK tip tanımlarını kodla birebir eşleşecek şekilde günceller.

Yetenek 9: Performans Benchmark Doğrulaması (perf-benchmark-gate)

Performans iyileştirmesi iddiasıyla açılan PR'ların gerçekten hızlanma sağlayıp sağlamadığını doğrulamak için perf-benchmark-gate yeteneği mikro-benchmark motorlarını (Java JMH, Rust Criterion, Go bench, Node Vitest bench) kullanır:

• İzole konteynerde önce mevcut dalı (main) ardından yeni yamayı çoklu ısınma (warmup) turlarıyla koşturur.
• Ortalama gecikme (ns/op), kuyruk gecikmesi (p99) ve işlem başına bellek tahsisi (B/op) metriklerini karşılaştırarak istatistiksel olarak anlamlı bir regresyon varsa yamayı reddeder.

Yetenek 10: Çok Aşamalı Görev Planlama (PLANS.md ve Hiyerarşik AGENTS.md)

Onlarca dosyaya yayılan büyük özellik geliştirmelerinde veya mimari dönüşümlerde ajanın tek seferde kod yazmaya başlaması başarısızlıkla sonuçlanır. Codex'in Çok Aşamalı Planlama (multi-stage-planner) yeteneği:

1. Görevi başlamadan önce depo içinde PLANS.md (veya .codex/ACTIVE_PLAN.md) adlı yaşayan bir mimari plan dosyası oluşturur.
2. İşi bağımsız doğrulanabilir kilometre taşlarına (Milestones 1..N) böler.
3. Her kilometre taşını tamamladığında testleri çalıştırır, PLANS.md içindeki ilgili adımı [x] olarak işaretler, keşfedilen teknik notları kaydeder ve bir sonraki aşamaya temiz bir durumla geçer.

3. En Popüler 10 OpenAI Codex Mühendislik Yeteneğinin Mimari Karşılaştırma Tablosu

Aşağıdaki tablo, incelenen 10 temel Codex yeteneğinin yürütme ortamını, sandbox güvenlik modelini, doğrulama kanıtını ve üretim etkisini karşılaştırmaktadır:

4. Kurumsal Mühendislik Ekipleri İçin Uygulama İlkeleri

OpenAI Codex CLI ve Bulut Ajanlarını üretim hattına entegre ederken maksimum verim ve güvenlik elde etmek için üç temel ilke uygulanmalıdır:

1. setup.sh İle Çevrimdışı Hazırlık, Ağ-Kapalı Yürütme: Bulut ajanlarının çalışma aşamasında dış ağ erişimi kapalı olduğu için tüm paket yöneticisi önbellekleri (pnpm store, .m2, pip cache) ve derleme araçları mutlaka kurulum betiğinde (setup.sh) hazır hale getirilmelidir.
2. AGENTS.md İçinde Doğrulanabilir Komutlar Tanımlamak: Soyut tavsiyeler yerine ajanın her değişiklikten sonra çalıştırabileceği deterministik tek satırlık doğrulama komutları (pnpm --filter <pkg> test) açıkça yazılmalıdır.
3. Büyük Görevleri PLANS.md İle Atomik Kilometre Taşlarına Bölmek: 10'dan fazla dosyayı etkileyen mimari görevlerde doğrudan kod üretimi yerine önce yaşayan bir plan dosyası oluşturulması ve her adımın test kanıtıyla kapatılması zorunlu kılınmalıdır.