GitHub Copilot CLI ile Next.js projelerinde verimli çalışma

Next.js projesinde terminalde copilot komutuyla başlayan GitHub Copilot CLI, planlama, dosya düzenleme, test ve lint çalıştırma adımlarını tek oturumda yürütür. Next.js’in server/client sınırları, route handler’ları ve cache davranışları düşünüldüğünde, ajanı yalnızca kod üretmek için değil, proje kurallarını izleyen bir pair programmer gibi kullanmak gerekir. Bu rehber App Router, Pages Router, route handler’lar, Vitest/Jest ve Playwright bağlamında pratik bir kurulum ve çalışma döngüsü sunar.

Neden GitHub Copilot CLI Next.js işlerine uygun?

Next.js projesinin çok katmanlı yapısı, tek dosyalık düzeltmelerden daha fazlasını gerektirir. GitHub Copilot CLI, depoyu okuyup package.json scriptlerini çalıştırabildiği için next build, eslint veya test çıktılarındaki hataları kendi düzeltme döngüsüne katabilir. App Router’da dosya tabanlı yönlendirme ve server/client bileşen ayrımı net klasör kurallarıyla anlatıldığında, ajan yeni sayfa, layout veya route handler eklerken tutarlı davranır. Ayrıca değişiklikleri küçük adımlara bölüp her adımda diff göstermesi, Next.js’te sık yaşanan “bir import yüzünden tüm route’un client’a dönmesi” gibi hataları erken yakalamayı sağlar.

Ajanın Next.js’e özgü katkıları şunlardır:

• Dosya sisteminden route’ları çıkarıp yeni sayfa/layout eklerken Next.js konvansiyonlarına uyar.
• Server component’lerde async veri çekme ve client component’lerde hook sınırlarını ayırır.
• Route handler’larda Request/Response tiplerini ve zod doğrulamasını önerir.
• next build çıktısında “use client” uyarılarını veya cache hatalarını yorumlayıp düzeltme önerir.
• Playwright veya Vitest testlerini çalıştırıp kırılan senaryoları raporlar.

Böylece ajan, yalnızca snippet üretmek yerine Next.js projesinin derleme ve test geri bildirim döngüsünün bir parçası haline gelir.

Projeyi ajan için hazırlamak

Ajanın en büyük gücü proje talimatlarını okumasıdır. .github/copilot-instructions.md veya AGENTS.md dosyasına Next.js’e özel komutlar ve kurallar koymak, her oturumda aynı kararları vermesini sağlar. Bu dosyanın genel yazımı için CLAUDE.md nasıl yazılır? sayfasındaki rehber de işe yarar. Talimat dosyası ne kadar net olursa, ajan o kadar az bağlam düzeltmesi ister; özellikle App Router ve Pages Router’ın bir arada bulunduğu projelerde bu fark hayati olabilir.

Aşağıdaki örnek, App Router ve Pages Router’ın birlikte bulunduğu bir repo için kısa ama etkili bir başlangıçtır:

# Proje talimatları

## Komutlar
- `pnpm install`
- `pnpm dev`
- `pnpm build`
- `pnpm lint`
- `pnpm test` (Vitest)
- `pnpm test:e2e` (Playwright)

## Klasör kuralları
- App Router: `src/app/**`; Pages Router: `src/pages/**`
- Server component varsayılan olsun; `"use client"` yalnızca state, event handler veya browser API gerektiğinde ekle.
- Route handler'ları `src/app/api/**/route.ts` altında tut; doğrulama için `zod` kullan.
- Testler `src/**/*.test.ts(x)` veya `tests/**` altında olsun.

## Next.js'e özgü kurallar
- Server component'ten client component'e event handler veya state geçirme; sınırı dar tut.
- Fetch çağrılarında cache davranışı gerekiyorsa `cache: "no-store"` veya `next: { revalidate }` yorumunu ekle.
- `next/link`, `next/image`, `next/font` kullan.
- Route handler'larda `export const runtime` değerini değiştirme.
- ESLint ve TypeScript hatalarını düzeltmeden görevi tamamlama.

Bu dosyayı ekledikten sonra terminalde copilot komutunu çalıştırıp görevi doğal dille anlatmak yeterli. Ajan, talimatları her oturumun başında okur; değişiklik yaptıktan sonra dosyayı güncellemeyi unutmayın.

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

Next.js’te güvenli bir döngü şöyledir: önce ajanın plan çıkarmasını isteyin, sonra değişiklikleri küçük parçalara bölmesini söyleyin, her adımda test ve lint çalıştırın, en sonda diff’i inceleyip next build ile doğrulayın. Bu döngüyü uygulamanın pratik yolları şunlardır:

1. Plan isteyin: “Önce mevcut yapıyı incele ve App Router sayfası için bir dosya planı çıkar; hangi dosyaların server, hangilerinin client olacağını belirt.”
2. Küçük adımlara bölün: “Değişikliği üç commit’e böl: önce route handler’ı, sonra data fetching’i, en son UI bileşenini ekle.”
3. Her adımda doğrulama komutu çalıştırın: “Bu adımı bitirdikten sonra pnpm lint ve pnpm test çalıştır, hataları düzelt.”
4. Diff’i inceleyin: “Şimdi yaptığın değişikliklerin diff’ini göster ve sadece server/client sınırıyla ilgili olanları açıkla.”
5. Son doğrulama: “En son pnpm build çalıştır; eğer build başarılıysa özet çıkar, değilse hataları düzelt ve tekrar dene.”

Bu döngüyü kullanarak ajanı serbest bırakmak yerine kontrollü ilerlersiniz. Aşağıdaki örnek promptlar tipik Next.js görevleri için başlangıç noktası olabilir:

• “src/app/(dashboard)/layout.tsx içindeki nav bileşenini server component olarak bırak; kullanıcı menüsünü ayrı bir user-menu.tsx client component’ine taşı ve gerekli sınırı koru.”
• “/api/products route handler’ında GET isteğine searchParams.q filtresini ekle; zod ile doğrula, geçersiz değerde 400 döndür.”
• “Ürün listesi sayfasında fetch çağrısını cache: 'no-store' olacak şekilde güncelle ve aynı rotaya loading.tsx ekle.”
• “Bu form bileşenini useActionState ile yeniden yaz; Vitest testini güncelle ve pnpm test çalıştır.”
• “Playwright ile giriş sayfası için bir smoke testi ekle; pnpm test:e2e ile doğrula.”

Her prompt sonrası ajanın ürettiği diff’i gözden geçirin; özellikle "use client" direktiflerinin yalnızca gerekli dosyalara eklendiğinden emin olun.

İyi gittiği işler ve dikkat edilecek tuzaklar

GitHub Copilot CLI; Pages Router’dan App Router’a geçiş, route handler ekleme, veri çekme katmanını düzenleme ve ESLint/TypeScript hatalarını çözme gibi işlerde iyi sonuç verir. Ancak Next.js’in örtük davranışları yüzünden diff’i dikkatle incelemek gerekir. Ajanın hızlı çözüm üretme eğilimi bazen gereksiz client bileşenlerine veya cache’in kaldırılmasına yol açabilir; bu nedenle aşağıdaki tabloyu akılda tutmak faydalıdır.

Ayrıca, ajanın Next.js sürüm farklarını karıştırabileceğini unutmayın; örneğin App Router’a özgü params tipi veya cookies() kullanımı Pages Router ile uyumsuz olabilir. Büyük refactor’ları küçük adımlara bölerek bu riski azaltırsınız.

Test ve doğrulama

Next.js projesinde ajanın işini yalnızca “kod yazıldı” diye bitirmesine izin vermeyin. Talimat dosyasındaki komutlarla pnpm test, pnpm lint ve pnpm build çalıştırmasını isteyin. Vitest veya Jest ile birim testler server/client ayrımını doğrulamaz; bu yüzden next build şarttır. TypeScript kontrolü için npx tsc --noEmit de ajanın hata düzeltme döngüsüne dahil edilebilir. Tarayıcı testleri için Playwright kullanıyorsanız, ajanın Yapay zekâ ajanıyla tarayıcı testi sayfasındaki Playwright MCP kurulumuna uygun hareket etmesi faydalıdır. Ajan her hata sonrası düzeltme önerse de, route handler’ların gerçek HTTP davranışını görmek için e2e testleri ayrıca çalıştırın.

Doğrulama adımlarını ajanla şu şekilde yürütebilirsiniz:

• Birim test: Değişiklik yapılan dosyaya en yakın Vitest/Jest testini çalıştırın; ajan hata verirse düzeltmesini isteyin.
• Lint: next lint veya ESLint scriptini çalıştırın; "use client" veya import hatalarını yakalayın.
• Build: next build her zaman son adım olsun; server/client sınırı ve route handler tip hataları yalnızca build’de ortaya çıkar.
• E2E: Kritik akışlar için Playwright testlerini ajanın başlatmasını sağlayın; gerçek tarayıcıda smoke test geçmeden görevi kapatmayın.

Bu adımlar, ajanın ürettiği kodu Next.js üretim ortamına yakın bir senaryoda doğrular.

Birden fazla ajanı AgentVera ile paralel çalıştırma

Next.js projelerinde birden fazla ajan çalıştırmak işleri hızlandırır, ancak dosya çakışmaları risklidir. AgentVera masaüstü uygulaması, GitHub Copilot CLI dahil ajanları kendi gerçek terminal panellerinde yan yana çalıştırır. Next.js için en değerli özellikler şunlardır: her ajan ayrı git worktree’de çalışarak dosyaları ezmez; ikinci model otomatik kod incelemesi yaparak server/client sınırı ihlallerini file:line ile işaretler; checkpoints sayesinde cache değişikliği sonrası bozulan bir build tek tıkla geri alınabilir. Token bütçeleri ise ajanların günlük kullanımı kontrolden çıkarmadan durmasını sağlar. Böylece App Router geçişi, test ekleme ve e2e doğrulama paralel ilerler.

Sonuç

GitHub Copilot CLI, Next.js projelerinde yalnızca kod üretmekle kalmaz; proje kurallarınızla birlikte next build, lint ve test döngüsünü yönetebilir. Önemli olan server/client sınırlarını, cache davranışlarını ve route handler kurallarını talimat dosyasına net biçimde yazmak ve her oturumu diff + build ile kapatmaktır. Bu disiplinle ajan, Next.js’in karmaşık taraflarında güvenilir bir yardımcı haline gelir.