# Codex TypeScript: Tip Güvenli Kodlama Ajanı Rehberi

Adres: https://agentvera.dev/blog/codex-ile-typescript/ · Yayın: 2026-11-01

Codex’i TypeScript projelerinde etkili kullanın: AGENTS.md kurulumu, tsc --noEmit doğrulama, tip daraltma, generic dönüşüm ve monorepo ipuçları.

**Kısaca:**

- Codex’i TypeScript projesinde verimli kullanmak için AGENTS.md’ye tsc, test ve lint komutlarını net yazın.
- Küçük adımlarla çalıştırıp her değişiklikten sonra tsc --noEmit ve testleri çalıştırın; tip hatalarını erken yakalayın.
- Paralel ajan kullanırken git worktree ve otomatik kod incelemesi tip güvenliğini korur.

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](/ajanlar/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](/blog/codex-cli-nasil-kullanilir/) 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:

```markdown
# 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](/blog/baglam-muhendisligi/) 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:

| Komut | Ne kontrol eder |
|---|---|
| `pnpm tsc --noEmit` | Tüm projedeki tip hatalarını, strict mod ihlallerini |
| `pnpm vitest run` | Birim testlerinin geçtiğini; tip düzeltmesinin davranışı bozmadığını |
| `pnpm eslint src test` | Kod stilini, `any` yasaklarını ve diğer lint kurallarını |
| `pnpm build` | Üretim derlemesinin başarılı olduğunu, tip ve modül çözümlemesini |

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](/blog/agentvera-nasil-kullanilir/) 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.

## Sık sorulanlar

**Codex TypeScript projelerinde tip hatalarını kendisi düzeltebilir mi?** Evet, Codex tsc çıktısını okuyarak tip hatalarını düzeltebilir; ancak çıktıyı her seferinde görmesi ve hata ayıklama döngüsünü sizin onaylamanız gerekir. Karmaşık generic veya union daraltma hatalarında yanlış tip iddiaları ekleyebilir, bu yüzden diff’i inceleyin.

**AGENTS.md’ye TypeScript için neler yazmalıyım?** Build, test, lint komutlarını; src/ ve test/ klasör yapısını; strict mod kurallarını ve any kullanımını yasaklayan notları yazın. Ayrıca tsc --noEmit’in CI’da zorunlu olduğunu belirtin.

**Codex’i monorepo’da nasıl kullanırım?** Codex’i monorepo kökünde başlatmak yerine ilgili paket klasöründe çalıştırın. AGENTS.md’de workspace sınırlarını, paket bazlı tsconfig’leri ve cross-package import kurallarını yazın.

**Codex ürettiği kodu test eder mi?** Talimat verirseniz ilgili test komutunu çalıştırır. Küçük değişikliklerde 'önce tsc --noEmit, sonra vitest run' gibi net bir doğrulama zinciri isteyin.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/