Claude Code ile React projelerinde hızlı geliştirme

Claude Code’u React projenizde kullanmak için terminalde proje klasörüne gidip claude yazmanız yeterli. Bu rehber, ajanı bileşen ve hook geliştirme, test ve refactor işlerinde verimli kullanmanın pratik yolunu gösterir. Daha önce Claude Code kullanmadıysanız, başlangıç için Claude Code nasıl kullanılır rehberine göz atabilirsiniz.

Neden Claude Code React için uygun

Claude Code terminalde dosyaları okur, düzenler, komut çalıştırır ve git diff üretebilir. React tarafında en sık yapılan işler kalıp tabanlıdır: fonksiyonel bileşen iskeleti, prop tipleri, useState/useEffect kullanımı, liste render etme, form yönetimi ve test kurulumu. Ajan mevcut bileşenleri ve hook’ları okuyarak projenin kod tarzına uygun öneriler üretir; Vite, Vitest ve ESLint komutlarını çalıştırarak sonucu doğrular. Örneğin, Button bileşenine yeni bir variant eklemek istediğinizde ajan önce dosyayı ve mevcut stilleri inceler, ardından prop tanımını, stil koşulunu ve testi birlikte günceller. Bileşenler arası veri akışını anlamak için import grafiğini takip eder; context veya state kütüphanesi kullanıyorsanız, değişikliğin diğer bileşenleri nasıl etkilediğini kontrol eder. Böylece siz mimari kararlara ve iş kurallarına odaklanırken tekrar eden yazım işlerini devredersiniz. Claude Code terminal tabanlı olduğu için React projesinin gerçek komutlarıyla bütünleşir; bu da onu yalnızca sohbet eden bir asistandan ayırır. Ayrıca test ve lint komutlarını kendi başına çalıştırıp çıktıyı yorumlayarak iteratif düzeltme yapabilir.

Projeyi ajana hazırlama ve CLAUDE.md

Claude Code her oturumda proje kökündeki CLAUDE.md dosyasını okur. React projesi için bu dosyaya komutlar, klasör düzeni ve React’e özgü kurallar yazın. Ajan, siz her seferinde tarif etmek zorunda kalmadan test komutunu, lint’i ve dosya yerlerini bilir. Dosya kısa ve net olmalı; ajanın her turda okuyacağı için gereksiz açıklamalardan kaçının. Kuralları değiştirdiğinizde CLAUDE.md’yi güncelleyin; ajan yeni kuralları hemen uygular. Ayrıca projede kullandığınız state kütüphanesi, form aracı veya UI kütüphanesi gibi önemli bağımlılıkları belirtin; böylece ajan yanlış import aramaz.

Örnek CLAUDE.md:

# CLAUDE.md

## Komutlar
- Kurulum: `npm install`
- Geliştirme: `npm run dev` (Vite)
- Test: `npm run test -- --run` (Vitest)
- Lint: `npm run lint`
- Tip kontrolü: `npx tsc --noEmit`
- Storybook: `npm run storybook`

## Klasör düzeni
- `src/components/` yeniden kullanılabilir bileşenler
- `src/hooks/` özel hook'lar
- `src/pages/` sayfa bileşenleri
- `src/__tests__/` test dosyaları
- `src/stories/` Storybook hikayeleri
- `src/store/` state yönetimi (Zustand store'ları)

## React kuralları
- Fonksiyonel bileşenler ve hook'lar kullan.
- Bileşen ve dosya adları PascalCase, hook dosyaları `use` ile başlar.
- Prop tiplerini TypeScript ile tanımla; `any` kullanma.
- Yan etkileri `useEffect` içinde yaz ve temizleme fonksiyonu döndür.
- Testlerde `@testing-library/react` ve `user-event` kullan; uygulama detayına değil kullanıcı davranışına odaklan.
- State yönetimi için önce yerel state, sonra context; global state gerekirse Zustand kullan.
- Formlarda `react-hook-form` ve `zod` şemalarını kullan.
- Stil için CSS Modules tercih et; inline style'dan kaçın.

Bu örnekteki gibi, ajanın her komutta ne çalıştıracağını bilmesi için --run bayrağı gibi incelikleri ekleyin. Ayrıca src/__tests__/ klasörünü belirtmek, ajanın test dosyalarını doğru yere koymasını sağlar. Hikaye dosyalarını src/stories/ altında tutmak, Storybook entegrasyonunu hızlandırır. State kütüphanesi ve form yaklaşımını yazmak, ajanın yanlış mimari önermesini engeller. CLAUDE.md’yi projeye özel tutun; genel React kuralları yerine ekibinizin kararlarını yazın.

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

Verimli çalışma için büyük bir görevi tek seferde istemeyin. Şu döngüyü izleyin:

1. Önce ajanın ilgili dosyaları okumasını ve kısa bir plan çıkarmasını isteyin.
2. Plana göre tek bir küçük değişiklik yaptırın.
3. Ajanın testleri ve tip kontrolünü çalıştırmasını isteyin.
4. git diff ile değişiklikleri inceleyin.
5. Hata varsa düzeltmesini söyleyin; yoksa bir sonraki küçük adıma geçin.

Örnek istekler:

• “Mevcut Button bileşenini incele; variant ve size prop’ları ekle, mevcut stilleri bozmadan testini güncelle.”
• “Kullanıcı listesini fetch ile çeken bir useUsers hook’u yaz; loading, error ve data döndürsün, temizleme fonksiyonu olsun.”
• “Vitest’te Modal bileşeni için açılma, kapanma ve dış tıklama senaryolarını React Testing Library ile yaz.”
• “CartContext içindeki gereksiz yeniden render’ları bul; useMemo ve useCallback ile düzelt ama davranışı değiştirme.”
• “Bu sayfa bileşenini UserList ve UserFilter olarak ikiye ayır; importları güncelle ve mevcut testleri çalıştır.”

Her adımda ajanın neyi neden değiştirdiğini kısaca açıklamasını isteyebilirsiniz; bu, diff incelemesini hızlandırır. Ayrıca ajanın planını önce sizin onaylamanız, büyük refactor’larda güven verir. Örneğin, “önce hangi dosyaları değiştireceğini listele” dedikten sonra onay verip uygulatabilirsiniz. Planlama için Claude Code plan modu rehberine de başvurabilirsiniz.

React’te iyi yaptığı işler ve dikkat edilecek noktalar

Claude Code şu React işlerinde güçlüdür: yeni bileşen ve hook iskeleti çıkarmak, prop tiplerini TypeScript ile yazmak, liste ve koşullu render kalıplarını uygulamak, test dosyalarını oluşturmak, importları yeniden düzenlemek ve küçük refactor’lar yapmak. State kütüphanesi entegrasyonu veya form şeması gibi net kurallı işlerde de tutarlı sonuç verir. Örneğin, Zustand store’u içindeki bir aksiyonu değiştirmek istediğinizde, ajan ilgili store dosyasını ve kullanan bileşenleri bulup günceller. Storybook hikayesi eklemek de iyi çalışır; bileşenin farklı prop kombinasyonlarını hızlıca oluşturur.

Dikkat edilmesi gereken yerler:

• useEffect bağımlılık dizisi: Ajan bazen eksik veya gereksiz bağımlılık yazabilir; özellikle kapalı değişkenlerde stale closure oluşur. Değişiklikleri inceleyip react-hooks/exhaustive-deps kuralını çalıştırın. Örnek: useEffect(() => { fetchData(id); }, []) yazarsa id değiştiğinde yeniden çalışmaz; bunu mutlaka düzeltin.
• Gereksiz yeniden render: useMemo veya useCallback eklerken ajan aşırıya kaçabilir. Önce profilleme yapmadan mikro optimizasyon istemeyin. Bazen basit bir bileşende useCallback sarmak okunabilirliği azaltır; yalnızca gerçek performans sorununda uygulayın.
• Bileşen sözleşmeleri: Mevcut bir bileşenin prop adını veya davranışını değiştirirse tüm kullanımları güncellemeli; ajan bazen bir yeri atlar. Değişiklik sonrası rg ile prop adını aratıp tüm kullanımların güncellendiğini doğrulayın.
• Testi geçirmek için testi değiştirme: “Testi düzelt” derken ajanın üretim kodunu değil testi gevşetmediğinden emin olun. Başarısız testi önce sizinle paylaşmasını isteyin. Ajan, getByText yerine queryByText kullanarak yokluk testini geçiştirebilir; niyeti sorgulayın.
• Tip hataları: Ajan any kullanarak tip kontrolünü geçiştirebilir; CLAUDE.md’de any yasaklıysa daha az olur. Yine de diff’te any görürseniz neden kullanıldığını sorun.
• State mimarisi: Yerel state yeterliyken context veya global store önerebilir. Kabul etmeden önce gerçek ihtiyacı sorgulayın. Örneğin, yalnızca bir bileşende kullanılan bir durum için Zustand store açmak gereksizdir.
• StrictMode: Ajan useEffect içindeki API çağrılarını çift çalıştırabilir; geliştirme ortamında bu normaldir ama temizleme fonksiyonu yoksa yan etki iki kez olur. Ajanın yazdığı effect’lerde temizleme (cleanup) döndürdüğünden emin olun.

Test ve doğrulama

Claude Code ile her değişiklikten sonra doğrulama zincirini çalıştırın. Ajan komutları kendisi koşabilir; siz çıktıyı takip edin. React için pratik doğrulama tablosu:

Özellikle hook’lu bileşenlerde testleri user-event ile yazdırın; fireEvent yerine kullanıcı davranışına yakın olur. Ajan test eklerken await screen.findBy... kullanmasını isteyin; böylece asenkron state güncellemeleri yarışa girmez. Ajan test yazarken vi.mock ile modül taklit edebilir; ancak aşırı mock gerçek davranışı gizler. Yalnızca ağ ve zamanlayıcı gibi dış bağımlılıkları mocklayın. Snapshot testleri kararlı olabilir ancak büyük snapshot’lar diff incelemesini zorlaştırır; ajanın snapshot kullanmasını istiyorsanız küçük bileşenlerle sınırlayın. Ajan test dosyalarını src/__tests__/ altına koyduğunda, import yollarının doğru olduğunu doğrulayın. Ayrıca testlerin --run bayrağıyla çalıştığından emin olun; aksi halde watch modda takılır. Gerekirse ajanın npx vitest related komutunu kullanarak yalnızca değişen dosyalarla ilgili testleri koşturmasını isteyin.

Bir React projesinde birden fazla ajanla çalışma

React’te birden çok bileşeni veya sayfayı aynı anda geliştirirken AgentVera işe yarar. Her ajan kendi git worktree’sinde çalıştığı için biri Button’ı düzenlerken diğeri useUsers hook’unu ezmez. Ajanın turu bitince ikinci bir model kodu inceler; hook bağımlılıkları veya state güncellemeleri gibi React hatalarını dosya:satır olarak gösterir. Checkpoint’ler sayesinde kötü bir refactor’ı tek tıkla geri alabilirsiniz. Token bütçeleri ise uzun test oturumlarında ajanın kontrolden çıkmasını engeller. Daha fazla ayrıntı için Birden fazla Claude Code ajanını paralel çalıştırma sayfasına bakabilirsiniz.

Kapanış

Claude Code, React projenizde günlük geliştirme hızını artıran pratik bir araçtır. Proje kurallarını CLAUDE.md ile netleştirin, küçük adımlarla ilerleyin, testleri ve diff’i sık sık kontrol edin. Ajanın önerdiği mimari değişiklikleri sorgulayın; son kararı siz verin. Böylece hem hızlı hem de güvenli bir React geliştirme döngüsü yakalarsınız. Unutmayın, ajan bilgi işçinizdir; React’in inceliklerini bilen sizsiniz.