opencode Astro ile kodlama: pratik rehber ve ipuçları

opencode bir Astro projesinin kök klasöründe doğrudan opencode komutuyla başlatıldığında, projedeki AGENTS.md talimatlarını okur ve içerik koleksiyonları, .astro bileşenleri, statik build ve entegrasyonlar üzerinde pratik değişiklikler yapabilir. Astro’ya özgü frontmatter, dosya tabanlı yönlendirme ve island mimarisi gibi konularda net kurallar verirseniz, agent tekrarlayan düzenlemeleri hızlandırır ve hataları erken yakalar. Bu rehberde kurulumdan doğrulamaya kadar somut bir çalışma düzeni anlatıyorum.

Opencode neden Astro işleri için uygun?

Astro projelerinde asıl yük, içerik koleksiyonlarının tip güvenliği, Markdown frontmatter tutarlılığı, .astro bileşenlerindeki props geçişi ve statik/etkileşimli kod ayrımıdır. opencode bu yapıyı tek tek elle düzeltmek yerine AGENTS.md üzerinden öğrenir ve dosya sistemi üzerinde doğrudan çalışır. Bir model sağlayıcıya bağlı olmadığından, mevcut API anahtarınızla veya tercih ettiğiniz sağlayıcıyla kullanabilirsiniz; Astro projesi için ayrı bir eklenti gerekmez. Özellikle şunlarda işe yarar: içerik şeması değişince tüm koleksiyon dosyalarını güncellemek, astro check hatalarını satır satır çözmek, birden çok .astro bileşeninde tutarlı props tipleri uygulamak ve entegrasyon ayarlarını düzenlerken build kırılmalarını önlemek. Terminal tabanlı çalıştığı için komutları sizin yerinize çalıştırıp çıktıyı okuyabilir; bu, statik build doğrulamasını gerçek bir döngüye dönüştürür.

Projeyi agent için hazırlama

Kök dizine AGENTS.md koyun. Bu dosya opencode’un projeye dair kullanacağı tek kaynak olmalı; yoksa agent genel Astro bilgisiyle tahmin yürütür. İçinde komutlar, klasör sözleşmeleri, içerik koleksiyonu kuralları ve island/hydration sınırları olsun. Aşağıdaki örnek gerçek bir Astro projesine göre kısa tutulmuştur:

# AGENTS.md

## Komutlar
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test` (Vitest)
- Lint: `pnpm lint` (eslint ile birlikte astro check)
- Tip kontrolü: `pnpm astro check`

## Klasör kuralları
- `src/content/`: içerik koleksiyonları; şema değişikliklerinde `src/content.config.ts` dosyasını güncelle.
- `src/components/`: yalnızca UI bileşenleri; veri erişimi veya iş mantığı olmasın.
- `src/layouts/`: BaseLayout gibi sayfa iskeletleri.
- `src/pages/`: dosya tabanlı rotalar; statik build varsayılan.

## Astro kuralları
- `.astro` dosyalarında frontmatter dışında script yazma; component script kullanma.
- Props tiplerini `interface Props` ile tanımla ve bileşenin üstünde dışa aktar.
- Adalar için `client:visible`, `client:load` gibi direktifleri yalnızca gerçekten etkileşimli bileşenlere ekle; tüm sayfayı hydrate etme.
- İçerik koleksiyonlarında `getCollection` veya `getEntry` kullan; `import.meta.glob` ile Markdown okumayı karıştırma.
- `astro check` geçmeden build veya commit yapma.

Bu dosyayı kısa ama net tutun; opencode uzun genel açıklamalardan çok kesin kurallarla daha iyi çalışır. Kurulumla ilgili daha geniş bir adım adım rehber için opencode nasıl kullanılır? Adım adım rehber sayfasına bakabilirsiniz.

Çalışma döngüsü

Astro projesinde opencode ile güvenli bir döngü şöyle olmalı: önce yapılacak işi küçük bir göreve indirgeyin, ajanın neyi değiştireceğini ve neyi değiştirmemesi gerektiğini net yazın. Ardından ajan dosyaları düzenlesin ve ilgili komutu çalıştırsın. Siz git diff ile yalnızca amaçlanan değişiklikleri inceleyin; özellikle src/content.config.ts ve astro.config.* gibi merkezi dosyalarda tek satırlık değişiklik bile tüm build’i etkileyebilir. Son olarak pnpm astro check, pnpm test ve pnpm build komutlarını geçmeden işi bitmiş saymayın.

Tipik Astro görevleri için şu promptlar işe yarar:

• “src/content/posts/ altındaki tüm Markdown dosyalarını posts koleksiyon şemasındaki coverImage zorunlu alanına göre denetle; eksik alanları dosya adından türetilmiş varsayılan bir değerle ekle ve astro check çalıştır.”
• “BaseLayout içindeki title prop’unu tüm sayfalarda frontmatter.title değerinden güvenli şekilde geçecek biçimde tip güvenli hale getir; varsayılan title’ı koru.”
• “Bu ProductCard.astro bileşenindeki client:load direktifini kaldırıp yalnızca buton adasını client:visible ile hydrate et; statik HTML çıktısını bozmadan çalıştığından emin ol.”
• “src/content.config.ts içindeki blog koleksiyonuna yeni bir tags alanı ekle, şema tipini güncelle, ardından tüm eski içeriklerin frontmatter’ına boş tags: [] ekle.”
• “Projede @astrojs/sitemap entegrasyonunun ayarlarını incele ve site alanını astro.config.mjs içindeki gerçek site URL’siyle güncelle; gerekirse pnpm build ile doğrula.”

Tipik Astro görevleri ve dikkat edilecek noktalar

opencode içerik koleksiyonlarında şema güncelleme, toplu frontmatter düzeltme, .astro bileşenlerini yeniden düzenleme, entegrasyon ekleme veya kaldırma, route parametreleri ve getStaticPaths gibi işlerde iyi sonuç verir. Ancak Astro’ya özgü bazı tuzaklar vardır. Aşağıdaki tablo sık karşılaşılanları özetler:

Bunların dışında dikkat edilecek iki Astro tuzağı daha var. Birincisi, src/content.config.ts içindeki koleksiyon adı ile src/content/<ad> klasör adı eşleşmeli; agent birini değiştirip diğerini unutabilir. İkincisi, import.meta.glob ile getCollection karıştırılırsa tip güvenliği kaybolur ve statik build’de beklenmeyen dosyalar üretilebilir. Değişiklikleri her zaman astro check ve pnpm build ile doğrulayın.

Test ve doğrulama

Bir Astro projesinde opencode ile çalışırken doğrulama üç katmandan oluşur: tip kontrolü, birim/integrasyon testi ve statik build. pnpm astro check içerik koleksiyonu tipleri ile .astro bileşenleri arasındaki uyumsuzlukları yakalar; bu yüzden her değişiklikten sonra mutlaka çalıştırın. pnpm test ile içerik şemasından türetilen verileri veya ada bileşenlerinin SSR olmayan davranışını test edebilirsiniz; opencode’den Vitest veya Playwright test senaryoları yazmasını isteyebilirsiniz. Son adımda pnpm build çıktısını dist/ altında gözden geçirin; özellikle statik sayfa sayısını ve getStaticPaths ile üretilen rotaları kontrol edin. Agent’a şu tür istekler verin: “Eklediğin her içerik koleksiyonu alanı için tip testi yaz ve eksik frontmatter durumunda anlamlı hata döndüğünü doğrula.” Bu döngü, Astro’nun en sinsi hatalarının erken yakalanmasını sağlar.

Aynı Astro projesinde birden fazla agent çalıştırma

Aynı Astro projesinde birden fazla agent kullanmak istediğinizde AgentVera işe yarar; her agent kendi gerçek terminal panelinde çalışır ve ayrı git worktree’leri sayesinde aynı dosyaları üzerine yazmaz. Böylece biri içerik koleksiyonu şemasını düzenlerken diğeri .astro bileşenlerini güncelleyebilir. Git ve GitHub entegrasyonu değişiklikleri, geçmişi ve otomatik commit mesajları ile PR’ları yönetir; otomatik code review, bir agent işini bitirdiğinde ikinci modelin Astro’ya özgü hataları (hydrate direktifi, frontmatter tipi) yakalamasını sağlar. Checkpoint’ler sayesinde yanlış bir build öncesi duruma tek tıkla dönülebilir. Bu, paralel Astro çalışmalarında güvenli bir zemin oluşturur.

Kapanış

opencode, Astro projelerinde tekrarlayan içerik ve bileşen işlerini hızlandırmak için doğru kurulumla oldukça pratiktir. Önemli olan AGENTS.md içinde Astro’ya özgü kuralları net yazmak, her değişikliği astro check ve build ile doğrulamak, adalar ile statik sınırlarını korumak. Daha fazla paralel çalışmaya ihtiyacınız varsa, ayrı worktree ve code review katmanı ile riski azaltabilirsiniz. Küçük adımlarla ilerleyin; opencode Astro’nun karmaşık yapısını sizin verdiğiniz kurallar kadar iyi yönetir.