Bir CLI kodlama ajanı, fatura gelene kadar “özgür” görünür. Claude Code veya Codex’i bir depoya yönlendirip bir modülü yeniden düzenlemesini istediğinizde, on dakika içinde kırk dosya okumuş, testleri üç kez çalıştırmış ve aslında hiç gerek olmayan bağlam için altı haneli token harcamış olabilir. Bunu gün boyu ajan kullanan sekiz kişilik bir ekiple çarptığınızda maliyet hızla büyür. İyi haber: Kodlama ajanlarında token israfının büyük kısmı, modeli değiştirmeden veya çıktı kalitesinden vazgeçmeden komut satırı alışkanlıklarıyla azaltılabilir.
TL;DR #
Ajan maliyetini düşürmek için modele gitmeden önce bağlamı küçültün:
- Çalışma kümesini dosya/dizin bazında sınırlayın.
CLAUDE.md
gibi bellek dosyalarını kısa tutun. - Uzun oturumlarda
/compact
veya/clear
kullanın. - Kararlı ön ekler için istem önbellekleme açın.
- Basit alt görevleri daha ucuz modele yönlendirin.
- Test, kurulum ve diff çıktısını filtreleyin.
- Her çalıştırmanın token ve maliyetini ölçün.
Giriş #
Sorun genelde iki şekilde görünür: Ya görev ortasında haftalık/oturum limitine çarparsınız ya da ay sonunda API faturası gelir ve “AI asistanı neden bu kadar pahalı?” sorusu sorulur.
Temel neden aynıdır: CLI ajanları varsayılan olarak çok fazla bağlam taşır. On satır koda ihtiyaç duyduklarında tüm dosyayı okurlar, her dönüşte konuşma geçmişini yeniden gönderirler, komut çıktılarını ham haliyle bağlama eklerler ve aynı sistem istemini binlerce kez tekrar yollarlar.
Bu kaçınılmaz değildir. 2.000 token’lık kod üzerinde akıl yürütmesi gereken bir refactor işleminin 180.000 token bağlama ihtiyacı yoktur. Aradaki fark sizin tasarruf alanınızdır.
Bu rehberde şu başlıkları uygulamalı olarak ele alacağız:
- CLI ajan çalışmasında token’ların nereye gittiği
- Bağlam hijyeni ve bellek dosyaları
- İstem önbellekleme
- Model yönlendirme
- Araç çıktısını ve dosya alımını kısaltma
- Çalıştırma başına maliyet ölçümü
Örnekler Claude Code ve Codex üzerinden ilerliyor, ancak aynı ilkeler token tabanlı API kullanan çoğu kodlama ajanı için geçerlidir.
Ek bir maliyet kaynağı da API hata ayıklamasıdır. Güvenilmez bir dahili API’ye bağlanan ajan, her denemede token harcar: yeniden dener, hata gövdelerini okur, belgeleri tekrar tarar ve aynı döngüye girer.
💡 Ajanlarınız API’lerle çalışıyorsa, API’leri ajana vermeden önce Apidog’da tasarlamak, mock verilerle test etmek ve sözleşmesini doğrulamak pahalı deneme-yanılma döngülerini azaltır. Ajan, sürprizlerle dolu canlı bir endpoint yerine beklenen davranışı olan bir API sözleşmesine karşı çalışır.
CLI Ajan Çalışmasında Token’lar Nereye Gider? #
Bir ajan dönüşünde modele giriş yükü gönderilir ve modelden çıktı alınır. İkisi için de ödeme yaparsınız. Çoğu sağlayıcıda çıktı token’ları, giriş token’larından daha pahalıdır.
Örnek olarak bir model ailesinde:
- Giriş: milyon token başına yaklaşık 3$
- Çıkış: milyon token başına yaklaşık 15$
- Daha küçük modelde giriş: yaklaşık 1$
- Daha küçük modelde çıkış: yaklaşık 5$
Bunları sabit fiyat olarak değil, oranları anlamak için örnek kabul edin. Güncel fiyatları her zaman sağlayıcının fiyatlandırma sayfasından kontrol edin.
Tipik bir ajan çalışmasında giriş token’larını büyüten kalemler şunlardır:
Sistem istemi ve araç tanımları: Ajan talimatları ve araç JSON şemaları. Her dönüşte tekrar gönderilir. -
Bellek/proje dosyaları:CLAUDE.md
gibi dosyalar, depo kuralları ve kalıcı talimatlar. -
**Konuşma geçmişi:**Önceki kullanıcı mesajları, model yanıtları, araç çağrıları ve araç sonuçları. -
Okunan dosya içerikleri: Ajanın açtığı kaynak dosyalar. -
Araç çıktısı: Test logları,npm install
çıktısı,git diff
, stack trace’ler.
En kritik nokta: Konuşma geçmişi her dönüşte yeniden oynatılır.
30 dönüşlük bir oturum, tek dönüşün 30 katı değildir; büyüyen bir ön ekin tekrar tekrar gönderilmesine benzer. Bu yüzden uzun ve dağınık oturumlar pahalıdır.
Oturum ve limit muhasebesi hakkında daha fazla detay için Claude Code token penceresinin nasıl sıfırlandığına dair açıklama faydalı bir tamamlayıcıdır.
1. Bağlam Hijyeni ve Bellek Dosyaları #
En ucuz token, hiç göndermediğiniz tokendir.
Çalışma kümesini baştan sınırlayın
Ajanı depo kökünde açıp şunu demeyin:
claude "fatura mantığını yeniden düzenle"
Bu, ajanın gereksiz keşif yapmasına yol açar.
Bunun yerine dosya ve kapsam belirtin:
claude "src/payments/retry.ts ve ilgili test dosyasında üstel geri çekilmeyi kullanacak şekilde yeniden deneme mantığını yeniden düzenle"
Daha iyi bir istem şunları içerir:
- Değiştirilecek dosyalar
- Değişiklik hedefi
- Test kapsamı
- Okunmaması gereken alanlar
Örnek:
claude "
Sadece şu dosyaları kullan:
- src/payments/retry.ts
- src/payments/retry.test.ts
Amaç:
Yeniden deneme mantığını üstel geri çekilme kullanacak şekilde düzenle.
Kısıtlar:
- Public API imzasını değiştirme.
- Başka dizinleri tarama.
- Sadece başarısız testleri çalıştır.
"
Bellek dosyasını kısa tutun
CLAUDE.md
veya eşdeğer proje bellek dosyası her dönüşte bağlama eklenebilir. Bu dosya büyüdükçe her ajan çağrısının sabit maliyeti artar.
Yaklaşık token sayısını kontrol edin:
wc -c CLAUDE.md | awk '{print "≈", int($1/4), "token/dönüş"}'
İyi bir CLAUDE.md
şunları içermelidir:
## Komutlar
- Test: npm test --silent
- Lint: npm run lint
- Typecheck: npm run typecheck
## Kod Kuralları
- Public API imzalarını değiştirme.
- Yeni bağımlılık eklemeden önce sor.
- Test eklemeden refactor tamamlanmış sayılmaz.
## Belgeler
- API sözleşmeleri: docs/api.md
- Ödeme akışı: docs/payments.md
Kötü örnek:
Bu proje 2021 yılında başladı...
Burada tüm mimari geçmişi...
Tüm endpoint belgeleri...
Tüm veritabanı tabloları...
Tüm onboarding notları...
Bellek dosyası wiki değildir. Sık kullanılan kuralları tutun, detaylı belgeleri linkleyin.
Uzun oturumları sıkıştırın veya temizleyin
Bir görev bittiğinde aynı konuşma içinde yeni göreve geçmeyin. Eski bağlam yeni görevin maliyetini artırır.
Claude Code’da:
/compact
Bu, geçmişi kısa bir özete dönüştürür.
Yeni ve ilgisiz bir göreve başlıyorsanız:
/clear
Basit kural:
- Aynı mantıksal görev: devam edin.
- Yeni görev:
/compact
veya/clear
.
Claude Code iş akışlarındaki desenler bu kapsam belirleme alışkanlığına dayanır.
Ignore dosyası kullanın
Ajanın şu dizinleri okumasını engelleyin:
node_modules/
dist/
build/
coverage/
.next/
.vendor/
*.lock
Ajan node_modules/
veya dist/
görmezse, bu dosyaları okuyup token harcayamaz.
2. İstem Önbellekleme: Aynı Ön Ek İçin Tekrar Ödeme Yapmayın #
İstem önbellekleme, sistem istemi, araç tanımları ve depo kuralları gibi kararlı ön eklerin sağlayıcı tarafından önbelleğe alınmasını sağlar.
Ekonomi basittir:
- İlk yazma normal girişten biraz pahalıdır.
- Sonraki okumalar yaklaşık %90 indirimlidir.
- Büyük ve sabit ön eklerde ciddi tasarruf sağlar.
Kararlı içeriği önce, değişken içeriği sonra koyun:
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=2048,
system=[
{
"type": "text",
"text": SYSTEM_PROMPT + REPO_CONVENTIONS,
"cache_control": {"type": "ephemeral"},
}
],
messages=[
{
"role": "user",
"content": user_task,
}
],
)
Kullanımı ölçün:
u = response.usage
print("önbellek yazma:", u.cache_creation_input_tokens)
print("önbellek okuma :", u.cache_read_input_tokens)
print("yeni giriş :", u.input_tokens)
Dikkat edilmesi gerekenler:
- Önbellek kesme noktasından önce değişken veri koymayın.
- Sistem istemine timestamp eklemeyin.
- Aynı işleri yakın zaman aralığında çalıştırın.
- Ön ek bayt düzeyinde kararlı olmalıdır.
Örnek senaryo:
- Sistem istemi + repo kuralları: 8.000 token
- Günlük çağrı sayısı: 60
Önbellekleme yoksa 8.000 token için 60 kez ödeme yaparsınız. Önbellekleme varsa ilk yazmadan sonra çoğu çağrı indirimli okunur.
OpenAI tarafında da desteklenen modellerde önbelleğe alınmış giriş için benzer indirimler otomatik uygulanabilir. Ayarlar değişebilir, ancak ilke aynıdır.
Codex tarafında yönlendirme ve ücretsiz katman seçenekleri için Codex aracılığıyla GPT-5.5’i ücretsiz çalıştırma rehberi bu stratejiyi tamamlar.
3. Model Yönlendirme: Basit İşe Ucuz Model #
Her görev en güçlü modeli gerektirmez.
Şunlar genellikle küçük modelle yapılabilir:
- Commit mesajı yazma
- Diff özetleme
- Changelog girdisi oluşturma
- Basit test taslağı üretme
- Değişken yeniden adlandırma
- Lint hatası açıklama
Şunlar daha güçlü model gerektirebilir:
- Mimari karar
- Karmaşık refactor
- Çok dosyalı hata ayıklama
- Performans analizi
- Güvenlik açısından kritik değişiklik
CLI’dan model seçimi:
claude --model haiku "evreye alınmış diff için conventional commit mesajı yaz"
claude --model sonnet "ödeme servisi için cache katmanını yeniden tasarla"
Varsayılan strateji:
alias ccheap='claude --model haiku'
alias cstrong='claude --model sonnet'
Kullanım:
ccheap "bu diff'i 5 maddede özetle"
cstrong "src/payments içindeki retry ve idempotency akışını analiz et"
Çoğu ekip tersini yapar: Her şeyi pahalı modelle çalıştırır ve basit işler için gereksiz ödeme yapar.
Alt-ajan destekleyen sistemlerde de aynı kural geçerlidir:
- Üst ajan: güçlü model, küçük karar sayısı
- Alt ajan: ucuz model, dar görev, kısa bağlam
Örneğin:
Alt ajan görevi:
Sadece src/payments dizininde retry ile ilgili fonksiyonları bul.
Kod değiştirme.
En fazla 10 maddelik özet döndür.
Üst ajan sadece özetlenmiş sonucu görür; tüm arama bağlamını taşımak zorunda kalmaz.
Bu yetki devri desenleri için Codex ve Claude Code’daki hedef komut rehberindeki otonom döngü örnekleri faydalıdır.
Limitli plan kullanıyorsanız model yönlendirme yalnızca maliyeti değil, hakkınızın ne kadar dayanacağını da etkiler. Claude Code haftalık limit artışı yardımcı olabilir, ancak doğru yönlendirme hâlâ kritik kaldıraçtır.
4. Araç Çıktısını Kısaltın #
Ajanın çalıştırdığı her komut metin döndürür. Bu metin bağlama eklenir ve sonraki dönüşlerde tekrar gönderilir.
Gürültülü komutlar pahalıdır:
npm test
npm install
git diff
pytest
Komutları sessiz çalıştırın
npm test
npm test --silent -- --reporter=dot
npm install
npm install --silent --no-audit --no-fund
Çıktıyı filtreleyin
pytest -q 2>&1 | tail -n 30
git diff --stat
npm test 2>&1 | grep -E "(FAIL|✗|Error)" | head -n 20
Ajan çoğu zaman tüm loga değil, şu bilgilere ihtiyaç duyar:
- Test geçti mi?
- Hangi test başarısız oldu?
- Hata mesajı nedir?
- İlgili stack trace’in son kısmı nedir?
Büyük diff’leri sınırlayın
Şunu yaptırmayın:
git diff
Önce özet alın:
git diff --stat
Sonra yalnızca ilgili dosyayı açtırın:
git diff -- src/payments/retry.ts
Kilit dosyaları özellikle tehlikelidir:
git diff -- package-lock.json
Bu çıktı binlerce satır olabilir. Ajanın genelde tamamına ihtiyacı yoktur.
5. Tüm Dosya Yerine Hedefli Okuma Kullanın #
Bir fonksiyonu değiştirmek için 1.500 satırlık dosyanın tamamını okumak israftır.
Daha iyi yaklaşım:
grep -n "function retryPayment" src/payments/retry.ts
Sonra ilgili pencereyi okuyun:
sed -n '120,220p' src/payments/retry.ts
Ajan istemine bunu açıkça yazın:
Tüm dosyayı okuma.
Önce retry mantığını grep ile bul.
Sadece ilgili fonksiyonun çevresindeki yaklaşık 100 satırı oku.
Büyük dosyalarda bu fark ciddi olabilir:
- Tüm dosya: ~18.000 token
- Hedefli pencere: ~800 token
6. RAG ve Doküman Alımını Sınırlayın #
Ajanınız kod tabanı araması veya doküman RAG kullanıyorsa, alınan parçaların sayısı ve boyutu maliyeti doğrudan etkiler.
Kötü varsayılan:
top_k = 50
chunk_size = 800
Bu, modele 40.000 token’a yakın bağlam taşıyabilir.
Daha iyi başlangıç:
top_k = 8
chunk_size = 200
Pratik kural:
- Daha az ama daha alakalı parça
- Kısa chunk
- Soruya göre filtrelenmiş dizin
- Gereksiz doküman koleksiyonlarını dışarıda bırakma
Örnek istem:
Sadece docs/payments ve src/payments altında arama yap.
Genel README, changelog ve onboarding belgelerini kullanma.
En fazla 8 kısa sonuç döndür.
7. Her Çalıştırmanın Maliyetini Ölçün #
Ölçmediğiniz maliyeti azaltamazsınız.
API yanıtındaki kullanım bilgilerini kaydedin:
u = response.usage
INPUT_RATE = 3.00 / 1_000_000
OUTPUT_RATE = 15.00 / 1_000_000
CACHE_READ = 0.30 / 1_000_000
CACHE_WRITE = 3.75 / 1_000_000
cost = (
u.input_tokens * INPUT_RATE +
u.output_tokens * OUTPUT_RATE +
u.cache_read_input_tokens * CACHE_READ +
u.cache_creation_input_tokens * CACHE_WRITE
)
print(
f"çalıştırma maliyeti ≈ ${cost:.4f} "
f"(girdi={u.input_tokens}, "
f"çıktı={u.output_tokens}, "
f"önbellek okuma={u.cache_read_input_tokens})"
)
CLI kullanıyorsanız:
claude /cost
Daha iyi izleme için ajan çağrısını küçük bir wrapper içine alın:
#!/usr/bin/env bash
TASK="$1"
START=$(date -Iseconds)
claude "$TASK"
END=$(date -Iseconds)
echo "$START,$END,$TASK" >> agent-runs.csv
Daha gelişmiş sürümde şunları da kaydedin:
- Model
- Proje
- Görev etiketi
- Giriş token
- Çıkış token
- Cache read/write token
- Yaklaşık maliyet
API anahtarlarını da ayırın:
- Proje başına anahtar
- Ajan türü başına anahtar
- Ortam başına anahtar
Böylece harcama tek bir toplamda kaybolmaz.
Taktik Karşılaştırması #
| Taktik | Tipik token tasarrufu | Çaba |
|---|---|---|
| Çalışma kümesini sınırlama | Çalıştırma başına girdide %30–60 | Düşük |
| Kısa ve kararlı bellek dosyası | Her dönüşte %5–15 | Düşük |
/compact veya /clear |
||
| Uzun oturumlarda %40–80 | Düşük | |
| İstem önbellekleme | Önbelleğe alınan ön ekte ~%90 | Orta |
| Model yönlendirme | Yönlendirilen alt görevlerde %50–80 | Orta |
| Sessiz/filtrelenmiş araç çıktısı | Araç yoğun çalıştırmalarda %20–50 | Düşük |
| Hedefli dosya okuma | Büyük dosyalarda %70–95 | Düşük |
| Kısıtlı RAG alımı | RAG yoğun ajanlarda %30–60 | Orta |
| Çalıştırma başına maliyet ölçümü | Doğrudan %0; diğerlerini mümkün kılar | Düşük |
Tasarruf oranları örnektir. Gerçek kazanç, mevcut israf seviyenize bağlıdır.
Uygulanabilir Kontrol Listesi #
Başlamak için sırayla şunları yapın:
[ ] CLAUDE.md dosyasını 1.000 token altına indir.
[ ] node_modules, dist, build, coverage ve lock dosyalarını ignore et.
[ ] Ajan istemlerinde dosya/dizin kapsamı belirt.
[ ] Test komutlarını sessiz moda al.
[ ] git diff yerine önce git diff --stat kullan.
[ ] Uzun oturumlarda /compact kullan.
[ ] Yeni görevlerde /clear ile başla.
[ ] Commit mesajı/diff özeti gibi işleri ucuz modele yönlendir.
[ ] Kararlı sistem istemi için prompt caching aç.
[ ] Her çalıştırma için token ve maliyet kaydı tut.
Sonuç #
Ajan token maliyetlerinin çoğu modelden değil, çalışma şeklinden kaynaklanır. Gereksiz bağlam, uzun konuşma geçmişi, ham araç çıktısı ve yanlış model seçimi faturayı büyütür.
Önce düşük çabalı adımları uygulayın:
- Kapsamı daraltın.
- Bellek dosyasını küçültün.
- Araç çıktısını sessizleştirin.
- Uzun oturumları temizleyin.
- Basit işleri ucuz modele taşıyın.
Ardından istem önbellekleme ve maliyet ölçümü ekleyin. Bu kombinasyon, çıktı kalitesini düşürmeden ajan maliyetlerini yönetilebilir hale getirir.