GitHub Copilot CLI ile Nuxt Projesinde Verimli Çalışma

GitHub Copilot CLI’ı Nuxt projesinde terminalden copilot komutuyla çalıştırdığınızda dosya tabanlı routing, server routes ve composables üzerinde doğrudan değişiklik yapabilir. Bu rehber, Nuxt bilen geliştiriciler için GitHub Copilot CLI ile çalışma döngüsünü, proje talimatlarını ve sık düşülen tuzakları somut biçimde ele alır.

Neden GitHub Copilot CLI Nuxt işleri için uygun?

Nuxt projesi büyük ölçüde klasör yapısı ve dosya adlarıyla çalışır: pages/ routing, server/ Nitro API, composables/ otomatik import. Terminalde çalışan bir ajan bu dosya ağacını doğrudan okuyup değiştirebilir ve npm run dev, npx vitest run gibi komutları kendisi çalıştırabilir. Böylece sadece kod önermekle kalmaz; bir sayfa oluşturur, server route’u yazar, testi çalıştırıp hatayı düzeltir.

Örneğin, ajan pages/blog/[slug].vue dosyasını açıp mevcut useAsyncData kalıbını takip ederek yeni bir sayfa tasarlayabilir; ardından server/api/posts.ts içindeki handler’ı güncelleyip tip uyumunu kontrol edebilir. Nuxt’un otomatik import kuralları projede zaten açık olduğu için ajan, useFetch, useAsyncData, defineEventHandler gibi API’leri doğru bağlamda kullanabilir. Ayrıca nuxt.config.ts içindeki runtimeConfig, modules ve nitro ayarlarını okuyarak mevcut yapılandırmaya saygı gösterir. Bu, ajanın bağlamı yalnızca dosya içeriğinden değil, proje genelinden almasını sağlar.

Projeyi ajan için hazırlama

GitHub Copilot CLI, proje kökündeki .github/copilot-instructions.md veya AGENTS.md dosyasını okur. Bu dosya, ajanın proje hakkında önceden bilgi sahibi olmasını sağlar; komutlar, klasör kuralları, kod stili ve Nuxt’a özgü davranışlar buraya yazılır. Nuxt projelerinde bu dosyaya yalnızca komutları değil, ajanın kaçıracağı kuralları da eklemeniz gerekir. Amaç ajanı daraltmak: nereye bakacağını, hangi komutun doğrulama anlamına geldiğini ve hangi kalıplardan kaçınacağını önceden söylemek.

Aşağıdaki örnek bir Nuxt 3 projesi için kısa ama işlevsel bir başlangıçtır:

# Nuxt proje talimatları

## Komutlar
- Kurulum: `npm ci`
- Geliştirme: `npm run dev`
- Derleme: `npm run build`
- Test: `npx vitest run`
- Lint: `npm run lint`
- Tip kontrolü: `npx nuxi typecheck`

## Klasör kuralları
- Sayfalar `pages/` altında dosya adıyla route olur; layout ve middleware için `definePageMeta` kullan.
- `composables/` içindeki dosyalar otomatik import edilir; fonksiyonlar `use` önekiyle export edilmeli.
- `server/api/` altındaki dosyalar Nitro handler'dır; `defineEventHandler` kullan ve return değerini serialize edebilir tut.
- `.nuxt` veya `node_modules` içine elle dosya yazma; tipler için `npx nuxi typecheck` çalıştır.

## Nuxt'a özel kurallar
- Ortam değişkenleri için `process.env` yerine `useRuntimeConfig()` kullan; client'ta yalnızca `public` alanına eriş.
- `useFetch` veya `useAsyncData` sonucu hata durumunda `error.value` kontrolü yap; `createError` ile fırlat.
- Değişiklik sonrası `npx vitest run` ve `npx nuxi typecheck` çalıştırmadan işi bitmiş sayma.

Bu dosyayı kısa tutun; ajan uzun talimatları göz ardı edebilir. Her madde tek bir davranışı anlatmalı ve komutlar doğrudan kopyalanabilir olmalıdır. Dosya, .github/copilot-instructions.md veya AGENTS.md olarak proje köküne konur ve GitHub Copilot CLI bunu otomatik algılar. Doğru biçim ve diğer ajan talimat dosyaları hakkında daha geniş bilgi için CLAUDE.md nasıl yazılır? AGENTS.md ve GEMINI.md rehberi yazısına bakabilirsiniz.

Çalışma döngüsü

Ajanla çalışırken kural basit: planı netleştir, küçük adım iste, test çalıştır, diff’i incele. Önce hangi dosyaların değişeceğini söyleyip onay alın; sonra tek bir sorumluluğu bitirmesini isteyin. Her adımdan sonra git diff ile değişiklikleri gözden geçirin. Nuxt’ta özellikle route kaldırma veya server/api dosya taşıma işlemlerinde beklenmedik import kırılmaları olabilir. Özellikle büyük Nuxt monorepo’larında ajanın doğru dosyaları bulması için yapay zeka ajanları için kod haritası yaklaşımını uygulayın.

Gerçek bir oturum şöyle ilerleyebilir: ajan pages/blog/index.vue oluşturur, siz git diff ile kontrol edersiniz, sonra server/api/posts.ts eklemesini istersiniz, ajan testleri çalıştırır, başarısız olan bir testi düzeltir, siz npx nuxi typecheck ile doğrularsınız. Bu döngüyü sürdürün; ajanı bir kerede çok fazla görevle boğmayın.

Örnek promptlar:

• “pages/blog/[slug].vue dosyasını oluştur. useAsyncData ile $fetch('/api/blog') üzerinden yazıyı çek, yazı bulunamazsa createError ile 404 fırlat. TypeScript hatalarını düzelt.”
• “server/api/posts.ts içinde GET handler yaz. useRuntimeConfig içindeki apiBase değerini kullan, yanıt tipini Post[] olarak tanımla ve defineEventHandler ile export et.”
• “Mevcut useAuth composable’ına logout fonksiyonu ekle. useCookie ile token’ı temizle, ardından navigateTo('/login') çağır. composables/useAuth.ts dışında dosya değiştirme.”
• “components/AppHeader.spec.ts testi başarısız. Vitest ile mount testini düzelt, @vue/test-utils kullan ve geçmesini sağla. Test sonrası npx vitest run çalıştır.”
• “layouts/default.vue içindeki nav menüsüne Blog linki ekle. Mevcut NuxtLink stillerini koru ve active class’ını uygula. Sonra npm run lint ile format kontrolü yap.”

Her prompt sonrası ajanın çalıştırdığı komutları isteyin veya kendiniz tekrarlayın. Özellikle npx nuxi typecheck ajanın gözden kaçırdığı üretilmiş tip hatalarını yakalar.

İyi gittiği işler ve dikkat edilmesi gerekenler

GitHub Copilot CLI, Nuxt projelerinde özellikle şu alanlarda hızlıdır:

• pages/ altında yeni route dosyası oluşturma ve definePageMeta ile layout/middleware bağlama.
• server/api/ altında Nitro handler taslağı yazıp useRuntimeConfig ile ortam değişkeni okuma.
• composables/ içinde otomatik import edilen use fonksiyonları üretme.
• Vitest spec dosyası yazıp mevcut bileşen testini geçirme.

Buna karşılık ajanın sıklıkla hata yaptığı Nuxt’a özgü yerler vardır:

• Otomatik import kapsamını abartıp #imports içinden elle import ekleyebilir veya ~/.nuxt içine müdahale etmeye çalışabilir.
• useFetch/useAsyncData dışında kalan client-server sınırını karıştırabilir; örneğin server-only bir modülü client tarafında kullanabilir.
• server/ route’larını taşırken eski import yollarını güncellemeyi unutabilir ve Nitro derleme hatası üretebilir.
• Test çalıştırırken Nuxt ortamını kurmadan düz vitest çağırabilir; bu da bileşen testlerinin yanlış sonuç vermesine yol açar.

Aşağıdaki tablo bu noktaları özetler:

Bu yüzden ajanın ürettiği her değişiklikte tablonun sağ sütununu göz önünde bulundurun. Ayrıca ajan, nuxt.config.ts içindeki modül değişikliklerini yaparken mevcut yapılandırmayı yanlış yorumlayabilir; modül ekleme/kaldırma işlemlerini kendiniz yapın veya ajanın çıktısını dikkatle inceleyin.

Nuxt’ta test ve doğrulama

Ajanı yalnızca kod yazmak için değil, doğrulama zincirini çalıştırmak için de kullanın. Küçük bir değişiklikten sonra şu komutları sırayla isteyin:

• npx vitest run – birim ve bileşen testlerini çalıştırır.
• npx nuxi typecheck – üretilen .nuxt tipleri üzerinden TypeScript hatalarını yakalar.
• npm run build – Nitro server ve client derlemesini birlikte doğrular.

Ajan testleri geçtikten sonra bile manuel kontrol yapın. Çünkü nuxi typecheck her zaman server/api içindeki runtime hatalarını yakalamaz; useRuntimeConfig içindeki eksik anahtar derlemede görünmeden çalışma anında patlayabilir. Testlerin gerçek bir Nuxt ortamında çalıştığından emin olmak için @nuxt/test-utils kullanılıyorsa ajanın test dosyasına gerekli ortam kurulumunu eklemesini isteyin. Ayrıca ajanın yalnızca kendi eklediği testleri çalıştırıp tüm paketi atlamasına izin vermeyin; npx vitest run komutunu her seferinde açıkça verin.

Vitest ile Nuxt bileşen testi yazarken ajanın mountSuspended veya mockNuxtImport gibi Nuxt test utility’lerini kullanmasını isteyin. Örneğin useAsyncData içeren bir bileşeni test ederken registerEndpoint ile mock’lama yapmasını söyleyin. Test çıktısını birlikte inceleyin; ajan bazen başarısız olan testi geçirmek için assertion’ı gevşetebilir, bu da gerçek hatayı gizler. Bu nedenle testlerin anlamlı olduğunu doğrulamak için git diff ile değişen test dosyalarını kontrol edin.

Birden fazla ajanı AgentVera ile yönetme

Birden fazla ajanı aynı Nuxt projesinde koşuştururken AgentVera işe yarar; her ajanı kendi gerçek terminal panelinde çalıştırır ve ayrı git worktree’ler sayesinde pages/ veya server/api/ üzerinde çakışma yaşanmaz. Bir ajanın sırası bittiğinde ikinci model kod değişikliklerini otomatik inceler; Nuxt’ta sık görülen import ve SSR hataları için bulgu file:line ile gösterilir. Yanlış bir route veya composable değişikliği checkpoint ile tek tıkla geri alınabilir. Token bütçeleri sayesinde ajan, günlük limit dolsa bile konuşmayı kaybetmeden durur.

Özet

GitHub Copilot CLI, Nuxt projesinde terminal tabanlı, kendi kendini doğrulayan bir iş ortağı olarak kullanılabilir. Anahtar, .github/copilot-instructions.md ile Nuxt kurallarını netleştirmek, değişiklikleri küçük tutmak ve her adımda vitest ile nuxi typecheck çalıştırmaktır. Ajanın güçlü yanları dosya tabanlı routing ve server route üretimi; riskli yanları ise client-server sınırı ve otomatik import varsayımlarıdır. Aynı projede çok sayıda ajan kullanacaksanız AgentVera’nın worktree, otomatik review ve checkpoint özellikleri işinizi sağlama alır.