Codex TypeScript: Tip Güvenli Kodlama Ajanı Rehberi

Codex’i TypeScript projenizde codex komutuyla başlattığınızda, ajanın en güçlü yanı tsc ile aynı dili konuşmasıdır. Ancak gerçek verim için AGENTS.md’de net kurallar, küçük adımlı döngü ve sürekli tsc --noEmit doğrulaması gerekir. Bu rehber, tip güvenliği bozmadan Codex’ten maksimum fayda almanızı sağlar.

Codex neden TypeScript işine uygun

TypeScript’in statik analizi Codex için doğal bir geri bildirim döngüsü oluşturur. Ajan, tsc --noEmit çıktısını satır numarası ve tip mesajıyla birlikte okuyup düzeltmeyi aynı bağlamda yapabilir. strict mod açıkken tip hataları derleme zamanında ortaya çıktığı için ajan, tahmin yürütmek yerine derleyicinin söylediği hatayı giderir. strict: true altında noImplicitAny, strictNullChecks ve noUncheckedIndexedAccess gibi bayraklar ajanın her değişken ve dönüş tipini açıkça düşünmesini zorlar. Generic dönüşümler, union daraltma ve lib.d.ts ile gelen tipler gibi konularda projenin mevcut tip tanımlarını okuyarak tutarlı kod üretir. Codex’in genel davranışı için Codex sayfasına bakabilirsiniz.

TypeScript’e özgü bir avantaj, ajanın tip çıkarımı ve daraltma kalıplarını öğrenebilmesidir. Örneğin bir union tip üzerinde typeof veya in kontrolü eklemesini istediğinizde bunu doğru yapar; Array.isArray gibi tip guard’ları önerir. Generic fonksiyonlarda kısıtları (<T extends ...>) anlar ve mevcut arayüzlerle uyumlu dönüş tipleri üretir. Ayrıca satisfies operatörünü kullanarak tip güvenli nesne tanımları önerebilir. Ancak bu yetenekler, projenin tip kuralları AGENTS.md’de açıkça belirtilirse ortaya çıkar; aksi halde ajan any ile kolay yolu seçebilir.

TypeScript projesi için Codex hazırlığı

Proje kökünde terminalden codex komutunu çalıştırın. Ajan, kök klasördeki AGENTS.md dosyasını okur; TypeScript projelerinde bu dosya, ajanın doğru komutları ve tip kurallarını bilmesini sağlar. Temel kurulum için Codex CLI nasıl kullanılır? Adım adım rehber sayfasına bakabilirsiniz.

AGENTS.md şu bilgileri içermeli: kurulum, tip kontrolü, test, lint ve build komutları; kaynak ve test klasörleri; monorepo varsa paket sınırları; strict mod kuralları ve any kullanımına dair yasaklar. Örnek bir dosya:

# AGENTS.md

## Komutlar
- Bağımlılıkları kur: `pnpm install`
- Tip kontrolü: `pnpm tsc --noEmit`
- Test: `pnpm vitest run`
- Lint: `pnpm eslint src test`
- Build: `pnpm build`

## Klasör yapısı
- `src/` kaynak kod
- `test/` birim testleri
- `types/` paylaşılan tip tanımları

## TypeScript kuralları
- `strict: true` her zaman; `noImplicitAny` ve `strictNullChecks` kapalı olmaz.
- `any` kullanma; bilinmeyen tipler için `unknown` + daraltma kullan.
- Generic fonksiyonlarda tip çıkarımına güven; gereksiz tip iddiası (`as`) ekleme.
- Union tiplerde daraltma yapmadan property erişme.
- Monorepo: her pakette kendi `tsconfig.json`; cross-package import sadece `exports` üzerinden.

Ayrıca bağlam yönetimi hakkında Bağlam mühendisliği: yapay zeka kodlama ajanları rehberi yazısı faydalı olur. tsconfig’de strict yanında noUncheckedIndexedAccess, exactOptionalPropertyTypes gibi bayraklar açıksa bunları da belirtin. Monorepo kullanıyorsanız kök tsconfig.json referanslarını, paths eşleşmelerini ve paketlerin build sırasını ekleyin. Ajan, doğrulama komutlarını çalıştırırken bu bilgileri kullanır; örneğin tek bir pakette değişiklik yaptığında ilgili paketin testini koşması gerektiğini bilir.

Codex ile çalışma döngüsü

Codex’i çalıştırırken şu döngüyü uygulayın: plan yapın, küçük adımlara bölün, her adımdan sonra testleri ve tsc --noEmit çalıştırın, diff’i inceleyin. Ajan tek seferde büyük refactor yaparsa tip hataları yığılır; bunun yerine tek bir tip hatasını veya fonksiyonu hedef alın. Birleşik tip tanımları üzerinde çalışırken önce türü değiştirin, sonra kullanım yerlerini güncelleyin; arada tsc --noEmit çalıştırın.

Tipik TypeScript görevleri için örnek promptlar:

• “src/utils/format.ts içindeki formatDate fonksiyonunu strict moda uygun hale getir; any parametreyi Date | string | number union’ına çevir ve tsc --noEmit ile doğrula.”
• “User arayüzüne role: 'admin' | 'user' ekle; bu union’a göre permissions fonksiyonunu tip daraltarak yeniden yaz.”
• “Api istemcisindeki generic request<T> fonksiyonunu, hata durumunda Error fırlatacak ve başarılı yanıtı T olarak döndürecek şekilde güncelle; testleri çalıştır.”
• “Monorepo’da @app/shared paketindeki tip değişikliğinin @app/web üzerindeki etkisini bul; tsc --noEmit ile tüm paketleri kontrol et.”
• “CI’daki tsc --noEmit hatasını çöz; hata satırına göre tip düzeltmesi yap ve ilgili testi ekle.”
• “src/state/reducer.ts içindeki action union’ına yeni bir LOGOUT tipi ekle; tüm switch case’leri exhaustive kontrol edecek şekilde güncelle.”

Her adımdan sonra diff’i okuyun; özellikle tip iddiaları ve ! operatörü kullanımlarını inceleyin. Ajan bazen foo!.bar yazarak strictNullChecks hatasını bastırabilir; bunun yerine açık null kontrolü isteyin.

Codex’in iyi yaptığı TypeScript işleri ve tuzaklar

Codex, mevcut tip tanımlarını okuyarak arayüz değişikliklerini diğer dosyalara yansıtmada, generic fonksiyonları yeniden yazmada, union daraltma eklemede ve tsc hatalarını düzeltmede başarılıdır. Ayrıca tip güvenli test yazımı ve unknown’dan type guard ile geçiş konularında iyi sonuç verir. Eski koddaki any’leri unknown’a çevirme, Promise dönüş tiplerini düzeltme ve readonly ekleme gibi mekanik işlerde hızlıdır.

Ancak şu noktalara dikkat edin: ajan bazen as unknown as Type gibi zincirleme tip iddiaları ekleyerek hatayı gizleyebilir; strictNullChecks altında ! operatörünü aşırı kullanabilir; union daraltmada in veya typeof kontrolü yerine tip iddiasına başvurabilir; genel any ekleyerek tüm tip kontrolünü devre dışı bırakabilir. Monorepo’da paket sınırlarını aşıp doğrudan iç dosyalara import ekleyebilir. Ayrıca declaration dosyalarında (*.d.ts) değişiklik yaparken global tip çakışmalarına yol açabilir; import type yerine normal import kullanarak runtime döngüselliği oluşturabilir. Bu yüzden her diff’i gözden geçirin; özellikle as, !, any ve declaration dosyalarındaki değişiklikleri sorgulayın.

TypeScript için test ve doğrulama

Ajan her değişiklikten sonra doğrulama komutlarını çalıştırmalıdır. Sıralama önemlidir: önce tsc --noEmit ile tip kontrolü, sonra birim testleri, ardından lint. Tip hatası kaldıysa ajanın testleri geçmesi yanıltıcı olur. CI entegrasyonunuzda tsc --noEmit zorunluysa, ajanın aynı komutu yerelde çalıştırmasını sağlayın; böylece CI’da sürpriz yaşanmaz.

Aşağıdaki tablo doğrulama araçlarını özetler:

Ajanın çalıştırdığı komutların çıktısını terminalde görebilirsiniz; hata varsa ajan düzeltmek için geri dönecektir. Ancak son onayı siz verin. Testlerin yanında type coverage araçları kullanıyorsanız (ör. type-coverage) ajanın bu metriği bozmamasını isteyin. Snapshot testleri tip değişikliklerinden etkilenebilir; ajan snapshot’ı güncellerse diff’i kontrol edin. Büyük refactorlarda ara commit’ler alın; böylece tip bozulursa geri dönmek kolay olur.

AgentVera ile paralel ajan kullanımı

AgentVera’da birden fazla Codex ajanını aynı TypeScript projesinde çalıştırırken her ajan kendi git worktree’sinde ilerler; böylece tip tanımları üzerinde çakışma olmaz. Bir ajanın işi bitince ikinci bir model otomatik kod incelemesi yapar ve tip güvenliği ihlallerini dosya:satır olarak gösterir. Ayrıca her turun anlık görüntüsü (checkpoint) alınır; tip bozan bir değişikliği tek tıkla geri alabilirsiniz. Token bütçeleri, geniş monorepo tip dönüşümlerinde maliyeti kontrol altında tutar. Detaylar için AgentVera nasıl kullanılır: ilk proje, ajanlar ve ızgara sayfasına bakın.

Sonuç

Codex, TypeScript projelerinde tip sistemini aktif olarak kullanarak verimli bir asistan olur; ancak başarı, AGENTS.md’de net kurallar, küçük adımlı döngü ve düzenli tsc --noEmit doğrulamasına bağlıdır. as ve any tuzağına karşı diff’i inceleyin, monorepo sınırlarını koruyun. Paralel çalışmada AgentVera’nın worktree ve otomatik inceleme özellikleri tip güvenliğini sürdürür. Ajanı tip sisteminin bir uzantısı olarak düşünün: derleyiciyle birlikte çalıştığında üretkenlik artar, ancak son karar her zaman sizin denetiminizdedir.