# Cursor Agent Astro: Terminal Ajanıyla Astro Geliştirme

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

Astro projelerinde Cursor Agent’ı (cursor-agent) nasıl kullanacağınızı öğrenin: AGENTS.md ayarları, içerik koleksiyonları, adalar ve test doğrulama ipuçları.

**Kısaca:**

- Cursor Agent, Astro projesinde terminal üzerinden planlı ve test güdümlü değişiklikler yapmak için kullanılır.
- AGENTS.md veya .cursor/rules dosyasına Astro’ya özgü build, lint ve içerik koleksiyonu kuralları ekleyin.
- Ajan, içerik koleksiyonları ve adalar gibi Astro özelliklerinde iyidir; ancak istemci adası sınırlarını manuel doğrulayın.

Cursor Agent, bir Astro projesinde terminalden `cursor-agent` komutuyla başlatılan ve proje talimatlarını okuyan bir kodlama ajanıdır. İçerik koleksiyonları, adalar ve statik build gibi Astro’ya özgü yapılarla çalışırken ajan, komutları ve dosya düzenini öğrenerek görevleri planlı biçimde yürütür. [Cursor Agent](/ajanlar/cursor-agent/) hakkında temel bilgi için ilgili sayfaya bakabilirsiniz.

## Cursor Agent neden Astro işlerine uygun?

Astro projeleri net bir yapıya sahiptir: statik sayfalar `.astro` dosyalarında, içerikler `src/content` altında, istemci etkileşimleri ise adalar aracılığıyla ayrılır. Cursor Agent bu ayrımı kurallar dosyasından okuyup dosya sistemine uygulayabilir. Örneğin, `src/content/config.ts` içindeki Zod şeması, ajanın yeni içerik eklerken hangi alanların zorunlu olduğunu bilmesini sağlar. Benzer şekilde `client:load`, `client:visible` gibi direktiflerin varlığı, ajanın hangi bileşenin istemciye gönderileceğini anlamasına yardımcı olur. Ajan ayrıca `npm run astro check` ve `npm run build` gibi komutları çalıştırarak değişikliklerin tip güvenliğini ve statik çıktıyı doğrulayabilir. Bu sayede içerik şeması değişiklikleri, rota ekleme veya ada dönüşümü gibi işlerde geri bildirim döngüsü kısalır.

Ajanın bir diğer avantajı, terminal komutlarını gerçekten çalıştırabilmesidir. `astro sync` ile otomatik oluşturulan tipleri güncelleyebilir, `astro dev` ile hızlıca yeni bir sayfayı test edebilir veya `vitest` ile birim testlerini çalıştırabilir. Astro’nun kendine özgü hata mesajları (örneğin, içerik şeması uyuşmazlığı veya geçersiz `client` direktifi) ajan tarafından yorumlanıp düzeltilebilir. Bu yüzden ajan, Astro projesindeki rutin bakım ve küçük feature eklemeleri için pratik bir çözümdür.

## Projeyi ajan için hazırlama

Ajan, proje kökündeki `AGENTS.md` veya `.cursor/rules` dosyasından talimatları okur. Astro projesi için bu dosyada komutlar, klasör düzeni ve framework’e özgü kurallar yer almalıdır. Aşağıdaki örnek, ajanın doğru komutları bilmesini ve statik/ada sınırlarını korumasını sağlar:

```markdown
# AGENTS.md

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

## Klasör düzeni
- `src/pages/` dosya tabanlı rotalar
- `src/content/` içerik koleksiyonları
- `src/components/` yeniden kullanılabilir bileşenler
- `src/layouts/` sayfa şablonları

## Astro kuralları
- `src/content/config.ts` içindeki şemalar içeriğin tek doğruluk kaynağıdır; önce şemayı güncelle, sonra içerik dosyalarını düzelt.
- İstemci etkileşimi gerekmiyorsa `client:*` direktifi ekleme.
- Statik çıktı için `output: 'static'` varsayımını koru; gereksiz adapter ekleme.
- `astro sync` ile oluşturulan `.astro` klasörünü düzenleme.
- Bir görevi bitirince `npm run astro check && npm run build` çalıştır.
```

Kurallar ne kadar kısa olursa ajan o kadar az sapma yapar. `AGENTS.md` yerine `.cursor/rules` dizini tercih edilebilir; dosya başına tek konu koymak daha temiz olur. Örneğin `content-rules.md` adında bir dosya sadece içerik koleksiyonu şema kurallarını, `islands-rules.md` ise ada dönüşümü kurallarını içerebilir. Ajan, bu dosyaları birleştirerek çalışır. [Cursor CLI nasıl kullanılır?](/blog/cursor-cli-nasil-kullanilir/) adlı rehberde terminal ajanı alışkanlıkları hakkında ek ipuçları bulabilirsiniz.

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

Ajanla çalışırken her görevi tek dosya grubuyla sınırlayın. Önce ajanın dosyaları incelemesini ve kısa bir plan çıkarmasını isteyin; ardından uygulamayı küçük adımlara bölün. Her adımdan sonra `npm run astro check` veya `npm run build` çıktısını ajanla paylaşın. Son olarak `git diff` üzerinden değişiklikleri inceleyin; özellikle `astro.config.mjs`, `src/content/config.ts` ve `client:*` direktiflerindeki satırlara bakın. Bu döngü, ajanın yanlış varsayımlarını erken yakalamayı sağlar.

Örnek Astro görevleri:

- "`src/content/blog/*.md` içindeki tüm yazıların frontmatter’ında eksik `description` alanlarını şemaya göre ekle ve `astro check` çalıştır."
- "Yeni bir `projects` içerik koleksiyonu ekle, `src/content/config.ts` şemasını tanımla ve üç örnek proje dosyası oluştur."
- "`src/components/ThemeToggle.astro` bileşenini bir ada olarak `client:visible` ile `src/layouts/Base.astro` içine yerleştir; istemciye giden kodu ayrı bir `<script>` etiketinde tut."
- "Mevcut statik sayfada başlık ve meta açıklamalarını düzenle; `astro build` sonrası `dist/index.html` içinde güncellendiğini doğrula."
- "`src/utils/formatDate.ts` için Vitest testleri yaz ve `npm run test` çalıştır; başarısız olursa düzelt."
- "`astro.config.mjs` içine `@astrojs/sitemap` entegrasyonunu ekle, gerekli paketi kur ve `astro build` ile `sitemap-index.xml` oluştuğunu doğrula."
- "`src/pages/blog/[slug].astro` dosyasında `getStaticPaths` kullanarak tüm içerik koleksiyonu girdileri için statik sayfalar üret; her slug’ın doğru HTML çıktısını kontrol et."

Bu promptlarda ajanın yalnızca dosya değişikliği yapmasını değil, aynı zamanda doğrulama komutunu da çalıştırmasını istemek önemlidir. Böylece hatalar anında görünür. Ajan bazen komutları atlayabilir; bu yüzden prompt sonunda "ve sonucu bana özetle" demek faydalı olur.

## Tipik Astro görevleri ve dikkat edilecek noktalar

Cursor Agent şu görevlerde iyi sonuç verir: içerik koleksiyonu şeması tanımlama, markdown/MDX dosyalarını güncelleme, yeni rota sayfaları oluşturma, mevcut `.astro` bileşenleri refactor etme, statik varlıkları `public/` altına taşıma ve basit testler yazma. Ayrıca `astro.config.mjs` içine popüler entegrasyonları (Site Haritası, RSS, görüntü optimizasyonu) ekleme işini de yapabilir. Ancak şu noktalarda ajanı manuel denetlemek gerekir:

- **Adaların sınırları:** Ajan, bir bileşene gereksiz yere `client:load` ekleyebilir veya istemciye giden JavaScript’i ana bundle içinde bırakabilir. Her ada değişikliğinden sonra `astro build` çıktısındaki chunk boyutlarını ve `dist/_astro` klasörünü kontrol edin.
- **İçerik şeması uyumu:** `src/content/config.ts` değiştiğinde ajan tüm içerik dosyalarını güncellemeyi unutabilir. `astro check` hatalarını dikkatle inceleyin.
- **Statik çıktı varsayımı:** Ajan, `@astrojs/netlify` gibi bir adapter ekleyerek projeyi sunucu moduna çevirebilir. Kural dosyasında statik çıktıyı açıkça belirtin.
- **Rota çakışmaları:** Yeni sayfa eklerken mevcut dosya tabanlı rotalarla çakışma olabilir. `astro build` sırasında uyarıları izleyin.
- **MDX ve remark eklentileri:** Ajan, MDX içine istemci bileşeni eklemeye çalışabilir; bu genellikle desteklenmez. MDX dosyalarını düzenlerken ekstra dikkat edin.
- **Public klasörü ve import yolları:** Ajan, `public/` altındaki varlıkları yanlış şekilde import edebilir veya `src/assets` ile karıştırabilir. Varlık yollarını kontrol edin.
- **Integrasyon sürümleri:** Ajan, `package.json` içine uyumsuz bir entegrasyon sürümü ekleyebilir. `npm install` sonrası `npm run build` başarısız olursa paket sürümlerini kontrol edin.

Bu tuzakların çoğu, kurallar dosyasında net sınırlar çizilerek azaltılabilir. Örneğin "hiçbir zaman `output: 'server'` olarak değiştirme" gibi kesin ifadeler kullanın.

## Astro’da test ve doğrulama

Astro projelerinde ajanla doğrulama üç katmandan oluşur: tip kontrolü, birim testler ve üretim build’i. `npm run astro check` komutu içerik koleksiyonu şemalarını ve bileşen tiplerini doğrular; `npm run test` Vitest gibi bir test çalıştırıcısıyla utility fonksiyonlarını ve ada mantığını test eder; `npm run build` ise statik çıktının hatasız üretildiğini garantiler. Ajanın her görev sonunda bu üç komutu çalıştırmasını isteyin.

Aşağıdaki tablo, doğrulama için hangi dosyanın hangi komutla kontrol edileceğini özetler:

| Dosya / Klasör | Doğrulama yöntemi |
|---|---|
| `src/content/config.ts` ve içerik dosyaları | `npm run astro check` |
| `src/components/*.astro` ve adalar | `npm run astro check` + `npm run build` |
| `astro.config.mjs` | `npm run build` ve `npm run dev` ile smoke test |
| `src/utils/*.ts` | `npm run test` |
| `dist/` çıktısı | `grep` veya manuel inceleme ile beklenen içerik |

Ajan, `astro build` sonrası `dist/` klasöründeki HTML dosyalarını inceleyerek meta etiketlerin, içerik parçalarının ve ada script etiketlerinin doğru yerleştiğini doğrulayabilir. Bunu prompt içinde açıkça isteyin. Örneğin, "`dist/blog/merhaba-dunya/index.html` dosyasında `<title>` etiketinin doğru metni içerdiğini kontrol et" gibi bir komut verin. Ayrıca `astro check` çıktısındaki uyarıları ciddiye alın; bazen ajan uyarıları görmezden gelir ve hatalar build aşamasında ortaya çıkar. [Vibe coding nasıl yapılır?](/blog/vibe-coding-nasil-yapilir/) makalesindeki güvenli iş akışı prensipleri burada da geçerlidir.

## Birden fazla ajanı AgentVera ile yönetme

AgentVera, Astro projesinde birden çok Cursor Agent’ı aynı anda çalıştırırken her birini kendi git worktree’sinde izole eder; böylece ajanlar birbirinin dosyalarını ezmez ve değişiklikler ayrı ayrı commit’lenebilir. Bir ajanın işi bittiğinde ikinci bir model otomatik kod incelemesi yapar ve bulguları `file:line` olarak gösterir; bu, içerik şeması veya ada dönüşümü gibi hassas değişikliklerde hataları erken yakalar. Checkpoint’ler sayesinde hatalı bir tur tek tıkla geri alınabilir; token bütçesi sınırı ise ajanın günlük kullanımını kontrol altında tutar. [Paralel kodlama ajanları](/blog/paralel-yapay-zeka-kodlama-ajani-araclari/) hakkında daha fazla bilgi için ilgili sayfaya bakabilirsiniz.

## Özet

Cursor Agent, Astro projesinde terminalden çalışan, kurallara dayalı ve test güdümlü bir iş akışı kurmanızı sağlar. `AGENTS.md` veya `.cursor/rules` dosyasına Astro’ya özgü komutları ve klasör düzenini yazdığınızda ajan, içerik koleksiyonları, adalar ve statik build görevlerini güvenle yürütür. Her değişiklik sonrası `astro check` ve `build` çıktılarını inceleyerek özellikle istemci adası sınırlarını ve içerik şeması uyumunu doğrulayın. Birden fazla ajan gerektiğinde AgentVera gibi bir araçla paralel çalışmayı izole worktree’ler ve otomatik review ile yönetin.

## Sık sorulanlar

**Cursor Agent Astro projesinde nasıl başlatılır?** Proje klasöründe terminalde cursor-agent komutunu çalıştırın. Ajan, AGENTS.md veya .cursor/rules dosyasındaki talimatları okur; bu yüzden önce Astro’ya özgü komutları ekleyin.

**Cursor Agent Astro’da içerik koleksiyonlarını yönetebilir mi?** Evet, schema tanımlarını okuyup yeni içerik dosyaları oluşturabilir veya mevcut markdown/MDX dosyalarını güncelleyebilir. Ancak astro sync çıktısını ve tip hatalarını doğrulamak gerekir.

**Cursor Agent ile Astro adaları güvenli şekilde değiştirilir mi?** Ajan, .astro dosyalarındaki client:directives ekleyip kaldırabilir; yine de hidrasyon sınırlarını ve bundle boyutunu astro build çıktısından kontrol edin. Adanın yalnızca istemciye gönderilmesi gereken kodu içerdiğinden emin olun.

**Cursor Agent için hangi kurallar Astro projesine eklenmeli?** Build, test ve lint komutları; src/pages, src/content, src/components ayrımı; astro check kullanımı; statik çıktıda istemci JavaScript kuralları. Kısa ve spesifik tutun.

---

**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/