Codex ile Vue.js projelerinde pratik rehber

Codex, proje kökünde codex komutuyla başlatılan ve dosya sistemi üzerinde çalışan bir kodlama ajanıdır. Vue.js projesinde Composition API, tek dosyalı bileşenler ve Pinia ile kullanırken ajanın en büyük katkısı, küçük ve test edilebilir değişiklikleri hızla uygulamasıdır. Bu rehberde Codex’i Vue.js projesine nasıl bağlayacağınızı, AGENTS.md ile nasıl besleyeceğinizi ve güvenli bir çalışma döngüsü kuracağınızı anlatıyorum. Codex sayfasında ajanın temelleri var; burada doğrudan Vue.js pratiğine giriyoruz.

Codex neden Vue.js işine uygun

Vue.js projeleri çoğunlukla tek dosyalı bileşenlerden oluşur; her bileşen template, script ve style bölümlerini aynı dosyada taşır. Codex, proje ağacını ve import grafiğini okuyabildiği için src/components altındaki bir bileşenin nerede kullanıldığını bulur, prop ve emit değişikliklerini tüm kullanım yerlerine yayar. Composition API’de ref, computed, watch gibi yapıların dönüşümleri küçük ve test edilebilir adımlara bölünebildiğinden Codex’in ‘önce incele, sonra değiştir’ döngüsü iyi çalışır. Pinia store’ları da ayrı dosyalar olduğu için ajan state, getter ve action eklerken proje genelindeki kullanımları tarayabilir. Ayrıca AGENTS.md dosyasına yazdığınız npm run test:unit ve npm run lint komutları sayesinde her turda doğrulama yapmayı öğrenir. Vue SFC’lerinde <script setup lang="ts">, scoped stiller ve defineProps/defineEmits gibi kalıplar Codex’in iyi tanıdığı standartlardır.

Projeyi ajan için hazırlama ve AGENTS.md

Codex, bağlam mühendisliği açısından en çok proje kökündeki AGENTS.md dosyasından beslenir. Bu dosyada komutlar, klasör düzeni ve Vue.js’e özel kurallar olmalı. Bağlam mühendisliği rehberi, ajanın doğru bağlamı alması için kısa ve eyleme dönük talimatlar yazmayı anlatır. Aşağıdaki örnek, orta büyüklükte bir Vite + Vue 3 + Pinia projesi için başlangıçtır. Gerçek projenizde komutları ve klasör adlarını kendi yapınıza göre güncelleyin; ajan bu dosyayı birincil talimat olarak okur.

# Vue 3 + Vite + Pinia proje talimatı

## Komutlar
- Kurulum: `npm ci`
- Geliştirme: `npm run dev`
- Test: `npm run test:unit` (Vitest, jsdom)
- Lint: `npm run lint` (ESLint + eslint-plugin-vue)
- Tip kontrolü: `npm run type-check` (vue-tsc --noEmit)

## Klasör düzeni
- `src/components/` : SFC bileşenler; dosya adı PascalCase, örn. `TodoItem.vue`.
- `src/composables/` : `use*` adıyla Composition API mantığı.
- `src/stores/` : Pinia store'ları; her store kendi dosyasında.
- `src/views/` : route seviyesinde bileşenler.
- `src/__tests__/` : Vitest testleri; `*.spec.ts`.

## Vue kuralları
- Bileşenlerde `<script setup lang="ts">` kullan.
- Props ve emit'ler için `defineProps` ve `defineEmits` tipli olmalı; emit adları kebab-case.
- Reaktif durum yalnızca `ref` veya `reactive`; `computed` türetilmiş değerler için.
- Pinia store'da state dışındaki iş mantığını action içine koy; getter'lar türetme içindir.
- Yeni bir bileşen eklediğinde varsa `src/components/__tests__` altına temel render testi ekle.
- Değişiklik sonrası `npm run test:unit` ve `npm run type-check` çalıştır; kırmızı test bırakma.
- Lint hatalarını `npm run lint` ile düzelt, otomatik düzeltme için `npm run lint -- --fix`.

Bu dosyayı güncel tutmak, ajanın yanlış komut icat etmesini veya yanlış klasöre dosya eklemesini azaltır. Özellikle vue-tsc --noEmit komutunu eklemek, TypeScript hatalarının erken görülmesini sağlar.

Çalışma döngüsü ve örnek promptlar

Codex ile verimli çalışma sırası genelde şöyledir: görevi net yazın, ajanın önce ilgili dosyaları okumasını isteyin, planı onaylayın, küçük bir değişiklik yaptırın, testleri çalıştırın, git diff ile değişikliği inceleyin. Her turda tek bir sorumluluk verin; ‘tüm formu refactor et’ yerine ‘ProductCard props’unu ve testini güncelle’ deyin. Ajan test komutu çalıştıramıyorsa siz npm run test:unit çıktısını yapıştırın. CLI’nin temel kullanımı için Codex CLI nasıl kullanılır? sayfasına bakın.

• src/components/ProductCard.vue içindeki props tanımını incele. price alanını Intl.NumberFormat ile para birimi olarak formatlayan bir computed ekle, mevcut testleri bozma.
• Pinia’daki useCartStore dosyasını oku. removeItem action’ı ekle ve src/__tests__/cart.spec.ts içine bu action için bir test yaz.
• useDebouncedSearch composable’ını src/composables/ altında oluştur; ref ve watch kullan. Vitest ile iki durumlu test yaz.
• TodoList.vue içindeki uzun template’i alt bileşenlere böl. Önce mevcut testlerin kapsadığı davranışları listele, sonra böl ve tüm testleri çalıştır.
• Kırmızı durumdaki Checkout.spec.ts testini incele. Hatayı yalnızca ilgili bileşen dosyasında düzelt, testi tekrar çalıştır ve sonucu özetle.

Codex’in iyi yaptığı Vue.js işleri ve tuzaklar

Ajan özellikle şablon bazlı SFC oluşturma, props/emit refactor’ü, Pinia store düzenleme ve Vitest test taslağı çıkarmada hızlıdır. Ancak Vue reactivity ve test kurulumu ince detaylar içerir; ajanın ürettiği kodu doğrudan kabul etmeyin.

En kritik tuzaklar şunlardır: ref değerine script içinde .value ile erişilmesi gerekirken template’de otomatik unwrap edilir; ajan bazen bunu karıştırır. Reactivity’de sonradan eklenen özelliklerin izlenmesi için reactive yerine ref veya toRefs gerekir. watch içinde DOM güncellemesi beklerken nextTick çağrılmaması testleri kararsız hale getirir. Bu nedenle her Vue.js değişikliğinde ajanın önerdiği reactivity modelini ve test beklentilerini siz de gözden geçirin.

Test ve doğrulama

Codex’in Vue.js projesinde en güvenilir çalışma şekli, değişikliği küçük tutup test çıktısıyla doğrulamaktır. Ajanın test eklemesi yeterli değildir; testlerin gerçekten koştuğunu görmek gerekir. Vue Test Utils ile mount edilen bileşenlerde await flushPromises() veya await nextTick() kullanılmadan yapılan asenkron iddialar yanıltıcı olabilir. Pinia store testlerinde her test öncesi setActivePinia(createPinia()) çağrısı şarttır, yoksa store durumu testler arasında sızar. Agent’a şu komutları çalıştırmasını söyleyin: npm run test:unit -- --run (veya projenizdeki karşılığı) ve ardından npm run type-check. Hata çıktısını ajanı geri besleyin; ajan genellikle testin hangi satırda takıldığını okuyup düzeltebilir. Lint için npm run lint ayrıca çalıştırılmalıdır. Özellikle prop tipleri ve emit isimleri hatalıysa vue-tsc bunu erken yakalar. Doğrulama döngüsünde git diff incelemesi, istenmeyen dosya değişikliklerini ve yanlış import düzenlemelerini ortaya çıkarır. Ajanın önerdiği düzeltmeyi kabul etmeden önce diff içinde yalnızca ilgili dosyaların değiştiğini kontrol edin.

Birden fazla ajanı AgentVera ile yürütmek

Vue.js projesinde birden fazla Codex oturumu veya farklı ajan çalıştırmak gerektiğinde AgentVera masaüstü uygulaması işe yarar. Her ajan kendi git worktree’sinde çalışabildiği için paralel görevler aynı SFC dosyasını ezmez; otomatik kod incelemesi, reactivity hatalarını dosya:satır göstererek yakalar; checkpoint’ler başarısız bir refactor’ü tek tıkla geri alıp oturumu adım adım tekrar oynatmayı sağlar. Böylece bileşen bazlı paralel işlerde çakışma azalır, Vue Test Utils testleri bozulduğunda geri dönüş hızlanır.

Kapanış

Codex’i Vue.js projesinde verimli kullanmanın anahtarı, ajanı iyi bir AGENTS.md ile sınırlamak ve her turu test çıktısıyla kapatmaktır. Composition API ve Pinia’nın inceliklerini bilen bir geliştirici, Codex’in hızını kendi doğrulama disipliniyle birleştirdiğinde refactor ve test yazımında ciddi zaman kazanır. Unutmayın: ajanın önerdiği her değişikliği git diff ile inceleyin, testleri siz de çalıştırın ve reactivity hatalarını erken yakalayın.