# opencode Node.js: Node.js Projesinde Etkili Kullanım

Adres: https://agentvera.dev/blog/opencode-ile-nodejs/ · Yayın: 2026-11-01

Node.js projelerinde opencode kodlama ajanını Express/Fastify, npm scriptleri, ES modules ve test akışlarıyla nasıl kullanacağınızı adım adım öğrenin.

**Kısaca:**

- opencode Node.js projesinde AGENTS.md kurallarını okuyarak Express/Fastify kodu yazar, testleri çalıştırır ve diff üretir.
- Node.js’e özgü tuzaklardan kaçınmak için ES modules, async/await ve npm scriptlerini AGENTS.md’de açıkça belirtin.
- Küçük görevler verip her adımda test çalıştırdığınızda opencode ile güvenilir sonuç alırsınız.

opencode Node.js projelerinde terminalden çalıştırdığınız bir kodlama ajanıdır. Proje klasöründe `opencode` komutuyla başlatılır; projenin AGENTS.md dosyasındaki talimatları okur, Node.js kodunu yazar, testleri çalıştırır ve diff üretir. Bu rehber, Express veya Fastify, npm scriptleri, ES modules ve node:test veya Jest kullanan projelerde ajandan en iyi şekilde yararlanmanızı sağlar; temel kullanım için [opencode sayfasına](/ajanlar/opencode/) bakabilirsiniz.

## Opencode Node.js işleri için neden uygundur

opencode, Node.js projesinin doğal çalışma alanı olan terminali ve package.json komutlarını kullanır; IDE bağlamına ihtiyaç duymaz. `npm test`, `npm run lint`, `npm run build` gibi scriptleri çalıştırabilir, çıktıyı okuyup hatayı düzeltebilir. ES modules ile CommonJS farkını, asenkron akışı ve Node.js standart kütüphanesini bilir; Express veya Fastify route, middleware ve validation yazarken proje stilini korur. Ayrıca AGENTS.md üzerinden belirlediğiniz Node.js kurallarına her turda sadık kalır; bu, özellikle hızlı iterasyon gerektiren API geliştirme ve refactor işlerinde işe yarar. Örneğin, `fs/promises` kullanarak dosya okuma işlemlerini asenkron hale getirmek veya Fastify şemasıyla input doğrulama eklemek gibi tekrarlayan işlerde ajan, proje bağlamını koruyarak doğru deseni üretir. Node.js’in event loop modelini bilmesi sayesinde, blocking kod yerine `async`/`await` veya `Promise` tabanlı çözümler önerir; bu da uzun vadede daha sürdürülebilir bir kod tabanı bırakır.

## Projeyi opencode için hazırlama

opencode’un Node.js projenizi doğru anlaması için kök dizine AGENTS.md ekleyin. Dosya kısa, komut ve klasör odaklı olmalı; ajanın her turda okuyacağı bağlamı netleştirir. Aşağıdaki örnek, Express veya Fastify tabanlı bir API servisi için yeterlidir:

```text
# AGENTS.md
# Bu proje Node.js 20+ ile çalışır, ES modules kullanır.

## 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, her modül kendi klasöründe
- test/: test dosyaları, *.test.js
- config/: ortam ayarları, dotenv ile yüklenir

## Kurallar
- import/export sözdizimini koru, require kullanma.
- Asenkron işlemlerde async/await kullan, callback zinciri kurma.
- Hata durumlarını try/catch ile sarmala ve anlamlı log bas.
- API yanıtlarında tutarlı { data, error } formatı kullan.
- Ortam değişkenlerine yalnızca config modülünden eriş.
- node_modules ve .env dosyalarını asla değiştirme veya commit etme.
```

Bu dosyada Node.js sürümü, modül sistemi, test komutu ve klasör kuralları açıkça belirtilir. `npm ci` kullanmak, lockfile’a bağlı kalmayı garanti eder ve ajanın gereksiz bağımlılık eklemesini engeller; `node --test` veya Jest komutunu netleştirmek doğru test çalıştırmasını sağlar. Kurallara Node.js’e özgü maddeler ekleyin: `require` kullanma, `process.exit` yerine hata döndür, `node_modules` ve `.env` dosyalarına dokunma. Ayrıca, `console.log` yerine yapılandırılmış bir logger kullanmasını, hata yanıtlarında stack trace sızdırmamasını ve `process.on('unhandledRejection')` gibi global yakalayıcılar eklemesini isteyebilirsiniz. Bu talimatlar, ajanın ürettiği kodun proje standartlarıyla uyumlu olmasını sağlar. opencode’un genel adım adım kullanımı için [opencode nasıl kullanılır rehberine](/blog/opencode-nasil-kullanilir/) göz atabilirsiniz.

## Çalışma döngüsü ve örnek komutlar

opencode ile Node.js’te verimli çalışma döngüsü şöyledir: küçük bir hedef belirle, tek bir görev ver, testleri çalıştırmasını iste, oluşan diff’i incele, sonra onayla veya düzeltme iste. Ajan her seferinde yalnızca ilgili dosyaları değiştirmeli; büyük refactorları birkaç küçük adıma bölün. Her turdan sonra `git diff` çıktısını inceleyin; beklenmedik değişiklik varsa geri alın. Aşağıdaki örnek komutlar tipik Node.js görevlerini kapsar:

- `src/routes/users.js` içindeki GET /users endpoint’ini Fastify şemasıyla yaz; test dosyasını `test/users.test.js` olarak oluştur ve `npm test` çalıştır.
- Express uygulamasına merkezi hata yakalama middleware’i ekle; route’lardaki try/catch bloklarını kaldır ve mevcut testlerin geçmesini sağla.
- `package.json` içindeki `dev` scriptini `node --watch src/server.js` olarak değiştir; `nodemon` bağımlılığını kaldır.
- Mevcut 3 senkron dosya okuma fonksiyonunu `fs/promises` ile async hale getir; ilgili testleri güncelle ve çalıştır.
- Config modülünü `dotenv` ile yeniden yaz; eksik `PORT` ve `DATABASE_URL` değişkenlerinde açıklayıcı hata fırlat.

Bu döngüde diff’i incelemek kritik; opencode bazen beklenmedik dosyaları (ör. package-lock.json) değiştirebilir. `git diff` çıktısında yalnızca hedef dosyaların değiştiğinden emin olun. Ajanın değiştirdiği her dosyayı onaylamadan önce `npm test` ve `npm run lint` komutlarının temiz geçtiğini doğrulayın. Gerekirse ajanın yaptığı değişiklikleri `git add -p` ile parça parça alın.

## Opencode’un iyi yaptığı Node.js görevleri ve dikkat edilecekler

opencode, Express veya Fastify’da CRUD route yazma, validation schema tanımlama, middleware zinciri kurma, package.json script düzenleme, node:test veya Jest ile test yazma ve senkron kodu async/await’e dönüştürme işlerinde başarılıdır. Ayrıca dotenv tabanlı config modülü oluşturma ve hata mesajlarını standartlaştırma gibi tekrarlayan işleri hızla yapar. Node.js’in `stream` API’sini kullanarak büyük dosya işleme görevleri de verilebilir; ancak backpressure yönetimi gibi ince noktaları AGENTS.md’de belirtmek gerekir.

Dikkat edilmesi gereken Node.js’e özgü tuzaklar: ES modules ile CommonJS karışıklığında ajan `import`/`require` arasında hata yapabilir; `package.json` dosyasında type: module olup olmadığını kontrol edin. Uzun süren döngülerde synchronous `fs` çağrıları event loop’u bloke edebilir. `process.exit` kullanımı test çalıştırıcılarını bozabilir. Ajan, Node.js’in daha yeni sürümlerinde eklenen `node:test`, `fetch` veya `--watch` gibi özellikleri projenizin sürümünden bağımsız önerebilir; `engines` alanını ve gerçek Node.js sürümünü netleştirin. Ayrıca `node_modules` veya `.env` dosyasına dokunmamasını AGENTS.md’de açıkça belirtin. `npm install` ile yeni paket eklediğinde lockfile’ı güncellediğinden emin olun; ajan bazen yalnızca `package.json` değiştirir ama lockfile’ı unutabilir. Child process veya `spawn` kullanan kodlarda hata yönetimini ve `stdio` ayarlarını gözden geçirin; ajan bazen basit `exec` kullanabilir. Son olarak, production ve development ortam farklılıklarını (`NODE_ENV`) ajanın dikkate almasını isteyin.

## Test ve doğrulama

Node.js projelerinde ajanın ürettiği kodu kabul etmeden önce testleri çalıştırmasını isteyin. `npm test` komutunu her değişiklikten sonra çalıştırmasını söyleyin; hata çıktısına göre düzeltme yapmasını isteyin. node:test kullanıyorsanız `node --test` çıktısındaki başarısız assertion’ları yorumlayabilir. Jest kullanıyorsanız `npm test -- --runInBand` gibi tek process çalıştırma seçenekleri daha kararlı olur. Ajanın testleri kendisinin yazmasını da isteyin; kritik route, config ve servis modülleri için en az birim testi bulunsun.

| Doğrulama adımı | opencode’a verilecek komut |
| --- | --- |
| Tek test dosyası | `npm test -- test/users.test.js` çalıştır, hataları düzelt ve tekrar çalıştır. |
| Tüm testler | `npm test` çalıştır; başarısız testleri listele ve her biri için düzeltme öner. |
| Lint kontrolü | `npm run lint` çalıştır, tüm ESLint hatalarını düzelt; kural ihlallerini açıklama. |
| Bağımlılık kontrolü | `npm ls --depth=0` çalıştır; eksik veya gereksiz bağımlılıkları raporla. |

Test çıktısında yalnızca passed değil, gerçek assertion sayısını da kontrol edin. Fastify projelerinde `app.inject()` ile HTTP isteklerini test edin; bu, gerçek ağ bağlantısı gerektirmez ve hızlı çalışır. Express uygulamalarında supertest benzeri bir çözüm kullanıyorsanız, ajanın testleri izole etmesini sağlayın: her test öncesi veritabanı durumu sıfırlanmalı, ortam değişkenleri test sonunda eski haline dönmelidir. Ajanın test dosyalarına yalnızca test kodu eklemesini, üretim kodunu test için değiştirmemesini isteyin. Coverage hedefi koymayın ancak ajanın test sonucunda eksik kalan kritik dallar için ek test önermesine izin verin.

## Birden fazla ajanı Node.js projesinde çalıştırma

AgentVera, opencode dahil birden çok kodlama ajanını kendi gerçek terminal panellerinde yan yana çalıştıran bir masaüstü uygulamasıdır. Node.js projesinde her ajanı ayrı bir git worktree üzerinde çalıştırarak `src/routes`, `src/services` veya test dosyalarını paralel değiştirebilirsiniz; böylece dosya çakışmaları oluşmaz. Her tur sonundaki otomatik kod incelemesi asenkron hata yakalama ve modül sınırı hatalarını file:line seviyesinde gösterir. Token bütçeleri sonsuz test-debug döngüsünü engeller, checkpoints ise kötü bir refactoru tek tıkla geri almanızı sağlar. Daha geniş paralel çalışma seçenekleri için [paralel kodlama ajanları sayfasına](/blog/paralel-yapay-zeka-kodlama-ajani-araclari/) bakabilirsiniz.

## Sonuç

opencode, Node.js projesiyle terminal doğal akışında çalışan, özellikle AGENTS.md kurallarını iyi uygulayan bir ajandır. Express veya Fastify API geliştirmede, test yazımında ve refactor işlerinde en iyi sonucu, küçük görevler verip her adımda testleri çalıştırdığınızda alırsınız. Kuralları netleştirin, diff’i inceleyin ve Node.js’e özgü tuzaklara karşı dikkatli olun; böylece opencode, geliştirme hızınızı belirgin şekilde artırır.

## Sık sorulanlar

**opencode Node.js projesinde nasıl başlatılır?** Proje klasöründe terminalde opencode komutunu çalıştırın. Ajana görev vermeden önce kök dizindeki AGENTS.md dosyasına Node.js komutlarını ve kurallarını ekleyin.

**opencode Express veya Fastify projelerinde test yazabilir mi?** Evet, node:test veya Jest ile test dosyaları oluşturabilir, npm test çalıştırabilir ve hataları düzeltebilir. Test komutunu AGENTS.md’de netleştirmek daha doğru sonuç verir.

**opencode CommonJS ile ES modules arasındaki farkı anlar mı?** Genel olarak anlar ancak projenin package.json dosyasında type: module olup olmadığını ve kullanılan import/export stilini AGENTS.md’de belirtmeniz gerekir. Aksi halde require/import karışıklığı yaşanabilir.

**opencode Node.js için hangi komutları çalıştırabilir?** Projenin package.json içindeki npm scriptlerini (npm test, npm run lint, npm run build, npm run dev) ve temel Node.js komutlarını çalıştırabilir. Hangi komutların çalıştırılacağını AGENTS.md’de tanımlayabilirsiniz; opencode bu tanımlı komutları kullanır.

---

**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/