Codex, terminalde codex komutuyla başlatılan bir kodlama ajanıdır. React projesinde bileşen, hook, test ve refactor işlerini doğrudan dosya sisteminde yürütür. Bu yazı, Codex’i bir React projesinde güvenilir biçimde kullanmak için kurulumu, çalışma döngüsünü ve sık karşılaşılan tuzakları anlatır. Genel kullanım için Codex sayfasına göz atabilirsiniz.
Codex React işlerine neden uygun
React’in bileşen tabanlı yapısı, Codex’in dosya düzeyinde değişiklik yapmasına çok uygundur. Bir bileşenin props, state ve JSX çıktısı çoğu zaman tek bir dosyada görülebilir; Codex bu sınırları kolayca anlar. Hook’lar ve yardımcı fonksiyonlar da ayrı dosyalara bölündüğünde ajan, değişikliği izole edip mevcut testleri çalıştırarak geri bildirim alabilir. React Testing Library ve Vitest gibi araçların senaryoları metin tabanlı olduğu için Codex test yazarken davranışı doğrudan ifade edebilir. Storybook hikayeleri de aynı şekilde bileşenin farklı durumlarını üretmek için iyi bir iş kalemidir. Ayrıca form bileşenleri, liste render eden bileşenler veya veri çeken hook’lar gibi tekrar eden kalıpları hızlıca üretebilir. State kütüphaneleri (Zustand, Redux Toolkit gibi) kullanıyorsanız, ajanın mevcut kalıpları taklit etmesi için AGENTS.md içinde birer örnek dosyayı işaret edin. TypeScript’li bir projede ise prop tiplerini ve generic bileşenleri doğru yazması için tsconfig yollarını bilmesi yeterlidir. Codex, Vite gibi hızlı kurulumlu araçlarda çalışırken komutları bizzat çalıştırabilir; böylece döngüyü kısaltır. Örneğin yeni bir bileşen oluşturmasını istediğinizde, bileşeni, testini ve Storybook hikayesini tek seferde üretebilir. Ancak karmaşık state geçişleri veya performans optimizasyonları gibi nüanslı konularda insan gözetimi şarttır.
Projeyi Codex için hazırlamak
Codex kök dizindeki AGENTS.md dosyasını okur. React projesinde bu dosya; kullanılan komutları, klasör düzenini, state yönetimi tercihini ve test yaklaşımını net biçimde belirtmelidir. Böylece ajan her seferinde hangi test komutunu çalıştıracağını, bileşeni nereye koyacağını ve hangi kurallara uyacağını bilir. Dosya kısa ve öz olmalıdır; gereksiz satırlar bağlamı kirletir ve ajanın doğru karar vermesini zorlaştırır. Aşağıda Vite + TypeScript + Vitest kullanan bir proje için gerçekçi bir örnek yer alıyor:
# AGENTS.md
## Komutlar
- Kurulum: `npm install`
- Geliştirme: `npm run dev`
- Build: `npm run build`
- Test: `npm test -- --run`
- Lint: `npm run lint`
- Tip kontrolü: `npm run typecheck`
## Klasör düzeni
- Bileşenler `src/components` altında, her biri kendi klasöründe (`Button/Button.tsx`, `Button/Button.test.tsx`).
- Hook'lar `src/hooks` altında.
- Sayfalar `src/pages` altında.
- Ortak tipler `src/types` altında.
## React kuralları
- Fonksiyonel bileşen ve hook kullan.
- State yönetimi için Zustand kullan (örnek: `src/store/useUserStore.ts`).
- useEffect yalnızca dış senkronizasyon için kullan; veri çekme için React Query tercih et.
- Prop tipleri TypeScript ile ayrı arayüzde tanımla.
- Testler React Testing Library + Vitest ile yazılır; her bileşen için en az bir render testi ekle.
- Stil için CSS Modules kullan.Bu dosyayı kısa ve güncel tutun; AGENTS.md’deki her satır ajanın bağlamına girer, gereksiz bilgi karar kalitesini düşürür. Bağlamın nasıl optimize edileceği hakkında bağlam mühendisliği rehberine bakabilirsiniz. Ayrıca .gitignore, çevre değişkenleri veya özel scriptler gibi projeye özgü ayrıntıları da birkaç satırla ekleyebilirsiniz; ancak uzun açıklamalar yerine komut ve yol gösterin. Örneğin “Test ortam değişkenleri .env.test dosyasından yüklenir” gibi tek cümle yeterlidir.
Codex ile çalışma döngüsü
Codex ile güvenli bir döngü dört adımdan oluşur: plan iste, küçük adım uygulat, testleri çalıştır, diff’i incele. İlk olarak ajana yapılacak işi tek cümleyle anlatın; mümkünse hedef bileşeni veya dosyayı belirtin. Codex bir plan önersin, planı onayladıktan sonra tek seferde yalnızca bir değişiklik isteyin. Her adımdan sonra npm test -- --run ve npm run typecheck çalıştırın; başarısız olursa hatayı ajanın kendisine düzelttirin. Son olarak git diff ile değişiklikleri gözden geçirin, özellikle beklenmeyen dosya silmelerini veya import düzenlemelerini kontrol edin. İşe başlamadan önce bir git branch’i açmak ve temiz bir commit noktası oluşturmak, geri dönüşü kolaylaştırır. Ajan bir hatayı düzeltmeye çalışırken bazen kapsamı genişletebilir; bu yüzden her adımı ayrı bir değişiklik olarak tutun. Testleri çalıştırmak için ajanın kullandığı komutu doğrulayın; bazen watch modunda takılıp kalabilir. --run gibi tek seferlik çalıştıran bayraklar kullanmasını isteyin. Hata mesajlarını ajanın girdi olarak sunmak, sorunu daha hızlı çözmesini sağlar.
Sık kullanılan iyi prompt’lar:
- “Button bileşenine loading prop’u ekle; loading true iken spinner göster, metni gizle ve mevcut testini güncelle.”
- “useUsers hook’unu React Query ile yaz; hata, veri ve yüklenme durumunu döndürsün.”
- “LoginForm bileşenindeki tekrar eden input alanlarını ayrı bir FormField bileşenine taşı, prop tiplerini güncelle.”
- “Modal bileşeni için açılma ve kapanma testini Vitest ile yaz, userEvent kullan.”
- “Button bileşeninin Storybook hikayesine variant’lar için kontrol ekle ve varsayılan hikayeyi güncelle.”
Bu prompt’ların ortak noktası, kapsamın dar olması ve beklenen davranışın net biçimde ifade edilmesidir. Ajan, belirsiz isteklerde varsayımlar yapabilir; bu nedenle soruyu netleştirmeyi alışkanlık haline getirin.
Codex’in iyi yaptığı React işleri ve dikkat edilecek yerler
Codex özellikle sıfırdan bileşen oluşturma, hook çıkarma, test yazma ve küçük refactor işlerinde başarılıdır. Aşağıdaki tablo tipik görevler için etkili prompt örnekleri gösterir:
| Görev | İyi bir prompt örneği |
|---|---|
| Bileşen oluşturma | “src/components/Badge altında Badge bileşeni oluştur; variant prop’u alsın ve CSS Modules ile stillensin.” |
| Hook yazma | “useLocalStorage hook’unu yaz; değer değiştiğinde localStorage’a yazsın, başlangıç değerini param olarak alsın.” |
| Test ekleme | “Mevcut Button bileşeni için tıklama olayını test eden bir Vitest testi ekle.” |
| Refactor | “Kart bileşenindeki inline stilleri CSS Modules’a taşı, class adlarını güncelle ve mevcut testleri geçir.” |
Buna karşılık ajanın ürettiği kodu en çok şu noktalarda denetleyin: useEffect bağımlılık dizilerinde eksik değişkenler, stale closure riski, gereksiz yeniden render’a yol açan inline nesne/function tanımları, state güncellemelerinde immutability ihlali, StrictMode çift çalıştırmada yan etkiler ve liste render’da key seçimi. Ayrıca Context value’sunu memoize etmesi gerektiğini bilmeyebilir. Bu tür hatalar genellikle testlerde hemen ortaya çıkmaz; kod incelemesi sırasında yakalanmalıdır. Özellikle useMemo ve useCallback kullanımında gereksiz optimizasyonlar yapabilir; bunları ölçmeden kabul etmeyin. Portallar veya event listener’lar gibi DOM dışı yan etkilerde temizlik fonksiyonlarının doğru yazıldığından emin olun. Form bileşenlerinde kontrolsüz/ kontrollü bileşen uyumsuzluklarına dikkat edin. Ajanın ürettiği erişilebilirlik özellikleri bazen eksik kalabilir; ARIA etiketlerini ve klavye navigasyonunu manuel kontrol edin.
React testleri ve doğrulama
Codex’in yazdığı testler her zaman davranışı doğrulamaz; bazen yalnızca render edilip edilmediğini kontrol eder. Bu nedenle her değişiklikten sonra testleri çalıştırmanın yanı sıra testin gerçekçi bir kullanıcı etkileşimini kapsadığından emin olun. npm test -- --run komutu Vitest’i tek seferlik çalıştırır; ajan bunu kendi başına tetikleyebilir. Ayrıca npm run typecheck ve npm run lint komutlarını da döngüye ekleyin. Storybook kullanıyorsanız, ajanın hikayeleri güncellediğinde npm run storybook ile görsel doğrulama yapın. Testleri yazarken ajana şu soruları sorun: “Kullanıcı bu bileşenle nasıl etkileşime girer?”, “Hangi durumlar kritik?”, “Başarısızlık senaryosu ne?” Kod incelemesinde testlerin anlamlı olduğunu doğrulamak için test isimlerinin davranışı açıkladığını kontrol edin. Örneğin “renders without crashing” yerine “displays error message when API fails” gibi açıklayıcı bir isim tercih edin. Ajan, test kapsamını genişletmek istediğinde mevcut testleri kopyalayıp değiştirebilir; bu, bakımı zorlaştıran tekrarlar yaratır. Test yardımcı fonksiyonları çıkarmasını isteyin. CI’da otomatik düzeltme akışı kurmak isterseniz CI hatasını yapay zeka düzeltsin başlıklı yazı fikir verebilir.
Birden fazla ajanı AgentVera ile yönetmek
React projesinde birden fazla ajanı paralel çalıştırmak için AgentVera kullanabilirsiniz. Ajanlar kendi git worktree’lerinde çalıştığı için birinin bileşen değişikliği diğerinin test dosyasını ezmez; paralel çalışma sırasında izolasyon sağlanır. Her tur sonunda ikinci bir model kod incelemesi yapar; useEffect ve state hatalarını file:line ile gösterir, böylece React’e özgü tuzaklar erken yakalanır. Checkpoints sayesinde yanlış bir refactor’ü tek tıkla geri alabilirsiniz; uzun süren bir yeniden yazım sırasında güvenli bir geri dönüş noktası sunar. Ayrıca token bütçeleri ajan başına, tur başına ve gün başına sınır koyabilir; %80’de uyarı verir ve bütçe dolduğunda ajan durur ama konuşmayı korur. Bu, büyük bir bileşen kütüphanesi üzerinde çalışırken maliyetleri kontrol etmenize yardımcı olur. Detaylar için AgentVera nasıl kullanılır sayfasına bakın.
Özet
Codex, React projelerinde üretkenliği artırır; ancak kontrol sizde kalmalıdır. AGENTS.md ile proje kurallarını netleştirin, küçük adımlarla ilerleyin, her adımda test ve tip kontrolü yapın, diff’i inceleyin. React’e özgü tuzakları bilerek ajanın çıktısını denetleyin. Birden fazla ajan gerektiğinde AgentVera ile paralel çalışmayı güvenli hale getirin.