opencode ile TypeScript projelerinde verimli çalışma

opencode, TypeScript projenizin kökünde terminalde opencode komutuyla başlattığınız bir kodlama ajanıdır. Bu rehber, ajanı TypeScript’e özel olarak nasıl yönlendireceğinizi, hangi görevlerde güvenebileceğinizi ve tsc ile CI döngüsünü nasıl sağlam tutacağınızı gösterir. Örneğin bir fetchUser fonksiyonunun dönüş tipini Promise<User | null> yerine Result<User, ApiError> yaparsanız, ajan tüm çağrı noktalarında hata işlemeyi güncelleyebilir.

TypeScript işleri için opencode neden uygun?

opencode yalnızca kod parçacığı üretmez; proje dosyalarını okur, terminal komutlarını çalıştırır ve derleyici çıktısına göre düzeltme yapar. TypeScript’te asıl mesele tip çıkarımını ve daraltmayı korumak olduğu için bu döngü kritik önem taşır. Ajan, tsc --noEmit hatalarını aldığında hatanın kaynağını görür ve unknown daraltma, discriminated union eksikliği veya yanlış generic kısıtı gibi sorunları gidermeye çalışır.

TypeScript’e özgü avantajlar şunlardır:

• Derleyici geri bildirimiyle düzeltme: Ajan, tsc hatalarını okur ve tip uyumsuzluklarını gidermek için kodda değişiklik yapar. Örneğin Property 'id' does not exist on type 'User | Admin' hatasını, ilgili kodda in operatörü veya switch ile daraltma ekleyerek çözer.
• Refactor ve imza değişiklikleri: Bir arayüzde alan adını değiştirdiğinizde ajan, projedeki tüm kullanımları bulur ve günceller. Generic bir fonksiyona yeni bir tip parametresi eklerseniz, etkilenen tüm çağrıları düzenler.
• Monorepo desteği: Kök ve paket seviyesindeki tsconfig.json dosyalarını kullanarak paketler arası tip değişikliklerini yayabilir. Project references kullanılan bir monorepo’da, bir paketteki tip değişikliğinin diğer paketlerde nasıl hatalara yol açtığını anlar.
• Model esnekliği: Ajan, farklı model sağlayıcılarıyla çalışabildiği için TypeScript çıkarımı güçlü bir model seçebilirsiniz. Bu, karmaşık conditional type veya template literal type içeren projelerde önemlidir.

Daha fazla bilgi için opencode sayfasına bakabilirsiniz.

Projeyi ajan için hazırlama ve AGENTS.md

opencode, proje kökündeki AGENTS.md dosyasını talimat kaynağı olarak okur. TypeScript projesinde bu dosya, ajanın doğru komutları ve tip güvenliği kurallarını bilmesini sağlar. Aşağıdaki örnek, küçük bir uygulama için yeterli bir başlangıçtır:

# AGENTS.md

## Komutlar
- Kurulum: `pnpm install`
- Build: `pnpm build` (tsc -p tsconfig.json && vite build)
- Test: `pnpm test` (vitest run)
- Lint: `pnpm lint` (eslint .)
- Tip kontrolü: `pnpm typecheck` (tsc --noEmit)

## Klasör kuralları
- `src/` altında özellik bazlı klasörler; ortak tipler `src/types/` altında.
- Üretilen `dist/` klasörünü düzenleme.

## TypeScript kuralları
- `strict` açık; `noUncheckedIndexedAccess` açık.
- Her fonksiyon dönüş tipini açıkça yaz.
- `any` kullanma; bilinmeyen tipleri `unknown` ile daralt.
- Discriminated union'larda exhaustiveness kontrolünü koru.
- Jeneriklerde gereksiz kısıt ekleme; `unknown` ile başla.

Bu dosya, ajanın tüm görevlerde aynı kuralları uygulamasını sağlar. Özellikle any yasağı ve dönüş tipi zorunluluğu, ajanın tip güvenliğini zayıflatacak kısayollara başvurmasını engeller. strict altındaki noUncheckedIndexedAccess gibi seçenekleri de belirtmek, array[index] erişimlerinde undefined olasılığını ajanın dikkate almasını sağlar.

Monorepo’larda kök AGENTS.md dosyasına ek olarak her paketin kendi talimatları olabilir. Kök dosyada paket adları, bağımlılık ilişkileri ve çalıştırma komutları belirtilmelidir. Örneğin:

# Monorepo AGENTS.md (kök)

- Paketler: `packages/core`, `packages/api`, `packages/web`
- Tip kontrolü: her paket için `pnpm --filter <paket> typecheck`
- Tip değişikliği yaparken önce `packages/core` içindeki ortak tipleri güncelle; ardından bağımlı paketlerdeki hataları düzelt.
- Çalışma düzeni: `packages/core` -> `packages/api` -> `packages/web`

Ayrıca opencode nasıl kullanılır? Adım adım rehber başlangıç akışını netleştirir.

Çalışma döngüsü ve örnek istemler

TypeScript’te ajanla verimli çalışmanın döngüsü şudur: önce değişikliği küçük bir adımla planlayın; ajanın değişikliği yapmasını isteyin; ardından pnpm typecheck ve testleri çalıştırın; son olarak git diff ile tip bazlı değişiklikleri inceleyin. Bu döngüyü her istekte tekrarlayın.

İyi bir istem, beklenen davranışı ve tip güvenliği sınırlarını netleştirir. Aşağıdaki istemler tipik TypeScript görevlerinde iyi başlangıç noktalarıdır:

• “src/api/user.ts içindeki unknown dönüş tipini daraltarak hata mesajını gider; davranışı değiştirme.”
• “User ve Admin tiplerini discriminated union’a çevir; ilgili tüm switch ifadelerini exhaustive hale getir.”
• “Bu modüldeki any kullanımlarını tespit et ve uygun tiplerle değiştir; her değişiklikten sonra pnpm typecheck çalıştır.”
• “Şu generic fonksiyonun tip çıkarımını bozan kısıtı düzelt; etkilenen testleri güncelle.”
• “Monorepo’da packages/core içindeki ApiResponse tipini değiştir; bu tipi kullanan tüm paketlerde importları ve kullanımları güncelle.”
• “process.env değerlerini okuyan bir config dosyası oluştur; her değişken için tip daraltma yap ve eksik değerlerde net hata fırlat.”

Döngü sırasında ajanın ürettiği diff’i dikkatle inceleyin. Özellikle as any, @ts-ignore, ! non-null assertion ve any dönüş tipleri arayın. Bu ifadeler, derleyiciyi susturur ama gerçek tip güvenliğini zedeler. Ajan bir hatayı çözmek için bu yollara başvurduysa, daha güvenli bir çözüm isteyin.

Opencode’un iyi yaptığı TypeScript işleri ve dikkat edilecek noktalar

Ajan, özellikle tip daraltma, unknown’dan güvenli dönüşüm, exhaustive switch, import güncelleme ve basit generic düzeltmelerde başarılıdır. tsc hatalarını okur ve ilgili satırları düzeltmeye çalışır; bu, sıkı modda büyük zaman kazandırır.

Ajanın güvenilir olduğu senaryolara örnekler:

• Discriminated union geçişleri: type Shape = Circle | Square gibi bir union’da alan eklediğinizde, ajan tüm switch bloklarını ve type guard’ları günceller.
• Generic fonksiyonların düzeltilmesi: function identity<T>(arg: T): T gibi basit yapılarda hata varsa, kısıtları doğru şekilde ayarlar.
• any temizliği: Bir kod tabanındaki any kullanımlarını tespit edip yerine doğru tipleri koyabilir; özellikle API yanıtları ve event handler’larında.
• Config nesnelerinin tiplenmesi: as const veya satisfies kullanarak literal tipleri korur.

Ancak ajan bazen derleyiciyi susturmak için tip güvenliğinden ödün verebilir. En sık görülen tuzaklar şunlardır:

• as any eklemek: Ajan bir tip hatasını çözmek için as any dökümü kullanabilir. Bu, hatayı gizler ama sonraki hatalara davetiye çıkarır.
• @ts-ignore veya @ts-expect-error kullanmak: Özellikle çok sayıda hata olduğunda ajan bu yorumları ekleyebilir; ancak bu, gerçek düzeltmeyi erteler.
• Gereksiz non-null assertion (!) eklemek: Bir değerin undefined olamayacağını varsaymak, çalışma zamanında hatalara yol açar.
• strict ayarını gevşetmek: Ajan bazen tsconfig.json içindeki strict: false yapmayı önerebilir; buna asla izin vermeyin.
• Karmaşık conditional type’larda yanlış çıkarım: Özellikle distributif conditional type’lar veya infer kullanımında ajan hatalı sonuç üretebilir; bu durumda testlerle doğrulama şarttır.
• satisfies veya as const gibi ifadeleri kaldırmak: Ajan, hata çözmek adına tip daraltmayı genişletebilir; bu, literal tiplerin kaybolmasına neden olur.
• Monorepo’da yalnızca bir paketi düzeltmek: packages/core içindeki bir tip değişikliği sonrası bağımlı paketlerdeki hataları görmezden gelebilir. Her zaman tüm paketlerde tip kontrolü yapın.

Bu tuzakları yakalamak için diff incelemesini rutin haline getirin. Özellikle as any, @ts-ignore, ! ve tsconfig değişikliklerini arayın. Eğer ajan bu yollara başvurduysa, “as any kullanmadan, tipi daraltarak düzelt” gibi daha sıkı talimatlar verin.

Test ve doğrulama

TypeScript’te doğrulamanın ilk kapısı tip kontrolüdür. Ajanın yaptığı her değişiklikten sonra pnpm typecheck çalıştırmasını isteyin; hata varsa önce onları çözdürün. Ardından birim testleri ve lint’i çalıştırın. Aşağıdaki tablo temel kontrolleri özetler:

| Kontrol | Komut | Ajan için not | | Tip kontrolü | pnpm typecheck | Hata varsa başka işe geçme; önce bunları düzelt. | | Birim testler | pnpm test | Tip değişikliği davranışı bozmamalı. | | Lint | pnpm lint | Kullanılmayan import ve any uyarılarını temizle. | | Diff incelemesi | git diff | as any, @ts-ignore, gereksiz ! ara. |

Bu adımları CI’da da zorunlu tutun; tsc --noEmit başarısızsa merge engellensin. Ajan, terminal çıktısını okuyabildiği için hataları kendi kendine giderebilir; ancak siz yine de nihai diff’i inceleyin.

Tip testlerini otomatikleştirmek için tsd veya eslint-plugin-expect-type gibi araçlar kullanabilirsiniz. Ajan, bu testleri de yazabilir; böylece karmaşık tip çıkarımları davranışsal testlerden bağımsız olarak doğrulanır. Örneğin, bir generic fonksiyonun dönüş tipini kontrol eden bir expectType testi eklemesini isteyebilirsiniz.

Birden fazla ajanı tek TypeScript projesinde çalıştırmak (AgentVera)

TypeScript projesinde paralel refactor’lar risklidir; iki ajan aynı dosyayı düzenlerse tip uyumsuzlukları oluşur. AgentVera, her ajanı kendi git worktree’sinde çalıştırarak çakışmaları önler ve ajan bittiğinde ikinci bir model kodunu inceleyip as any gibi tip zayıflatmalarını file:line bağlantısıyla bildirir. Checkpoint’ler sayesinde yanlış bir tip değişikliği tek tıkla geri alınabilir; token bütçeleri de ajanın sonsuz tsc düzeltme döngüsüne girmesini engeller. Bu konuda paralel kodlama ajanları için en iyi araçlar sayfası daha geniş bir bakış sunar.

Sonuç

opencode, TypeScript projesinde doğru talimatlarla ve sıkı doğrulamayla güçlü bir yardımcıdır. AGENTS.md’yi net tutun, her değişiklikte tsc ve testleri çalıştırın, diff’i tip güvenliği açısından denetleyin. Böylece ajanın hızından yararlanırken strict modun getirdiği güveni korursunuz. Ajan, yalnızca kod yazmakla kalmaz; projedeki tip ilişkilerini anlayarak daha güvenli bir kod tabanı oluşturmanıza yardımcı olur.