# Gemini CLI ile Astro projesi geliştirme rehberi

Adres: https://agentvera.dev/blog/gemini-cli-ile-astro/ · Yayın: 2026-11-01

Gemini CLI ile Astro projelerinde içerik koleksiyonları, .astro bileşenleri ve statik build süreçlerini yönetmek için pratik GEMINI.md ayarları ve doğrulama döngüsü.

**Kısaca:**

- Gemini CLI, Astro projelerinde GEMINI.md talimatlarını okuyarak içerik koleksiyonları ve .astro bileşenleri üzerinde çalışır.
- Net klasör kuralları ve doğrulama komutları, ajanın statik build hatalarını erkenden yakalamasını sağlar.
- Küçük adımlar, sürekli test ve diff incelemesi Astro’da güvenilir bir çalışma döngüsü oluşturur.

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](/ajanlar/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:

```md
# 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?](/blog/gemini-cli-nasil-kullanilir/) 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](/blog/kodlama-ajanlari-icin-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.

| Görev | İyi prompt örneği | Dikkat edilecek nokta |
|---|---|---|
| İçerik koleksiyonuna alan ekleme | “Blog şemasına `updatedAt: z.date().optional()` ekle ve tüm içerik dosyalarını güncelle.” | Şema değişince ajan tüm markdown dosyalarını güncellemezse `astro build` başarısız olur; önce tek bir örnek üzerinde çalışmasını isteyin. |
| .astro bileşen düzenleme | “`src/components/Hero.astro` içindeki başlığı props’tan alsın, `title` ve `subtitle` ekle.” | Sunucu tarafı çalışan koda `client:*` direktifi eklemesin; hydration sınırını koruyun. .astro içinde JSX sözdizimi kullanmasına izin vermeyin. |
| Statik sayfa üretme | “`src/pages/blog/[slug].astro` içinde `getStaticPaths` kullanarak tüm yazılar için sayfa üret.” | `getStaticPaths` içinde `Astro.url` kullanmaya çalışmasın; statik build’de `Astro.site` gerekir. Ayrıca dinamik route’ta fallback değerlerine dikkat edin. |
| Entegrasyon ekleme | “`@astrojs/sitemap` entegrasyonunu kur ve `astro.config.mjs` içine ekle.” | Entegrasyon sürümünü package.json’a elle yazmasın; `npx astro add @astrojs/sitemap` komutunu tercih edin. |

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.

## Sık sorulanlar

**Gemini CLI Astro projesinde nasıl başlatılır?** Proje klasöründe terminalden gemini komutunu çalıştırın. Ajan, kök dizindeki GEMINI.md dosyasını okuyarak Astro’ya özel kuralları öğrenir ve ardından görevlerinizi kabul eder.

**GEMINI.md dosyasına Astro için neler yazılmalı?** Build, test, lint komutlarının yanı sıra src/pages, src/components, src/content klasör sözleşmeleri ve getCollection kullanımı gibi Astro’ya özel kurallar yazılmalıdır. Kısa ve net talimatlar, ajanın hata yapma riskini azaltır.

**Gemini CLI .astro dosyalarını düzenleyebilir mi?** Evet, .astro şablonlarını, frontmatter’ı ve bileşen yapısını düzenleyebilir. Ancak sunucu/istemci sınırını korumak için client:* direktiflerini yalnızca gerektiğinde eklemesini GEMINI.md’de belirtmelisiniz.

**İçerik koleksiyonu şeması değişince ajan ne yapmalı?** Önce src/content.config.ts içindeki şemayı güncellemeli, ardından tip üretimini yenilemeli ve tüm içerik dosyalarındaki frontmatter’ı yeni şemaya uygun hale getirmelidir. Sonrasında npx astro check ve npm run build çalıştırıp hataları düzeltmelidir.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/