Cursor Agent ile Angular projelerinde pratik çalışma

Cursor Agent Angular projelerinde cursor-agent komutuyla başlatılan bir kodlama ajanıdır. Angular CLI, standalone component, signal ve RxJS gibi yapılarla çalışırken planlı küçük adımlar, test ve diff incelenmesiyle refactor ve hata ayıklama işlerini hızlandırır. Doğru proje talimatları sayesinde Angular’a özgü DI ve change detection tuzaklarını azaltır. Bu rehberde Angular geliştiricileri için pratik bir kurulum, çalışma döngüsü, sık yapılan işler ve doğrulama adımlarını bulacaksınız.

Cursor Agent ile Angular çalışması neden iyi sonuç verir

Angular’ın güçlü kuralları vardır: standalone component dosyaları, DI token’ları, TypeScript strict modu ve şablon ile sınıfın aynı dosyada olması. Ajan bu yapıyı tek diff içinde görebildiği için @Component metadata, import array ve sınıf mantığını birlikte değiştirir. Servis eklerken providedIn: 'root' kullanır, component’i standalone yapar ve routing dosyasını günceller. Signals ile RxJS arasındaki sınırı AGENTS.md içinde net tanımlarsanız ajan effect içinde state yazmak gibi yaygın hatalara düşmez. Ayrıca Angular CLI’nin ürettiği dosya adları ve klasör yapısına sadık kalarak yeni modüllerin mevcut projeyle uyumlu olmasını sağlar.

Angular’da component ve şablon aynı dosyada bulunur; ajan şablonu değiştirirken sınıftaki public alanların varlığını kontrol edebilir. Örneğin bir ProductListComponent içindeki products$ Observable’ını products signal’ine çevirirken şablondaki async pipe’ı kaldırıp doğrudan {{ products() }} yazabilir ve OnPush değişiklik algılamayı korur. Bu tür bütünsel değişiklikler, ajanın dosyanın tamamını okuması sayesinde tutarlı olur.

Buna karşın ajanın Angular’a özgü bazı incelikleri atlayabileceğini unutmayın: OnPush component’lerde markForCheck çağrısının gerekip gerekmediğini her zaman doğru değerlendiremeyebilir; effect içinde state güncelleyen kod üretebilir. Bu yüzden ajanı serbest bırakmak yerine sıkı bir inceleme döngüsü kurmak gerekir.

Proje kurulumu ve ajan talimatları

Ajan proje kökündeki AGENTS.md veya .cursor/rules dosyasını okur. Angular projesinde bu dosyaya CLI komutları, klasör kuralları ve Angular’a özgü kuralları yazın. Ajanın hangi komutu ne zaman çalıştıracağını bilmesi, yanlış test veya lint komutuyla zaman kaybetmesini önler. cursor-agent başlatma detayları için Cursor CLI nasıl kullanılır? Adım adım rehber faydalıdır. Örnek bir AGENTS.md aşağıdaki gibidir; kendi projenizin komutlarına göre güncelleyin.

# AGENTS.md

## Komutlar
- Kurulum: `npm ci`
- Geliştirme: `npm start`
- Test: `npm test -- --watch=false` (Jest) veya `ng test --watch=false --browsers=ChromeHeadless`
- Lint: `npm run lint`
- Build: `npm run build`
- Tip kontrolü: `npx tsc --noEmit`

## Klasör kuralları
- Feature bazlı klasörler: `src/app/features/<feature>/`
- Paylaşılan parçalar: `src/app/shared/`
- Her feature kendi routing dosyasına sahiptir.
- Servisler `src/app/core/services/` altında tutulur.

## Angular kuralları
- Yeni component'lar standalone olur.
- Servisler `providedIn: 'root'` ile sağlanır.
- Durum yönetiminde öncelik signal ve computed; RxJS yalnızca async kaynaklar için kullanılır.
- `OnPush` bileşenlerde `markForCheck` yerine sinyal veya async pipe kullan.
- Şablon tipleri her zaman açık yaz; `any` kullanma.
- Yeni dosyalar Angular CLI naming convention'a uyar: `kebab-case.component.ts`, `kebab-case.service.ts`.
- RxJS'ten sinyale dönüşümde `toSignal` veya `output()` kullan; `effect` içinde state yazma.
- Testlerde `TestBed` ile gerçek servis yerine stub kullan.

Bu kurallar, ajanın Angular CLI’nin varsayılan davranışlarına uygun kod üretmesini sağlar. Örneğin component oluştururken inline template yerine harici template dosyası kullanması gerektiğini burada belirtebilirsiniz.

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

Ajanı serbest bırakmayın. Önce mevcut dosyaları okutup plan isteyin, sonra tek bir sorumluluk verin. Her adımdan sonra git diff ile değişiklikleri inceleyin, npm test -- --watch=false ve npm run lint çalıştırın. Hata mesajlarını ajana geri vererek düzeltmesini isteyin; kendi başına tahmin etmesine izin vermeyin. Angular’da template tip hataları ancak build veya tsc ile yakalanır, bu yüzden ajan işini bitirdiğinde npm run build veya npx tsc --noEmit çalıştırın.

İyi bir döngü şöyle işler:

1. Ajanın okuması için ilgili dosyaları listeleyin: “Şu dosyaları oku: src/app/features/cart/cart.component.ts, cart.service.ts ve cart.store.ts. Mevcut mimariyi özetle.”
2. Dar kapsamlı bir değişiklik isteyin: “CartComponent içindeki items$ Observable’ını items signal’ine çevir. Şablondaki async pipe’ları {{ items() }} ile değiştir. Sadece bu dosyaları etkile.”
3. Ajanın ürettiği diff’i git diff ile inceleyin. Özellikle import array, constructor DI değişiklikleri ve şablondaki değişikliklere bakın.
4. Testleri ve lint’i çalıştırın. Hata çıktısını ajana yapıştırın: “Şu hata var: Property 'items' does not exist on type 'CartComponent'. Düzelt.”
5. Tip kontrolü ve build alın. Ardından bir sonraki adıma geçin.

Örnek promptlar:

• Mevcut ProductListComponent’i incele. Standalone kalacak şekilde, ürün verisini ProductService’ten alan signal tabanlı bir refactor planı çıkar; kod yazma, sadece plan ver.
• CartService’teki addToCart RxJS zincirini koru, ancak cartCount alanını signal’e çevir. Etkilenen testleri güncelle ve npm test -- --watch=false çalıştır.
• UserProfileComponent’in standalone import array’ine eksik ReactiveFormsModule’i ekle. Form kurulumunu FormBuilder ile sadeleştir ve yalnızca o dosyayı değiştir.
• Jasmine testlerini Jest’e taşı. Önce mevcut spec dosyalarını listele, hangi dönüşümlerin gerektiğini açıkla; kod değiştirme.
• app.config.ts içindeki provideHttpClient ayarını koruyarak yeni OrderService’i providedIn: 'root' ile ekle. OrderListComponent içinde DI ile kullan ve test yaz.
• ProductsComponent içindeki *ngFor döngüsünü yeni @for sözdizimine çevir. Track by ifadesini koru ve şablondaki tip kontrolünü npx tsc --noEmit ile doğrula.
• AuthGuard’ı functional guard’a çevir, CanActivateFn kullan. Eski class guard’ı sil ve routing dosyasındaki referansları güncelle. Testleri çalıştır.

Her prompt tek bir amaca odaklanmalı; böylece inceleme ve geri alma daha kolay olur.

Angular’a özgü güçlü yönler ve tuzaklar

Ajan en iyi şu işlerde çalışır:

Buna karşın şu noktalarda yakından izleyin: Standalone geçişi tamamlanmamış projelerde ajan @NgModule import’larını karıştırabilir. RxJS’ten signal’e dönüşümde effect içinde state yazma, yanlış computed bağımlılığı veya untracked kullanımı gibi hatalar oluşabilir. Yeni kontrol akışı @if ve @for ile eski *ngIf/*ngFor karışabilir. Büyük refactorlarda constructor tabanlı DI yerine inject() fonksiyonunun yanlış sıralanması veya OnPush component’lerde markForCheck yerine yanlış çağrı yapılabilir. Ajan ayrıca Angular CLI workspace kurallarını atlayıp src/app dışına dosya ekleyebilir; yolları her zaman doğrulayın. provideHttpClient gibi sağlayıcıların yanlış yerde eklenmesi veya withInterceptors kullanımı da dikkat gerektirir.

Test ve doğrulama

Ajanın ürettiği kodu doğrulamadan birleştirmeyin. Angular’da en önemli doğrulama adımları şunlardır:

• npm test -- --watch=false ile birim testleri çalıştırın; Jest kullanıyorsanız --runInBand ekleyin. Jasmine/Karma kullanıyorsanız ng test --watch=false --browsers=ChromeHeadless tercih edin.
• npm run lint ile şablon ve TypeScript kurallarını denetleyin.
• npm run build -- --configuration production çalıştırın; Angular compiler’ın strictTemplates ve fullTemplateTypeCheck ayarları ancak build sırasında şablon tip hatalarını ortaya çıkarır.
• npx tsc --noEmit ile tip kontrolü yapın; bu, şablon dışı TypeScript hatalarını yakalar.
• git diff --check ile boşluk hatalarını ve kazara yapılan değişiklikleri görün.
• Ajan test yazdıysa, TestBed içinde gerçek servis yerine stub kullanıldığını, fixture.detectChanges() çağrıldığını ve fakeAsync/tick kullanımının doğru olduğunu gözden geçirin.
• E2E test varsa npm run e2e ile kritik akışları ayrıca doğrulayın.

Angular testlerinde sık yapılan hatalar: TestBed.configureTestingModule içinde providers yerine imports içine servis eklenmesi, standalone component’lerde fixture.detectChanges() sonrası fixture.componentInstance üzerinden input set edilip tekrar detectChanges çağrılmaması, fakeAsync içinde tick() ile zaman ilerletmeden asenkron işlemlerin beklenmesi. Bu hataları ajana geri bildirerek testlerin yeşil olmasını sağlayın.

Paralel çalışma: AgentVera ile çoklu ajan

Angular projelerinde aynı anda farklı feature’larda çalışmak için AgentVera, Cursor Agent dahil komut satırı ajanlarını kendi gerçek terminallerinde paralel çalıştırır. Her ajan kendi git worktree’sinde ilerlediği için aynı app.config.ts veya servis dosyası üzerine yazma çakışması olmaz. Ajan turu bitince ikinci model otomatik kod incelemesi yapar; Angular’da DI ve standalone import hatalarını dosya:satır olarak gösterir. Checkpoint’ler sayesinde yanlış bir refactor tek tıkla geri alınabilir ve oturum adım adım tekrar izlenebilir. Daha geniş paralel kurulum seçenekleri için Paralel kodlama ajanları için en iyi araçlar (2026) rehberine bakabilirsiniz.

Sonuç

Cursor Agent Angular projelerinde sıkıcı refactorları, servis çıkarma işlerini ve test yazımını hızlandırır; ancak Angular’a özgü kuralları açıkça tanımlamak ve her adımı doğrulamak şarttır. AGENTS.md dosyanızı güncel tutun, ajanı küçük adımlarla çalıştırın ve diff ile test çıktılarını inceleyin. Böylece standalone component, signal ve RxJS geçişlerinde güvenli bir iş akışı kurarsınız.