# Gemini CLI ile TypeScript projelerinde pratik rehber

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

TypeScript projelerinde Gemini CLI ile nasıl çalışılır? GEMINI.md kurulumu, etkili prompt örnekleri, tsc ile tip doğrulama ve paralel ajan kullanımı bu rehberde.

**Kısaca:**

- Gemini CLI, GEMINI.md talimatları ve tsc --noEmit ile TypeScript projelerinde tip güvenliğini korur.
- Küçük adımlı plan-test-diff döngüsü, ajanın ürettiği kodlardaki tip hatalarını erken yakalar.
- AgentVera ile birden fazla ajanı ayrı git worktree’lerinde çalıştırarak ortak tip dosyalarında çakışmayı önlersiniz.

Gemini CLI, bir TypeScript projesinin kök dizininde `gemini` komutuyla başlatılır; proje talimatlarını GEMINI.md dosyasından okur ve terminalden kod üretir, test çalıştırır, tip hatalarını yorumlar. TypeScript tarafında en büyük avantajı, `tsc --noEmit` çıktısını doğrudan kullanabilmesidir. Bu rehberde kurulum, çalışma düzeni ve sık karşılaşılan tuzakları somut biçimde ele alıyorum.

## Gemini CLI neden TypeScript işlerine uygun?

TypeScript’in statik analizi, ajanın ürettiği kodun hatalarını anında görünür kılar. Gemini CLI, tsconfig.json ayarlarını okuyabilir ve `strict` modun gerektirdiği null kontrolü, indeks erişimi ve fonksiyon dönüş tipi gibi kısıtları komut çıktısından öğrenebilir. Böylece "bunu düzelt" komutundan sonra ajan yalnızca semptomu değil, tipin kaynağını değiştirmeye yönelir. Örneğin, `order.total` alanının `number | undefined` olduğu bir fonksiyonda ajan, sadece `!` operatörü eklemek yerine, kontrol akışını `if (order.total !== undefined)` ile daraltmayı öğrenebilir. Bu, özellikle `strictNullChecks` açıkken çalışan projeler için kritik bir farktır. Ayrıca monorepolarda package references ve path alias’ları anlamlandırabilir; bu da elle konfigürasyon anlatmayı azaltır. TypeScript için yazılmış bir GEMINI.md ile ajan, `any` kullanmama, generic kısıtları ve type guard tercihlerini projeye özgü kurallar olarak uygular. Sonuçta refactor sırasında tip güvenliği korunur ve CI’daki `tsc` adımı daha az kırılır. Daha genel kurulum ve çalıştırma için [Gemini CLI](/ajanlar/gemini-cli/) sayfasına bakılabilir.

## TypeScript projesi için kurulum ve GEMINI.md

Proje kökünde terminali açın ve `gemini` yazın. Ajan, mevcut dizindeki GEMINI.md içeriğini talimat olarak alır. TypeScript projesinde bu dosya, ajanın her adımda uyması gereken komutları, klasör düzenini ve tip kurallarını içermelidir. Kısa ve net tutmak ajanın uyumunu artırır; uzun paragraflar yerine komut ve kural listeleri kullanın. Aşağıdaki örnek, pnpm/vitest kullanan bir proje için temel bir şablondur.

```
# TypeScript projesi kuralları

## Komutlar
- Kurulum: `pnpm install`
- Build: `pnpm build`   # tsc -p tsconfig.json
- Test: `pnpm test`     # vitest run
- Lint: `pnpm lint`     # eslint . --ext .ts,.tsx
- Tip kontrolü: `pnpm typecheck`  # tsc --noEmit

## Klasör kuralları
- Kaynak kod `src/`, testler `src/**/*.test.ts`
- Paylaşılan tipler `src/types/`
- API istemcileri `src/api/`, servisler `src/services/`

## TypeScript kuralları
- `strict: true` varsay; dosyada `any` kullanma.
- Fonksiyon dönüş tiplerini her zaman açık yaz.
- `unknown` değerleri tip guard ile daraltmadan kullanma.
- `as` tip iddiası yerine type guard veya discriminated union tercih et.
- Generic fonksiyonlarda `extends` kısıtı koy; gerekmedikçe `any` parametre ekleme.
- Hata durumları için `Result<T>` veya `Either` benzeri union kullan.
```

Bu dosyayı güncelledikçe `gemini` yeniden başlatıldığında yeni talimatları okur. Komutların yorum satırındaki açıklamaları, ajanın hangi aracı ne zaman kullanacağını netleştirir. Monorepo kullanıyorsanız, kök GEMINI.md dosyasına her paketin build ve test komutunu ayrı ayrı yazın; ajan böylece hangi pakette çalıştığını bilir. `tsconfig.json` içinde `baseUrl` ve `paths` alias’ları varsa, "### import kuralı" bölümü ekleyerek ajanın relative import yerine alias kullanmasını şart koşabilirsiniz. Kurulumla ilgili daha fazla ayrıntı için [Gemini CLI nasıl kullanılır?](/blog/gemini-cli-nasil-kullanilir/) rehberine bakabilirsiniz.

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

Verimli döngü şudur: önce ajanın neyi değiştireceğini 2-3 cümleyle planlatın; ardından küçük bir diff üretmesini isteyin; sonra `pnpm typecheck`, `pnpm test` ve `pnpm lint` komutlarını kendisi çalıştırsın; en son `git diff` ile değişiklikleri siz inceleyin. Tek seferde büyük bir refactor istemek yerine, tip daraltma, generic ekleme ve test yazımını ayrı adımlara bölün. Ajan takıldığında ona `tsc --noEmit` hata çıktısını yapıştırmak, sorunu anlamasını hızlandırır. Örneğin, "`src/services/order.ts` içinde `Property 'customer' does not exist on type 'Order'` hatası var; bunu düzelt" demek, ajanın ilgili tipleri bulmasını ve doğru union’ı oluşturmasını sağlar. Aynı işlemi kapalı uçlu bir soruyla istemek yerine, ajanın önce tip akışını analiz etmesini isteyebilirsiniz: "`Order` tipinin `customer` içermediği tüm kullanım noktalarını listele ve sonra hangi arayüzü genişletmemiz gerektiğini öner." Promptlarınızı daha etkili yazmak için [kodlama ajanları için prompt yazmak](/blog/kodlama-ajanlari-icin-prompt-yazmak/) yazısındaki önerilere göz atabilirsiniz. İşte tipik TypeScript işleri için kullanabileceğiniz promptlar:

- "`src/services/order.ts` içindeki `calculateTotal` fonksiyonunu `strict` moda uygun hale getir. `any` parametrelerini `OrderItem` tipiyle değiştir, dönüş tipini açık yaz ve null dönebilecek yolları `Result<number>` ile işaretle."
- "`User` ve `Admin` tiplerini `role` alanına göre discriminated union’a çevir. `hasPermission` fonksiyonuna daraltılmış tipi kullan, hiçbir yerde `as` kullanma."
- "`src/api/client.ts` içindeki `fetchData` fonksiyonunu generic hale getir. Çağıran tarafta `fetchData<User>('/me')` şeklinde kullanılabilsin; hata ve başarı durumları `ApiResult<T>` union’ı ile dönsün."
- "CI’daki `tsc --noEmit` adımı `src/utils/mapper.ts` 34. satırda hata veriyor. Hatayı bul, kök nedenini açıkla ve mevcut testleri bozmadan düzelt."
- "`OrderStatus` geçişleri ve indirim hesaplaması için vitest ile 3 yeni test ekle. Tip hataları testlerle birlikte çalıştırıldığında görünür olsun."

## İyi gittiği işler ve dikkat edilecek noktalar

Gemini CLI, `strict` mod geçişi, `any` temizliği, discriminated union dönüşümü, generic API sarmalayıcıları ve type guard ekleme gibi mekanik işlerde başarılıdır. Ayrıca tsconfig.json içindeki `strictNullChecks`, `noImplicitAny` gibi bayrakların açılmasından sonra ortaya çıkan hataları tek tek düzeltebilir. Monorepo içinde `project references` kullanan yapılar için paketler arası tip hatalarını izleyebilir. Örneğin, `packages/core` içindeki bir arayüz değiştiğinde, bağımlı `packages/web` içindeki tüm kırmızı çizgileri listeleyip düzeltebilir.

Ancak şu noktalarda yakından izleyin: Ajan bazen bir hatayı susturmak için `// @ts-ignore` veya `as unknown as` ekleyebilir; bu tip güvenliğini deler. Generic çıkarımın zorlandığı yerlerde aşırı geniş `any` veya `unknown` bırakabilir; `T extends object` yerine `T = any` gibi varsayılanlar üretebilir. Değişiklik yaparken bir fonksiyonun imzasını değiştirip tüm çağrıları güncellemediği durumlar olur; bu yüzden `tsc --noEmit` olmadan işi bitmiş saymayın. Ayrıca test dosyalarında tip hatalarını görmezden gelip yalnızca çalışma zamanını kontrol edebilir; `pnpm typecheck` adımını testlerden ayrı çalıştırmasını isteyin. Bir başka tuzak da, ajanın `unknown` tipini daraltmadan kullanmaya çalışmasıdır; örneğin `const data: unknown = response.data; const name = data.name;` gibi bir satır `strict` modda hata verir. Ajanı bu tür senaryolara karşı uyarmak için GEMINI.md dosyanıza "bilinmeyen tipleri kullanmadan önce tip guard yaz" kuralını ekleyin.

## TypeScript için test ve doğrulama

Ajanın ürettiği her değişiklikten sonra şu kontrolleri yapın. Komutlar doğrudan terminalde sizin de çalıştırabileceğiniz standart TypeScript araçlarıdır.

| Komut | Ne doğrular |
| --- | --- |
| `pnpm typecheck` | Tüm projede `strict` mod dahil tip hatalarını |
| `pnpm test` | Davranışsal regresyonu ve test tiplerinin derlenmesini |
| `pnpm lint` | `no-explicit-any`, `consistent-type-assertions` gibi kuralları |
| `git diff --stat` | Ajanın dokunduğu dosya kapsamını ve istenmeyen değişiklikleri |

Ajanın işi bitirdikten sonra `tsc --noEmit` çıktısını kendisinin yorumlamasını isteyin; hata mesajlarını satır numarasıyla birlikte düzeltmesi daha güvenilirdir. Tip değişiklikleri söz konusuysa `git diff src/types` çıktısına bakarak kamu API’sinde kırılma olup olmadığını kontrol edin. Eğer monorepo kullanıyorsanız, bağımlı paketlerin `tsc -b` ile yeniden derlenmesini de doğrulatın. Sürekli entegrasyon (CI) ortamında `tsc` zaten koşuyorsa, ajanın ürettiği kodu push etmeden önce yerelde aynı komutu çalıştırmasını sağlayın. TypeScript’e özgü bir doğrulama daha: Ajanın eklediği tip korumalarını test etmek için küçük bir tip testi yazmasını isteyebilirsiniz; örneğin `assertType<ExpectedType>` kullanan bir vitest testi, tip seviyesindeki hataları yakalar. Bu yaklaşım, özellikle generic fonksiyonlar ve discriminated union’larda işe yarar. Son olarak, değiştirilen dosyaların import düzenini `eslint --fix` ile kontrol ettirerek alias’ların doğru kullanıldığından emin olun.

## Birden fazla ajanı AgentVera ile çalıştırmak

Aynı TypeScript projesinde birden fazla ajan çalıştıracaksanız AgentVera’nın paralel ajan özelliği işinize yarar. Her ajan kendi git worktree’sinde çalıştığı için `src/types` gibi ortak dosyalar üzerinde çakışma yaşanmaz. Bir ajanın turu bittiğinde ikinci bir modelin kod incelemesi, tip güvenliğini bozan değişiklikleri file:line ile gösterir. Checkpoint’ler sayesinde yanlış bir generic refactor tek tıkla geri alınabilir; token bütçeleri de ajanın sonsuz `tsc` hata döngüsüne girmesini önler. Ajan ekibi kurulumunu derinlemesine düşünüyorsanız [yapay zeka ajan ekibi](/blog/yapay-zeka-ajan-ekibi/) başlıklı yazı yol gösterir.

## Sonuç

Gemini CLI, TypeScript projelerinde özellikle tip odaklı refactor ve `strict` mod uyumluluğu için güçlü bir araçtır. Başarı, ajanı serbest bırakmakta değil; net GEMINI.md, küçük adımlı döngü ve `tsc --noEmit` doğrulamasını zorunlu tutmakta yatar. Bu disiplini kurduğunuzda ajan, CI’da kırılan tip hatalarını erkenden yakalar.

## Sık sorulanlar

**Gemini CLI TypeScript projesinde nasıl başlatılır?** Proje kök dizininde terminalde gemini komutunu çalıştırmanız yeterlidir. Ajan, aynı dizindeki GEMINI.md dosyasındaki TypeScript komutlarını ve kurallarını okuyarak başlar.

**Gemini CLI için GEMINI.md dosyasına neler yazılmalı?** TypeScript projesi için build, test, lint ve tip kontrolü komutlarını; klasör kurallarını; strict mod, any kullanmama ve generic kısıtları gibi projeye özel kuralları yazın. Komutları kısa ve yorumlu tutmak ajanın uyumunu artırır.

**Gemini CLI TypeScript kodundaki tip hatalarını düzeltebilir mi?** Evet, tsc --noEmit çıktısını okuyarak hataları satır numarasıyla birlikte düzeltebilir. Ancak bazen // @ts-ignore veya as unknown as ekleyerek hatayı susturmaya çalışabilir; bu yüzden diff’i incelemeniz gerekir.

**Gemini CLI ile birden fazla ajan aynı TypeScript projesinde nasıl çalıştırılır?** AgentVera gibi bir masaüstü uygulamasıyla her ajanı kendi git worktree’sinde paralel çalıştırabilirsiniz. Böylece aynı src/types dosyaları üzerinde çakışma yaşanmaz ve otomatik kod incelemesi tip güvenliğini korur.

---

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