opencode, proje klasöründe opencode komutuyla başlattığınız terminal tabanlı bir kodlama ajanıdır. Genel kurulum bilgisi için opencode sayfasına göz atın. Next.js projelerinde App Router, Pages Router, sunucu/istemci bileşenleri, route handler’lar ve build süreçleriyle çalışırken AGENTS.md dosyasındaki talimatları izler; komutları çalıştırır, kod yazar ve test eder. Bu rehberde opencode’u Next.js ile güvenli ve verimli kullanmanın pratik yollarını anlatıyorum.
Neden opencode Next.js projelerinde iyi çalışır
Next.js, dosya tabanlı routing, React Server Components (RSC), route handler’lar, middleware ve cache katmanı gibi birçok kuralı aynı anda yönetmeyi gerektirir. opencode, proje dosyalarını okuyup AGENTS.md talimatlarını izleyerek pnpm lint, pnpm test, pnpm build gibi komutları doğrudan çalıştırabilir. Bu sayede yalnızca kod önermekle kalmaz; değişikliğin tip hatalarını, lint sorunlarını ve test başarısızlıklarını anında görür. Örneğin App Router’a geçişte getServerSideProps yerine async sunucu bileşeni kullanımı, use client sınırının yeniden çizilmesi veya generateStaticParams eklenmesi gibi çok adımlı refactor’ları küçük parçalar halinde uygulayabilir. Pages Router ve App Router karışık projelerde hangi klasörün hangi yapıya ait olduğunu AGENTS.md’den öğrenerek yanlış dosyaya müdahale etme riskini azaltır.
Projeyi ajana hazırlama ve AGENTS.md
opencode, proje kökündeki AGENTS.md dosyasını talimat kaynağı olarak kullanır. Next.js projesinde bu dosya; kurulum, geliştirme, build, lint, tip kontrolü ve test komutlarını açıkça yazmalıdır. Ayrıca App Router ile Pages Router ayrımı, server/client sınırı, route handler ve server action kuralları gibi projeye özgü kararları içermelidir. Aşağıdaki örnek, pnpm kullanan bir Next.js 15 App Router projesi için kısa bir başlangıç şablonudur; kendi monorepo veya farklı test runner kurulumunuza göre uyarlayabilirsiniz.
## Komutlar
- Kurulum: pnpm install
- Geliştirme: pnpm dev
- Build: pnpm build
- Lint: pnpm lint
- Tip kontrolü: pnpm typecheck
- Test: pnpm test (Vitest)
- E2E: pnpm test:e2e (Playwright)
## Klasör kuralları
- App Router: app/ altında page.tsx, layout.tsx, route.ts kullanın.
- Client component'ler "use client" ile başlar; sunucu bileşenlerinde asla tarayıcı API'si kullanmayın.
- Server actions dosyalarını "use server" ile işaretleyin.
- API route handler'ları app/api/.../route.ts altında tutun.
- Ortak tipler src/types altında, utility'ler src/lib altında.
## Next.js özel kuralları
- RSC ve client sınırını koruyun; client component'ler yalnızca yaprak düzeyde olmalı.
- fetch çağrılarında Next.js cache yönergelerini (`cache: 'no-store'` vs) bilinçli kullanın.
- `next lint` yerine ESLint'i doğrudan çalıştırın; ESLint yapılandırması next/core-web-vitals içermelidir.
- Değişikliklerden sonra `pnpm lint && pnpm typecheck && pnpm test` komutlarını çalıştırın.Bu dosya haricinde opencode, package.json scriptlerini ve tsconfig.json’u da okur; ancak açık talimatlar belirsizliği azaltır. Kullanım ipuçları için opencode nasıl kullanılır? rehberine göz atabilirsiniz.
Çalışma döngüsü ve örnek promptlar
opencode ile etkili çalışma döngüsü şöyledir: önce görevi küçük parçalara bölün, ajana net bir hedef verin; ardından ajanın ürettiği değişiklikleri inceleyin (git diff ile), ilgili test ve lint komutlarını çalıştırın, hataları geri bildirin ve onaylayın. Büyük bir özelliği tek seferde istemek yerine, her adımda doğrulanabilir küçük işler verin. Aşağıda Next.js projeleri için örnek promptlar bulunmaktadır:
- “app/(dashboard)/layout.tsx dosyasına bir üst bilgi ekle; sadece sunucu bileşeni olarak ve mevcut yapıyı bozma.”
- “src/lib/api.ts içindeki fetch çağrısını Next.js 15’in cache kurallarına göre yeniden düzenle, hata yönetimini ekle ve ilgili testi güncelle.”
- “app/api/users/route.ts için yeni bir POST endpoint’i yaz; request şemasını zod ile doğrula, hata durumlarını döndür, ESLint geçsin.”
- “Pages Router’dan App Router’a taşınan /blog sayfasını generateStaticParams ile statik hale getir; build sırasında veri getirilmesini sağla.”
- “Client component’e dönüştürülmesi gereken bir bileşeni tespit et, ‘use client’ ekle ve gereksiz yere client olan diğer bileşenleri sunucuya taşı.”
Bu promptlar, ajanın plan yapmasına, dosyaları düzenlemesine ve komutları çalıştırmasına olanak tanır. Yanıtlarında önerdiği adımları okumayı ihmal etmeyin.
opencode’un iyi yaptığı Next.js görevleri ve dikkat edilmesi gerekenler
opencode, dosya sistemini ve proje yapısını anladığı için özellikle refactor, route handler yazımı, server action ekleme, TypeScript geçişi ve test oluşturma gibi görevlerde iyi sonuç verir. Ancak Next.js’in incelikli cache davranışı, RSC sınırları ve build optimizasyonları konusunda gözünüz üzerinde olmalı. Aşağıdaki tablo, sık karşılaşılan görevler için iyi bir prompt ve dikkat edilecek noktaları özetler:
| Görev | İyi prompt | Dikkat edilecek nokta |
|---|---|---|
| Server action ekleme | app/actions.ts içine yeni bir server action ekle; zod ile doğrula, use server direktifini kullan. | Sunucu eyleminin istemci bileşeninden çağrıldığından emin ol; hata yönetimi ve revalidatePath kullan. |
| Route handler yazma | app/api/orders/route.ts için GET yaz; query parametrelerini doğrula, JSON döndür, cache yönergesini belirt. | Route handler’lar varsayılan olarak statik render edilmez; cache ayarını bilinçli yap. |
| RSC/client sınırını düzeltme | Bu bileşeni sunucuda tut; tarayıcı API’si kullanan kısmı ayrı client component’e taşı. | Gereksiz yere client yapmak performansı düşürür; sınırı yaprak düzeyde tut. |
| Veri getirme optimizasyonu | Sunucu bileşenindeki fetch’i Next.js cache kurallarına göre düzenle; revalidate süresini ayarla. | fetch caching ve full route cache arasındaki farkı bilmek kritik. |
| Test yazma | Vitest ile bu utility fonksiyonu için birim testi ekle; ESLint kurallarına uygun olsun. | Ajan bazen test kapsamını abartabilir; mevcut test desenlerine uymasını iste. |
Ajanın ürettiklerini incelemek, özellikle cache ve RSC hatalarını yakalamanın en garantili yoludur.
Next.js’te test ve doğrulama
opencode, terminal komutlarını çalıştırabildiği için test sürecini otomatikleştirebilir. AGENTS.md dosyanıza eklediğiniz doğrulama komutlarını ajan görev sonunda kendisi çalıştırır; yine de siz de tetikleyebilirsiniz. Next.js projesinde doğrulama zinciri şu olmalıdır: pnpm lint (veya next lint), pnpm typecheck (tsc —noEmit) ve pnpm test (Vitest/Jest). E2E testler için pnpm test:e2e (Playwright) kullanılır. Ajan, App Router sayfalarında route handler ve server action hatalarını genellikle test çalıştırarak fark eder; ancak sunucu bileşeni hataları sadece build sırasında ortaya çıkabilir. Bu yüzden her PR’dan önce pnpm build komutunu çalıştırmasını isteyin. Playwright ile kritik user flow’ları test ediyorsanız, ajanın testleri güncellemesini ve çalıştırmasını isteyin; böylece yanlışlıkla bozulan route’lar erken yakalanır.
AgentVera ile birden fazla ajanı aynı Next.js projesinde çalıştırma
Next.js projesi; UI bileşenleri, API route handler’ları ve yapılandırma gibi birbirinden bağımsız işler içerir. AgentVera, aynı projede birden fazla opencode ajanını paralel çalıştırmanıza olanak tanır; her ajan kendi git worktree’sinde çalıştığı için dosya çakışmaları olmaz. Böylece biri client bileşenleri düzenlerken diğeri API endpoint’lerini yazabilir. Ajanın işi bittiğinde ikinci bir model otomatik kod incelemesi yapar ve RSC sınırı, cache yanlışı gibi Next.js hatalarını file:line ile raporlar. Ayrıca checkpoint özelliği sayesinde riskli bir değişikliği tek tıkla geri alabilir veya oturumu adım adım tekrar oynatabilirsiniz. Bu, büyük Next.js refactor’larını güvenle yönetmenizi sağlar. Daha fazlası için paralel kodlama ajanları rehberine bakabilirsiniz.
Sonuç
opencode, Next.js projelerinde disiplinli bir AGENTS.md ile güvenilir bir yardımcıdır. Küçük adımlarla ilerleyip her değişiklikte lint, tip kontrolü ve testleri çalıştırdığınızda, ajanın üretkenliği hata riskini aşar. Next.js’e özgü cache ve RSC sınırlarını yakından takip edin; ajanın önerilerini daima inceleyin. Projede birden fazla görev paralel yürüyecekse AgentVera gibi araçlarla worktree ve otomatik inceleme katmanı ekleyin. opencode ile Next.js geliştirmenin anahtarı, net talimatlar ve sıkı doğrulamadır.