# Gemini CLI ile Node.js projelerinde verimli kodlama

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

Gemini CLI’yı Node.js projelerinde nasıl kullanacağınızı öğrenin: GEMINI.md kurulumu, Express/Fastify için çalışma döngüsü, test ve doğrulama ipuçları.

**Kısaca:**

- Gemini CLI, Node.js projelerinde GEMINI.md talimatlarıyla test ve lint komutlarını kullanarak küçük adımlarla çalışır.
- Express, Fastify, Jest veya node:test ile terminal üzerinden doğrudan kod üretip doğrulayabilirsiniz.
- Ajanın diff’lerini gözden geçirmek ve testleri çalıştırmak, Node.js’e özgü sürprizleri azaltır.

Gemini CLI, Node.js projelerinde terminal üzerinden çalışan bir kodlama ajanıdır; proje klasöründe `gemini` komutunu çalıştırarak başlatırsınız. Ajan, proje kökündeki GEMINI.md dosyasını okuyarak build, test ve lint komutlarınızı öğrenir ve bu komutları doğrulama için kullanır. Express, Fastify, ES modules ve npm scriptleriyle çalışırken ajanı etkili yönetmenin yollarını aşağıda bulacaksınız.

## Gemini CLI Node.js işleri için neden uygun
Node.js projelerinin çoğu benzer bir ritüele sahiptir: package.json’daki scriptler, node_modules, test koşuları ve lint. Gemini CLI bu ritüeli doğrudan yürütebilir; `npm install`, `npm test`, `npm run lint` gibi komutları çalıştırıp çıktıyı yorumlayabilir. Express middleware zinciri, Fastify plugin kaydı, async route handler’ları ve stream’ler gibi Node.js’e özgü desenleri tanır. Bu sayede sıfırdan açıklama yapmadan mevcut kod tabanınız üzerinde değişiklik önerebilir.

Ayrıca Node.js’in modüler yapısı ajan için avantajdır: her dosya bağımsız bir birimdir ve değişikliklerin etkisini tahmin etmek kolaydır. `package.json` içindeki `"type": "module"` alanını görünce import/export kullanacağını bilir, CommonJS karışıklığına düşmez. Geliştirme sunucusunu `npm run dev` ile ayağa kaldırıp hızlıca endpoint denemesi yapabilir. Önemli olan ajanı serbest bırakmak değil, ona doğrulanabilir küçük adımlar vermektir; çünkü Node.js’te hatalar genellikle runtime’da ortaya çıkar ve test komutu en güvenilir geri bildirimdir.

## Projeyi ajan için hazırlama ve GEMINI.md
GEMINI.md dosyasını proje köküne koyun; ajan her oturumda bu dosyayı okur. Dosyada Node.js sürümü, paket yöneticisi, klasör kuralları ve çalıştırma komutları net olsun. Çok uzun tutmayın; ajanın her adımda uyması gereken 7-10 madde yeterlidir. Aşağıdaki örnek Express tabanlı, ES modules kullanan ve node:test ile test edilen bir projeye uygundur:

```markdown
# GEMINI.md

## Komutlar
- Kurulum: `npm install`
- Test: `npm test` (node --test)
- Lint: `npm run lint`
- Build: `npm run build`
- Geliştirme: `npm run dev`

## Kurallar
- Node.js 20+ kullan; `"type": "module"` olmalı.
- Yeni route dosyalarını `src/routes/`, servisleri `src/services/`, testleri `test/` altına ekle.
- Ortam değişkenlerini yalnızca `src/config.js` içinde oku; route veya service içinde `process.env` kullanma.
- Her yeni endpoint için en az bir test yaz.
- Bağımlılık eklerken `npm install <paket>` komutunu kullan ve `npm run lint` ile bitir.
- Hata yakalama için async route'larda try/catch veya wrapper kullan; hataları yutma.
```

Bu dosya ajanın Node.js projenizi anlamasını hızlandırır. Özellikle "test" ve "lint" komutlarının belirtilmesi, ajanın her değişiklikten sonra otomatik doğrulama yapmasını sağlar; siz söylemeseniz bile bu komutları çalıştırma eğiliminde olur. Ortam değişkenlerini merkezi bir config dosyasına yönlendirmek, ajanın `process.env` kullanımını disipline eder ve production/development farklarını netleştirir. Genel Gemini CLI kurulumu için [Gemini CLI](/ajanlar/gemini-cli/) sayfasına bakabilirsiniz.

## Ç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 hedef vermek yerine döngüyü siz yönetin. Önce mevcut kodu incelemesini isteyin, sonra tek bir değişiklik yapmasını söyleyin, ardından testi çalıştırın ve diff’i gözden geçirin. Ajan her adımda `git diff` veya doğrudan dosya içeriğini gösterebilir; değişiklikleri commit’lemeden önce mutlaka kendiniz okuyun.

Node.js projelerinde şu döngüyü uygulayın:
1. Ajanın ilgili dosyaları okumasını ve mevcut davranışı özetlemesini isteyin.
2. Tek bir görev tanımlayın; örneğin "şu endpoint için validation ekle" gibi.
3. Görevi tamamladıktan sonra `npm test` çalıştırmasını isteyin.
4. Test geçerse `npm run lint` ile stil kontrolü yaptırın.
5. `git diff` çıktısını inceleyin, anlamadığınız her satırı ajanla tartışın.

Node.js için kullanabileceğiniz örnek istemler:

- "Mevcut Express uygulamasındaki tüm route’ları listele ve hata yönetimi eksik olanları işaretle; önce plan çıkar, kod değiştirme."
- "`POST /api/orders` için Fastify’da zod şemasıyla request doğrulaması ekle; yeni route’u `src/routes/orders.js` dosyasına yaz ve `test/orders.test.js` testini oluştur."
- "`npm test` başarısız olan 3 testi sırayla düzelt; her düzeltmeden sonra sadece ilgili test dosyasını çalıştır ve sonucu göster."
- "Şu diff’i incele: `src/services/userService.js` içinde hangi davranışlar değişti? Yan etki riski var mı?"
- "`npm outdated` çıktısına göre yalnızca güvenli yamaları uygula, sonra `npm test` ve `npm run lint` çalıştır."

Bu istemler ajanın kapsamını daraltır ve Node.js runtime hatalarını erken yakalamanızı sağlar. Ajanın verdiği cevaplarda "test geçti" ifadesine güvenmeyin; gerçek çıktıyı terminalden kontrol edin veya isterseniz `npm test -- --reporter=verbose` gibi ek parametrelerle çalıştırmasını isteyin.

## Node.js’te iyi çalıştığı işler ve dikkat edilecek yerler
Ajan; route ekleme, middleware yazma, validation şeması oluşturma, servis katmanını refactor etme ve test yazma işlerinde oldukça iyidir. Ancak Node.js’in dinamik doğası nedeniyle bazı yerlerde sıkı takip gerekir: async hata yakalama, unhandled rejection’lar, `process.exit` kullanımı, `package-lock.json` değişiklikleri ve CommonJS/ESM karışıklığı.

Özellikle async route’larda try/catch unutulması en sık karşılaşılan hatadır; ajan bazen error middleware’e güvenir ama Express’te async hatalar otomatik yakalanmaz. `package-lock.json` üzerinde gereksiz değişiklik yapabilir veya yanlış bağımlılık ekleyebilir; her `npm install` sonrası diff’i inceleyin. Ayrıca Node.js sürümüne özgü API’ler (ör. `fs/promises`, `node:test`) konusunda bazen eski alışkanlıklara dönebilir; GEMINI.md içinde hedef Node sürümünü belirtmek bu riski azaltır.

Aşağıdaki tablo sık yapılan görevler için iyi bir istem örneği ve izlemeniz gereken noktayı gösterir:

| Görev | İyi istem | Dikkat edilecek yer |
|-------|-----------|---------------------|
| Yeni route | "Express’te `GET /api/users/:id` route’unu ekle, hata durumunda 404 döndür." | Async handler’da try/catch unutulabilir; hata middleware’ine düşmeyebilir. |
| Test yazma | "Bu servis için node:test ile birim testi yaz, mock kullanma." | Testlerde ağ çağrısı gerçekten yapılırsa yavaş ve kırılgan olur. |
| Bağımlılık ekleme | "`zod` paketini ekle ve schema tanımını `src/schemas/` altına koy." | `npm install` sonrası package-lock.json değişikliğini incele; gereksiz paket eklenmesin. |
| Refactor | "Callback tabanlı `fs` okuma kodunu `fs/promises` ile async/await’e çevir." | Hata mesajları ve akış davranışı değişebilir; `process.exit` eklenmesin. |

Ayrıca ajan bazen Node.js sürüm farklarını göz ardı edebilir; örneğin `node:test` yerine Jest varsayabilir. GEMINI.md içinde test komutunu net belirtmek bu riski azaltır. Terminal ajanı seçimi konusunda kararsızsanız [Gemini CLI nedir? Gemini CLI mı Claude Code mu?](/blog/gemini-cli-mi-claude-code-mu/) yazısı fikir verebilir.

## Node.js’te test ve doğrulama
Ajanın ürettiği kodu asla test etmeden kabul etmeyin. Node.js’te test komutu genellikle `node --test` veya `npm test` olur; ajanın bu komutu kendisinin çalıştırmasını isteyin. Test çıktısındaki başarısızlıkları okumasını ve düzeltmesini söyleyin; böylece döngü kısa kalır.

Test yazarken şu yaklaşımı deneyin: önce ajanın başarısız olacak testleri yazmasını isteyin, sonra bu testleri geçecek kodu üretmesini söyleyin. Örneğin "`GET /api/users` endpoint’i için supertest ile iki test yaz: biri 200 döndürmeli, diğeri boş veri için 204 döndürmeli. Şimdilik route yok, testler fail olacak." Bu yöntem, ajanın ürettiği kodun doğruluğunu artırır.

Doğrulama için şu sırayı kullanın:
1. Değişiklikten sonra `npm test` çalıştırın.
2. Lint için `npm run lint` çalıştırın; Node.js stil hatalarını gösterir.
3. Build adımı varsa `npm run build` ile derleme veya syntax hatası olmadığını kontrol edin.
4. Ajanın değiştirdiği dosyaları `git diff` ile inceleyin; test kapsamına girmeyen yan etki var mı bakın.

Node.js’te testlerin yanı sıra `npm run dev` ile uygulamayı kısa süre ayağa kaldırıp elle bir istek atmak da faydalıdır. Ajan `curl` komutunu çalıştırabiliyorsa `curl -X POST localhost:3000/api/orders` gibi bir istekle endpoint’i sınayabilir. Yine de asıl güvence, otomatik testlerin geçmesidir. Jest kullanıyorsanız ajanın `jest --watch` gibi etkileşimli modları çalıştırmasını engelleyin; `--watchAll=false` veya `CI=true` ortam değişkeni ile non-interactive kalmasını sağlayın.

## Paralel ajanlarla Node.js projesi yönetme
Node.js projesinde birden fazla ajanı paralel çalıştırmak için AgentVera kullanabilirsiniz. Her ajan kendi git worktree’sinde çalıştığı için birisi `src/routes/orders.js` üzerinde değişiklik yaparken diğeri `src/services/userService.js` üzerinde bağımsız ilerler, dosyalar çakışmaz. Ajanın sırası bittiğinde ikinci bir model kodu otomatik inceler; bulgular `file:line` olarak bağlanır ve async hata yönetimi gibi Node.js’e özgü sorunları yakalar. Checkpoint’ler sayesinde yanlış bir refactor tek tıkla geri alınabilir, Flows ile bir ajanın çıktısı diğerine aktarılır. Ajan ekibi kurulumu hakkında daha fazlası [Yapay zeka ajan ekibi: yönetici, roller ve iş teslimi](/blog/yapay-zeka-ajan-ekibi/) sayfasında.

## Sonuç
Gemini CLI, Node.js projelerinde GEMINI.md ile yönlendirildiğinde test ve lint komutlarını kullanarak güvenilir bir çift pilot olur. Önemli olan büyük hedefler vermek değil; planlatmak, küçük adımlar attırmak ve her adımda doğrulama yapmaktır. Böylece Express veya Fastify uygulamanızda hızlı ilerlerken runtime sürprizlerini minimumda tutarsınız.

## Sık sorulanlar

**Gemini CLI Node.js projesinde nasıl başlatılır?** Proje klasöründe terminalde gemini komutunu çalıştırın. GEMINI.md dosyasına build, test ve lint komutlarını yazarsanız ajan bu komutları kullanır.

**Gemini CLI Node.js için GEMINI.md nasıl olmalı?** Kısa ve net olmalı; Node sürümü, paket yöneticisi, klasör yapısı, çalıştırma komutları ve dikkat edilecek kurallar bulunmalı. Örnekte olduğu gibi test ve lint komutlarını ekleyin.

**Gemini CLI Node.js testlerini kendisi çalıştırır mı?** Evet, siz GEMINI.md veya istemde belirtirseniz ajan npm test gibi komutları çalıştırabilir. Sonuçları yorumlayıp hataları düzeltebilir.

**Gemini CLI ile Express ya da Fastify projesi düzenlenebilir mi?** Evet, mevcut yapıyı inceler, yeni route, middleware veya servis ekleyebilir. Doğrulama için testleri çalıştırmasını isteyin.

---

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