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

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 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:

# 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? 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:

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? 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ı 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.