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 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 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:
# 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çindeBu 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 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 /usersendpoint’ine sayfalama ekle;limitveoffsetdeğerlerini query parametrelerinden oku, yanıtı{ data, total }biçiminde döndür. node:test ile testini yaz venpm testçalıştır.” - “Fastify projesinde yeni bir
POST /productsrotası oluştur; şema doğrulamasını ekle. Ortak hata yakalayıcıyı güncelle, sonranpm run lintile kontrol et.” - “
src/services/userService.jsiçindekicreateUserfonksiyonunu 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ı.” - “
PORTortam değişkeni zorunlu olsun; yoksa uygulama başlangıçta hata fırlatsın..env.exampledosyası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 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.