Claude Code, Node.js projesinin kök dizininde claude komutuyla açılan ve terminal üzerinden dosya okuyup düzenleyen bir kodlama ajanıdır. Node.js tarafında asıl farkı, package.json script’lerini, test koşucusunu ve linter’ı doğrudan çalıştırıp çıktıya göre kodu düzeltmesidir. Bu rehberde Express veya Fastify, ES modules, node:test veya Jest kullanan bir proje için somut bir çalışma düzeni kuruyoruz. Daha genel başlangıç için Claude Code ve Claude Code nasıl kullanılır? sayfalarına bakılabilir.
Claude Code Node.js işine neden uygun?
Node.js projelerinde geliştirme döngüsü büyük ölçüde komut satırında geçer: npm install, npm test, npm run lint, npm run dev. Claude Code bu komutları aynı terminal oturumunda çalıştırıp çıktıyı okuyabilir; böylece hata mesajını görüp dosyayı düzeltme döngüsünü tek başına tamamlayabilir. JavaScript ve TypeScript dosyalarını parse edebildiği için import yollarını, modül çözümlemesini ve async/await hatalarını hızlı analiz eder. Özellikle Express route’ları, Fastify plugin yapısı, process.env erişimi ve package.json script düzenlemeleri üzerinde iyi çalışır.
Node.js çalışma zamanı davranışları ise ayrı bir doğrulama gerektirir. Event loop, stream backpressure, child process ve native modül konularında ajanın önerisi mantıklı görünse bile Node sürümüne ve işletim sistemine göre sonuç değişebilir. Bu yüzden ajanı “komut çalıştırıp çıktıyı okuyan” bir yardımcı olarak konumlandırmak en verimlisidir.
Proje nasıl hazırlanır ve CLAUDE.md’ye ne yazılır?
Claude Code, proje kökündeki CLAUDE.md dosyasını otomatik okur. Node.js projesi için bu dosya kısa tutulmalı ve ajanın en çok ihtiyaç duyduğu komutlar ile kuralları içermelidir. Gizli anahtar, veritabanı şifresi veya .env içeriği bu dosyaya yazılmaz.
Gerçekçi bir örnek:
# CLAUDE.md
## Komutlar
- Kurulum: `npm ci`
- Geliştirme: `npm run dev`
- Test: `npm test` (node --test)
- Lint: `npm run lint` (eslint .)
- Build: `npm run build`
## Klasörler
- `src/` kaynak kod; bu klasör dışında yeni dosya oluşturma.
- `src/routes/` Express route tanımları.
- `src/plugins/` Fastify plugin kayıtları.
- `test/` test dosyaları; adlandırma `*.test.js`.
## Kurallar
- ES modules kullan (`import`/`export`); CommonJS (`require`) ekleme.
- `process.env` erişimi yalnızca `src/config.js` içinde olsun.
- Asenkron route handler'larda her zaman try/catch veya sarmalayıcı kullan.
- Bağımlılık eklerken `npm install <paket>` çalıştır; `package.json`'ı elle düzenleme.
- Node sürümünü `engines` alanıyla koru; uyumsuz syntax önerme.Bu dosyayı güncelledikçe ajan da güncel kurallara göre davranır. Çok uzun tutmak ters etki yapar; önemli olan build, test ve lint komutlarının net olmasıdır. Ayrıca node_modules ve .env dosyalarını .gitignore’da tutmak, ajanın bu dosyaları okumaya çalışmasını engeller.
Çalışma döngüsü ve örnek komutlar
Node.js projelerinde ajanla güvenli döngü şudur: önce küçük bir plan isteyin, sonra tek bir dosyada veya tek bir test kapsamında değişiklik yaptırın, ardından test ve lint çıktısını birlikte yorumlatın, son olarak git diff ile değişikliği inceleyin. Claude Code plan modu bu döngünün ilk adımını disipline eder; önce dokunulacak dosyaları ve testleri netleştirmek boşa giden komut çalıştırmayı azaltır.
Örnek komutlar:
- “
npm test’i çalıştır; kırmızı testleri listele ve her seferinde tek testi geçecek şekilde kodu düzelt.” - “Express uygulamasına
GET /users/:idrotasını ekle; kodusrc/routes/users.jsiçine yaz,node --test test/users.test.jsile doğrula.” - “Bu Fastify plugin’ini
src/plugins/db.jsiçine taşı ve tüm import yollarını güncelle; ardından lint ve testleri çalıştır.” - “
src/config.jsiçindeki env erişimini şemaya bağla; eksik değişkenlerde uygulama başlangıcında hata fırlat.” - “Şu async fonksiyondaki olası race condition’ı bul; düzeltmeyi ayrı bir commit için diff olarak göster, ilgili testi çalıştır.”
Her komuttan sonra ajanın test çıktısını gerçekten okuduğundan emin olun; test geçmiyorsa döngüyü kırmadan önce hata mesajını ve git diff --stat çıktısını birlikte isteyin.
Node.js projelerinde iyi olduğu işler ve dikkat edilecek yerler
Aşağıdaki tablo, Node.js’e özgü tipik işleri ve riskli alanları özetler.
| İş | İyi olduğu durum | Dikkat edilecek yer |
|---|---|---|
| Route ekleme/düzenleme | Express ve Fastify route tanımlarını hızlı yazar, parametre doğrulama önerir. | Mevcut middleware zincirini bozabilir; yetkilendirme sırasını kontrol edin. |
| Env ve config yönetimi | process.env erişimini tek dosyada toplar, varsayılan değer ekler. | Eksik değişkenlerde sessizce geçebilir; hata fırlatmasını isteyin. |
| Test yazma ve düzeltme | node:test veya Jest ile test ekler, kırmızı testleri adım adım geçirir. | Mock’ları yanlış kurarak testi geçirip gerçek hatayı gizleyebilir. |
| Async/await hataları | Unhandled rejection ve callback cehennemi dönüşümlerinde yardımcı olur. | Event loop’ta uzun süren işlemleri gözden kaçırabilir; timeout ekleyin. |
| package.json script’leri | dev, test, lint script’lerini düzenler, eksik bağımlılığı önerir. | npm install olmadan script çalıştırabilir; bağımlılık eklerken paketi kurmasını isteyin. |
Claude Code, sözdizimi hatası, import yolu yanlışı ve basit test beklentilerini düzeltmede güvenilirdir. Ancak Node.js’e özgü davranışlarda (stream backpressure, event loop tıkanması, cluster/fork, native addon) her zaman çıktıyı ve gerçek çalışma zamanını siz doğrulamalısınız. Özellikle process ortamı, dosya izinleri ve farklı işletim sistemlerinde değişen davranışlar, ajanın önerdiği kodda beklenmeyen sonuçlara yol açabilir.
Node.js ile test ve doğrulama nasıl yapılır?
Ajanın ürettiği her değişiklikten sonra test komutunu çalıştırmak şarttır. node --test kullanıyorsanız ajanı “test dosyalarını test/ altında bul, npm test çalıştır ve başarısız olanları listele” diye yönlendirin. Jest kullanıyorsanız jest --runInBand veya jest --watchAll=false gibi CI dostu seçenekler, ajanın terminalde takılmasını önler. Lint ve format kontrolü için npm run lint sonrası çıkan hataları da düzeltmesini isteyin.
Gerçek doğrulama için ajanın test geçtikten sonra git diff çıktısını incelemesini sağlayın; böylece yanlışlıkla silinen import veya değişen env erişimi yakalanır. Ayrıca node --check ile syntax doğrulaması yaptırmak, büyük refactor’lerde hızlı bir ön kontrol sağlar. Testler geçse bile uygulamayı npm run dev ile kısa süre çalıştırıp birkaç istek atmak, runtime hatalarını ortaya çıkarır.
Birden fazla Node.js ajanını aynı projede çalıştırmak
Aynı Node.js projesinde birden çok Claude Code örneği çalıştırmak istediğinizde AgentVera işe yarar. AgentVera, her ajanı kendi gerçek terminal panelinde çalıştırır ve git worktree desteği sayesinde ajanlar birbirinin dosyalarını ezmez. Node.js projelerinde paralel çalışma özellikle ön uç ve API ayrımı, ayrı modül refactor’leri veya farklı test dosyalarının düzeltilmesi için uygundur. Checkpoint ve token bütçesi özellikleri, uzun süren ajan oturumlarında kontrolü elde tutmanızı sağlar. Bu sayede bir ajan route eklerken diğeri test yazabilir; çakışma riski worktree ile minimuma iner.
Kapanış
Claude Code, Node.js projelerinde komut çalıştırma ve dosya düzenleme döngüsünü önemli ölçüde hızlandırır. Başarı, iyi tanımlanmış bir CLAUDE.md, küçük adımlı talimatlar ve her değişiklikten sonra test/lint doğrulamasına bağlıdır. Ajanı Node.js runtime’ın karmaşık alanlarında tek başına karar verici olarak görmek yerine, test çıktılarını okuyan ve diff sunan bir çift geliştirici gibi konumlandırın.