GitHub Copilot CLI ile Astro Projesi Geliştirme Rehberi

GitHub Copilot CLI, Astro projesinde terminalde copilot komutuyla başlattığınız kodlama ajanıdır; proje kökündeki .github/copilot-instructions.md veya AGENTS.md dosyasını okuyarak Astro’ya özgü kuralları uygular. İçerik koleksiyonları, .astro bileşenleri, adalar ve statik derleme üzerinde hedefli değişiklikler yapabilir. Bu rehberde kurulum, doğru talimat dosyası ve güvenli çalışma düzeni anlatılıyor.

Neden GitHub Copilot CLI Astro işine uygun

Astro projeleri dosya tabanlı yönlendirme, içerik koleksiyonları ve adalar mimarisiyle çalışır. Ajan, proje klasörünü tarayarak src/pages, src/content, src/layouts ve astro.config.mjs gibi yapıları öğrenir; .astro dosyalarındaki frontmatter’ı ve bileşenler arası veri akışını çözümleyebilir. Statik derleme hedefi olduğu için, ajanın önerdiği değişikliklerin npm run build ile doğrulanması kolaydır. Ayrıca ajan, içerik koleksiyonu şemasını güncellerken hem config.ts hem de .md dosyalarını aynı anda düzenleyebilir; bu, elle yapıldığında hata riski taşıyan bir iştir. Yine de Astro’nun kendine özgü kuralları (client direktifleri, import yolları, üretilen klasörler) ajanın varsayılan davranışında bulunmaz; bunları talimat dosyasına yazmak gerekir.

Ajanın Astro’ya uygunluğu iki somut özellikte öne çıkar: içerik koleksiyonları ve adalar. İçerik koleksiyonlarında şema değişikliği yaparken ajan src/content/config.ts ile birlikte tüm ilişkili .md dosyalarını günceller; böylece astro sync sonrasında tip hataları oluşmaz. Adalar konusunda ise ajan, bir bileşenin hangi bölümünün tarayıcıda etkileşimli olması gerektiğini anlayıp doğru client:* direktifini önerebilir; örneğin yalnızca görünür olduğunda yüklenmesi gereken bir görüntülenme sayacını client:visible ile işaretler. Ancak ajan bazen aşırı hevesli davranıp gereksiz yere tüm sayfayı ada haline getirebilir; bu nedenle talimatlarda “yalnızca gerekli bileşenlere client direktifi ekle” gibi kurallar bulunmalıdır. Ayrıca Astro’nun astro:content modülünden yapılan importların doğru kullanılması, ajanın sık yaptığı hatalardan biridir.

Projeyi ajan için hazırlama

GitHub Copilot CLI, çalışmaya başlarken .github/copilot-instructions.md dosyasını arar; yoksa AGENTS.md’ye bakar. Astro projesi için bu dosyaya derleme, test, lint ve tip kontrolü komutlarını, klasör kurallarını ve Astro’ya özgü kuralları yazın. İşte gerçekçi bir örnek:

# Astro projesi için GitHub Copilot CLI talimatları

## Komutlar
- Geliştirme: npm run dev
- Derleme: npm run build
- Önizleme: npm run preview
- Test: npm run test
- Lint: npm run lint
- Tip kontrolü: npm run check

## Klasör kuralları
- Sayfalar: src/pages
- Bileşenler: src/components
- Düzenler: src/layouts
- İçerik: src/content
- Statik varlıklar: public
- Üretilen klasörlere yazma: .astro, dist, node_modules

## Astro kuralları
- Her .astro dosyasında frontmatter en üstte olmalı.
- Content collections için şemayı src/content/config.ts içinde tanımla.
- Client-side etkileşim için yalnızca gerekli adalara client:* direktifi ekle.
- Static build'de tarayıcı API'si kullanma; gerekirse <script> içinde çalıştır.
- Integrations eklerken astro.config.mjs dosyasını güncelle ve bağımlılığı package.json'a ekle.
- import yolları relative kullan; alias yalnızca tsconfig.json içinde tanımlıysa geçerlidir.

Dosyayı kısa tutun; her komutun çalıştığından emin olun. AGENTS.md ve CLAUDE.md rehberi bu dosyanın yapısı için ek ipuçları verir. Eğer proje TypeScript kullanıyorsa npm run check yerine astro check komutunu da ekleyebilirsiniz; bu komut .astro dosyalarını ve içerik koleksiyonu tiplerini denetler. Talimat dosyasına ayrıca ajanın sorması gereken soruları veya göz ardı etmesi gereken desenleri ekleyin; örneğin public klasöründeki varlıkların import edilmemesi gibi.

Çalışma döngüsü

Ajana büyük bir hedef vermek yerine döngüyü şöyle kurun: önce plan isteyin, sonra tek bir dosya veya küçük bir modül değişikliği yaptırın, ardından npm run check veya npm run build çalıştırın ve git diff ile farkı inceleyin. Her turda yalnızca bir kavramı değiştirin; adalar, koleksiyon şeması ve sayfa yapısı gibi konuları ayrı turlarda ele alın. Testler başarısızsa hatayı ajana yapıştırıp düzeltmesini isteyin. Böylece her adımın etkisi net görülür ve geri almak kolaylaşır. Astro projesindeki tipik bir tur şöyle görünür:

1. Ajan mevcut dosyaları okur ve ne yapacağını açıklar; siz onaylayın.
2. Ajan değişiklikleri uygular; siz git diff ile kontrol edin.
3. npm run check ve npm run build çalıştırın; hata varsa ajana geri bildirin.
4. Başarılıysa değişikliği commit’leyin ve bir sonraki göreve geçin.

Örnek promptlar:

• ‘src/content/blog koleksiyonuna yayinTarihi alanı ekle; şemayı güncelle ve mevcut tüm .md dosyalarında bu alanı doldur.’
• ‘src/components/BlogCard.astro bileşenini oluştur; koleksiyondan gelen post verisini props olarak alsın ve tarihi Intl.DateTimeFormat('tr-TR') ile biçimlendirsin.’
• ‘Ana sayfada son 3 blog gönderisini listeleyen bir bölüm ekle; her kart için client:visible direktifiyle bir görüntülenme sayacı adası oluştur.’
• ‘astro.config.mjs içine sitemap entegrasyonunu ekle, paketi yükle ve site alanını güncelle.’
• ‘src/pages/about.astro sayfasındaki statik metni içerik koleksiyonundan gelen veriyle değiştir.’

Her prompttan sonra ajanın önerdiği değişiklikleri inceleyin; özellikle .astro dosyalarındaki frontmatter ve script bölümlerini gözden geçirin. Ajan bazen import yollarını yanlış yazabilir veya client: direktiflerini hatalı ekleyebilir; bu yüzden diff incelemesi kritik önem taşır.

Tipik Astro görevleri ve tuzaklar

Ajan şu işleri iyi yapar: içerik koleksiyonu şeması ekleme, .astro bileşeni oluşturma, mevcut sayfaya veri bağlama, basit entegrasyon kurulumu ve statik varlık yollarını düzeltme. Ancak bazı Astro tuzaklarına dikkat edin.

Dikkat edilecekler:

• Ajan gereksiz client:load veya client:visible ekleyerek tüm sayfayı adaya çevirebilir; yalnızca etkileşimli parçalara direktif verin.
• Content collections import yolu astro:content olmalıdır; ajan bazen ../content gibi yanlış yol kullanır.
• .astro dosyalarında frontmatter kapanış --- işaretini unutabilir veya script etiketlerini hatalı kapatabilir; diff’i kontrol edin.
• Static build sırasında window, document veya localStorage kullanmamalı; gerekirse <script> etiketi içinde çalıştırın.
• Ajan, astro.config.mjs içine entegrasyon eklerken ilgili paketi package.json’a eklemeyi atlayabilir; npm install gerekip gerekmediğini kontrol edin.
• Üretilen .astro ve dist klasörlerine dokunmaması talimat dosyasında açıkça yazılmalı.

Ek olarak, ajanın slug veya URL oluşturma mantığını değiştirirken mevcut bağlantıları bozmamasına dikkat edin; özellikle dinamik rotalarda params yapısını koruyun. İçerik koleksiyonlarında alan adları değiştiğinde tüm bileşenlerdeki kullanımları da güncellemesini isteyin; aksi halde derleme hatası alırsınız.

Test ve doğrulama

Her ajan turundan sonra sırasıyla npm run check, npm run build ve gerekirse npm run preview çalıştırın. astro check, .astro ve TypeScript dosyalarındaki tip hatalarını yakalar; npm run build ise statik derlemenin temiz olup olmadığını gösterir. Adalar içeren sayfalar için yalnızca build yeterli olmayabilir; etkileşimleri tarayıcıda test etmek için yapay zekâ ajanıyla tarayıcı testi rehberindeki Playwright MCP yaklaşımını kullanabilirsiniz. Ajanın değiştirdiği dosyaları git diff --stat ile özetleyin, ardından tam diff’i inceleyin; özellikle content collections şeması ve adaların direktiflerini doğrulayın.

Ayrıca npm run lint komutunu çalıştırarak stil sorunlarını yakalayın; Astro projelerinde sıklıkla ESLint ve Prettier kullanılır. Eğer proje astro check destekliyorsa bunu da ekleyin; tip hataları erken ortaya çıkar. İçerik koleksiyonlarında astro sync sonrası oluşan tiplerin güncel olduğundan emin olun. Ajanın yazdığı yeni .astro bileşenlerinde lang="ts" kullanımı ve frontmatter içindeki değişkenlerin tip güvenliği de kontrol edilmelidir.

Astro projesinde birden fazla ajanı AgentVera ile çalıştırma

AgentVera, GitHub Copilot CLI dahil birden çok kodlama ajanını aynı pencerede gerçek terminal panellerinde çalıştırır. Astro projelerinde aynı anda hem içerik koleksiyonu hem de .astro bileşeni üzerinde iki ajanı paralel koşabilirsiniz; her biri kendi git worktree’sinde çalıştığı için dosyalar çakışmaz. Bir ajanın turu bitince ikinci bir model değişiklikleri otomatik inceler ve bulguları dosya:satır olarak gösterir. Checkpoint’ler sayesinde yanlış bir adım tek tıkla geri alınabilir ve oturum adım adım yeniden oynatılabilir. Bu, Astro’nun statik derleme ve adalar gibi birbirine bağlı bölümlerinde güvenli paralel çalışma sağlar.

Özet

GitHub Copilot CLI, proje talimatları doğru yazıldığında Astro işlerinde güvenilir bir yardımcıdır. Küçük adımlarla, her turda build ve diff kontrolü yaparak çalışmak, ajanın Astro’ya özgü tuzaklara düşmesini büyük ölçüde engeller. Birden çok ajanı paralel yürütmek için AgentVera gibi bir ortam, işleri hızlandırır ve hataları erken yakalar.