# Codex ile Astro projelerinde pratik çalışma rehberi

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

Astro projenizde Codex ajanını nasıl kullanacağınızı öğrenin: AGENTS.md kurulumu, içerik koleksiyonları, adalar ve statik derleme ipuçları.

**Kısaca:**

- Codex, Astro projelerinde klasör ve şema sözleşmelerine uygun düzenlemeleri hızlıca yapar.
- AGENTS.md dosyasına derleme, test ve klasör kurallarını eklemek ajanı yönlendirir ve hata riskini azaltır.
- Astro’ya özgü adalar ve statik çıktı kısıtlarını bilmek, Codex’in güvenli değişiklikler yapmasını sağlar.

Codex, Astro projenizde terminalde `codex` komutuyla başlattığınız bir kodlama ajanıdır. Bu rehber, ajanın Astro’ya özgü işleri nasıl güvenle yapacağını, hangi kurallarla yönlendirileceğini ve hangi tuzaklara dikkat edileceğini gösterir. Astro’nun dosya tabanlı yapısı ve net sözleşmeleri sayesinde ajan hızlıca üretken olur.

## Neden Codex Astro işleri için uygundur?

Astro projeleri net klasör sözleşmelerine dayanır: sayfalar `src/pages/`, bileşenler `src/components/`, içerikler `src/content/` altında toplanır. Codex bu yapıyı okuyup düzenlemeleri doğru yere yapabilir. İçerik koleksiyonlarında şema tanımı (`src/content.config.ts`) ve frontmatter ilişkisi tip güvenliği sağlar; ajan bu sözleşmeyi bozmadan alan ekleyip çıkarabilir. Adalar mimarisi de sınırlıdır: yalnızca `client:*` direktifi alan bileşenler istemciye hidratlanır. Böylece ajanın yaptığı değişikliklerin etkisi tahmin edilebilir. Statik çıktı hedefleyen projelerde `output: 'static'` ayarı belirleyicidir; ajan bu sınırları bilirse sunucuya özgü API çağrılarından kaçınır. `astro.config.mjs` içindeki integrasyonlar (örneğin sitemap veya RSS) değiştirilirken dosyanın geri kalanını bozmaması da beklenir. Terminalden `codex` başlatıldığında proje kökündeki AGENTS.md dosyasını okur, böylece derleme ve kontrol komutlarını her seferinde yeniden öğrenmek zorunda kalmaz. Daha fazla bilgi için [Codex](/ajanlar/codex/) sayfasına bakabilirsiniz.

## Projeyi ajana hazırlama: AGENTS.md

AGENTS.md dosyası depo köküne konur; Codex bunu her oturumda bağlam olarak kullanır. Astro projesi için en az üç şey yazılmalıdır: komutlar, klasör sözleşmeleri ve Astro’ya özel kurallar. Aşağıdaki örnek gerçekçi bir başlangıçtır.

```markdown
# AGENTS.md

## Komutlar
- Kurulum: `pnpm install`
- Geliştirme: `pnpm dev`
- Derleme: `pnpm build`
- Tip kontrolü: `pnpm astro check`
- Lint: `pnpm lint`

## Klasör kuralları
- `src/content/` yalnızca içerik koleksiyonları içindir; şema `src/content.config.ts` içinde tanımlanır.
- `src/components/` yeniden kullanılabilir `.astro` bileşenler içindir.
- `src/layouts/` sayfa iskeletleri içindir.
- `src/pages/` dosya tabanlı rotalar içindir.
- Adalar yalnızca `src/components/` altında ve `client:` direktifi ile kullanılır.

## Astro'ya özel kurallar
- `src/content/` içindeki her koleksiyon için schema zorunludur; tip üretimini `astro sync` ile yenile.
- Statik çıktı hedefleniyorsa `output: 'static'` kalmasına dikkat et; `Astro.request` veya `Astro.cookies` kullanma.
- Adalarda `client:load` yalnızca gerçekten etkileşimli bileşenler için; `client:idle` tercih edilir.
- İçerik dosyalarında frontmatter alanlarını şemaya uygun yaz; eksik alan derlemeyi kırar.
```

Bu dosyayı olabildiğince kısa tutun; ajanın karar vermesi için yeterli bilgi olmalı, ama her kuralı tekrarlamayın. Astro’nun kendi dokümantasyonunda olan genel bilgiler yerine, bu projeye özgü alışkanlıkları yazın. Örneğin, projede tüm yazıların `src/content/blog/YYYY-MM-DD-slug.md` biçiminde olması gerektiğini belirtmek, ajanın dosya adlarını doğru üretmesini sağlar. Bağlam mühendisliği üzerine daha geniş bir bakış için [Bağlam mühendisliği](/blog/baglam-muhendisligi/) yazısına göz atın.

## Çalışma döngüsü

Başarılı bir Codex oturumu planla, küçük adımlara böl, testleri çalıştır ve diff’i incele döngüsüyle işler. Ajan büyük bir görevi tek seferde yapmaya çalışırsa çıktıyı gözden geçirmek zorlaşır. Bunun yerine, her istekte tek bir Astro katmanını hedefleyin: önce şema, sonra içerik, sonra bileşen, sonra sayfa. Her adımdan sonra `astro check` veya `pnpm build` çalıştırmasını isteyin. Ajan değişiklikleri yaptıktan sonra `git diff` çıktısını inceleyin; özellikle import yolları ve `client:` direktifleri gözünüzden kaçmasın. Ajan bir adımda birden fazla dosya değiştirdiyse, bu dosyaların amaçlarını ve birlikte davranışlarını doğrulamak için önce `pnpm dev` ile hızlı bir ön izleme yapın.

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

- Yeni bir blog yazısı için `src/content/blog/` altında frontmatter’ı şemaya uygun bir `.md` dosyası oluştur ve `astro check` ile doğrula.
- Mevcut `BaseLayout.astro` dosyasına bir dark mode toggle adası ekle; yalnızca `client:idle` kullan ve sunucu tarafı API çağrısı yapma.
- Tüm `src/pages/` sayfalarında kullanılan başlık bölümünü `src/components/Title.astro` olarak çıkar, import yollarını güncelle ve `pnpm build` çalıştır.
- Bir içerik koleksiyonunun şemasına `tags: z.array(z.string())` alanı ekle, ilgili içerik dosyalarını güncelle ve tip hatalarını düzelt.
- `astro check` uyarılarını listele, her birini ayrı commit’ler halinde düzelt, sonra `pnpm lint` çalıştır.

## Astro’da Codex’in iyi yaptığı işler ve tuzaklar

Codex özellikle içerik koleksiyonu şemalarını genişletmek, `.astro` bileşenlerini bölmek, statik sayfa üretmek ve meta verileri düzenlemek konusunda hızlıdır. Aşağıdaki tablo görevleri ve net istemleri özetler:

| Görev | Codex’e verilecek iyi istem |
|---|---|
| Koleksiyon şemasına alan ekleme | `src/content.config.ts` içindeki `blog` koleksiyonuna `draft: z.boolean().default(false)` alanını ekle, tüm içerik dosyalarını buna göre güncelle ve `pnpm astro check` çalıştır. |
| Adalarda hidrasyon hatalarını giderme | `src/components/ThemeToggle.astro` dosyasındaki `client:load`'u `client:idle` ile değiştir, bileşenin yalnızca görünür olduğunda yüklenmesini sağla ve `pnpm build` doğrula. |
| Statik sayfaya form ekleme | `src/pages/contact.astro` sayfasına basit bir HTML formu ekle, sunucu tarafı işlem gerektirmediğini söyle ve `astro check` çalıştır. |
| RSS akışı oluşturma | `astro.config.mjs` içindeki `@astrojs/rss` entegrasyonunu kullanarak `/rss.xml` rotası oluştur, `site` alanını `src/config.ts` içinden oku ve `pnpm build` ile doğrula. |

Bu işler genellikle sorunsuz ilerler. Dikkat edilmesi gereken tuzaklar şunlardır: Ajan, `.astro` dosyalarında `import` yollarını değiştirirken yanlış göreli yol üretebilir; `src/components/` altındaki dosyalar için mutlak alias (`@/components/...`) tercih edilmelidir. İçerik koleksiyonlarında bir alanı kaldırırken tüm frontmatter’ları güncellemezseniz, `astro check` hatası alırsınız; ajan bunu genelde yapar ama yine de doğrulamak gerekir. Adalar için `client:` direktifi yanlışlıkla sunucu bileşenine eklenirse hidrasyon hataları oluşur; ajanın özellikle `client:only` kullanmasını engellemek iyi olabilir. Son olarak, ajan `astro.config.mjs` içindeki integrasyonları değiştirirken mevcut ayarları bozabilir; her değişiklikten sonra `git diff` ile tam dosyayı inceleyin.

## Astro ile test ve doğrulama

Astro projelerinde güvenilir sonuç için üç komut vazgeçilmezdir: `pnpm astro check`, `pnpm build` ve `pnpm lint`. `astro check` TypeScript hatalarını ve şema uyumsuzluklarını yakalar; `pnpm build` statik çıktının üretilebildiğini doğrular ve tüm sayfaların geçerli olduğunu gösterir; `pnpm lint` ise stil ve kalıp hatalarını bulur. Codex ile çalışırken her adımın sonunda bu komutlardan en az birini çalıştırmasını isteyin. Ajan hata alırsa, hatayı nasıl çözdüğünü açıklamasını ve sonra ilgili dosyaları düzeltmesini söyleyin. Özellikle `astro check` çıktısında satır numaraları varsa, ajan bunları direkt kullanabilir. Ayrıca `pnpm astro sync` ile tip dosyalarını güncelledikten sonra çalışmak önemlidir. Ajanın ürettiği değişiklikleri `git diff` ile inceleyin ve kritik bölümleri manuel olarak test edin; örneğin bir adadaki etkileşimi tarayıcıda açıp deneyin.

## Bir projede birden fazla ajan: AgentVera

Astro projenizde birden fazla işi paralel yürütmek istediğinizde AgentVera kullanışlıdır. Her ajan kendi git worktree’sinde çalıştığı için dosyalar çakışmaz; örneğin biri içerik koleksiyonu şemasını güncellerken diğeri bir adayı yeniden yazabilir. Ajanın turu bittiğinde ikinci bir model otomatik kod incelemesi yapar ve bulgular dosya:satır olarak bağlanır, böylece Astro bileşenlerindeki hataları yakalamak kolaylaşır. Ayrıca her turun anlık görüntüsü (checkpoint) alınır; istenmeyen bir değişiklik tek tıkla geri alınabilir. Token bütçeleri ajan başına, tur başına ve günlük olarak sınırlandırılabilir; sınır aşıldığında ajan durur ama sohbet korunur, Astro derlemesi yarım kalmadan müdahale edebilirsiniz. Daha fazla bilgi için [AgentVera nasıl kullanılır](/blog/agentvera-nasil-kullanilir/) sayfasına bakın.

## Sonuç

Codex, Astro projelerinde içerik koleksiyonları, adalar ve statik sayfalar üzerinde hızlı ve güvenilir değişiklikler yapabilir. İyi hazırlanmış bir AGENTS.md, küçük adımlı istemler ve düzenli doğrulama komutları ile ajanın çıktısını üretim kalitesine yaklaştırırsınız. Tuzakları bilmek, özellikle import yolları ve client direktiflerini kontrol etmek, sürprizleri azaltır. Birden fazla ajanla çalışırken AgentVera, worktree izolasyonu ve otomatik kod incelemesiyle işleri ölçeklendirmenizi sağlar.

## Sık sorulanlar

**Codex Astro projesinde nasıl başlatılır?** Proje klasöründe terminali açıp codex komutunu çalıştırın. Codex kökteki AGENTS.md dosyasını okuyarak proje komutlarını ve kurallarını öğrenir. Daha sonra doğal dille görevler verebilirsiniz.

**AGENTS.md dosyasına Astro için neler yazmalıyım?** Derleme, geliştirme, tip kontrolü ve lint komutlarını; src/content/, src/components/, src/pages/ klasör sözleşmelerini yazın. Ayrıca client:* direktifleri ve statik çıktı kuralları gibi Astro’ya özgü kısıtları belirtin. Dosyayı kısa ve projeye özel tutun.

**Codex Astro’da içerik koleksiyonu şeması değişikliklerini yapabilir mi?** Evet, src/content.config.ts içindeki şemayı güncelleyebilir ve ilgili içerik dosyalarını buna göre düzenleyebilir. Değişiklik sonrası astro sync ve astro check komutlarını çalıştırarak tip tutarlılığını doğrulayın.

**Codex adalardaki hidrasyon hatalarını düzeltebilir mi?** Evet, client:load yerine client:idle veya client:visible gibi direktifler önerebilir ve uygulayabilir. Sunucuya özgü API kullanımını tespit etmek için statik çıktı kuralını AGENTS.md içinde açıkça belirtmelisiniz.

---

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