# Cursor Agent ile TypeScript projelerinde pratik kullanım rehberi

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

Cursor Agent’ı TypeScript projelerinde etkili kullanmak için AGENTS.md kurulumu, örnek istemler, tsc ile doğrulama ve gerçek monorepo ipuçları.

**Kısaca:**

- Cursor Agent, TypeScript projelerinde tsc hatalarını ve tip daraltmalarını hızlı düzeltir.
- AGENTS.md dosyasına build, test ve lint komutları ile strict kuralları yazmak ajanın doğruluğunu artırır.
- Ajanın önerdiği diff’i her adımda pnpm exec tsc --noEmit ve testlerle doğrulayın.

`cursor-agent` komutu ile bir TypeScript projesinde çalışan Cursor Agent, tip hatalarını düzeltmek, refactor yapmak ve test koşmak için terminal tabanlı bir kodlama ajanıdır. Bu rehber, strict mode, tsconfig, generics ve monorepo gibi TypeScript’e özgü konularda ajanı nasıl yapılandıracağınızı ve güvenle kullanacağınızı gösterir. Daha fazla başlangıç bilgisi için [Cursor Agent](/ajanlar/cursor-agent/) sayfasına bakabilirsiniz.

## Neden Cursor Agent TypeScript işine uygun?

Cursor Agent, TypeScript projesinin derleyicisini ve test çerçevesini doğrudan çalıştırır; bu sayede `tsc` hatalarını gerçek hata mesajlarıyla görür ve düzeltmeye çalışır. Tip sistemi sayesinde, ajanın ürettiği kodun en azından derlendiğini doğrulayabilirsiniz; bu, dinamik dillerdeki belirsizliğe kıyasla büyük bir avantajdır. Ajan, `strict` modun getirdiği `noImplicitAny`, `strictNullChecks`, `noUncheckedIndexedAccess` gibi bayrakları bilir ve bu kurallara uygun kod üretmeye çalışır. Örneğin, `null` veya `undefined` döndürebilen bir fonksiyonu çağıran kodda tip hatası varsa, ajan otomatik olarak `if` bloğu ile daraltma ekleyebilir veya fonksiyon imzasını düzeltebilir.

TypeScript projelerinde tip daraltma (type narrowing) ve generic kullanımı sık yapılan işlerdir. Cursor Agent, `typeof`, `instanceof`, discriminated union gibi kalıpları tanır ve olası hataları düzeltir. Generics’te ise `<T extends ...>` kısıtlarını doğru şekilde ekleyebilir; örneğin bir API istemcisini generic hale getirirken dönüş tipini `Promise<T>` olarak belirleyip çağrıları günceller. Monorepo yapısında her paketin kendi `tsconfig`'i olduğunda, ajan doğru paket sınırlarını anlamak için proje talimatlarına ihtiyaç duyar; doğru yapılandırma ile paketler arası tip hatalarını bulabilir ve düzeltebilir.

Ayrıca ajan, `package.json` içindeki script’leri okuyup doğrudan çalıştırabilir. Örneğin projede `pnpm test` komutu varsa, testleri kendisi koşar ve başarısız olanları düzeltmeye çalışır. Bu, TypeScript’in derleme sonrası çalışma zamanı hatalarını da yakalamasına olanak tanır; çünkü tip kontrolü tek başına yeterli değildir. Ajan, test sonuçlarına göre tip tanımlarını veya implementasyonu değiştirir, ancak her değişikliği sizin onayınıza sunar.

## Projeyi ajan için hazırlama

Cursor Agent, proje kökündeki `AGENTS.md` veya `.cursor/rules` dosyalarındaki talimatları okur. TypeScript projesi için bu dosyaya aşağıdakileri ekleyin:

- Build, test ve lint komutları (ör. `pnpm build`, `pnpm test`, `pnpm lint`).
- Kaynak kod klasörleri (`src`, `tests`, `packages/*/src`).
- `strict` mod kullanıldığını ve `any` tipinden kaçınılması gerektiğini belirtin.
- Monorepo ise workspace kökünü ve paket bağımlılıklarını tanımlayın.
- Tip kontrol komutunu ekleyin: `tsc --noEmit` veya `pnpm exec tsc --noEmit`.
- Değişiklik yapmadan önce mevcut tip hatalarını listeleyin; ajan yalnızca istenen dosyayı düzeltsin, tüm projeyi yeniden düzenlemesin.

Aşağıda gerçekçi bir `AGENTS.md` örneği verilmiştir:

```markdown
# TypeScript Proje Kuralları

## Komutlar
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Tip kontrol: `pnpm exec tsc --noEmit`

## Klasör Yapısı
- `src/` ana kaynak kod; `tests/` testler; `packages/*/src` monorepo paketleri.
- Her paket kendi `tsconfig.json` dosyasına sahiptir; kök `tsconfig.json` referansları içerir.

## TypeScript Kuralları
- `strict: true` her zaman açıktır; `any`, `@ts-ignore` ve `@ts-expect-error` kullanmayın.
- Tip daraltma için `in`, `typeof`, `instanceof` veya discriminated union kullanın.
- Generic fonksiyonlarda tip parametreleri açıkça belirtin; tip çıkarımına güvenmeyin.
- Değişiklik yaparken yalnızca istenen dosyayı düzenleyin; tüm projeyi yeniden yazmayın.
- Her adımdan sonra `pnpm exec tsc --noEmit` çalıştırın ve hataları giderin.
```

Bu talimat dosyasını versiyon kontrolüne ekleyin; böylece tüm ekip üyeleri ve ajan aynı kuralları kullanır. Ajan ayrıca `.cursor/rules` altındaki kural dosyalarını da okuyabilir; bu dosyalar daha modüler bir yapı sunar. Örneğin `typescript.rules` dosyasına yalnızca tip kurallarını, `ci.rules` dosyasına CI komutlarını koyabilirsiniz.

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

Verimli bir döngü şöyle işler: görevi küçük adımlara bölün, ajanın her adımda plan yapmasını isteyin, ürettiği diff’i dikkatle inceleyin ve ardından tip kontrol ve testleri çalıştırın. Ajanın tek seferde büyük bir değişiklik yapmasına izin vermeyin; her adımı kendiniz onaylayın. Örneğin bir refactor görevinde önce arayüzleri güncelleyin, sonra implementasyonları, son olarak testleri. Her adımda `git diff` çıktısını inceleyin ve `tsc --noEmit` komutu ile hata olmadığını doğrulayın.

Aşağıda tipik TypeScript görevleri için kullanabileceğiniz örnek istemler verilmiştir:

- `src/utils/parse.ts` dosyasındaki `tsc` hatalarını listele ve `strict` moda uygun şekilde düzelt. `any` kullanma.
- `src/api/client.ts` içindeki `fetchData` fonksiyonunu generic yap; dönüş tipini `T` olarak belirt ve çağrıları güncelle.
- `processInput` fonksiyonunda `input` parametresi `string | number`; tip daraltma ekle ve her dalı test et.
- `packages/shared` paketindeki `User` tipine yeni bir alan ekle; bağımlı paketlerdeki kullanımları bul ve güncelle.

Bu istemlerde açıkça dosya yolu, beklenen davranış ve kısıtları belirtmek ajanın doğru sonuç üretme olasılığını artırır. Ayrıca ajanın plan istemesini sağlayabilirsiniz: `Bu görev için önce planını açıkla, sonra onay verirsem uygula.` Bu, büyük değişikliklerde kontrolü elinizde tutmanızı sağlar.

Aşağıdaki tablo, doğrulama sürecinde hangi komutun ne işe yaradığını özetler:

| Komut | Ne kontrol eder |
|-------|----------------|
| `pnpm exec tsc --noEmit` | Tip hatalarını ve strict mode ihlallerini |
| `pnpm test` | Birim testlerini ve davranışı |
| `pnpm lint` | Kod stili ve potansiyel hataları |
| `git diff` | Ajanın yaptığı değişiklikleri gözden geçirme |

## Hangi işler iyi gider, nelere dikkat etmeli?

Cursor Agent şu TypeScript işlerinde oldukça başarılıdır:

- **Tip hatalarını düzeltme:** `tsc` çıktısındaki her hatayı okuyup düzeltir; özellikle `Property 'x' does not exist` gibi basit hatalar.
- **Tip daraltma:** Union type’larda `if` blokları ile daraltma ekler; `in` operator veya `typeof` kullanır.
- **Generic fonksiyonlar:** Mevcut fonksiyonları generic hale getirir; tip parametrelerini ve kısıtlarını ekler.
- **Refactor:** Tip tanımlarını ayrı dosyalara taşır, interface’leri yeniden adlandırır.
- **tsconfig ayarları:** `strict` bayraklarını ekler veya kaldırır (dikkatli olun; ajan bazen gereksiz yere gevşetebilir).

Ancak şu tuzaklara dikkat edin:

- **Hayali tipler:** Ajan bazen mevcut olmayan bir tip veya modül import edebilir. Her diff’i `tsc --noEmit` ile doğrulayın.
- **`any` kullanımı:** Ajan karmaşık bir hatayı çözmek için `any` veya `@ts-ignore` ekleyebilir. AGENTS.md dosyanızda bunu yasaklayın.
- **tsconfig değişiklikleri:** Ajan, `strict` bayrağını kapatarak hataları gizlemeye çalışabilir. Bu değişiklikleri reddedin.
- **Monorepo sınırları:** Ajan, paket bağımlılıklarını yanlış anlayıp başka paketin dosyasını değiştirebilir. Her paket için ayrı istem verin.
- **Tip daraltma aşırılığı:** Gereksiz yere karmaşık tip guard’ları üretebilir; sade ve okunaklı kodu tercih edin.
- **Generic karmaşası:** Ajan, generic tip parametrelerini gereğinden fazla çoğaltabilir; tip çıkarımını bozabilir. Basit tutun ve gerekirse sınırlandırın.

## Test ve doğrulama

TypeScript projelerinde ajanın çıktısını doğrulamanın en güvenilir yolu `tsc --noEmit` komutunu çalıştırmaktır. Ajanın her değişikliğinden sonra bu komutu siz çalıştırın; ajan kendisi de çalıştırabilir ama yine de kontrol edin. Ayrıca projenin test süitini çalıştırın: `pnpm test` veya `npm test`. Eğer lint aracınız varsa `pnpm lint` ile stil ve tip güvenliği kurallarını denetleyin.

Ajanın ürettiği diff’i satır satır inceleyin; özellikle `any`, `as` tip iddiaları ve `// @ts-ignore` gibi ifadeleri arayın. Monorepo’da her paketin kendi tip kontrolünü ayrı ayrı çalıştırın; örneğin `pnpm --filter @myorg/shared exec tsc --noEmit`. CI ortamında zaten bu kontroller varsa, yerel olarak aynı komutları kullanmak ajanın CI’ı geçmesini sağlar. Ajanın değişikliklerini birleştirmeden önce `git diff` ile tüm değişiklikleri gözden geçirin; tip sisteminin sessizce geçmesine izin veren `any` veya `as any` ifadelerini reddedin.

Ayrıca test kapsamını artırmak için ajanın yazdığı kodlara birim testleri eklemesini isteyebilirsiniz. Örneğin yeni eklenen bir tip guard için pozitif ve negatif test senaryoları isteyin. Bu, tip güvenliğinin yanı sıra davranışsal doğruluğu da sağlar.

## AgentVera ile birden fazla ajan çalıştırma

AgentVera, aynı TypeScript projesinde birden fazla kodlama ajanını paralel çalıştırmanızı sağlayan bir masaüstü uygulamasıdır. Her ajan kendi git worktree’sinde çalıştığı için dosyalar birbirinin üzerine yazmaz; böylece aynı anda farklı paketlerde veya özelliklerde güvenle geliştirme yapabilirsiniz. Bir ajanın turu bittiğinde otomatik kod incelemesi devreye girer ve bulgular `dosya:satır` biçiminde gösterilir; bu, TypeScript tip hatalarını hızlı yakalamanıza yardımcı olur. Ayrıca her turun anlık görüntüsü (checkpoint) alındığı için istediğiniz bir noktaya tek tıkla geri dönebilirsiniz. Token bütçeleri sayesinde ajanın harcamasını sınırlandırabilir, bütçe dolduğunda ajan durur ama konuşmasını korur. Daha fazla bilgi için [paralel kodlama ajanları](/blog/paralel-yapay-zeka-kodlama-ajani-araclari/) sayfasına göz atabilirsiniz.

## Kapanış

Cursor Agent, TypeScript projelerinde tip güvenliğini koruyarak hızlı geliştirme yapmanızı sağlar. Doğru proje talimatları, küçük adımlı istemler ve sürekli `tsc` doğrulaması ile ajanın çıktısını güvenle kullanabilirsiniz. Terminal tabanlı ajanlar ve editör entegrasyonu hakkında daha fazla karşılaştırma için [Claude Code mu Cursor mu?](/blog/claude-code-mu-cursor-mu/) yazısına bakabilirsiniz.

## Sık sorulanlar

**Cursor Agent TypeScript projesinde nasıl başlatılır?** Proje klasöründe cursor-agent komutunu çalıştırın; ajan AGENTS.md veya .cursor/rules dosyalarındaki talimatları okur. TypeScript için build ve test komutlarını bu dosyada belirtmek ilk adımı kolaylaştırır.

**Cursor Agent TypeScript hatalarını düzeltebilir mi?** Evet, tsc hatalarını, tip daraltma eksiklerini ve generic kullanımındaki sorunları düzeltebilir. Ancak çıktıyı mutlaka tsc --noEmit ve testlerle doğrulamalısınız.

**AGENTS.md dosyasına TypeScript için neler yazılmalı?** Build, test ve lint komutlarını, kaynak kod klasörlerini, strict mode’u ve tip kurallarını belirtin. Örneğin pnpm build, pnpm test, pnpm lint ve tsc --noEmit komutları ile any kullanımından kaçınma talimatı ekleyin.

**Cursor Agent monorepo’da nasıl çalışır?** Monorepo’da tsconfig referanslarını ve workspace kökünü AGENTS.md dosyasında tanımlayın. Ajan, paket sınırlarını anlar ve yalnızca ilgili pakette değişiklik yapar; yine de her paketin kendi test ve tip kontrolünü ayrı ayrı çalıştırması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/