# Claude Code ile TypeScript Projelerinde Etkin Çalışma Rehberi

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

Claude Code’u TypeScript projelerinde nasıl kullanacağınızı öğrenin: CLAUDE.md kurulumu, tip güvenliği, test döngüsü ve paralel ajanlarla pratik ipuçları.

**Kısaca:**

- Claude Code, TypeScript projelerinde tip hatalarını erken yakalamak için tsc ve testleri her adımda çalıştırmalıdır.
- CLAUDE.md dosyasına build, test, lint komutları ve tip güvenliği kuralları ekleyerek ajana net bağlam verin.
- Paralel ajanlar için git worktree kullanın ve her değişikliği diff ile inceleyin; ajanların generics ve type narrowing hatalarını gözden geçirin.

[Claude Code](/ajanlar/claude-code/), TypeScript projelerinde terminalden `claude` komutuyla çalışan bir kod ajanıdır; tip hatalarını, refactor işlerini ve test döngülerini sizinle birlikte yürütür. Doğru kurulum ve net talimatlarla, tsc çıktısını yorumlayıp daraltma (type narrowing) ve generic hatalarını düzeltebilir. Bu rehber, TypeScript bilen geliştiriciler için pratik bir çalışma düzeni sunar, ajanı projeye bağlamayı ve güvenli bir döngü kurmayı somut adımlarla anlatır.

## TypeScript işleri için neden uygun

Claude Code, proje klasörünün tamamını okuyabildiği için tsconfig.json, package.json ve kaynak dosyaları arasındaki ilişkiyi görür. `strict` modda çalışan bir projede tsc hatalarını satır bazında gösterir, önerdiği değişiklikleri uyguladıktan sonra aynı kontrolü tekrar çalıştırabilir. Böylece tip güvenliğini bozmadan refactor yapmak, union tipleri daraltmak ve generic imzaları sadeleştirmek için hızlı bir geri bildirim döngüsü kurar. Ayrıca tip tanımlarını ayrı dosyalara çıkarmak, `any` kullanımını `unknown` ve type guard’larla değiştirmek gibi sıkıcı ama riskli işleri adım adım yapabilir.

Örneğin, bir API response modelinde `data?: User | null` gibi opsiyonel bir union varsa, ajan erişimden önce daraltma yapmayı önerebilir. Benzer şekilde, bir generic fonksiyonun çıkarımını bozan `as` eklemelerini fark edip düzgün kısıtlar yazabilir. Ancak bu yetenek ancak doğru bağlamla ortaya çıkar: ajana hangi komutların çalıştığını, hangi klasörlerin dokunulmaz olduğunu ve hangi tip kurallarının ihlal edilmemesi gerektiğini CLAUDE.md üzerinden söylemek gerekir. Bu dosya, ajanın her oturumda referans aldığı kısa bir sözleşme gibidir.

## Projeyi ajan için hazırlama ve CLAUDE.md

Claude Code, proje kökündeki CLAUDE.md dosyasını otomatik okur. TypeScript projesinde bu dosyaya build, test, lint ve tip kontrolü komutlarını; klasör yapısını; import alias’larını ve zorunlu tip kurallarını yazın. Monorepo varsa her paketin kendi tsconfig’i olduğunu ve komutların hangi pakette çalıştırılacağını belirtin. Aşağıdaki örnek, gerçek bir projeden uyarlanmıştır ve ajanın hızlıca uyum sağlamasını hedefler:

```
# CLAUDE.md

## Komutlar
- Kurulum: pnpm install
- Build: pnpm build (tsc -b)
- Test: pnpm test (vitest run)
- Lint: pnpm lint (eslint .)
- Tip kontrolü: pnpm typecheck (tsc --noEmit)

## Klasör yapısı
- `src/` kaynak kod; `src/features/` altında özellik modülleri.
- `tests/` birim testleri; test dosyaları `*.test.ts` olarak adlandırılır.
- Import'larda `@/` alias'ı `src/` köküne işaret eder.

## Zorunlu TypeScript kuralları
- `strict` açık; `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes` ve `noImplicitOverride` etkin.
- `any` kullanma; gerekiyorsa `unknown` + type guard yaz.
- Generic fonksiyonlarda çıkarımı bozma; `as` yalnızca dış API sınırında.
- Union tiplerde özellik erişiminden önce daraltma yap.

## Ajanın çalışma sırası
1. İlgili dosyaları oku.
2. Değişiklikleri küçük parçalar halinde yap.
3. Her parçadan sonra `pnpm typecheck` çalıştır.
4. İlgili testleri çalıştır, sonra diff göster.
```

Bu dosyayı kısa tutun; gereksiz genel tavsiyeler yerine bu projeye özgü komutları ve kuralları yazın. Ajan her oturumda bu bağlamı kullanacağı için CI ile aynı komutları çalıştırması tutarlılık sağlar. Eğer monorepo kullanıyorsanız, paketler arası bağımlılıkları ve her paketin build sırasını da ekleyin; örneğin `packages/core` derlenmeden `packages/app` test edilmemeli gibi.

Ayrıca, tsconfig içindeki `baseUrl` ve `paths` ayarlarını CLAUDE.md’ye yansıtın; ajanın import çözümlemede hata yapmaması için bu kritik. Ek olarak, `skipLibCheck` veya `lib` gibi ortam ayarlarını da not edin; ajan bazen DOM tipleri ile Node tipleri arasında karışıklık yaşayabilir.

## Çalışma döngüsü: planla, küçük adımlar at, testleri çalıştır, diff’i incele

Claude Code’a tek seferde büyük bir görev vermek yerine, önce hedefi ve sınırları netleştirin. 'Şu dosyayı incele, önerini söyle, uygulamadan önce plan göster' gibi bir başlangıç, ajanın tip sistemini yanlış anlamasını engeller. Uygulama sırasında her küçük adımdan sonra `pnpm typecheck` ve ilgili testleri çalıştırmasını isteyin. Commit atmadan önce kendiniz `git diff` ile değişiklikleri gözden geçirin; ajanın önerdiği tip değişikliği bazen çalışma zamanı davranışını etkileyebilir. Daha geniş bir kontrol listesi için [Claude Code en iyi pratikler](/blog/claude-code-en-iyi-pratikler/) yazısına göz atın.

Aşağıdaki örnek istekler, tipik TypeScript görevlerini ajana nasıl devredebileceğinizi gösterir:

- `src/api/client.ts` içindeki `fetchData` fonksiyonunu generic hale getir; hata durumlarını `ApiError` union tipiyle döndür. Önce tip tanımlarını göster.
- `tsc --noEmit` çalıştır, `noImplicitAny` hatalarını listele ve her dosya için düzeltme öner. Uygulamadan önce onay iste.
- `User` ve `Admin` tipleri için `isAdmin` type guard’ı yaz. `formatUser` içinde daraltmayı kullan, sonra `pnpm typecheck` çalıştır.
- `tests/user.test.ts` içindeki mock nesnesinin tipini gerçek `User` tipine uydur. Vitest’i çalıştır ve kırılan testleri göster.
- `src/utils/result.ts` içindeki `Result` tipini discriminated union’a çevir; tüm kullanım yerlerini güncelle ve test et.

Bu istekler, ajanın neyi değiştireceğini, hangi kurala uyacağını ve hangi komutu çalıştıracağını açıkça söyler. Böylece tip hatalarını gizleyen `any` eklemeleri ya da gereksiz `as` kullanımı azalır. Her turda ajanın çıktısını okuyun; eğer tsc hala hata veriyorsa, ajana hatayı gösterip düzeltmesini isteyin. Bazen hata mesajı uzun olabilir; ajanın yalnızca ilgili satırlara odaklanmasını söyleyin.

## İyi gittiği işler ve dikkat edilmesi gerekenler

Claude Code; tip tanımlarını ayıklamak, union’ları daraltmak, generic kısıtları düzenlemek, `unknown` tabanlı tip daraltma yazmak ve tsconfig seçeneklerini kademeli sıkılaştırmak gibi işlerde etkilidir. Özellikle büyük bir refactor sırasında tsc hatalarını tek tek çözmek yerine, hata desenlerini görüp aynı çözümü birden çok dosyaya uygulayabilir.

Buna karşılık şu noktalarda dikkatli olun ve ajanı sık sık denetleyin:

| Pitfall | Neden riskli | Nasıl önlenir |
|---|---|---|
| `any` veya `as` ile hata susturma | Tip güvenliği kaybolur, çalışma zamanı hataları artar | CLAUDE.md’de yasakla, diff’te bu kalıpları arayın |
| Yanlış type narrowing | `undefined` veya `null` erişimi çalışma zamanında patlar | Ajanın önerdiği guard’ları test edin, edge case’leri sorun |
| Monorepo’da yanlış tsconfig | Paketler arası çakışma veya yanlış tip çözümü | Her paketin kendi komutlarını belirtin, ajanı paket sınırlarına yönlendirin |
| Gereksiz generic karmaşıklık | Okunması zor kod, tsc performansı düşer | Basit tutun, ajanın generic’i neden eklediğini sorgulayın |

Bu tablo, gözden geçirme sırasında odaklanmanız gereken ana riskleri toplar. Ajan bazen karmaşık bir generic hatasını susturmak için `as` veya `any` ekleyebilir; CLAUDE.md’deki kurala rağmen bunu yaparsa diff’te yakalayın. Type narrowing konusunda aşırı hevesli olup, çalışma zamanında `undefined` olabilecek bir değeri garanti gibi gösterebilir. Monorepo’da paketler arası import’larda yanlış tsconfig’e bakabilir; ona 'yalnızca bu paketin tsconfig’ini kullan' demek gerekebilir. Ayrıca yalnızca tip seviyesinde yapılan bir değişikliğin build çıktısını değiştirmediğini doğrulamak için her zaman `pnpm build` çalıştırın.

## TypeScript ile test ve doğrulama

Ajanın önerdiği her değişiklikten sonra en az üç katman doğrulama yapın: `pnpm typecheck` ile statik tip kontrolü, `pnpm lint` ile kural ihlalleri ve `pnpm test` ile çalışma zamanı davranışı. Claude Code’a bu komutları sırayla çalıştırmasını söyleyin; başarısız olan adımda durup size hatayı göstermesini isteyin. CI’da aynı komutlar çalıştığı için, ajanın yerel doğrulaması CI sürprizlerini azaltır. Özellikle generic değişikliklerde, tip testleri yazmak (örneğin `expectTypeOf` gibi) ajanın ürettiği tip çıkarımını test etmenizi sağlar. Ajanın testleri yalnızca geçirmek için üretim kodunu gevşetmediğinden emin olun; `git diff -- src` ile yalnızca kaynak değişikliklerini inceleyin.

Ayrıca, ajanın değiştirdiği dosyalarda `// @ts-ignore` veya `// @ts-expect-error` ekleyip eklemediğini kontrol edin; bunlar genellikle kaçamak çözümlerdir. Testlerin kapsamını artırmak isterseniz, ajandan belirli bir fonksiyon için edge case’ler üretmesini isteyebilirsiniz; bu, özellikle type guard’ların doğruluğunu test etmek için yararlıdır.

## Birden fazla ajanı paralel çalıştırma

Birden fazla TypeScript görevini aynı anda yürütmek isterseniz AgentVera, her Claude Code oturumunu kendi gerçek terminal panelinde ve kendi git worktree’sinde paralel çalıştırır. Böylece biri `src/api` üzerinde generic refactor yaparken diğeri test tiplerini düzeltir; dosyalar çakışmaz. Her tur sonunda ikinci bir model otomatik kod incelemesi yapar ve bulgular `file:line` olarak işaretlenir; bu, TypeScript’te gözden kaçan `any` veya yanlış daraltmayı yakalamak için kritiktir. Checkpoint’ler sayesinde kötü bir tip değişikliğini tek tıkla geri alabilirsiniz. Ayrıntılı paralel çalıştırma için [Birden fazla Claude Code ajanını paralel çalıştırma](/blog/birden-fazla-claude-code-ajani/) sayfasına bakın.

## Sonuç

Claude Code, TypeScript projesinde net bir CLAUDE.md, sıkı bir tip kontrolü döngüsü ve dikkatli bir diff incelemesiyle güvenilir bir yardımcı olur. Küçük başlayın; önce tip hatalarını temizletin, sonra refactor’lara geçin. Ajanın her önerisini `tsc` ve testlerle doğrulayın, `any` veya `as` eklemelerini asla gözden kaçırmayın. Paralel işler için git worktree tabanlı bir kurulum, çakışmaları önler ve ajanların birbirinin çalışmasına müdahale etmeden ilerlemesini sağlar.

## Sık sorulanlar

**Claude Code TypeScript projelerinde nasıl kullanılır?** Terminalde proje klasöründe claude komutunu çalıştırın. Proje köküne CLAUDE.md ekleyip build, test, lint ve tip kontrolü komutlarını yazın; ardından ajanın önerilerini tsc ve testlerle doğrulayın.

**TypeScript projesi için CLAUDE.md dosyasına ne yazmalıyım?** Build, test, lint ve tip kontrolü komutlarını; klasör yapısını; import alias’larını ve zorunlu tip kurallarını yazın. Özellikle strict mod, any yasağı ve type guard beklentilerini açıkça belirtin.

**Claude Code TypeScript tip hatalarını çözebilir mi?** Evet, tsc çıktısını okuyup union daraltma, generic düzeltme ve unknown tabanlı type guard gibi çözümler önerebilir. Ancak any veya as ekleyerek hatayı gizlemesini önlemek için diff’i inceleyin.

**Claude Code TypeScript testlerini nasıl çalıştırır?** Ajana pnpm test veya pnpm typecheck gibi komutları çalıştırmasını söyleyebilirsiniz. Her değişiklikten sonra bu komutları sırayla çalıştırıp başarısız adımda durmasını 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/