Gemini CLI ile React projelerinde pratik çalışma rehberi

Gemini CLI, React projesinde terminalden gemini komutuyla başlatılır; bileşen ekleme, hook dönüştürme, test yazma ve refactor işlerini doğrudan kod tabanında yapabilir. Bu rehberde Vite, Vitest, React Testing Library ve Storybook kullanan tipik bir kurulumda ajanın nasıl çalıştırılacağını, hangi kurallarla yönlendirileceğini ve güvenli bir döngünün nasıl kurulacağını anlatılıyor. Gemini CLI hakkında temel bilgi için ayrıntılı sayfaya bakabilirsiniz.

Gemini CLI neden React işlerine uygun

React projelerinde kod genellikle küçük ve sınırları belirli parçalara ayrılır: bileşenler, hook’lar, test dosyaları ve stil dosyaları. Gemini CLI, bu dosyaların içeriğini okuyup değiştirebilir, ardından test ve lint komutlarını kendisi çalıştırarak sonucu doğrulayabilir. Vite’ın hızlı geri bildirimi sayesinde değişiklikler kısa sürede test edilir; agent, npm run test -- --run gibi komutları GEMINI.md’den öğrenir. Örneğin bir useEffect içindeki fetch mantığını custom hook’a çıkarırken agent, dosya içindeki mevcut testleri görebilir ve onları da güncelleyebilir. JSX yapısı ve hook kuralları agent için tahmin edilebilir olduğundan refactor önerileri daha isabetli olur; Storybook entegrasyonu sayesinde görsel doğrulama adımlarını da tarif edebilirsiniz. Üstelik agent, React’in bileşen yaşam döngüsünü ve state güncelleme davranışını bildiği için useState ve useReducer arasındaki seçimi de proje bağlamına göre yapabilir. Bileşenlerinizi küçük ve odaklı tuttuğunuz sürece Gemini CLI’nın ürettiği kod, insan elinden çıkmış gibi okunabilir ve bakımı kolay olur.

Projeyi agent için hazırlama: GEMINI.md

Agent’ın React projenizde doğru komutları ve kuralları bilmesi için kök dizine GEMINI.md ekleyin. Dosyada build, test, lint komutları, klasör yapısı ve React’e özel kurallar yer almalı. Agent her göreve başlarken bu dosyayı okur; böylece yanlış test komutu veya yanlış klasör varsayımı yapmaz. Kurulum adımları için Gemini CLI nasıl kullanılır? Adım adım rehber sayfasına da bakılabilir. Aşağıdaki örnek, Vite + Vitest + React Testing Library + Storybook kullanan bir proje için kısa ama işlevsel bir dosyadır; kendi projenize göre komutları ve kuralları düzenleyebilirsiniz.

Örnek GEMINI.md:

# GEMINI.md

## Komutlar
- dev: `npm run dev`
- build: `npm run build`
- test: `npm run test -- --run`
- lint: `npm run lint`
- storybook: `npm run storybook`

## Klasör yapısı
- `src/components`: yeniden kullanılabilir bileşenler
- `src/hooks`: custom hook'lar
- `src/pages`: rota bazlı sayfalar
- `src/__tests__`: test dosyaları (bileşenlerle aynı klasörde de olabilir)
- `src/stories`: Storybook hikayeleri

## Kurallar
- Bileşenler fonksiyonel olmalı, hook'lar `use` önekiyle yazılmalı.
- `useEffect` bağımlılık dizisini eksiksiz yaz; lint hatası varsa düzelt.
- Test sorgularında `data-testid` yerine rol, etiket ve metin sorgularını tercih et.
- Yerel state yeterliyse Context, Zustand veya React Query'ye geçme.
- Yeni bir bileşen eklediğinde Storybook story'sini de ekle.
- Tailwind varsa class sıralamasını koru; gereksiz `!important` kullanma.

Bu dosyayı güncel tutmak agent’ın başarısını doğrudan etkiler; özellikle test komutunu atlamak ajanın yanlış npm test çağırmasına neden olabilir. Ayrıca GEMINI.md’ye React’e özgü ek kurallar ekleyebilirsiniz: örneğin useEffect içinde asenkron fonksiyon tanımlama, useMemo ve useCallback kullanımı için eşik değerleri, erişilebilirlik öznitelikleri (aria-*, rol) gibi. Ajan, bu kuralları hem kod üretiminde hem de mevcut kodu düzeltirken dikkate alır.

Güvenli çalışma döngüsü

Agent’a büyük bir görevi tek seferde vermek yerine şu döngüyü izleyin: önce görevi netleştirin, agent’tan kısa bir plan isteyin, küçük bir adım uygulatın, testleri çalıştırın, diff’i inceleyin, sonra devam edin. Bu döngü, ajanın yanlış varsayımlarını erkenden yakalar ve geri dönüşü kolaylaştırır. İyi bir prompt yazımı için Kodlama ajanları için prompt nasıl yazılır? rehberindeki önerilere göz atabilirsiniz.

React’e özel örnek prompt’lar:

• “Mevcut Button bileşenini incele; variant prop’unu ekle ve primary ile secondary görünümlerini uygula. Mevcut testleri güncelle ve npm run test -- --run ile doğrula.”
• “useUsers hook’undaki fetch mantığını React Query’nin useQuery’siyle değiştir; hata, yükleme ve yeniden deneme durumlarını ekle. Testleri güncelle.”
• “LoginForm bileşenindeki doğrulamayı react-hook-form ile yeniden yaz; form gönderiminde API çağrısını mock’layan testi güncelle.”
• “Dashboard sayfasındaki useEffect ile veri yükleme kısmını kaldır; useQuery kullan. Gereksiz istekleri önlemek için staleTime ekle.”
• “Card bileşeni için Storybook’ta eksik olan default, withImage ve loading story’lerini yaz; argTypes’ta kontrolleri göster.”

Her adımdan sonra git diff ile neyin değiştiğini kontrol edin; agent’ın açıklamasıyla diff uyuşmuyorsa itiraz edin. Ajan bazen istenmeyen dosyaları da düzenleyebilir; diff’i satır satır incelemek bu riski azaltır. Ayrıca agent’tan her adımda hangi testlerin çalıştığını ve sonucunu raporlamasını isteyin; böylece test geçse bile mantık hatası olup olmadığını gözden geçirebilirsiniz.

Tipik React görevleri ve dikkat edilecekler

Agent şu işleri iyi yapar: bileşen oluşturma, prop tipi güncelleme, hook’a mantık çıkarma, liste render’ını map ile optimize etme, erişilebilirlik öznitelikleri ekleme, test yazma. Ancak React’e özgü bazı tuzaklara dikkat etmek gerekir:

Özellikle hook’ların çağrı sırası, useEffect temizlik fonksiyonları ve React 18 StrictMode’un geliştirme modunda effect’leri iki kez çalıştırması gibi konulara dikkat edin. Agent, StrictMode davranışını göz ardı edip “çift istek” sorunu rapor edebilir; temizlik fonksiyonlarını kontrol etmeden kabul etmeyin. Ayrıca ajan, bazen useEffect içinde asenkron fonksiyon tanımlayıp doğrudan çağırabilir; bu, lint kurallarıyla engellenebilir. useState güncellemelerinde fonksiyonel güncelleme kullanımı da gözden kaçabilir; ajanın ürettiği kodu manuel incelemek bu tür hataları yakalar.

Test ve doğrulama

Agent bir değişiklik yaptıktan sonra mutlaka şu komutları çalıştırın veya agent’a çalıştırtın:

• npm run test -- --run (Vitest watch modunu beklemeden tüm testleri koşar)
• npm run lint
• npm run build

Ayrıca React Testing Library sorgularının anlamlı olduğunu, testlerin DOM’da gerçek kullanıcı davranışını yansıttığını kontrol edin. Storybook kullanıyorsanız npm run storybook ile bileşenin görsel olarak bozulmadığını da doğrulayabilirsiniz. Agent’a “Değişikliklerin testini yaz ve hepsini çalıştır, sonucu göster” gibi bir talimat vermek, hataları erken yakalamayı sağlar. act() uyarıları veya fake timer kullanımı gerektiren testlerde agent bazen yanlış yönlendirebilir; bu durumda test çıktısını birlikte inceleyin. Test çalıştırma komutlarını GEMINI.md’de doğru tanımlamak, ajanın yanlış komutla boşa zaman harcamasını önler; ayrıca ajanın test sonuçlarını özetlemesini isteyerek hangi testlerin geçtiğini hızlıca görebilirsiniz.

Birden fazla ajan: AgentVera

React projelerinde birden fazla ajanı paralel çalıştırırken en kritik nokta dosya çakışmalarıdır; AgentVera her ajanı kendi git worktree’sinde çalıştırarak bunu önler. Otomatik kod incelemesi, bir ajan işini bitirdiğinde ikinci bir modelin React’e özgü hataları (yanlış hook kullanımı, eksik bağımlılıklar, state güncellemeleri) yakalamasına yardımcı olur. Checkpoint’ler yanlış bir refactor sonrası tek tıkla geri almayı; token bütçeleri ise ajan başına günlük harcamayı sınırlayarak uzun React oturumlarını yönetmeyi sağlar.

Sonuç

Gemini CLI, React projelerinde GEMINI.md ile doğru yönlendirildiğinde hızlı ve güvenilir bir kodlama ortağıdır. Küçük adımlar, test ve diff incelemesi ile ajanın önerilerini denetleyerek hem üretkenliği artırır hem de kod kalitesini korursunuz. Ajanın ürettiği kodu her zaman insan gözüyle değerlendirin; React’in incelikleri ve proje bağlamı, en iyi kodlama ajanlarının bile gözden kaçırabileceği ayrıntılar barındırır.