Claude Code Astro: Projede Verimli Kullanım Rehberi

Claude Code’u bir Astro projesinin kök klasöründe claude komutuyla başlattığınızda, ajan dosya sistemini okur, terminal komutlarını çalıştırır ve .astro, .ts, .md dosyalarını düzenleyebilir. Bu rehber; içerik koleksiyonları, adalar ve statik derleme gibi Astro’ya özgü işlerde Claude Code ile nasıl çalışacağınızı pratik biçimde gösterir. Doğru talimatlar ve küçük adımlı doğrulama döngüsüyle, ajanı güvenilir bir eş geliştiriciye dönüştürebilirsiniz.

Neden Claude Code Astro işlerine uyuyor?

Astro projeleri birçok küçük ve bağlantılı dosyadan oluşur: .astro bileşenleri, src/content altındaki Markdown ve MDX dosyaları, astro.config.mjs entegrasyonları ve src/content.config.ts şemaları. Claude Code proje klasörünü okuduğu için bu dosyalar arasındaki ilişkileri koruyarak düzenleme yapar. Örneğin bir blog yazısının frontmatter’ında eksik pubDate alanı varsa, ajan hem ilgili .md dosyasını hem de şemayı birlikte inceleyip tutarlı bir düzeltme önerebilir. İçerik koleksiyonları zorunlu alan doğrulaması yaptığı için, ajanın toplu frontmatter güncellemeleri genellikle doğru olur; siz yalnızca sonuçları doğrularsınız.

Ada mimarisi açısından, Claude Code istemci tarafında çalışması gereken bileşenleri ayırt edebilir. Bir bileşeni client:load veya client:visible ile island olarak eklerken gerekli import’ları ve direktifleri doğru şekilde yerleştirir; gereksiz istemci JavaScript’i yüklememek için statik kalması gereken kısımları ayırt eder. Statik derleme sürecinde astro build çıktısındaki hataları yorumlayarak, import yolu yanlışlarını, frontmatter hatalarını veya integration sorunlarını hızla çözebilir. Ayrıca astro sync ile oluşturulan tiplerin güncellenmesi gerektiğinde bunu otomatik olarak yapabilir. Tüm bunlar, tekrar eden refaktör işlerini ajanın küçük adımlarla yürütmesine imkân tanır; siz odaklanıp farkları gözden geçirirsiniz.

Projeyi ajan için hazırlama: CLAUDE.md

Claude Code proje kökündeki CLAUDE.md dosyasını talimat olarak okur. Bu yüzden Astro projesine özel komutları, klasör yapısını ve kuralları buraya yazmak ajanın ilk seferde doğru kod üretme olasılığını ciddi şekilde artırır. Aşağıdaki örnek, gerçekçi bir Astro projesi için başlangıç şablonudur:

# CLAUDE.md

## Komutlar
- Kurulum: `pnpm install`
- Geliştirme: `pnpm dev`
- Derleme: `pnpm build`
- Önizleme: `pnpm preview`
- Tip ve şema kontrolü: `pnpm astro check`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Klasör yapısı
- `src/pages`: dosya tabanlı rotalar (`.astro`, `.md`, `.mdx`)
- `src/content`: içerik koleksiyonları (blog, docs)
- `src/components`: yeniden kullanılabilir Astro bileşenleri
- `src/layouts`: BaseLayout, BlogLayout vb.
- `public`: statik varlıklar; buradaki dosyalar olduğu gibi kopyalanır

## Astro kuralları
- İçerik koleksiyonu şemaları `src/content.config.ts` içinde tanımlıdır; frontmatter alanlarını şemaya uygun yaz.
- `.astro` dosyalarında frontmatter bölümünde yalnızca import ve sabitler; şablon için JSX benzeri ifadeler kullan.
- İstemci etkileşimi gerektiren bileşenleri `client:load` veya `client:visible` ile ada olarak ekle; gereksiz istemci JS yükleme.
- Statik çıktı hedefleniyorsa `window`, `document` veya `localStorage`'a yalnızca istemci adalarında eriş; sunucu tarafında erişme.
- `astro.config.mjs` değişikliği gerekirse önce öner; entegrasyon sırasını kendin değiştirme.

Bu dosyayı projeye ekledikten sonra claude komutunu çalıştırın. İlk istekte ajanın bu talimatları okuduğundan emin olmak için ‘CLAUDE.md’yi oku ve projeyi tanı’ diyebilirsiniz. Ayrıca CLAUDE.md içine Node sürümü (ör. node >= 18.17.1), paket yöneticisi tercihi (pnpm/npm), kullanılan import alias’ları (@components, @layouts) ve resim işleme davranışları gibi ortam bilgilerini eklemek faydalıdır. Böylece ajan, yeni dosya oluştururken doğru alias’ları kullanır ve Image bileşeni ile public klasörü arasındaki farkı bilir.

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

Astro projesinde Claude Code ile güvenli çalışma döngüsü şöyledir: önce ajanın ilgili dosyaları incelemesini ve bir plan sunmasını isteyin; ardından değişikliği küçük adımlara böldürün. Her adımda pnpm astro check veya pnpm build gibi komutları çalıştırmasını isteyin; hata varsa aynı adım içinde düzeltsin. Son olarak git diff ile değişiklikleri kendiniz inceleyin; özellikle .astro frontmatter, import yolları ve ada direktiflerine bakın. Gerekirse plan modunu kullanarak ajanın dosyaları değiştirmeden önce plan yapmasını sağlayın. Bu döngü, ajanın yalnızca kendinden emin olduğu adımları atmasına yardımcı olur.

Tipik Astro görevleri için örnek istekler:

• Mevcut src/content/blog yazılarını incele, şemaya uymayan frontmatter alanlarını listele ve her dosya için düzeltme öner. Önce yalnızca listele, sonra onay verirsem uygula.
• src/pages/index.astro sayfasına son 3 blog yazısını gösteren bir kart listesi ekle; önce plan yap, sonra her dosya değişikliğinden sonra pnpm astro check çalıştır.
• Bir React bileşenini client:visible ada olarak ekle; kullanıcı bileşeni görünüme kaydırdığında yüklensin, gerekli import ve island yapısını kur.
• src/content/blog/ içinde yeni bir --slug--.md dosyası oluştur; frontmatter alanlarını src/content.config.ts içindeki şemaya göre doldur.
• pnpm build şu hatayı veriyor: [hata çıktısını yapıştır]. Hatayı incele, ilgili dosyayı düzelt ve değişiklikleri tek tek göster.
• Projedeki tüm client:load kullanımlarını client:visible ile değiştir, böylece sadece görüntü alanına girince yüklensin. Değişiklik sonrası pnpm build ve pnpm astro check çalıştır.

Bu listedeki istekler ajanın Astro’ya özgü bağlamı doğru kullanmasını sağlar. İsteği mümkün olduğunca dosya yolu ve beklenen davranışla somutlaştırın; belirsizlik durumunda ajan genel bir çözüm üretir ve Astro’nun özel kısıtlarını gözden kaçırabilir.

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

Claude Code Astro projelerinde şu işlerde başarılıdır: yeni içerik girişleri oluşturmak, frontmatter alanlarını şemaya göre toplu güncellemek, bileşenleri yeniden düzenlemek, import yollarını onarmak ve derleme hatalarını gidermek. Aşağıdaki tablo, sık kullanılan görevler için etkili istekleri özetler:

Yine de bazı noktalarda ajanı yakından izlemek gerekir. İçerik koleksiyonu şemaları ile frontmatter uyumsuzluğu en sık hatadır; ajan bazen şemada olmayan alanlar ekleyebilir ya da zorunlu alanları atlayabilir. Bu yüzden her değişiklikten sonra pnpm astro check çalıştırın. Statik derlemede sunucu tarafında window veya document kullanımı hata üretebilir; ajan bu tür globalleri yanlışlıkla .astro frontmatter içine koyabilir. Import yolları da kritik: ajan, @components/... gibi alias’ları doğru kullanmalı, yanlış göreli yollar üretmemelidir. astro.config.mjs içinde entegrasyon sırası ve ayarların değiştirilmesi ise projeyi bozabilir; bu dosyayı ajanın kendi başına değiştirmesine izin vermeyin. Ayrıca resim işleme: public klasöründeki görselleri doğru referans etmeli, Image bileşeni kullanılacaksa import { Image } from 'astro:assets' satırını eklemeyi unutmamalıdır. Routing çakışmaları (iki dosyanın aynı URL’i üretmesi) da ajanın gözünden kaçabilir; pnpm build sonrası dist çıktısını kontrol edin. Ajan, özellikle içerik koleksiyonu şeması değiştirirken eski şemaya bağlı tipleri güncellemeyi atlayabilir; pnpm astro sync sonrası tip hataları ortaya çıkabilir. Bu tür durumlarda ajanı “şema güncellendi, tipleri yenile ve tüm referansları düzelt” diye yönlendirin.

Astro için test ve doğrulama

Ajanın ürettiği kodu doğrulamak için pnpm astro check ilk adım olmalıdır; bu komut TypeScript hatalarını ve içerik koleksiyonu şeması uyumsuzluklarını yakalar. Ardından pnpm build ile statik çıktının üretilebildiğini görün; hata varsa ajanla birlikte dist çıktısındaki ilgili dosyayı inceleyin. Ada davranışını doğrulamak için pnpm preview ile oluşan önizlemeyi tarayıcıda açın ve yalnızca beklenen bileşenlerin istemci JavaScript’i yüklediğini kontrol edin. Projede Playwright veya Vitest gibi testler varsa pnpm test komutunu ajanın her büyük değişiklikten sonra çalıştırmasını isteyin. Ajanın test sonuçlarını raporlamasını isteyin; başarısız testlerin hangi satırdan kaynaklandığını görmek için test çıktısını ajanla paylaşın. Son olarak git diff çıktısını kendiniz inceleyin; .astro dosyalarındaki frontmatter, <script> etiketleri ve import satırları gözden kaçan hataların en sık bulunduğu yerlerdir. Ajanın yaptığı değişikliklerin içerik koleksiyonu şemasına uygunluğunu doğrulamak için pnpm astro check çıktısını satır satır okuyun; hata mesajları genellikle dosya ve alan adını belirtir.

Birden fazla ajanı AgentVera ile paralel çalıştırma

Astro projelerinde içerik üretimi, bileşen yeniden düzenleme ve şema geçişi gibi işler birbirinden bağımsız yürütülebilir. AgentVera, Claude Code ve benzeri CLI ajanlarını tek pencerede gerçek terminal panellerinde yan yana çalıştırır; her ajan ayrı bir git worktree üzerinde çalışarak aynı .astro ve .md dosyalarını ezmeden paralel ilerleyebilir. Ayrıca ajanın her turunun sonunda ikinci bir modelin yaptığı otomatik kod incelemesi, src/content.config.ts şemasındaki hataları satır bazında gösterir. Checkpoint’ler sayesinde yanlış bir içerik koleksiyonu geçişi tek tıkla geri alınabilir, böylece paralel çalışırken risk azalır. Bu yapıyı birden fazla Claude Code ajanını paralel çalıştırma yazısında inceledim.

Sonuç

Claude Code, Astro projesinde doğru CLAUDE.md, küçük adımlı çalışma döngüsü ve sürekli doğrulama ile güvenilir bir eş çalışan olur. İçerik koleksiyonları ve ada mimarisi gibi Astro’ya özgü noktaları talimatlara yazarsanız ajanın hata oranı belirgin biçimde düşer. Paralel işler için AgentVera gibi araçlarla işleri bölerek daha hızlı ilerleyebilir, ancak her ajanın ürettiği kodu yine de kendiniz gözden geçirmelisiniz.