# Claude Code Astro: Projede Verimli Kullanım Rehberi Adres: https://agentvera.dev/blog/claude-code-ile-astro/ · Yayın: 2026-11-01 Astro projelerinde Claude Code ile çalışmayı öğrenin: CLAUDE.md kurulumu, içerik koleksiyonları, adalar, statik derleme ve test doğrulama ipuçları. **Kısaca:** - Astro projesinde CLAUDE.md’ye build, test, lint komutları ve içerik şeması kuralları eklemek Claude Code’un doğru kod üretmesini sağlar. - Küçük adımlarla plan yaptırıp her değişiklikte pnpm astro check ve test çalıştırmak hata oranını düşürür. - Birden fazla ajan paralel çalıştırıldığında her birini ayrı git worktree’de tutmak dosya çakışmalarını önler. 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](/ajanlar/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: ```markdown # 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](/blog/claude-code-plan-modu/) 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: | Görev | Etkili istek | | --- | --- | | Yeni içerik girişi | `src/content/blog/` altına yeni bir `.md` dosyası oluştur; frontmatter’ı mevcut şemaya uygun doldur, ilk paragrafta özet ver. | | Ada dönüştürme | Bu bileşeni yalnızca kullanıcı kaydırdığında yüklenecek bir ada yap; `client:visible` kullan, gereksiz JS ekleme. | | Şema güncelleme | Blog koleksiyonuna `tags` alanını ekle, mevcut tüm `.md` dosyalarını güncelle, ardından `pnpm astro check` çalıştır. | | Derleme hatası | `pnpm build` çıktısını incele, ilgili satırdaki hata bağlamını bul, dosyayı düzelt ve her adımı göster. | 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, `