Codex ile Astro projelerinde pratik çalışma rehberi

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 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.

# 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 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:

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 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.