opencode ve React: Kodlama Ajanıyla Verimli Çalışma Rehberi

opencode’u bir React projesinin kök klasöründe opencode komutuyla başlattığınızda, proje bağlamını okur ve terminal üzerinden kod üretir, değişiklik yapar, test çalıştırır. Bu rehber, React bileşenleri, hook’lar, testler ve state yönetimi için opencode’dan en iyi şekilde yararlanmanızı sağlayacak pratik adımları içerir. Aşağıdaki bölümlerde kurulum, çalışma döngüsü, tipik görevler ve sık karşılaşılan tuzaklar ele alınıyor.

opencode neden React projelerine uygun?

opencode, proje dosyalarını ve AGENTS.md talimatlarını okuyarak çalışır; bu sayede bileşen ağacını, hook kurallarını ve state yönetimini anlar. JSX, TypeScript, Vite, Vitest gibi araçlarla uyumlu komutlar çalıştırabilir. Tekrarlayan işleri hızlandırır: yeni bir bileşen oluşturmak, mevcut bileşene prop eklemek, class component’i hook’a çevirmek, test yazmak. Ayrıca her değişiklikten sonra test ve lint çalıştırarak geri bildirim döngüsünü kısaltır. Bu, React’in hızlı iterasyon modeline uygundur.

React projelerinde opencode’un en büyük avantajı, dosya tabanlı yapıyı ve bileşen bağımlılıklarını anlayabilmesidir. Örneğin, bir bileşenin prop’larını değiştirdiğinizde, o bileşeni kullanan diğer dosyaları da güncellemesini isteyebilirsiniz. Vite tabanlı bir kurulumda, hot module replacement sayesinde değişiklikleri hızla görebilirsiniz. Ancak ajanın yaptığı değişiklikler tarayıcıda otomatik olarak görünmez; dev sunucusu zaten çalışıyorsa, kaydedilen dosyalar HMR ile güncellenir. Bu da gerçek zamanlı doğrulamayı kolaylaştırır.

Projeyi ajan için hazırlama: AGENTS.md

opencode, proje kökündeki AGENTS.md dosyasını okur. Bu dosyaya komutlar, klasör yapısı ve React’e özgü kurallar yazmak ajanın doğru kararlar vermesini sağlar. opencode sayfasında opencode’un genel çalışma prensipleri özetlenmiştir. Aşağıda bir React projesi için gerçekçi bir örnek verilmiştir:

# AGENTS.md

## Komutlar
- `npm run dev` - Vite geliştirme sunucusu
- `npm run build` - Üretim derlemesi
- `npm test` - Vitest ile test çalıştır
- `npm run lint` - ESLint kontrolü

## Klasör yapısı
- `src/components/` - Yeniden kullanılabilir bileşenler
- `src/hooks/` - Özel hook'lar
- `src/pages/` - Sayfa bileşenleri
- `src/store/` - Zustand store'ları

## React kuralları
- Bileşen dosyaları PascalCase, örn. `Button.tsx`.
- Hook'lar `use` ile başlar ve yalnızca bileşen veya başka hook içinden çağrılır.
- State yönetimi için Zustand kullanılır; prop drilling'den kaçınılır.
- Her bileşen için aynı klasörde `ComponentName.test.tsx` dosyası bulunmalıdır.
- useEffect içinde async fonksiyon doğrudan çağrılmaz; ayrı fonksiyon tanımlanır.
- Gereksiz useMemo/useCallback kullanılmaz; yalnızca performans sorunu ölçüldüğünde eklenir.

Bu dosya, ajanın projeye özgü kuralları göz ardı etmemesini sağlar. opencode komutuyla başlatıldığında bu talimatlar her görevde kullanılır.

AGENTS.md içine ekleyebileceğiniz diğer önemli noktalar şunlardır: stil yöntemi (CSS Modules, Tailwind, styled-components), state kütüphanesi (Redux, Zustand, Jotai), test kütüphanesi (React Testing Library, Vitest), ve dosya adlandırma düzeni. Ayrıca, bileşenlerin yalın tutulması, sunum ve kap (container) ayrımının hangi durumlarda yapılacağı gibi mimari tercihleri de belirtebilirsiniz. Örneğin, büyük projelerde “her sayfa için bir klasör, içinde index.tsx, types.ts, styles.ts gibi dosyalar” kuralı ajanın tutarlı olmasını sağlar. Eğer Storybook kullanıyorsanız, story dosyalarının *.stories.tsx olarak aynı klasörde bulunmasını şart koşun. Bu sayede ajan, yeni bileşen oluştururken story’yi de beraberinde üretir.

Çalışma döngüsü: planla, küçük adımlar at, test et, diff’i incele

opencode ile verimli çalışmanın anahtarı, her isteği küçük ve test edilebilir parçalara bölmektir. opencode nasıl kullanılır? Adım adım rehber adresindeki adım adım rehber bu yaklaşımı detaylandırır. Tipik döngü:

1. Plan: Ajan’dan önce mevcut kodu analiz etmesini ve önerilen değişiklikleri özetlemesini isteyin. Örneğin: “UserProfile bileşenini incele, mevcut state yönetimini ve prop akışını özetle, hangi hook’ların gereksiz olduğunu belirt.”
2. Küçük adım: Tek bir bileşen veya hook üzerinde çalışın, tüm uygulamayı değiştirmeyin. Örneğin: “Button bileşenine yalnızca loading prop’u ekle, loading durumunda spinner göster, ikon pozisyonunu ayarla.”
3. Test çalıştır: Her değişiklikten sonra npm test çalıştırın veya çalıştırmasını isteyin. Ajan’a test sonuçlarını analiz ettirip hataları düzeltmesini söyleyin, ancak çıktıyı kendiniz de kontrol edin.
4. Diff incele: git diff ile yapılan değişiklikleri kontrol edin, gereksiz kısımları reddedin. Özellikle ajanın eklediği gereksiz import’lar, stil değişiklikleri veya kapsam dışı iyileştirmelere dikkat edin.

React projeleri için örnek prompt’lar:

• “Button bileşenini incele; variant ve size prop’ları ekle, varsayılan değerleri belirle, Storybook story’lerini güncelle.”
• “useFetch hook’unu yaz: hata ve yükleme durumlarını yönet, istek iptali için AbortController kullan.”
• “ProductList sayfasında ürünleri API’den çek, Zustand store’a kaydet, yükleme sırasında skeleton göster.”
• “Mevcut testleri çalıştır, kırılanları düzelt, useCart hook’u için yeni testler ekle.”
• “Form bileşenini react-hook-form ve zod’a geçir; doğrulama şemasını ayrı dosyada tanımla.”

Her prompt’tan sonra test ve lint çalıştırmak, hataları erken yakalamayı sağlar. Ayrıca ajanın önerdiği değişiklikleri commit’lemeden önce git diff --stat ile dosya sayısını kontrol edin; beklenmedik dosyalar değiştiyse geri alın. Büyük refactor’larda ajanı adım adım yönlendirin: önce fonksiyonu çıkar, sonra bileşeni güncelle, sonra testleri düzelt gibi. Bu şekilde hata ayıklama kolaylaşır.

React’te iyi giden görevler ve dikkat edilecek tuzaklar

opencode, aşağıdaki gibi tekrarlayan ve kural tabanlı işlerde oldukça başarılıdır. Aşağıdaki tabloda görevler ve örnek prompt’lar eşleştirilmiştir:

Ayrıca, opencode’un yardımcı olduğu diğer alanlar şunlardır: prop-type veya TypeScript tanımları oluşturma, bileşenleri memoize etme (gerektiğinde), aksesuar bileşenleri yazma, form doğrulama mantığını soyutlama, ve API katmanı işlevlerini mock’lama. Storybook kullanıyorsanız, yeni bir bileşen için otomatik story oluşturması ve argTypes tanımlaması da yapabilirsiniz.

Ancak opencode’un React’e özgü bazı konularda dikkatli izlenmesi gerekir:

• Gereksiz optimizasyon: Ajan, ölçüm yapmadan useMemo ve useCallback ekleyebilir; bu da kod karmaşıklığını artırır ve aslında performansı düşürebilir. Yalnızca gerçekten pahalı hesaplamalar için kullanılmasını isteyin.
• Hook kuralları ihlali: Koşullu olarak hook çağırmak gibi hatalar yapabilir; özellikle refactor sırasında kontrol edin. Ajan bazen if içinde useState çağırabilir; bu derleme hatası verir.
• Aşırı state: Bileşen içinde gereğinden fazla useState kullanabilir; türetilmiş state yerine doğrudan hesaplama daha iyi olabilir. Örneğin, fullName için ayrı state tutmak yerine firstName + lastName kullanmak yeterlidir.
• Testlerin anlamsız olması: Yalnızca snapshot alan testler yazabilir; davranışı test eden RTL sorguları isteyin. Ayrıca, ajan testleri geçmek için testi zayıflatabilir; bunu gözden geçirin.
• Yan etkiler: useEffect’i yanlış bağımlılıklarla kullanabilir; her değişiklikte diff’i inceleyin. Özellikle useEffect içinde fetch yaparken cleanup fonksiyonu eksik olabilir.
• Stil tutarsızlığı: Tailwind ve CSS Modules karışımı gibi tutarsız stil yaklaşımları üretebilir; AGENTS.md’de kural belirleyin.

Bu noktalara dikkat ederek ajanın çıktısını insan gözüyle doğrulamak gerekir.

React’te test ve doğrulama

opencode ile test yazarken ve çalıştırırken şu adımları izleyin:

• Her değişiklikten sonra npm test -- --run (Vitest) çalıştırarak yalnızca değişen dosyaların testlerini çalıştırın. Vitest, dosya izleme modunda hızlıdır, ancak ajan araçları genellikle tek seferlik çalıştırma ister; bu yüzden --run bayrağı kullanışlıdır.
• Test kapsamını kontrol etmek için npm test -- --coverage kullanın; kritik bileşenler için %80 üzeri hedefleyin. Coverage raporundaki düşük satırları ajan’a gösterip eksik testleri yazmasını isteyebilirsiniz.
• Storybook görsel doğrulaması için npm run storybook ile bileşenleri gözden geçirin. Ajan, story dosyalarını güncelledikten sonra Storybook’u başlatarak görsel regresyonu kontrol etmez; bu sizin sorumluluğunuzdadır.
• ESLint hatalarını npm run lint ile kontrol edin; özellikle react-hooks kurallarını ihlal eden durumları düzeltin. Ajan, lint hatalarını düzeltmesi istendiğinde bazen kuralı devre dışı bırakabilir; bunu kabul etmeyin.
• Ajan’a “testleri çalıştır ve hataları düzelt” demek yerine spesifik test senaryoları verin; aksi halde yüzeysel düzeltmeler yapabilir. Örneğin: “LoginForm testinde, geçersiz e-posta girildiğinde hata mesajının göründüğünü doğrula.”

React Testing Library kullanırken, kullanıcı etkileşimlerini simüle eden testler yazmasını isteyin; DOM sorgularını getByRole, getByLabelText gibi erişilebilirlik odaklı seçeneklerle yapmasını belirtin. Bu, testlerin gerçek kullanıcı davranışını yansıtmasını sağlar. Ayrıca, fireEvent yerine userEvent kullanmasını söyleyin çünkü userEvent daha gerçekçi olaylar tetikler.

Ajanın ürettiği testlerde genellikle eksik kalan noktalar: async işlemlerde waitFor kullanımı, mock fonksiyonlarının temizlenmesi, ve beforeEach/afterEach içinde state sıfırlama. Bu eksiklikleri fark ettiğinizde ajan’a “testler arasında state sızıntısı olmaması için afterEach ekle” gibi talimatlar verin. Ayrıca, testlerin deterministik olması için zamanlayıcıları vi.useFakeTimers() ile kontrol etmesini önerin.

Bir React projesinde birden fazla ajanı AgentVera ile çalıştırma

AgentVera, opencode dahil birçok CLI ajanını tek pencerede, her biri kendi gerçek terminal panelinde çalıştırır. React projelerinde özellikle üç özellik öne çıkar: her ajanın kendi git worktree’sinde çalışabilmesi sayesinde bileşen veya hook geliştirmeleri paralel yapılır ve dosya çakışmaları önlenir. Otomatik kod incelemesi, bir ajanın ürettiği kodu ikinci bir modelin denetlemesini sağlar; böylece hook kuralları veya state yönetimi hataları erken yakalanır. Checkpoint’ler, her turun anlık görüntüsünü tutar; başarısız bir refactor’ı tek tıkla geri alabilirsiniz. Token bütçeleri, ajan başına günlük maliyeti sınırlandırır ve %80’de uyarı verir. Paralel kodlama ajanları için en iyi araçlar (2026) sayfasında paralel ajan kullanımına dair daha fazla bilgi bulunur. Bu özellikler, büyük React uygulamalarında iş bölümü ve kalite kontrolü için pratiktir.

Sonuç

opencode, React projelerinde doğru talimatlar ve küçük adımlarla kullanıldığında bileşen geliştirme, hook yazma, test ekleme ve refactor işlerini belirgin şekilde hızlandırır. AGENTS.md dosyasına proje kurallarını koymak, testleri sık çalıştırmak ve diff’leri incelemek, ajanın üretkenliğini artırırken riskini azaltır. Daha karmaşık senaryolarda AgentVera gibi araçlarla paralel ajan kullanımı, React uygulamasının farklı bölümlerinde eşzamanlı ilerleme sağlar. Sonuç olarak, opencode React geliştirme sürecine entegre edilebilecek güçlü bir yardımcıdır.