opencode ile Laravel projelerinde verimli çalışma rehberi

opencode, Laravel projenizin kök dizininde terminalde opencode komutuyla başlattığınız bir kodlama ajanıdır. Model sağlayıcısından bağımsız çalışır; Laravel’e özgü komutları ve proje kurallarınızı okuyarak Eloquent, migration, Blade, queue ve test işlerinde dosya düzenleyip terminal komutları çalıştırabilir. Bu rehber, Laravel bilen geliştiricilerin opencode’u gerçek iş akışında güvenle kullanması için somut adımlar verir; genel kurulum için opencode sayfasına bakabilirsiniz.

Neden opencode Laravel işlerine uygun?

opencode, proje dizininde çalıştığı için Laravel’in dosya yapısını doğal biçimde anlar. artisan komutlarını çalıştırabildiğinden php artisan make:model, migrate, test gibi işleri doğrudan yürütür; böylece hem kod üretir hem de sonucu terminalde doğrular. Eloquent ilişkileri, migration sıralaması, Blade bileşenleri ve queue job’ları gibi Laravel kavramlarına hâkim olduğu için sıradan CRUD işlerini uçtan uca tamamlayabilir. Model sağlayıcısından bağımsız olması, mevcut API anahtarınızla veya yerel bir modelle deneme yapmanıza olanak tanır. Ajan, AGENTS.md dosyasındaki komutları izlediği için pint, pest veya phpunit gibi araçları sizin belirlediğiniz biçimde kullanır. Karşılaştırma için opencode mu Claude Code mu? Dürüst bir karşılaştırma yazısına göz atabilirsiniz.

Ayrıca opencode, terminal çıktısını okuyup hata mesajlarına göre iterasyon yapar. Örneğin bir migration başarısız olduğunda hatayı görür, düzeltir ve php artisan migrate komutunu tekrar çalıştırır. Bu geri bildirim döngüsü, Laravel’in çalışma zamanı hatalarını hızlı çözmek için önemlidir.

Projeyi ajana hazırlama: AGENTS.md

opencode, proje kökündeki AGENTS.md dosyasını talimat olarak okur. Bu dosyada Laravel’e özgü komutlar, klasör kuralları ve ajanın uyması gereken kısıtlar yer almalı. Ne kadar kısa ve net olursa ajan o kadar az sapar. Aşağıdaki örnek, bir Laravel projesi için işe yarar bir başlangıçtır:

# AGENTS.md

## Komutlar
- Bağımlılık kurulumu: `composer install`
- Test: `php artisan test`
- Lint: `./vendor/bin/pint --test`
- Format: `./vendor/bin/pint`

## Klasör kuralları
- Modeller `app/Models`, migration'lar `database/migrations`, factory'ler `database/factories` altında olmalı.
- Form request'lerini `app/Http/Requests`, service sınıflarını `app/Services` altında tut.

## Laravel'e özel kurallar
- Migration değişikliği yaparken `php artisan migrate:fresh --seed` çalıştır.
- Eloquent'te `$fillable` veya `$guarded` tanımla; toplu atama riskini açıklamadan bırakma.
- Blade'de iş mantığı yazma; controller veya action sınıfına taşı.
- Queue job'ları için `php artisan queue:work` ile gerçek kuyruk davranışını test et.
- Testlerde `RefreshDatabase` kullan.

Bu dosyayı projeye ekledikten sonra opencode’u yeniden başlatın veya mevcut oturumda dosyayı okuması için talimat verin. Adım adım kurulum ayrıntıları için opencode nasıl kullanılır? Adım adım rehber rehberine bakabilirsiniz.

AGENTS.md içinde environment değişkenleri, cache temizleme rutinleri veya belirli model ilişkileri için ek kurallar da tanımlayabilirsiniz. Örneğin “Queue kullanırken QUEUE_CONNECTION=database varsayılanıyla çalış, sync kullanma” gibi bir kural eklemek gerçekçi davranışı test etmenizi sağlar.

Çalışma döngüsü: planla, küçük adımlar at, testleri çalıştır, diff’i incele

opencode ile güvenli döngü şu sırayla işler: önce yapılacak işi bir veya birkaç cümleyle tanımlayın; ajanın plan önermesini isteyin. Ajanın plan önerisi üretmesini bekleyin; planı onaylamadan kod yazmasına izin vermeyin. Büyük bir görevi aynı oturumda tek seferde istemek yerine, her biri test edilebilir olan ardışık adımlara bölün. Sonra küçük parçalara bölün: model ve migration, ardından controller ve form request, sonra test. Her adımda php artisan test çalıştırıp sonucu açıkça söyleyin. Bitince git diff ile değişiklikleri satır satır gözden geçirin. Bu döngü, Laravel’in sihirli kısımlarında service provider, event veya observer gibi yerlerde yanlış varsayımları erken yakalar.

Aşağıdaki istemler, tipik Laravel görevlerinde iyi sonuç verir:

• Order modelini, migration’ını ve factory’sini oluştur; user_id, status, total alanları olsun. Order ile User arasında belongsTo ilişkisi kur ve ilişkiyi test eden bir test yaz.
• Aşağıdaki feature test başarısız: PostControllerTest::test_store_requires_title. Hatayı incele, gerekli doğrulamayı controller veya form request’e ekle, testi tekrar çalıştır.
• SendWelcomeEmail job’ını user oluşturulduğunda kuyruğa ekleyen observer veya event listener yaz. queue:work ile çalıştığını doğrula.
• Blade dashboard.blade.php içindeki son 5 siparişi gösteren kısmı bir OrderList component’ine taşı; @foreach döngüsünü sadeleştir.
• php artisan make:command Report:DailySales ile komut oluştur; dünün satış toplamını hesaplayıp sales:daily imzasıyla çalıştır. Komut için bir test yaz.
• app/Http/Controllers altındaki bir controller’ı __invoke tabanlı tek eylem controller’ına dönüştür; route tanımını güncelle ve testi çalıştır.

Her adımdan sonra git diff çıktısını incelemek, özellikle migration dosyalarında down() metodunu, model $fillable alanlarını ve route tanımlarını kontrol etmek önemlidir. Ajanın ürettiği kodu anlamadığınız bir bölüm varsa, o bölümü açıklamasını isteyin.

İyi yaptığı Laravel işleri ve dikkat edilmesi gerekenler

Aşağıdaki tablo, opencode’un Laravel’de güçlü olduğu alanları ve her birinde göz önünde bulundurmanız gereken riskleri özetler:

Dikkat edilmesi gereken Laravel’e özgü tuzaklar şunlardır: migration dosyası çalıştırıldıktan sonra değiştirilirse rollback veya migrate:fresh gerekebilir; ajan bu durumu atlayabilir. Eloquent ilişkilerinde lazy loading N+1 üretir; üretimde with veya load kullanımını gözden geçirin. Config ve route cache dosyaları bootstrap/cache altında sürpriz davranışlara yol açabilir; değişiklik sonrası php artisan config:clear ve php artisan route:clear çalıştırın. Service provider veya event listener kayıtları doğru dosyada olmazsa sessizce çalışmaz; diff’te bu dosyaları özellikle inceleyin. Ayrıca validation kurallarında sometimes, nullable veya required_if gibi koşullu kurallar yanlış uygulanabilir; form request dosyalarını dikkatle kontrol edin. Örneğin, bir observer created eventini dinlerken, ajan observer’ı AppServiceProvider yerine yanlış bir yere kaydedebilir ve kod sessizce çalışmaz. Bu tür durumları yakalamak için php artisan event:list veya php artisan queue:monitor gibi komutlar kullanılabilir.

Test ve doğrulama

opencode’a test yazdırırken çıktıyı mutlaka kendiniz çalıştırın ve hata mesajlarını ajana geri iletin. Laravel projelerinde doğrulama komutları şunlardır:

• php artisan test veya ./vendor/bin/pest — tüm testleri çalıştırır.
• php artisan migrate:fresh --seed — veritabanını temizler ve seed’ler.
• php artisan route:list — route’ları ve middleware’leri listeler.
• php artisan queue:work --once — tek bir queue job’ı çalıştırır.
• php artisan config:clear — config cache’i temizler.

Ajanın ürettiği değişiklikleri git diff ile incelemeden commit etmeyin. Özellikle migration, model, service provider ve config dosyalarında satır satır kontrol yapın. Testlerde assertDatabaseHas, assertDatabaseCount, assertJson gibi Laravel assertion’larını kullanmasını isteyin; böylece yalnızca HTTP durum kodunu değil veritabanı ve JSON yapısını da doğrular. Ayrıca feature testlerde actingAs ile kimlik doğrulaması, withHeaders ile API istekleri ve assertQueued ile queue job doğrulaması yapılmasını talep edin. Belirli bir testi çalıştırmak için php artisan test --filter=OrderControllerTest kullanın; ajan bu komutu da biliyor olabilir. Test dosyalarını tests/Feature ve tests/Unit altında doğru yere yerleştirmesini sağlayın. Başarısız testleri ajan tek başına düzeltmeye çalışırken bazen gereksiz yere test koşulunu değiştirebilir; bu yüzden testin amacını açıklayan bir yorum veya başlık eklemesini isteyin.

Birden fazla ajan: AgentVera

Laravel projelerinde opencode dışında birkaç ajanı aynı anda koşturacaksanız AgentVera işe yarar. AgentVera, opencode gibi CLI ajanlarını gerçek terminal panellerinde yan yana çalıştıran bir masaüstü uygulamasıdır. Her ajan kendi git worktree’sinde çalışabildiği için migration, test ve Blade değişiklikleri birbirinin dosyalarını ezmez. Ajan turu bitince ikinci bir model otomatik kod incelemesi yapar; bu, Eloquent N+1 veya eksik index gibi Laravel sorunlarını erken yakalar. Token bütçeleri, ajanın migration ve queue denemelerinde kontrolden çıkmasını önler.

Özet

opencode, Laravel projesinde terminalden çalışarak sıradan CRUD ve test işlerini hızlandırır; ancak sihirli kısımlarda insan doğrulaması şarttır. AGENTS.md’yi net tutun, küçük adımlarla ilerleyin, her değişiklikten sonra testleri ve diff’i çalıştırın. Migration, queue ve cache konularında ajanı yalnız bırakmayın. Böylece opencode’u Laravel iş akışınızın güvenilir bir parçası yaparsınız.