Claude Code ile Laravel Geliştirme: Pratik Kılavuz

Claude Code, Laravel projelerinde terminalden claude komutuyla çalışan bir kodlama ajanıdır. Claude Code proje dosyalarınızı okur, Eloquent modelleri, migration’lar, Blade şablonları ve testleri düzenleyebilir, Artisan komutlarını çalıştırabilir. Bu rehber ajanı Laravel iş akışınıza güvenli ve verimli şekilde entegre etmenin yollarını gösterir.

Laravel iş akışında Claude Code’un gerçek avantajları

Ajanın en büyük farkı, yalnızca istenen dosyayı değil projenin tamamını bağlam olarak kullanmasıdır. Route tanımları, service provider’lar, Eloquent ilişkileri, migration geçmişi ve composer.json içindeki script’ler birbirine bağlıdır; ajan bunları birlikte değerlendirir. Örneğin Post modeline user() ilişkisi eklediğinizde ilgili migration’daki foreign key kolonunu, PostFactory içindeki user_id değerini ve PostPolicy veya testlerdeki ilişkiyi birlikte güncellemeyi hatırlar.

Claude Code aynı zamanda terminalde komut çalıştırabilir. php artisan route:list, php artisan migrate:status, php artisan test --filter=PostTest gibi komutların çıktısını okuyup bir sonraki adımı buna göre planlayabilir. Bu özellikle büyük refactor’larda işe yarar: route:list çıktısına bakarak eski controller action’larının hâlâ kullanılıp kullanılmadığını tespit edebilir, migrate:status ile pending migration’ları görür. Ajan ayrıca php artisan make:model -a gibi üretici komutları doğru bayraklarla kullanabilir; -a bayrağının migration, factory, seeder, policy ve controller ürettiğini bilir.

Laravel’in servis konteyneri ve facadeleri ajanın kod analizini zorlaştırabilir. Bu yüzden ajanın avantajı, statik analiz araçlarının sonuçlarını da okuyabilmesidir. Örneğin Larastan veya PHPStan raporundaki hataları koda uygulayabilir. Bir Eloquent modelinde eksik $fillable veya yanlış whereDate kullanımını bu şekilde yakalar. Gerçek fayda, ajanın test ve linter çıktılarını terminalden alıp otomatik düzeltmesidir.

Projeyi ajan için hazırlamak: CLAUDE.md

Claude Code proje kökündeki CLAUDE.md dosyasını talimat olarak okur. Bu dosya ne kadar net olursa ajan o kadar az yanlış varsayım yapar. Laravel projesi için komutlar, klasör kuralları ve Laravel’e özgü kısıtlar belirtilmelidir. Aşağıdaki örnek, orta ölçekli bir Laravel projesi için gerçekçi bir başlangıçtır:

# CLAUDE.md

## Komutlar
- Test: `composer test`
- Lint/format: `composer lint`
- Statik analiz: `composer analyse`
- Frontend build: `npm run build`

## Klasör kuralları
- Eloquent modelleri yalnızca `app/Models` altında tut.
- Form Request sınıfları `app/Http/Requests`, Resource'lar `app/Http/Resources`.
- İş mantığını controller içine yazma; `app/Actions` veya `app/Services` altında topla.
- Repository pattern kullanmıyorsan model bazlı scope'ları tercih et.

## Laravel'e özel kurallar
- Migration'da foreign key için `constrained()` kullan; `onDelete('cascade')` eklerken gerçekten gerekli olduğundan emin ol.
- Eloquent sorgularında N+1 kaçının; ilişkili verileri `with` veya `load` ile çek.
- Blade içinde veritabanı sorgusu yazma; veriyi controller'dan view'a geçir.
- Route model binding kullan; `findOrFail` ile elle arama yapma.
- Testlerde `RefreshDatabase` kullan; `migrate:fresh` komutunu onaysız çalıştırma.
- `.env` dosyasını değiştirme; yalnızca `.env.example` üzerinden öneri yap.
- Queue job'ları için `ShouldQueue` implementasyonunu yaz; dispatch'i controller içinde bırakabilirsin ama iş mantığını job'a taşı.

Bu dosya, ajanın test ve lint komutlarını doğru çağırmasını, dosya yerleşimini bilmesini ve tehlikeli migration komutlarından kaçınmasını sağlar. Eğer projede composer.json içinde test, lint veya analyse scriptleri tanımlı değilse önce onları ekleyin. Ajan bu komutları olduğu gibi çalıştırır; script tanımlı değilse hata verir ve görevi yarıda bırakabilir. Ayrıca CLAUDE.md içine projenin kullanmadığı kalıpları da yazın: örneğin app/Repositories yoksa repository katmanı oluşturmamasını, provider kayıtlarını manuel eklememesini isteyin. Bu tür negatif yönergeler ajanın istenmeyen dosya üretmesini engeller.

Küçük adımlarla çalışma döngüsü

Ajanı serbest bırakmak yerine her görevi küçük ve doğrulanabilir parçalara bölün. Şu döngüyü tekrarlayın: önce neyin değişeceğini yazdırın, ardından değişikliği yaptırın, testleri çalıştırın, git diff ile farkı inceleyin. Bir sonraki adımı ancak sonuç temizse verin. Claude Code plan modu bu döngünün ilk adımını otomatikleştirir; ajan kod yazmadan önce plan sunar. Planı onaylamadan elle değişiklik yapılmasına izin vermeyin.

Laravel için örnek istekler:

• posts tablosuna published_at nullable timestamp ekleyen migration’ı oluştur, Post modelinde datetime cast’ini güncelle, ilgili factory’ye değer ekle.
• PostController@store metodundaki doğrulamayı StorePostRequest Form Request sınıfına taşı; author_id alanını doğrulamadan çıkar ve oturumdaki kullanıcıdan al.
• /posts sayfasını render eden controller ve Blade dosyalarında N+1 sorgularını bul; with('author') kullanarak düzelt.
• Post modeli için published ve draft scope’larını içeren Pest testlerini yaz; eksik senaryoları kapat.
• SendWelcomeEmail job sınıfını kuyruğa dispatch eden kodu controller’dan action sınıfına taşı ve testini güncelle.

Her istekten sonra ajanın yalnızca ilgili dosyaları değiştirdiğini doğrulayın. Bir istekte migration + model + test varsa, ajan üçünü birden düzenleyebilir; bu normaldir ancak diff incelemesi şarttır. Özellikle composer.json veya config/ altındaki dosyalar değiştiyse dikkatli olun; ajan bazen php artisan optimize gibi komutları önerebilir, bunları uygulamadan önce nedenini sorgulayın.

İyi gittiği işler ve dikkat edilmesi gerekenler

Aşağıdaki tablo, Laravel’de Claude Code’un güçlü olduğu alanları ve tipik tuzakları özetler.

En sık karşılaşılan Laravel’e özgü hatalar şunlardır: ajanın app/Providers/AppServiceProvider.php gibi merkezi dosyalara gereksiz binding eklemesi, routes/web.php içine closure karmaşası yazması veya Eloquent yerine DB sorgusu önermesi. Bu tür değişiklikleri reddedin ve ajanı app/Actions veya repository katmanına yönlendirin. Ayrıca ajan test geçsin diye RefreshDatabase yerine DatabaseTransactions önerebilir; test sırasında migration’ı yenilemek istemediğiniz projelerde bu kabul edilebilir, ancak bilinçli olun. Migration’da unsignedBigInteger yerine foreignId kullanmadığında veya constrained() çağrısını atladığında SQLite testlerinde foreign key kısıtlamaları hata verebilir; ajan bazen bu hatayı görüp çözer, ancak siz diff’te kontrol edin.

Test ve doğrulama

Claude Code için en güvenilir doğrulama yolu testleri çalıştırmaktır. Ajan, composer test komutunu koşup başarısız olan testleri okuyabilir; ardından hatayı düzeltip yeniden test edebilir. Pest kullanan projelerde vendor/bin/pest --filter=PostTest gibi hedefli komutlar yazdırmak hız kazandırır. Ajan ayrıca test çıktısındaki assertion sayısını ve hata mesajlarını yorumlayabilir. Ancak yalnızca test sonucuna güvenmeyin: vendor/bin/pint --test ile kod stilini, vendor/bin/phpstan analyse ile statik hataları kontrol ettirin. Ajan bu komutları da composer.json script’leri tanımlıysa tek seferde çalıştırabilir.

Test izolasyonu konusunda ajanın seçimlerini gözden geçirin. RefreshDatabase her testte migration’ları yeniler; büyük projelerde yavaş olabilir. DatabaseTransactions ise hızlıdır ancak bazı durumlarda işlem dışına çıkan kodlarda sızıntıya neden olur. Ajan iki yaklaşım arasında geçiş yapabilir; projenizde hangisinin standart olduğunu CLAUDE.md içinde belirtin. Ayrıca factory ve seeder’ların setUp içinde çağrılmasını isteyin; her testte elle Post::factory()->create() kullanmak yerine RefreshDatabase ile birlikte $this->seed() kullanmasını söyleyin.

Birden fazla Claude Code ajanını Laravel projesinde paralel çalıştırmak

Bir Laravel projesinde migration, test ve controller işlerini eş zamanlı yürütmek istediğinizde AgentVera her ajanı kendi git worktree’sinde çalıştırır; böylece dosyalar birbirini ezmez. Ajanın işi bitince ikinci bir model kodu otomatik inceler ve Eloquent sorguları ile migration tutarlılığındaki hataları dosya:satır olarak gösterir. Checkpoint’ler sayesinde yanlış bir refactor tek tıkla geri alınır; token bütçeleri ise ajanın projeyi kontrolsüz değiştirmesini engeller. Bu yaklaşım, birden fazla Claude Code ajanını paralel çalıştırmak için özellikle Laravel modüllerini ayrıştırırken güvenlidir.

Sonuç

Claude Code, Laravel projelerinde tek başına bir yardımcı değil, proje bağlamını okuyan ve terminali kullanan bir iş ortağıdır. Önemli olan, CLAUDE.md ile sınırları çizmek, küçük adımlarla ilerlemek ve her değişikliği test ile diff üzerinden doğrulamaktır. Birden fazla işi paralel yürütmeniz gerektiğinde AgentVera gibi araçlar iş akışını güvenli hale getirir; böylece Laravel projenizde hız kazanırken kod kalitesini korursunuz.