Gemini CLI ile Astro projesi geliştirme rehberi

Gemini CLI, Astro projelerinde terminalden gemini komutuyla başlar; proje kökündeki GEMINI.md dosyasını okuyarak .astro bileşenlerini, içerik koleksiyonlarını ve statik build süreçlerini değiştirir. En pratik kullanım, Astro’ya özel komutları ve klasör kurallarını GEMINI.md içinde tanımlayıp ajanı küçük, doğrulanabilir görevlerle yönlendirmektir. Gemini CLI hakkında temel bilgi için ilgili sayfaya bakılabilir.

Gemini CLI Astro işleri için neden uygun

Gemini CLI, proje kökündeki GEMINI.md dosyasını her görevde bağlam olarak okur. Bu, ajanın Astro’nun kendine özgü kurallarını bilmesini sağlar: .astro dosya yapısı, frontmatter, içerik koleksiyonları ve statik üretim. Örneğin src/content.config.ts içindeki Zod şemalarını okuyup yeni bir alan ekleyebilir, ardından getCollection çağrılarını güncelleyebilir. .astro şablonlarında sunucu tarafı ile istemci tarafı ayrımını koruyarak bileşenler üzerinde değişiklik yapabilir. Statik build’de ise astro build çıktısını yorumlayıp hataları düzeltebilir; bu, elle hata ayıklamaya göre çok daha hızlıdır. Ayrıca entegrasyon eklerken astro.config.mjs dosyasını düzenleyebilir ve bağımlılıkları kurmak için paket yöneticisi komutlarını kullanabilir. Kısacası, Astro’nun dosya odaklı yapısı Gemini CLI’ın planlama ve düzenleme döngüsüne iyi uyum sağlar.

GEMINI.md ile Astro projesini ajan için hazırlama

Projedeki GEMINI.md dosyası, ajanın her görevi nasıl ele alacağını belirler. Astro için kısa ve kesin talimatlar içermeli; gereksiz genel açıklamalardan kaçınmalıdır. Özellikle komutlar, klasör sözleşmeleri ve Astro’ya özgü kurallar net olmalı. Gerçekçi bir örnek aşağıdaki gibidir:

# GEMINI.md

## Komutlar
- Kurulum: `npm install`
- Geliştirme: `npm run dev`
- Tip kontrolü: `npx astro check`
- Lint: `npm run lint`
- Test: `npm run test`
- Build: `npm run build`
- Önizleme: `npm run preview`

## Klasör sözleşmeleri
- `src/pages/` altındaki her .astro dosyası bir route'tur.
- Yeniden kullanılabilir bileşenleri `src/components/` altında tut.
- İçerik koleksiyonları `src/content/` altında; şema tek kaynak olarak `src/content.config.ts` içinde tanımlıdır.
- Layout'ları `src/layouts/` altında topla.

## Astro'ya özel kurallar
- .astro dosyalarında frontmatter dışında JavaScript çalıştırma; istemci script'leri yalnızca `<script>` etiketinde veya `client:*` direktifiyle kullan.
- İçerik koleksiyonlarına erişim için `getCollection` veya `getEntry` kullan; `import.meta.glob` yalnızca koleksiyon dışı dosyalar için.
- Statik build'de `Astro.url` yerine `Astro.site` veya `new URL(Astro.site)` kullan; SSR gerektiren özellik ekleme.
- Bir bileşene `client:load`, `client:visible` gibi direktif eklerken yalnızca gerekli adacığı hydrate et; gereksiz istemci kodu ekleme.
- Değişiklikten sonra `npx astro check` çalıştır; hata varsa düzeltmeden işi bitirme.

Dosya çok uzun olmamalı; yukarıdaki gibi 20-30 satır yeterli. Test komutu yoksa npm run test satırını kaldırıp sadece npx astro check ve npm run build kullanabilirsiniz. Gemini CLI nasıl kullanılır? sayfasındaki genel ayarlar da projeye uyarlanabilir.

Astro’da Gemini CLI ile çalışma döngüsü

Ajanla çalışırken büyük bir refactor yerine küçük, doğrulanabilir adımlar verin. Her adımdan sonra npx astro check veya npm run build çalıştırıp hatayı hemen düzelttirin. Değişiklikleri git diff ile inceleyin; özellikle .astro dosyalarındaki frontmatter ve şablon bölümlerinde istenmeyen değişiklikleri yakalayın. Kodlama ajanları için prompt yazmak rehberindeki net talimat ilkelerini buraya uygulayın.

Astro’ya özgü birkaç örnek prompt:

• “Blog içerik koleksiyonuna tags alanını ekle; src/content.config.ts şemasını güncelle, tip üretimini yenile ve mevcut markdown dosyalarının frontmatter’ını doldur.”
• “src/pages/index.astro içinde son üç blog yazısını getCollection ile al, BlogCard bileşenini kullanarak listele; mevcut grid düzenini koru.”
• “Header’daki mobil menüyü client:visible ile hydrate et; npx astro check ve npm run build çalıştırıp hataları düzelt.”
• “src/utils/formatDate.ts için Vitest testi yaz; mock gerekmeden tarih biçimini doğrula ve npm run test geçene kadar kodu düzelt.”
• “Tüm sayfalarda <title> ve meta description eksiklerini tespit edip tamamla; her sayfa için Frontmatter’dan değer alan bir layout kullan.”

Bu döngüde ajan bazen kendi başına bir adım ileri gidebilir; kapsam dışına çıkarsa görevi daraltın ve yalnızca istenen dosyaya dokunmasını söyleyin.

Astro’da Gemini CLI’ın iyi yaptığı işler ve tuzaklar

Gemini CLI, Astro’da en çok şu işlerde güvenilir çalışır: içerik koleksiyonu şemalarını güncellemek, getStaticPaths ile statik sayfa üretmek, .astro bileşenlerini parçalamak ve temel entegrasyon eklemek. Buna karşılık bazı noktalarda dikkatli olmak gerekir; çünkü ajan Astro’nun sunucu/istemci sınırını veya statik üretim kurallarını gözden kaçırabilir. Aşağıdaki tablo, tipik görevler, iyi prompt örnekleri ve dikkat edilecek tuzakları özetler.

Ayrıca şu tuzağa dikkat edin: ajan, içerik koleksiyonu yerine import.meta.glob kullanarak ham markdown okumaya çalışabilir. Bu, tipleri kaybettirir ve koleksiyon şemasını atlar. GEMINI.md’de açıkça getCollection kullanmasını söyleyin. Benzer şekilde, client:load direktifini tüm bileşene değil yalnızca etkileşimli kısma eklemesini isteyin; aksi halde statik sayfada gereksiz JavaScript yüklenir.

Gemini CLI ile Astro’da test ve doğrulama

Astro projesinde ajanın yaptığı her değişikliği en az iki katmanda doğrulayın: tip düzeyi ve üretim derlemesi. npx astro check, .astro ve TypeScript dosyalarındaki tip hatalarını yakalar; içerik koleksiyonu şeması ile kullanılan sorgular arasındaki uyumsuzlukları gösterir. Ardından npm run build çalıştırın; ajan statik sayfa üretimini ve getStaticPaths hatalarını burada görür. Görsel bir kontrol için npm run dev veya npm run preview kullanıp tarayıcıda sayfayı açmasını isteyebilirsiniz; ancak ajan tarayıcıyı kendisi açamıyorsa siz kontrol edin ve ekran görüntüsü paylaşın. Birim testler için Vitest yaygındır; ajan test yazabilir ve npm run test çalıştırabilir. Lint için npm run lint komutu, biçim ve basit hataları yakalar. E2E testleriniz varsa Playwright ile kritik sayfaları (örneğin ürün listesi, blog listesi) kapsayacak senaryoları ajanla birlikte yazabilirsiniz. Doğrulamayı görevin tanımına dahil edin: ajan yalnızca kod yazdığında değil, npx astro check ve npm run build komutlarını çalıştırıp temiz çıktı aldığında işi bitirmiş olmalı.

Birden fazla ajanı Astro projesinde AgentVera ile çalıştırma

Astro projesinde birden fazla kodlama ajanını paralel kullanmak isterseniz AgentVera masaüstü uygulaması işe yarar; her ajan kendi gerçek terminal panelinde çalışır. Astro için en değerli özellikler, ajanların ayrı git worktree’lerinde çalışarak dosyaların üzerine yazmasını önlemesi, iş bitince ikinci bir modelin kodu inceleyip dosya:satır olarak bulgu vermesi ve her turun geri alınabilir anlık görüntüsünün olmasıdır. Statik build ve içerik koleksiyonu değişiklikleri bütün siteyi bozabileceğinden bu üç özellik Astro’da kritik olur; ayrıca token bütçeleri maliyeti öngörülebilir kılar.

Gemini CLI, GEMINI.md ile doğru yapılandırıldığında Astro projelerinde hızlı ve güvenilir bir yardımcıdır. Küçük adımlar, sürekli doğrulama ve net klasör kuralları sayesinde içerik koleksiyonlarından adalara kadar birçok işi güvenle yürütebilirsiniz. Ajanı her görevden sonra npx astro check ve npm run build çalıştırmaya zorlayarak Astro’ya özgü hataları erkenden yakalayın.