# opencode ile TypeScript projelerinde verimli çalışma

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

opencode ajanını TypeScript projesinde nasıl kullanacağınızı öğrenin: AGENTS.md kurulumu, tip güvenliği, tsc doğrulama, testler ve paralel ajanlar.

**Kısaca:**

- opencode, TypeScript projesinde tsc ve testleri kendisi çalıştırarak tip hatalarını doğrudan düzeltebilir.
- AGENTS.md dosyasına net komutlar ve strict kurallar yazmak ajanın tip güvenliğini korumasını sağlar.
- Her değişiklikten sonra tip kontrolü ve diff incelemesi, as any gibi zayıflatmaları yakalar.

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](/ajanlar/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:

```markdown
# 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:

```markdown
# 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](/blog/opencode-nasil-kullanilir/) 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](/blog/paralel-yapay-zeka-kodlama-ajani-araclari/) 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.

## Sık sorulanlar

**opencode TypeScript projesinde nasıl başlatılır?** Proje klasöründe terminal açıp opencode komutunu çalıştırmanız yeterlidir. Ajan, AGENTS.md dosyasındaki talimatları ve tsconfig.json gibi yapılandırmaları okuyarak bağlamı oluşturur.

**opencode, TypeScript tip hatalarını kendiliğinden düzeltebilir mi?** Evet, tsc --noEmit çıktısını okuyup ilgili satırlardaki tip hatalarını gidermeye çalışır. Ancak bazen as any gibi kısayollara başvurabilir; bu yüzden diff’i gözden geçirmek gerekir.

**AGENTS.md dosyasına TypeScript için neler yazmalıyım?** Build, test, lint ve typecheck komutlarını, klasör kurallarını ve strict ayarlarına uyulması gerektiğini yazın. any kullanımını yasaklamak ve dönüş tiplerini zorunlu kılmak ajanı daha güvenli yapar.

**opencode monorepo içinde çalışır mı?** Evet, kök AGENTS.md dosyasında paket yapısını ve her paket için doğru komutları belirtirseniz monorepo’da çalışabilir. Paketler arası tip değişikliklerinde ilgili tüm tsconfig referanslarını dikkate alması için açık talimat verin.

---

**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/