# Codex ile Node.js Projelerinde Verimli Çalışma Rehberi

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

Node.js projelerinde Codex ile pratik çalışmayı; AGENTS.md, test döngüsü, ES modules ve dikkat edilecek noktaları uygulamalı anlatıyoruz.

**Kısaca:**

- Codex Node.js projesinde terminalden codex komutuyla başlar ve AGENTS.md’deki komutları izler.
- Net komutlar, dar görevler ve her değişiklik sonrası npm test çalıştırmak ajanın Node.js hatalarını azaltır.
- Ajanı async/await, ES module import ve ortam değişkeni gibi Node.js’e özgü alanlarda dikkatle denetleyin.

Codex Node.js projelerinde terminalden `codex` komutuyla başlar; proje klasöründe çalışır ve AGENTS.md dosyasındaki talimatları okur. Bu rehber, Express/Fastify, npm scriptleri, ES modules, node:test/Jest ve ortam değişkenleriyle çalışan bir Node.js projesinde [Codex](/ajanlar/codex/) ajanını verimli kullanmayı gösterir.

## Neden Codex Node.js işleri için uygun?

Node.js projelerinde işin büyük kısmı modül sınırları, async/await akışı, hata yakalama, npm scriptleri ve test çıktıları etrafında döner. Codex bu dört unsuru aynı anda görebildiği için sıradan bir sohbet ajanından daha etkili çalışır: dosya sisteminde değişiklik yapar, terminalde `npm test` çalıştırır, çıktıyı okur ve hatayı düzeltmek için dosyaya geri döner. Express veya Fastify gibi framework’lerde route tanımları, middleware zincirleri ve şema doğrulama gibi yapılar tahmin edilebilir olduğundan ajan hızlı ve tutarlı yamalar üretir. Ayrıca package.json ve lockfile’ı okuyarak bağımlılık sürümlerini ve script adlarını doğru yorumlar; bu, Node.js’e özgü `npm run` komutlarını doğru kullanmasını sağlar.

Yine de ajan yalnızca verdiğiniz bağlam kadar iyidir. Projede custom script’ler, env değişkenleri veya test runner tercihi varsa bunları AGENTS.md’ye yazmak kritik önem taşır.

## Projeyi ajan için hazırlama ve AGENTS.md

Codex, proje kökündeki AGENTS.md dosyasını talimat kaynağı olarak okur. Bu dosya, ajanın her görevde hangi komutları kullanacağını, klasör düzenini ve Node.js’e özgü kuralları belirler. Bağlam mühendisliği yaklaşımını [Bağlam mühendisliği: yapay zeka kodlama ajanları rehberi](/blog/baglam-muhendisligi/) sayfasındaki gibi uygulayın: tek satırlık ipuçları değil, ajanın karar verirken ihtiyaç duyacağı net bilgiler verin.

Bir Node.js projesi için AGENTS.md en az şunları içermelidir: kurulum, test, lint ve build komutları; src/ ve test/ klasör yapısı; ES modules veya CommonJS tercihi; env değişkenlerinin nasıl okunacağı; logger ve hata yakalama yaklaşımı. Aşağıdaki örnek, Express + node:test kullanan bir proje için kısa ve işlevsel bir başlangıç noktasıdır:

```markdown
# AGENTS.md

## Komutlar
- Kurulum: `npm install`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Klasör yapısı
- `src/` altında modüller; `test/` altında testler
- Ortak yardımcılar `src/lib/` içinde

## Node.js kuralları
- ES modules kullan (`import`/`export`)
- Dosya I/O için yalnızca `fs/promises` API'sini kullan
- Async/await ile try/catch kullan; unhandled rejection bırakma
- Testler `node:test` ve `node:assert/strict` ile yazılır
- Her değişiklikten sonra `npm test` çalıştır
- `.env` dosyasını asla commit etme; örnek değerler `.env.example` içinde
```

Bu dosyayı proje köküne koyduktan sonra Codex yeni bir göreve başladığında hangi komutu nerede kullanacağını bilir. Özellikle `npm test` komutunun tam adını yazmak, test runner’ı yanlış tahmin etmesini önler.

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

Codex ile verimli çalışma döngüsü kısadır: plan, küçük adım, test, diff incelemesi. Ajanın bir seferde büyük bir refactor yapmasına izin vermek yerine, tek bir davranışı değiştiren ve test edilebilir görevler verin. [Codex CLI nasıl kullanılır? Adım adım rehber](/blog/codex-cli-nasil-kullanilir/) sayfasındaki adımları temel alarak şu döngüyü izleyin: önce ajanın neyi değiştireceğini yazmasını isteyin, sonra uygulamasını söyleyin, mutlaka ilgili npm scriptini çalıştırın ve `git diff` ile değişiklikleri gözden geçirin. Test başarısızsa çıktıyı ajana yapıştırıp düzeltmesini isteyin.

Aşağıdaki örnek komutlar tipik Node.js görevlerinde işe yarar:

- "Express’te `GET /users` endpoint’ine sayfalama ekle; `limit` ve `offset` değerlerini query parametrelerinden oku, yanıtı `{ data, total }` biçiminde döndür. node:test ile testini yaz ve `npm test` çalıştır."
- "Fastify projesinde yeni bir `POST /products` rotası oluştur; şema doğrulamasını ekle. Ortak hata yakalayıcıyı güncelle, sonra `npm run lint` ile kontrol et."
- "`src/services/userService.js` içindeki `createUser` fonksiyonunu async/await’e çevir; gerekli importları güncelle, ilgili testleri çalıştır."
- "Projedeki tüm `console.log` çağrılarını pino logger’ına çevir; testler başarılı kalmalı."
- "`PORT` ortam değişkeni zorunlu olsun; yoksa uygulama başlangıçta hata fırlatsın. `.env.example` dosyasını güncelle."

## Codex’in iyi yaptığı işler ve dikkat edilmesi gerekenler

Codex Node.js projelerinde route ekleme, middleware yazma, şema doğrulama, CRUD servisleri, dosya I/O dönüşümü ve bağımlılık güncelleme gibi işlerde oldukça iyidir. Ancak Node.js’e özgü birkaç alanda dikkatli olun: async/await dönüşümünde hata akışını bozabilir, ES modules importlarında dosya uzantısını atlayabilir, process.env varsayılan değerlerini yanlış kurabilir ve callback tabanlı eski kodu promise tabanlı API’ye çevirirken yarım bırakabilir.

| Görev | Dikkat edilecek nokta |
|-------|----------------------|
| Async/await dönüşümü | Unhandled rejection ve hata akışını bozma riski; tüm `try/catch` bloklarını ve testleri kontrol edin |
| ES module import düzeni | Node.js’te `import ... from './x.js'` dosya uzantısı gerektirir; eksik uzantı hata üretir |
| `process.env` kullanımı | Varsayılan değer veya erken hata koymak gerekebilir; `.env` dosyasını commit etmeyin |
| Dosya I/O işlemleri | `fs` yerine `fs/promises` kullanılmalı; büyük dosyalarda stream tercih edilmeli |
| Bağımlılık güncelleme | package-lock.json ve peer deps değişikliklerini inceleyin; `npm audit` çıktısını dikkate alın |

Bu tablo, ajanın ürettiği yamayı incelerken bakmanız gereken kritik noktaları özetler. Özellikle ilk iki satır, Node.js projelerinde en sık görülen hata kaynaklarıdır.

## Node.js’te test ve doğrulama

Codex ile çalışırken testleri yalnızca geçip geçmediğine bakmayın; ajanın test kodunu da değiştirebileceğini unutmayın. Her görev sonunda `git diff` ile üretim kodu ve test dosyaları arasındaki farkı inceleyin. `npm test` komutunu ajan çalıştırdıktan sonra kendiniz de çalıştırarak çıktıyı doğrulayın. node:test veya Jest fark etmeksizin, testlerin başarılı olması kodun doğru olduğu anlamına gelmez; ajan bazen testi geçecek ama gerçek davranışı bozan yamalar üretebilir. Bu nedenle en az bir mutlu yol ve bir hata senaryosu için elle test yapın.

Ayrıca lint çıktısını da mutlaka inceleyin. `npm run lint` ajan tarafından çalıştırıldıysa, aynı komutu kendiniz de çalıştırın. Codex bazen lint hatasını susturmak için kuralı devre dışı bırakabilir; bu kabul edilemez. Node.js’te kod kalitesini korumak için lint, test ve git diff üçlüsünü ayrı ayrı doğrulayın.

## Aynı Node.js projesinde birden fazla ajan: AgentVera

AgentVera, aynı Node.js projesinde birden fazla kodlama ajanını gerçek CLI araçlarıyla yan yana çalıştıran bir masaüstü uygulamasıdır. Node.js’te özellikle paralel çalışan ajanların ayrı git worktree’lerde çalışması dosya çakışmalarını önler; her ajan kendi dalında değişiklik yapabilir. Ajan turu bittiğinde ikinci bir model kodunuzu otomatik inceler ve bulguları dosya:satır olarak bağlar; bu, async hata yakalama veya module path hatalarını yakalamada işe yarar. Checkpoint’ler sayesinde yanlış bir refactor’ü tek tıkla geri alabilir, token bütçeleri ile test döngüsüne takılan ajanı sınırlayabilirsiniz. Daha fazlası için [AgentVera nasıl kullanılır: ilk proje, ajanlar ve ızgara](/blog/agentvera-nasil-kullanilir/) sayfasına bakın.

## Kapanış

Codex Node.js projelerinde en çok, açık komutlar, dar görevler ve hızlı test döngüsüyle değer üretir. AGENTS.md’yi net tutun, her değişiklik sonrası `npm test` ve `git diff` incelemesi yapın; ajanın üretkenliği artar ve Node.js’e özgü sürprizler azalır.

## Sık sorulanlar

**Codex Node.js projesinde nasıl başlatılır?** Proje klasöründe terminalden codex komutunu çalıştırın. Codex mevcut dizindeki AGENTS.md dosyasını okur ve verdiğiniz talimatlara göre dosyaları düzenler.

**AGENTS.md dosyasına neler yazmalıyım?** npm install, npm test, npm run lint gibi komutları; src/ ve test/ klasör yapısını; ES modules veya CommonJS tercihini; env değişkeni kurallarını yazın. Böylece ajan projeye özgü bağlamı her görevde hatırlar.

**Codex Node.js testlerini kendisi çalıştırabilir mi?** Evet, terminale npm test veya npm run test:watch gibi komutları yazabilir. Çıktıyı okuyup hatayı düzeltmeye çalışır; yine de değişiklikleri incelemeniz gerekir.

**Codex async/await hatalarını yakalayabilir mi?** Kod yazarken async/await yapısını kullanır ancak unhandled rejection veya hata akışını bozabilir. Testleri çalıştırıp diff’i inceleyerek bu riski azaltabilirsiniz.

---

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