Cursor Agent’ı Laravel projesinde cursor-agent komutuyla başlattığınızda; Eloquent model, migration, test, Artisan command ve Blade işlerini terminal üzerinden bir ajanla yürütebilirsiniz. Bu rehber, projeyi ajan için hazırlamayı, güvenli bir çalışma döngüsünü ve Laravel’e özgü tuzakları ele alır. Daha genel terminal kullanımı için Cursor CLI nasıl kullanılır? Adım adım rehber sayfasına da bakabilirsiniz.
Cursor Agent neden Laravel projelerine uygun?
Laravel’in Artisan komutları, migration’ları ve Eloquent model kalıpları ajanın üreteceği kodu sınırlar. Ajan, php artisan test çıktısını okuyup bir sonraki küçük adımı planlayabilir; böylece uzun bir CRUD işini tek seferde değil, test edilebilir parçalara bölerek yürütür. Örneğin bir sipariş modülü eklerken önce Order modelini ve migration’ı üretir, ardından OrderController ve form request’i oluşturur, son olarak da Pest testlerini yazar. Bu yaklaşım, ajanın bağlamı korumasına yardımcı olur ve hata ayıklamayı kolaylaştırır.
Ajan ayrıca Artisan generator komutlarını doğal olarak kullanır: make:model, make:migration, make:controller, make:job gibi. Böylece dosya iskeletleri Laravel standartlarına uygun olur. Queue job’lar ve event listener’lar gibi tekrar eden yapılar da ajanın hızlı ürettiği işlerdendir. Yine de Laravel’in container, facade ve event sistemi gibi örtük davranışlarında ajanın kodunu her zaman gözden geçirmek gerekir. Cursor Agent’ın genel çalışma mantığı /ajanlar/cursor-agent/ sayfasında özetlenmiştir; burada Laravel’e odaklanıyorum.
Kurulum: AGENTS.md ve .cursor/rules
Ajan proje talimatlarını öncelikle kök dizindeki AGENTS.md veya .cursor/rules altındaki dosyalardan okur. Laravel için komutlar, klasör yapısı ve kalıpları yazın. Dosyayı kısa tutun; ajanın token kullanımını artırmadan sadece kritik kararları verin. Aşağıdaki örnek, bir Laravel projesi için başlangıç noktasıdır.
# AGENTS.md
## Komutlar
- Bağımlılıklar: `composer install`
- Test: `php artisan test`
- Lint: `vendor/bin/pint --test`
- Statik analiz: `vendor/bin/phpstan analyse --memory-limit=512M`
## Klasörler ve kurallar
- Modeller `app/Models` altında; `$fillable`, `$hidden`, `$casts` tanımla.
- Migration dosyalarını geriye dönük bozacak şekilde değiştirme; şema değişikliği için yeni migration ekle.
- Controller'lar ince olsun; doğrulama Form Request sınıflarında.
- Route isimlerini `route()` helper'ı ile kullan; route dosyalarını ayrı tut.
- Testler Pest ile `tests/Feature` ve `tests/Unit` altında; DB testlerinde `RefreshDatabase`.
- Queue job'ları `app/Jobs` altında; `ShouldQueue` kullan ve iş mantığını job içinde tut.Bu dosya ajanın her görevde başvuracağı bir sözleşme gibidir. Özellikle migration düzenleme yasağı, ajanın var olan şemayı bozmasını engeller. Route isimlendirme kuralı ise Blade şablonlarında route() helper’ının tutarlı kullanılmasını sağlar. Eğer projede farklı bir test framework’ü (PHPUnit) kullanıyorsanız komutu ona göre güncelleyin.
Çalışma döngüsü: plan, küçük adım, test, diff
Ajana görevi verirken önce plan isteyin, sonra en küçük uygulanabilir adımı yaptırın. Her adımdan sonra ilgili testi ve lint’i çalıştırmasını isteyin. git diff ile sadece amaçlanan dosyaların değiştiğini doğrulayın. Bu döngü, ajanın yanlış varsayımlarını erken yakalar.
Aşağıdaki tablo, tipik Laravel görevleri için etkili prompt örnekleri içerir.
| Tipik görev | Etkili prompt |
|---|---|
| Eloquent model ve migration | App\Models\Order modelini ve create_orders_table migration’ını oluştur. user_id, status, total_price alanları olsun; foreign key ve index ekle. Modelde $fillable ve $casts tanımla. |
| Form Request ve controller | OrderController@store metodunu StoreOrderRequest kullanacak şekilde refactor et. Doğrulama kurallarını form request’e taşı; controller sadece Order::create çağırsın. |
| Test yazımı | Pest ile Order modelinin status mutator’ı için unit test ekle. php artisan test --filter=OrderTest komutunu çalıştır ve çıktıyı göster. |
| N+1 düzeltme | OrderController@index içindeki Eloquent sorgusunu incele. Kullanıcı ilişkisini eager loading ile yükle ve testi tekrar çalıştır. |
| Artisan command | SendOrderReminders adında bir Artisan command oluştur. app/Jobs altında bir job dispatch etsin; protected $signature ve description tanımlarını unutma. |
Her prompt’tan sonra ajanın çıktısını inceleyin. Ajan bir migration oluşturduysa php artisan migrate:status ile gerçekten uygulanıp uygulanmadığını kontrol edin. Testler başarısızsa ajanın önerdiği düzeltmeyi uygulamadan önce hatanın kök nedenini anlamaya çalışın. Çünkü ajan bazen semptomu geçici olarak giderip asıl sorunu bırakabilir.
Cursor Agent ile Laravel’de iyi çalışanlar ve tuzaklar
İyi çalışanlar: model/migration ikilileri, basit Form Request dönüşümleri, Pest/PHPUnit testlerinin yazılması, route isimlendirme, Eloquent scope ve query refactor’ları. Ajanın ürettiği kod genellikle kalıplara uygundur; asıl risk Laravel’in örtük davranışlarında ortaya çıkar.
Dikkat edilecek tuzaklar:
- Migration düzenleme: Ajan var olan migration’ı değiştirebilir. AGENTS.md’de ‘yeni migration ekle’ kuralını net belirtin. Ayrıca
down()metodunun varlığını ve geri alma mantığını kontrol edin. - Facade ve container: Controller metoduna
Request $requestyerine kendi form request sınıfını enjekte etmeyi unutabilir; bağımlılıkları elleresolve()ile çözmeye çalışabilir. Bunu diff’te kontrol edin. - N+1: Ajan bazen ilişkileri lazy yükler;
with()kullanımını önerin ve testlerdeassertQueryCountgibi kontroller ekleyin. - Queue job’lar: Job sınıfının
handle()metoduna iş mantığını yazmak yerine controller içinde dispatch etmeden önce yan etkiler oluşturabilir. Job’ınShouldQueueimplementasyonunu vedispatchçağrısını doğrulayın. - Blade şablonları: Ajan bazen PHP kodu ile Blade direktiflerini karıştırır. Blade dosyalarının sunucu tarafında render edildiğini ve
@direktiflerinin korunması gerektiğini hatırlatın. Ayrıca@csrfve@methodgibi güvenlik direktiflerini atlamamasını sağlayın.
Test ve doğrulama
Ajana her görevden sonra php artisan test çalıştırmasını söyleyin; başarısız test çıktısını okuyup düzeltmesini isteyin. Pint ile kod stilini doğrulayın. Gerçek doğrulama için git diff okumak şart: sadece istenen dosyalar değişmeli, istenmeyen composer.json güncellemeleri veya debug satırları olmamalı. Özellikle migration dosyalarında down() metodunun varlığını kontrol edin. Ajanın ürettiği testleri önce kendiniz çalıştırıp manuel olarak da davranışı doğrulayın; bazen test geçse de iş kuralı yanlış olabilir.
Testleri küçük tutun ve her görevle ilişkilendirin. Örneğin Order modeli için sadece OrderTest yazın; tüm uygulamayı kapsayan entegrasyon testlerini sonraya bırakın. Ajan testi çalıştırdığında --filter kullanarak sadece ilgili testi çalıştırmasını isteyin; bu hız kazandırır. Eğer ajan testi yanlış yorumluyorsa, beklenen davranışı net bir cümleyle açıklayın.
Paralel ajanlar: AgentVera ile çalışma
Laravel projelerinde birden fazla Cursor Agent’ı aynı anda çalıştırmak isterseniz AgentVera kullanabilirsiniz; bu araç her ajanı kendi git worktree’sinde çalıştırarak dosya çakışmalarını önler. Özellikle büyük refactor’larda bir ajan migration yazarken diğeri test ekleyebilir; iş bitince birleştirirsiniz. Ayrıca bir ajanın turu bitince ikinci bir model kodu otomatik inceleyip file:line ile hataları gösterir. Token bütçeleri sayesinde ajan kontrolden çıkmadan durur. Paralel ajan kullanımı hakkında daha fazla bilgi için Paralel kodlama ajanları için en iyi araçlar (2026) sayfasına bakabilirsiniz.
Sonuç
Cursor Agent, Laravel’de tekrar eden işleri hızlandırmak için etkilidir; ancak güvenilir sonuç için net AGENTS.md talimatları, küçük adımlar, test zorunluluğu ve diff incelemesi şarttır. Paralel çalışma gerekiyorsa AgentVera gibi worktree destekli bir ortam seçin. Böylece ajan, Laravel projenizin kalitesini bozmadan üretkenliğinizi artırır.