Node.js projenizde cursor-agent komutunu çalıştırdığınızda, ajan proje bağlamını AGENTS.md veya .cursor/rules dosyalarından okur; package.json içindeki npm scriptlerini, test komutlarını ve lint kurallarını gerçek terminalde yürüterek değişiklikleri diff olarak önünüze getirir. Cursor Agent özellikle hızlı geri bildirim döngüsü olan Node.js projelerinde küçük adımlarla ilerlemek için uygundur. Bu rehber, Express veya Fastify, ES modules, node:test veya Jest ve ortam değişkenleri kullanan bir projede ajanla güvenli çalışma düzenini anlatır.
Neden Cursor Agent Node.js işlerine uygun?
Node.js projeleri genellikle tek bir package.json etrafında döner; bağımlılıklar, scriptler ve modül tipi nettir. Cursor Agent bu yapıyı doğrudan kullanır: npm install, npm run build, npm test gibi komutları çalıştırabilir, çıktıyı okuyup hataya göre kodu düzeltebilir. Express veya Fastify uygulamalarında rota tanımları, middleware zinciri ve async handler’lar küçük dosyalara bölünmüşse, ajanın yaptığı değişiklikler kolayca izlenir. ES modules ile import/export kullanımı statik analiz için daha elverişlidir; ajan dosyalar arası bağımlılıkları daha net görür. Ayrıca node:test veya Jest gibi test koşucuları terminalden hızlı sonuç verdiği için ajanın her adımda test çalıştırıp doğrulama yapması doğaldır. Bu, uzun derleme süreleri olan dillere kıyasla Cursor Agent’ın Node.js’de daha az bekleme ile daha çok döngü tamamlamasını sağlar.
Projeyi ajan için hazırlama
Ajanın ilk işi proje kurallarını okumaktır. Kök dizinde AGENTS.md veya .cursor/rules altında bir kural dosyası bulundurun. Dosyada build, test ve lint komutlarını, klasör yapısını, modül tipini (ESM/CJS), ortam değişkeni adlarını ve Node.js’e özgü yasakları net yazın. Örneğin, process.exit() kullanımını yasaklayın; ajanın sunucu sürecini öldürmesini istemezsiniz. Ayrıca node_modules ve .env dosyalarının asla diff’e girmemesi gerektiğini belirtin. Cursor CLI nasıl kullanılır? Adım adım rehber dosyasındaki temel kurulum adımları burada da geçerlidir; fark, Node.js komutlarını projeye özel yazmanızdır. Aşağıdaki örnek bir Fastify + ES modules + Jest projesi için kısa bir AGENTS.md içeriğidir.
# AGENTS.md
## Komutlar
- Kurulum: `npm ci`
- Geliştirme: `npm run dev`
- Build: `npm run build`
- Test: `npm test -- --runInBand`
- Lint: `npm run lint`
## Modül ve klasör kuralları
- ES modules kullan (`"type": "module"`).
- Kaynak kod `src/`, testler `test/`, yapılandırma `config/` altında.
- Her rota dosyası `src/routes/` içinde ayrı bir modül olsun.
- Servis katmanı `src/services/` altında, db erişimi `src/repositories/` altında.
## Node.js'e özgü kurallar
- `process.exit()` kullanma; hata fırlat veya graceful shutdown uygula.
- Async handler'larda try-catch veya Fastify'ın hata yakalama mekanizmasını kullan.
- `.env` dosyasını asla değiştirme; yalnızca `.env.example` üzerinden yeni değişken ekle.
- `node_modules` veya `package-lock.json`'u elle düzenleme; sadece `npm install <pkg>` kullan.
- Port `3000` varsayılan; çakışırsa `PORT` env değişkenini kontrol et.
- Unhandled rejection'ları logla, process'i sessizce bırakma.Çalışma döngüsü: planla, küçük adım at, testi çalıştır, diff’i incele
Ajanla çalışırken büyük bir görevi tek seferde istemek yerine plan isteyin, sonra küçük parçalar halinde ilerleyin. Her turdan sonra ajanın ürettiği diff’i inceleyin; özellikle package.json, package-lock.json ve src/ dışındaki dosyalara dikkat edin. Testlerin geçtiğini kendiniz de doğrulayın; ajanın çalıştırdığı komutların çıktısını terminalde görebilirsiniz. Aşağıdaki prompt kalıpları tipik Node.js işleri için iyi başlangıçlardır:
src/routes/users.jsiçindeki GET /users rotasını Fastify şemasıyla birlikte yaz, testinitest/users.test.jsaltına ekle venpm test -- --runInBandçalıştır.src/services/orderService.jsiçindeki async fonksiyonu hata yönetimi açısından incele; unhandled rejection riskini göster ve düzelt, sonra ilgili testi çalıştır.- Mevcut Express middleware zincirini Fastify’a taşı; önce rota listesini çıkar, sonra her rotayı sırayla dönüştür ve her adımda testleri yeşil tut.
node:testile yazılmış testleri Jest’e taşı; her test dosyası için dönüşümü yap,npm testile doğrula.config/altındaki ortam değişkeni okuma kodunudotenvkullanmadanprocess.envile yaz; eksik değişkenlerde açıklayıcı hata fırlat, test ekle.
Tipik görevler ve dikkat edilecek noktalar
Ajan şu işlerde iyi sonuç verir: CRUD route’ları, şema doğrulama, middleware sıralaması, basit servis katmanı, test yazımı, bağımlılık ekleme, hata mesajlarını iyileştirme. Aşağıdaki tablo, sık kullanılan görevler için örnek prompt ve Node.js’e özgü riskleri özetler.
| Görev | Örnek prompt | Dikkat edilecek nokta |
|---|---|---|
| Yeni rota ekleme | “Fastify’da POST /login rotasını ekle, body şemasıyla doğrula, test yaz” | Ajanın route’u yanlış plugin kapsamına koymaması; fastify.register kullanımı. |
| Async işlem | “Bu async fonksiyonu try-catch ile sar, hata durumunda 500 dön” | Unhandled rejection; event loop’u bloklayan senkron ağır işlem. |
| Paket ekleme | “zod paketini ekle, mevcut doğrulamayı zod şemasına çevir” | npm install sonrası lock dosyası değişimi; peer dependency çakışması. |
| Test yazma | “Bu handler için Jest ile unit test yaz, mock’ları ayarla” | Testin gerçek ağ veya db’ye bağlanması; --runInBand gerekebilir. |
| Config yönetimi | “Ortam değişkenlerini tek yerden oku, eksik olanlarda uyar” | .env dosyasının diff’e girmesi; production ortamında varsayılan değer. |
Ajanın zorlandığı yerler genellikle uzun süren asenkron akışlar, event emitter sızıntıları, native modül derlemeleri ve process yaşam döngüsü yönetimidir. Örneğin, bir sunucuyu app.listen ile başlatıp test bitince kapatmazsa port çakışması yaşarsınız. process.on('SIGTERM') gibi sinyal yakalayıcılar eklemesini isterken ajanın gerçekten graceful shutdown yazdığını kontrol edin. Ayrıca CommonJS ve ES modules karışımı projelerde __dirname kullanımı veya require dönüşümü hata üretebilir; bu tür değişiklikleri küçük tutun.
Test ve doğrulama
Node.js’de ajanın ürettiği her değişiklik testlerle doğrulanmalıdır. node:test kullanıyorsanız node --test komutu basittir; Jest kullanıyorsanız npm test -- --runInBand paralel testlerin dosya sistemi veya port çakışmasını önler. Ajanın test komutunu çalıştırdıktan sonra çıktıyı size özetlemesini isteyin; yalnızca ‘geçti’ demesi yeterli değildir, hangi testlerin koştuğunu ve kapsamı bilmeniz gerekir. Ajan ayrıca lint çıktısını yorumlayabilir; ESLint kurallarınızı AGENTS.md’ye yazarsanız, değişikliklerinde bu kurallara uyar. Gerekirse coverage raporu üretmesini isteyin: node --test --experimental-test-coverage veya jest --coverage. Ancak coverage’ı bir hedefe dönüştürmeyin; ajan bazen sırf satır kapsamak için anlamsız testler yazabilir. Bunun yerine kritik yolları ve hata durumlarını test etmesini isteyin.
Birden fazla ajanı Node.js projesinde çalıştırma
Birden fazla Cursor Agent örneğini aynı Node.js projesinde çalıştırmak isterseniz, her birini kendi git worktree’sinde başlatın; böylece dosya çakışmaları yaşanmaz. AgentVera, Cursor Agent dahil birden çok CLI ajanını aynı pencerede gerçek terminal panellerinde yürütür; ajan başına ve tur başına token bütçeleri uzun npm install veya test döngülerini sınırlar. Bir ajan turu bitince ikinci bir model kodu otomatik inceler ve bulguları dosya:satır olarak gösterir. Bu düzen, paralel refactor veya bağımlılık güncellemeleri gibi Node.js işlerinde riski azaltır; daha fazlası için Paralel kodlama ajanları için en iyi araçlar (2026) sayfasına bakabilirsiniz.
Sonuç
Cursor Agent, Node.js projelerinde test-güdümlü ve küçük adımlı bir çalışma düzeniyle en verimli hale gelir. Proje kurallarını AGENTS.md veya .cursor/rules içinde netleştirin, her turda diff ve test çıktısını inceleyin, async ve process yaşam döngüsü gibi Node.js’e özgü riskleri göz önünde bulundurun. Birden fazla ajan gerektiğinde git worktree ve paralel ajan yönetimi ile izolasyon sağlayın.