cursor-agent komutuyla proje klasöründe başlatılan Cursor Agent, React projelerinde terminalden kod üretmek, test yazmak ve refactor yapmak için kullanışlıdır. React’in bileşen ve hook tabanlı yapısı, ajanın diff üzerinden çalışmasına iyi uyum sağlar; ancak yanlış useEffect, state yönetimi veya prop drilling gibi konularda ajan kolayca hatalı kod üretebilir. Bu rehberde, ajanı React’e özel kurallarla nasıl besleyeceğinizi, güvenli bir çalışma döngüsünü ve tipik görevlerde dikkat etmeniz gereken noktaları anlatıyorum. Cursor Agent hakkında genel bilgiye ayrıca bakabilirsiniz.
React projelerinde neden Cursor Agent?
React’in bileşen tabanlı yapısı, terminal ajanının dosya bazlı değişikliklerine doğal bir zemin sunar. Bir bileşen genellikle kendi .tsx dosyasında, hook’ları, props’ları ve JSX’iyle birlikte durur; ajan dosyanın tamamını görüp tutarlı bir değişiklik yapabilir. Vite gibi hızlı bir geliştirme sunucusu ve Vitest gibi hızlı bir test çalıştırıcısı, ajanın her adımda geri bildirim almasını sağlar. Buna karşılık React’in hook kuralları, useEffect bağımlılık dizileri ve yeniden render davranışı ajan için ciddi hata kaynağıdır. Bu yüzden Cursor Agent’ı genel bir kod üretici gibi değil, açık talimatlarla yönlendirilen bir yardımcı olarak kullanmak gerekir.
React projesini agent için hazırlamak
Agent, proje kökündeki AGENTS.md veya .cursor/rules dosyasını okur. Bu dosyaya build, test ve lint komutlarını, klasör düzenini ve React’e özgü kuralları yazın. Aşağıdaki örnek, Vite + TypeScript + Vitest + Storybook kullanan bir proje için yeterli bir başlangıçtır. Daha detaylı terminal kurulumu için Cursor CLI nasıl kullanılır? rehberine bakabilirsiniz.
# AGENTS.md
## Komutlar
- `pnpm dev` – Vite dev sunucusu
- `pnpm build` – `tsc -b && vite build`
- `pnpm test` – `vitest run`
- `pnpm test:watch` – `vitest`
- `pnpm lint` – `eslint .`
- `pnpm storybook` – Storybook dev sunucusu
## Klasör kuralları
- `src/components/` – genel, yeniden kullanılabilir bileşenler
- `src/features/` – iş alanına özel modüller
- `src/hooks/` – özel hook'lar
- `src/lib/` – saf yardımcılar
- `src/test/` – test yardımcıları
## React kuralları
- Sadece fonksiyon bileşenleri ve hook kullan.
- Hook'lar bileşenin en üstünde olmalı; koşul içine alınmamalı.
- `useEffect` yalnızca dış dünyayla senkronizasyon için; türetilmiş veriyi state'e kopyalama.
- İki seviyeden fazla prop drilling yapma; gerekirse Zustand veya Context kullan.
- Sunucu durumu için React Query, istemci durumu için Zustand kullan.
- Dosya adı bileşen adıyla aynı olsun: `Button.tsx`.Bu kurallar ajanın varsayılan davranışını sınırlar. Örneğin useEffect içinde veri çekmesini istemiyorsanız, bunu açıkça belirtmeniz gerekir. State kütüphanesi değiştiyse veya test komutunuz farklıysa dosyayı güncelleyin; ajan her görevde bu dosyayı yeniden okur. AGENTS.md ile .cursor/rules arasında seçim yaparken proje geneli talimatlar için AGENTS.md yeterlidir; daha ince ayar istiyorsanız .cursor/rules altında React, TypeScript veya test için ayrı kural dosyaları kullanabilirsiniz. Kullandığınız state kütüphanesi, router veya form çözümü ne olursa olsun buraya yazın; ajan aksi hâlde kendi varsayılanıyla çelişen kod üretebilir.
Çalışma döngüsü ve örnek promptlar
Güvenli bir döngü şöyle işler: önce ajanın yalnızca plan çıkarmasını isteyin; planı onayladıktan sonra tek tek küçük adımlar verin. Her adımdan sonra pnpm test ve pnpm lint çalıştırmasını isteyin. Son olarak git diff çıktısını kendiniz inceleyin; ajanın özetlediği değişiklikler yerine gerçek diff’e bakın. Bu döngü, React’te sık yaşanan gizli state hatalarını erken yakalar. Tipik React istekleri için şu promptlar iyi sonuç verir:
src/components/ProductCard.tsxiçindeki fiyatıIntl.NumberFormatile formatlayan bir yardımcı oluştur ve bileşende kullan. Mevcut testleri güncelle.- Bu form bileşenine
react-hook-formile doğrulama ekle; hata mesajlarınıaria-livebölgesinde göster ve React Testing Library ile test yaz. useFetchUsershook’undakiuseEffecttabanlı isteği React QueryuseQueryile değiştir; loading ve error durumlarını aynı şekilde döndür.- Storybook’ta
Buttoniçin primary, secondary ve disabled varyantlarını ekle; mevcut CSS modüllerini kullan. - Vitest ile
ShoppingCartreducer’ı için test yaz; ürün ekleme, çıkarma ve stok aşımı senaryolarını kapsa.
Bu promptlarda ajan ilgili dosyaları okur, değişikliği yapar ve testleri çalıştırır; siz yalnızca diff’i onaylarsınız.
Tipik React görevleri ve dikkat edilmesi gerekenler
Cursor Agent şu işlerde iyidir: yeni bileşen oluşturmak, bir bileşeni TypeScript’e çevirmek, hook çıkarmak, test yazmak, Storybook hikâyesi eklemek ve bağımlılık güncellerken kırılan testleri düzeltmek. Buna karşılık ajanın önerdiği kodu körlemesine kabul etmeyin. Aşağıdaki tablo sık karşılaşılan görevleri ve dikkat noktalarını özetler.
| Görev | İyi prompt | Dikkat edilecek nokta |
|---|---|---|
| Bileşen oluşturma | src/components/Button.tsx içinde, children ve variant props alan erişilebilir bir buton bileşeni yaz. | Gereksiz useMemo/useCallback, eksik aria öznitelikleri, stil dosyasını yanlış import etme. |
| useEffect dönüşümü | useEffect ile yapılan veri çekmeyi React Query useQuery’ye çevir; hata ve yükleme durumlarını koru. | Bağımlılık dizisinden kaynaklı sonsuz döngü, stale closure, gereksiz abort. |
| Global state ekleme | Sepet durumunu Zustand store’a taşı; bileşenlerde seçici hook kullan. | Store’da türetilmiş veri tutmak, tüm store’u seçmek, prop drilling’i ajanın bırakması. |
| Test yazma | SearchInput için kullanıcı arama senaryosunu RTL ile test et. | container.querySelector gibi uygulama detayları, act uyarıları, eksik userEvent. |
Özellikle hook kuralları, useEffect bağımlılıkları ve gereksiz memoizasyon konularında ajanın ürettiği kodu incelemeden geçmeyin. React’te yanlış bir state güncellemesi, testler geçse bile arayüzde gecikmeli hataya yol açabilir. Ajan bazen key prop’unu atlayabilir veya listelerde indeks kullanabilir; bunları diff’te arayın. Ayrıca ajan, mevcut stil çözümünüz yerine CSS dosyası açmayı deneyebilir; AGENTS.md içinde stil konvansiyonunu belirtirseniz bu risk azalır.
React’te test ve doğrulama
Ajanın terminal erişimi olduğu için doğrulamayı işin içine katmak kolaydır. Her görevde şu komutların çalıştığını görün:
pnpm test– Vitest + React Testing Library testleripnpm lint– ESLintpnpm build–tsctip denetimi ve Vite üretim derlemesi
Ajan yalnızca test yazmakla kalmaz, kırmızı testleri okuyup düzeltebilir. Storybook varsa pnpm storybook ile bileşeni görsel olarak da hızlıca kontrol edebilirsiniz. Testlerde ajanın getByTestId yerine getByRole gibi kullanıcı odaklı sorgular kullanmasını isteyin; aksi hâlde testler gerçek davranışı yansıtmaz. API istekleri içeren testlerde msw ile mock kullanmasını söylerseniz daha kararlı sonuç alırsınız. Tip hataları genellikle en net geri bildirimi verir; pnpm build çıktısını ajanın düzeltmesine izin verin, ancak tip düzeltmek için any kullanmasına izin vermeyin. Ajanın testleri çalıştırdıktan sonra özetlediği sonucu değil, terminal çıktısını isteyin; böylece başarısızlığın hangi testten geldiğini görürsünüz.
Birden fazla agent ile React projesi: AgentVera
React projesinde aynı anda birden fazla görev yürütüyorsanız AgentVera işe yarar. AgentVera, Cursor Agent dahil komut satırı ajanlarını yan yana gerçek terminallerde çalıştıran bir masaüstü uygulamasıdır. Ajanlar paralel çalışabilir; her biri kendi git worktree’sinde ilerlediği için dosyalar birbirini ezmez. Ajanın turu bittiğinde ikinci bir model kodu otomatik inceler ve bulguları dosya:satır olarak gösterir; her turun anlık görüntüsü saklanır ve tek tıkla geri alınabilir. Bu üç özellik, React’te hızlı deneme-yanılma döngüsünü güvenli tutar. Daha fazlası için paralel kodlama ajanları araçlarına bakın.
Sonuç
Cursor Agent, React projesinde tek başına sihirli bir çözüm değildir; doğru kurallar ve disiplinli bir döngüyle güçlü bir yardımcıya dönüşür. AGENTS.md’yi baştan iyi yazın, görevleri küçük tutun, her adımda testleri çalıştırın ve diff’i inceleyin. Böylece hem hızlı geliştirir hem de React’e özgü hataları erken yakalarsınız.