Gemini CLI ile TypeScript projelerinde pratik rehber

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 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? 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 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.

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 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.