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

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

opencode ile Astro projesinde AGENTS.md kuralları, içerik koleksiyonları, island sınırları ve test döngüsü nasıl kullanılır? Pratik rehber.

**Kısaca:**

- opencode, Astro projesinde AGENTS.md talimatlarını okuyarak içerik koleksiyonu ve .astro bileşeni düzenlemelerini hızlandırır.
- Çalışma düzeni plan, küçük adım, astro check ve build doğrulaması üzerine kurulmalıdır.
- Birden fazla agent ayrı git worktree ve code review ile aynı Astro projesinde güvenle çalışabilir.

[opencode](/ajanlar/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:

```markdown
# 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](/blog/opencode-nasil-kullanilir/) 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:

| Görev | opencode iyi çalışır | Dikkat edilecek nokta |
|-------|----------------------|----------------------|
| İçerik koleksiyonu şeması değişikliği | Tüm markdown dosyalarını şemaya göre toplu düzeltir. | Eski alanları yanlışlıkla silebilir; önce bir yedek branch alın. |
| `.astro` bileşeni props tipleri | Tutarlı `interface Props` ekler ve kullanımları günceller. | Bileşen içinde global `Astro.props` erişimini bozabilir, `astro check` şart. |
| Island dönüşümü | Statik bileşeni ufak bir adaya çevirir. | Gereksiz yere `client:load` ekleyip tüm sayfayı hydrate edebilir; yalnızca etkileşimli yapıyı adaya taşımasını isteyin. |
| Entegrasyon ayarları | `astro.config.*` içinde site, base, sitemap gibi alanları düzenler. | Entegrasyon sırası ve çakışan ayarları gözden kaçırabilir; build sonrası `dist/` çıktısını kontrol edin. |

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](/blog/paralel-yapay-zeka-kodlama-ajani-araclari/) 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.

## Sık sorulanlar

**opencode Astro projesinde nasıl başlatılır?** Proje kök klasöründe terminalde opencode komutunu çalıştırmanız yeterlidir. Agent, AGENTS.md dosyasını okuyarak Astro’ya özgü kuralları öğrenir ve size görevleri sorar.

**opencode için Astro projesinde AGENTS.md dosyasına ne yazmalıyım?** Build, test, lint ve astro check komutlarını; klasör sözleşmelerini; içerik koleksiyonu kurallarını ve island/hydration sınırlarını yazın. Net kurallar, agent’ın tahmin yürütmesini engeller.

**opencode Astro’da içerik koleksiyonlarını güncelleyebilir mi?** Evet, şema değişikliğini tüm Markdown dosyalarına toplu olarak uygulayabilir. Ancak önce src/content.config.ts ve src/content klasör adının eşleşmesini kontrol edin, sonra astro check çalıştırın.

**opencode ile Astro statik build hatalarını nasıl çözerim?** Agent’a hatayı verin, önce astro check ile tip hatalarını gidermesini isteyin, sonra pnpm build çıktısını birlikte inceleyin. Değişiklikleri küçük adımlara bölmek hatanın kaynağını bulmayı kolaylaştırır.

---

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