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

Adres: https://agentvera.dev/blog/claude-code-ile-laravel/ · Yayın: 2026-11-01

Claude Code’u Laravel projelerinde migration, Eloquent, Blade ve test işlerinde verimli kullanın. CLAUDE.md, çalışma döngüsü ve paralel ajan ipuçları.

**Kısaca:**

- Claude Code, Laravel projesinde terminalden claude komutuyla çalışır ve proje dosyalarını okuyup düzenleyebilir.
- CLAUDE.md dosyasına test, lint ve Laravel kurallarını yazmak ajanın hata oranını düşürür.
- Küçük adımlar, test ve diff incelemesi ile ajanı güvenle kullanabilir; paralel işler için AgentVera worktree izolasyonu sağlar.

Claude Code, Laravel projelerinde terminalden `claude` komutuyla çalışan bir kodlama ajanıdır. [Claude Code](/ajanlar/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:

```markdown
# 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](/blog/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.

| Görev | Ajan iyi çalışır | Dikkat edilmesi gereken |
|-------|------------------|-------------------------|
| Migration ve model | Yeni tablo, kolon, cast, relation ekler | Mevcut veri ve index adları; `migrate:fresh` önerirse onaylamayın |
| Form Request | Doğrulama kurallarını koda döker, test ekler | `after` hook ve özel kural sınıflarını atlayabilir |
| Blade ve controller | Veriyi view’a taşır, döngü kurar | `@each`, `@includeWhen` gibi yapıları karıştırabilir |
| Queue ve Job | Job sınıfı, dispatch ve retry mantığı yazar | Queue connection, middleware ve failed job ayarlarını ezberden değiştirebilir |
| Test | Pest/PHPUnit testi ve factory üretir | Test izolasyonunu bozar, gerçek DB yerine yanlış trait kullanabilir |
| Eloquent scope ve query | `scopePublished`, `whereDate`, `whereBelongsTo` yazar | Raw SQL’e sapabilir; ajanı Eloquent builder ile sınırlayın |
| Event ve Listener | Event sınıfı, listener ve `ShouldQueue` ekler | `EventServiceProvider` içindeki kayıtları unutabilir, yanlış listener bağlar |

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](/blog/agentvera-nasil-kullanilir/) 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](/blog/birden-fazla-claude-code-ajani/) 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.

## Sık sorulanlar

**Claude Code Laravel projesinde nasıl başlatılır?** Proje klasöründe terminale claude yazıp enter’a basın. İlk çalıştırmada giriş yapmanızı ister; ardından ajan projeyi okur, CLAUDE.md varsa yönergeleri izler.

**Claude Code ile Laravel migration yazdırabilir miyim?** Evet. 'users tablosuna phone nullable string ekle' gibi net bir istek verin; ajan migration dosyasını oluşturur. Ancak çalıştırmadan önce dosyayı inceleyin ve php artisan migrate komutunu onaylayın.

**Claude Code Laravel testlerini çalıştırabilir mi?** Evet. composer test, vendor/bin/pest veya vendor/bin/phpunit komutunu kullanabilir. Başarısız testleri okur, hatayı düzeltip testleri yeniden çalıştırır.

**Claude Code Laravel projesinde hangi dosyaları düzenler?** Migration, model, controller, Form Request, service, test ve Blade dosyaları başta olmak üzere projede gerekli dosyaları düzenleyebilir. Yönlendirme ve config gibi kritik dosyalarda değişiklik önerdiğinde diff’i dikkatle inceleyin.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/