Agent Sistem Prompt'ları Yazmak İçin Kapsamlı Rehber — Claude Code Tersine Mühendisliğinden Dersler

Claude Code'un system prompt'unu decompile ettim, DeepAgents'in kaynak kodunu inceledim ve sıfırdan kendi AI agent'ımı geliştirdim. Çoğu prompt rehberi sadece laf kalabalığından ibaret.

Şu anda yapay zeka dünyasında kitlesel bir yanılgı yaşanıyor.

Her eğitim size sistem prompt'larını sanki bir büyü yapıyormuşsunuz gibi yazmanızı söylüyor — doğru sihirli sözcükleri bulduğunuzda model size itaat edecektir. "Sen 20 yıllık deneyime sahip, SON DERECE YETENEKLİ bir senior mühendissin..." Tanıdık geldi mi?

Geçtiğimiz birkaç ayı, derinlemesine pazar araştırması yapan ve VC düzeyinde analizler üreten bir yapay zeka startup danışmanı olan VibeCom'u inşa ederek geçirdim. Bu süreçte Claude Code'un sistem prompt'unu tersine mühendislikle inceledim, DeepAgents'ın middleware kaynak kodlarını okudum ve itiraf etmek istemeyeceğim kadar çok API kredisi yaktım. Çıkardığım en büyük ders ne mi oldu? İnsanların sistem prompt'ları hakkında önemli olduğunu düşündüğü şeylerin çoğu aslında önemsiz. Ve gerçekten önemli olan şeyleri ise neredeyse kimse konuşmuyor.

Bu yazı eksiksiz bir başucu rehberi — 5 dakikalık yüzeysel bir özet değil, bu işe başlamadan önce birinin bana söylemiş olmasını dilediğim her şey. Kahvenizi alın.

1. Tasarım Felsefesi: Modele Güvenin

"An agent is a model. Not a framework. Not a prompt chain." — shareAI-lab/learn-claude-code

Bu fikir benim için her şeyi değiştirdi. LLM zaten nasıl akıl yürüteceğini, plan yapacağını ve uygulayacağını biliyor. Sistem prompt'unuz ona düşünmeyi öğretmiyor — sadece içinde çalışacağı ortamı hazırlıyor.

Bunu kıdemli (senior) bir mühendisi işe almak gibi düşünün. Onlara her görev için 20 adımlık bir kontrol listesi vermezsiniz. Onlara şunu söylersiniz: Biz buyuz, sınırlarımız bunlar, iyi bir işin tanımı budur. Sonra da yollarından çekilirsiniz.

Sistem prompt'unuzun tam olarak dört görevi vardır:

Ona kim olduğunu söylemek — rol ve kimlik
Duvarların nerede olduğunu söylemek — güvenlik sınırları
İyinin neye benzediğini söylemek — kalite standartları
Ona araçlar (tools) vermek — yetenekler ve bilgi

Hepsi bu. Geri kalan her şey gürültüden ibaret.

Harness (Altyapı) Zihniyeti

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

Sistem prompt'unuz bu altyapının kullanım kılavuzudur. Katı bir boru hattı (pipeline) tasarlamıyorsunuz — modelin otonom olarak en iyi işini çıkarabileceği bir ortam tasarlıyorsunuz.

Sistem prompt'unuzu bir akış şeması gibi yazmayın. Model, yürütme sırasına kendisi karar verecektir.

2. Prompt Yapısı ve Bölüm Sıralaması

Önerilen Düzen (Claude Code v2.0.14'ten Tersine Mühendislikle Çıkarılmıştır)

┌─────────────────────────────────────────────┐
│ 1. Identity                                  │  ← Read first, anchors behavior
│ 2. Security & Safety                         │  ← IMPORTANT markers, non-negotiable
│ 3. Tone & Style                              │  ← Controls output format
│ 4. Core Workflow                             │  ← How to do the work
│ 5. Tool Usage Policy                         │  ← Tool selection priorities
│ 6. Domain Knowledge                          │  ← On-demand, not pre-loaded
│ 7. Environment Info                          │  ← Runtime context, dynamically injected
│ 8. Reminders                                 │  ← Re-state critical rules
├─────────────────────────────────────────────┤
│ [Tool Definitions — system-injected]         │  ← Not editable, usually very long
├─────────────────────────────────────────────┤
│ [User Message]                               │
└─────────────────────────────────────────────┘

Bu Sıralama Neden Önemli?

LLM'lerin U şeklinde bir dikkat eğrisi vardır — prompt'unuzun en başına ve en sonuna en çok dikkati verirler, ortalarda ise odaklarını kaybederler. Bu, literatürde iyi bilinen "Ortada Kaybolma" (Lost in the Middle) etkisidir.

Kimlik + Güvenlik en üstte: Model önce rolünü ve sınırlarını belirler (öncelik etkisi / primacy effect).
Temel İş Akışı (Core Workflow) üst-orta kısımda: En önemli bölümünüz — agent'ın işini nasıl yapacağı.
Tool Tanımları prompt'unuzdan sonra sistem tarafından enjekte edilir: Claude Code'un tool tanımları yaklaşık 11.438 token tüketir. Bu, yazdığınız özel içeriğin aslında beklediğinizden çok daha başlarda yer aldığı anlamına gelir — ki bu da kurallara uyumu (adherence) artırır.
Hatırlatıcılar en altta: Kritik kuralları pekiştirmek için yakınlık önyargısından (recency bias) yararlanın.

3. Her Bir Bölümü Yazmak

3.1 Identity (Kimlik) — Bu Agent Kim?

Hedef: Modelin rolünü 1-3 cümleyle sabitlemek.

You are Claude Code, Anthropic's official CLI for Claude.
You are an interactive agent that helps users with software engineering tasks.

Kurallar:

Kısa tutun — maksimum 1-3 cümle.
Rolü açıkça adlandırın (modelin bağlamları ayırt etmesine yardımcı olur).
Belirsiz bir "sen yardımsever bir asistansın" yerine temel sorumluluğu belirtin ("X konusunda yardımcı olur").
Varsa SDK/platformdan bahsedin ("Anthropic'in Claude Agent SDK'sı üzerine inşa edilmiştir").

Anti-pattern'ler:

"Sen yardımsever, zararsız ve dürüst bir yapay zeka asistanısın" — çok jenerik, rolü sabitlemiyor.
Tam bir paragraf dolusu arka plan hikayesi — token israfı, modelin karakter gelişimine ihtiyacı yok.

3.2 Security & Safety (Güvenlik) — Kesin Sınırlar

Hedef: İhlal edilemez davranışsal kısıtlamalar belirlemek.

IMPORTANT: Assist with defensive security tasks only.
Refuse to create, modify, or improve code that may be used maliciously.
IMPORTANT: You must NEVER generate or guess URLs for the user.

Kurallar:

IMPORTANT: önekini kullanın — Claude'un talimat hiyerarşisi eğitimi buna ekstra ağırlık verir.
Kesin bir dil kullanın: NEVER, MUST NOT, Refuse to.
Hem neye izin verildiğini HEM DE neyin yasaklandığını belirtin (çift yönlü kısıtlamalar daha nettir).
Ortaya gömmeyin, en üste yerleştirin.
Kritik güvenlik kurallarını en sonda tekrarlayın — Claude Code tam olarak bunu yapıyor.

Neden tekrarlamalıyız? Öncelik etkisi (başlangıç) + Yakınlık etkisi (son) = çifte pekiştirme. Claude Code'un güvenlik bildirimi prompt'un hem başında hem de sonunda yer alır. Mühendisler unutkan olduğu için değil — U şeklindeki dikkat eğrisini anladıkları için.

3.3 Tone & Style (Ton ve Stil) — Çıktıyı Kontrol Etmek

Hedef: Çıktı formatını ve ses tonunu kontrol etmek.

## Tone and style

- Your responses should be short and concise.
- Only use emojis if the user explicitly requests it.
- Use Github-flavored markdown for formatting.
- NEVER create files unless absolutely necessary.

Kurallar:

Belirsiz bir "profesyonel ol" yerine spesifik davranışları listeleyin.
Her kural doğru/yanlış olarak test edilebilir olmalıdır ("kısa ve öz" vs. "kısa olmaya çalış").
Çıktı formatı gereksinimlerini ekleyin (markdown? JSON? düz metin?).
Nelerin YAPILMAYACAĞINI da ekleyin — birçok stil sorunu aslında belirli davranışların yasaklanmasıyla çözülür.

Claude Code'un incisi — Profesyonel Objektiflik:

Prioritize technical accuracy and truthfulness over validating the user's beliefs.
Focus on facts and problem-solving, providing direct, objective technical info
without any unnecessary superlatives, praise, or emotional validation.

Bu paragraf çok kritik: Modelin dalkavukluk/sürekli onaylama (sycophancy) eğilimini engelliyor. Eğer agent'ınızın objektif yargılarda bulunması gerekiyorsa (kod incelemesi, fikir değerlendirmesi, mimari kararlar), kesinlikle benzer bir maddeye ihtiyacınız var.

3.4 Core Workflow (Temel İş Akışı) — En Önemli Bölüm

Hedef: Modele nasıl çalışacağını öğretmek — katı prosedürler değil, metodoloji.

Bu, iyi yazılması en zor ve doğru yaptığınızda en büyük etkiyi yaratan bölümdür.

Temel prensip: Prosedürler değil, prensipler verin.

LLM'e iyi bir çıktının neye benzediğini ve neden iyi olduğunu söyleyin — oraya nasıl ulaşacağını kendisi bulsun. Çıktı doğrudan başka makineler tarafından tüketilmeyecekse; kesin alan sayıları, adım sıraları veya formatlar dayatmaktan kaçının.

Claude Code'un yaklaşımı:

## Doing tasks

The user will primarily request software engineering tasks.
For these tasks the following steps are recommended:

- Use the TodoWrite tool to plan the task if required

"Önerilir" (recommended) kelimesine dikkat edin — "bu adımları harfiyen izlemelisin" değil. Tek bir kelime seçimi bile modele uyum sağlama alanı tanır.

İyi bir iş akışı tanımı:

1. Understand first — read existing code before modifying it
2. Plan first — break complex tasks into steps before executing
3. Minimal changes — only change what's necessary, don't "refactor while you're in there"
4. Verify — confirm your changes work (run tests, lint, etc.)

Her kuralın örtük bir "nedeni" vardır — model amacı anlayabilir ve bunu yeni senaryolara genelleyebilir.

Anti-pattern'ler:

Katı bir 20 adımlık prosedür — model mekanik olarak çalışacak ve beklenmedik girdilerde donup kalacaktır.
"Önce A'yı yap, sonra B'yi yap, sonra C'yi yap" — bu bir prompt zinciridir, agent prompt'u değil.
LLM'in zaten iyi olduğu konularda aşırı yönlendirme yapmak — token israfıdır.

Bunu VibeCom'da acı bir yoldan öğrendim. İlk versiyonlarda 10 adımlık bir araştırma iş akışı vardı. Model, 3. adım kullanıcının sorusunu zaten yanıtlamış olsa bile görev bilinciyle 10 adımın tamamını uyguluyordu. Prensiplere ("yeterli kanıt elde edene kadar araştır, sonra sentezle") geçtiğimde kalite arttı ve token maliyetleri düştü.

İstisna: Çıktı başka makineler tarafından tüketilecekse (agent'lar arası iletişim, API yanıt formatları), kesinlikle katı formatlar tanımlamalısınız. Prensipler davranışlar içindir; şemalar ise arayüzler içindir.

3.5 Tool Usage Policy (Araç Kullanım Politikası) — Belirsizliği Çözmek

Hedef: Birden fazla tool aynı şeyi yapabiliyorsa, modele hangisini tercih edeceğini söylemek.

## Tool usage policy

- Use specialized tools instead of bash commands:
  - Read for reading files instead of cat/head/tail
  - Edit for editing instead of sed/awk
  - Grep for searching instead of grep/rg
- You can call multiple tools in a single response. If independent, call in parallel.
- Use the Task tool for file search to reduce context usage.

Kurallar:

Önceliği ifade etmek için "yerine" (instead of) kalıbını kullanın (B yerine A).
Belirli tool'ların neden tercih edilmesi gerektiğini açıklayın ("daha iyi bir kullanıcı deneyimi sağlar", "context kullanımını azaltır").
Paralellik stratejisini tanımlayın (bağımsız → paralel, bağımlı → sıralı).
Tool kullanımı için güvenlik kısıtlamalarını listeleyin (yol doğrulama, izin kontrolleri).

Tool'lar ve prompt'lar arasındaki kritik ilişki:

Tool tanımları genellikle sisteme enjekte edilir ve bunları doğrudan düzenleyemezsiniz. Claude Code'un tool tanımları yaklaşık 11.438 token'dır. Bu şu anlama gelir:

Tool tanımlarında zaten var olan bilgileri tekrarlamayın.
Sistem prompt'unu stratejik rehberlik için kullanın: Her bir tool'un ne zaman kullanılacağı, birinin diğerine neden tercih edileceği, öncelik sıralaması.
Tool tanımının kalitesi agent'ın etkinliğini doğrudan etkiler — kendi agent'ınızı geliştiriyorsanız, mükemmel tool açıklamaları yazmaya zaman ayırın.

3.6 Domain Knowledge (Alan Bilgisi) — Baştan Yükleme, İhtiyaç Anında Çek

Hedef: Modelin eğitim verilerinde eksik olabilecek uzmanlık bilgisini sağlamak.

Temel prensip: Bilgi yığınları değil, kademeli açıklama (progressive disclosure).

❌ Paste all 200 API endpoints into the system prompt → token explosion
✅ Give the model a tool to look things up → "Load knowledge when you need it"

Bu strateji, Claude Code'un Skills sistemi ve DeepAgents'ın Progressive Disclosure middleware'i tarafından paylaşılır. Her ikisi de her şeyi baştan yüklemek yerine bilgiyi tool çağrıları aracılığıyla ihtiyaç anında yükler.

Uygulama yaklaşımları:

Sistem prompt'una işaretçiler koyun: "Gerektiğinde dokümantasyonu almak için get_api_docs tool'unu kullanın."
Proje bağlamı için CLAUDE.md / AGENTS.md kullanın — hardcode edilmez, çalışma zamanında (runtime) yüklenir.
Yetenek keşfi için Skills / SKILL.md kullanın — model mevcut yeteneklerin bir menüsünü görür, tam özellikleri talep üzerine çeker.

3.7 Environment Info (Ortam Bilgisi) — Çalışma Zamanı (Runtime) Bağlamı

Hedef: Modele çalıştığı ortamın farkındalığını kazandırmak.

<env>
Working directory: /Users/fengliu/Desktop/tfm/vibecom
Is directory a git repo: true
Platform: darwin
Today's date: 2026-03-21
</env>
You are powered by the model named Claude Opus 4.6.

Kurallar:

Dinamik olarak oluşturun, asla hardcode etmeyin.
Şunları ekleyin: çalışma dizini, platform, tarih, model adı, git durumu.
Kolay ayrıştırma için yapılandırılmış format (XML etiketleri veya kod blokları) kullanın.
Tarih önemlidir — modelin bilginin tazeliğini yargılamak için "şimdi"yi bilmesi gerekir.

3.8 Reminders (Hatırlatıcılar) — Son Pekiştirme

Hedef: En kritik kuralları prompt'un sonunda yeniden belirtmek.

Claude Code, güvenlik kısıtlamasını ve TodoWrite gereksinimini en altta tekrarlar:

IMPORTANT: Assist with defensive security tasks only. [repeated]
IMPORTANT: Always use the TodoWrite tool to plan and track tasks. [repeated]

Kurallar:

Sadece en kritik 2-3 kuralı tekrarlayın — her şeyi kopyalamayın.
Yakınlık önyargısından (recency bias) yararlanın — model son içeriği daha güçlü hatırlar.
En iyi adaylar: güvenlik kısıtlamaları, en sık ihlal edilen kurallar, temel iş akışı hatırlatıcıları.

4. Token Bütçesi ve Context Yönetimi

Bütçe Dağılımı Referansı

Bölüm	Önerilen Token	Notlar
Identity + Safety	200-500	Kısa ama tartışılamaz
Tone & Style	300-800	Kurallar spesifik olmalı ama lafı uzatmayın
Core Workflow	500-2.000	En önemli bölüm, yatırıma değer
Tool Usage Policy	300-1.000	Tool sayısına bağlıdır
Domain Knowledge	0-1.000	İhtiyaç anında yükleme tercih edilir
Environment Info	100-300	Dinamik olarak oluşturulur
Reminders	100-300	Sadece temel kuralları tekrarlayın
Sizin toplamınız	1.500-6.000
Tool Definitions (sistem)	5.000-15.000	Sizin kontrolünüzde değil

Bağlam Bozulma Eğrisi (Context Degradation Curve)

Topluluk testleri (Reddit u/CodeMonke_), gerçek dünyadaki kurala uyum bozulmasını haritalandırdı:

< 80K token: Prompt'a uyum stabil kalır
80K - 120K token: Talimatları takip etme bozulmaya başlar
> 120K token: Ciddi bozulma — model ilk talimatları "unutur"
> 180K token: Şiddetli bozulma

200K context pencereniz ≠ 200K efektif context. Planınızı buna göre yapın.

Hafifletme stratejileri:

Sistem prompt'unuzu yalın tutun (kendi kısmınız için < 6.000 token)
Konuşma geçmişini sıkıştırmak için özetleme kullanın (DeepAgents ~80K karakterde tetikler)
Kritik kuralları prompt'un her iki ucuna yerleştirin (U şeklindeki dikkat)
Sohbetin ortasında <system-reminder> etiketleri enjekte edin (bununla ilgili daha fazlası bölüm 8'de)

5. Yazım Prensipleri

5.1 Prosedür Değil, Prensip Verin

❌ "Step 1: Read the file. Step 2: Find the bug. Step 3: Fix it. Step 4: Run tests."
✅ "Always understand existing code before modifying it. Verify your changes work."

Prensipler genellenebilir. Prosedürler sadece mekanik olarak takip edilebilir. Model öngörmediğiniz bir durumla karşılaştığında, prensipler doğru karara rehberlik eder. Prosedürler etmez.

İstisna: Çıktı makineler tarafından tüketildiğinde (agent'lar arası iletişim, API formatları), katı şemalar tanımlayın.

5.2 Kesin Kısıtlamalar İçin Kesin Bir Dil Kullanın

Güç	Dil	Kullanım Alanı
Mutlak yasak	`NEVER`, `MUST NOT`	Güvenlik, geri alınamaz işlemler
Güçlü gereksinim	`ALWAYS`, `MUST`	Temel iş akışı kuralları
Öneri	`recommended`, `prefer`	İstisnaları olan en iyi pratikler
Tavsiye	`consider`, `you may`	İsteğe bağlı optimizasyonlar

Claude Code örnekleri:

NEVER update the git config — mutlak yasak
ALWAYS prefer editing an existing file — güçlü, ancak istisnaları var
The following steps are recommended — önerilen iş akışı

5.3 Açıklamalar Yerine Örnekler Kullanın

## Code References

When referencing specific functions or pieces of code include
the pattern `file_path:line_number`.

<example>
user: Where are errors from the client handled?
assistant: Clients are marked as failed in the `connectToServer`
function in src/services/process.ts:712.
</example>

Bir örnek, 100 kelimelik bir açıklamadan daha fazlasını öğretir:

Modeller, kalıpları soyut açıklamalardan ziyade örneklerden daha güvenilir bir şekilde öğrenir.
Kurallardan ayırmak için <example> etiketleriyle sarın.
Hem olumlu ("bunu yap") hem de olumsuz ("bunu yapma") örnekler verin.
Gerçek, spesifik örnekler kullanın — "foo/bar" gibi yer tutucular değil.

5.4 Çift Yönlü Kısıtlamalar

✅ "Use dedicated tools: Read for reading files, Edit for editing files."
✅ "Do NOT use bash for file operations (cat, head, tail, sed, awk)."

Sadece "bunu yap" demek → model bunu ne zaman YAPMAMASI gerektiğini bilmez. Sadece "bunu yapma" demek → model alternatifi bilmez. Çift yönlü → net ve tartışmasız.

5.5 Sadece Ne Olduğunu Değil, Nedenini de Açıklayın

❌ "Don't use git commit --amend."
✅ "Avoid git commit --amend. ONLY use --amend when either
   (1) user explicitly requested amend OR
   (2) adding edits from pre-commit hook.
   Reason: amending may overwrite others' commits."

Nedenini açıklamak, modelin uç durumlarda (edge cases) doğru kararlar vermesini sağlar. Claude Code'un git güvenlik protokolü bir ustalık sınıfıdır — her kural kendi mantığını da içerir.

5.6 Düz Metin Yerine Yapılandırılmış Format

Markdown başlıkları (##, ###) — modeller hiyerarşiyi tanır
Paragraflar yerine Madde işaretli listeler — her kural bağımsız olarak test edilebilir
Özel içerikler için XML etiketleri: <example>, <env>, <system-reminder>
Karşılaştırmalar ve eşlemeler için Tablolar
Asla yapılandırılmamış metin yığınları kullanmayın — yapılandırılmış prompt'lar, uyum testlerinde doğal dilde yazılmış düz metinlerden her zaman daha iyi performans gösterir.

6. Token'larınızı İsraf Eden Anti-Pattern'ler

Agent Kılığına Girmiş Prompt Zincirleri

"First call tool A to get data.
Then call tool B with the result.
Then format the output as JSON.
Then save to file."

Bu bir agent prompt'u değil — bu bir pipeline betiğidir. Model mekanik olarak çalışacak ve otonom planlama yeteneğini kaybedecektir.

Çözüm: Modele hedefi ve kısıtlamaları söyleyin. Adımlara kendisi karar versin.

Övgü Mühendisliği (Flattery Engineering)

"You are an EXTREMELY TALENTED and INCREDIBLY EXPERIENCED
senior software engineer with 20 years of experience..."

İltifatlar ve abartılı sıfatlar çıktı kalitesini artırmaz. Modelin okşanacak bir egosu yoktur. O 15 token'ı gerçek bir kural için saklayın.

Bilgi Yığınları (Knowledge Dumps)

"Here is the complete API documentation for our 200 endpoints..."

Bu, context pencerenizi yutar ve context çürümesini hızlandırır. Bunun yerine ihtiyaç anında yükleme kullanın:

"Use the get_api_docs tool to retrieve API documentation when needed."

Tool Açıklamalarını Tekrarlamak

Tool tanımında zaten "Read tool'u dosya sisteminden bir dosya okur" yazıyorsa, bunu sistem prompt'unuzda tekrar söylemeyin. Sadece tool tanımının kapsamadığı stratejik rehberliği ekleyin — ne zaman kullanılacağı, neden tercih edileceği, öncelik sıralaması.

Hata Yönetimi (Failure Handling) Eksikliği

Açık bir yönlendirme olmazsa, modeller başarısız olan tool çağrılarını sonsuz bir döngüde tekrar dener. Her zaman şunu ekleyin:

"If a tool call is denied, do not re-attempt the exact same call.
Think about why it was denied and adjust your approach."

Context Penceresi Çürümesini Görmezden Gelmek

200K context penceresi ≠ 200K efektif context. Gerçek dünya testleri bozulmanın 80K'da başladığını gösteriyor. Bir özetleme stratejisine ihtiyacınız var.

7. Enjeksiyon Noktaları ve Öncelik

Claude Code'un Üç Özelleştirme Yöntemi

Yöntem	Neyi Değiştirir	Konum	En İyi Kullanım Alanı
Output Styles	"Tone and style" + "Doing tasks" bölümleri	Tool tanımlarının hemen öncesi	Etkileşim stilini değiştirmek
--append-system-prompt	Hiçbir şeyi (eklemelidir)	Output style'dan sonra, tool tanımlarından önce	Spesifik davranışlar eklemek
--system-prompt	Tüm sistem prompt'unu	Tool tanımlarını + bir kimlik satırını korur	Tam özelleştirme (nükleer seçenek)

Birden fazlasını kullanırsanız: Output Style → Append Prompt → Tool Definitions

Talimat Hiyerarşisi

Claude, özel bir talimat hiyerarşisi ile eğitilmiştir:

1. User's explicit instructions (CLAUDE.md, direct requests)  ← Highest priority
2. Custom system prompt additions                               ← High
3. Default system prompt                                        ← Medium
4. Tool definitions                                             ← Reference level

Bunun anlamı şudur:

CLAUDE.md kuralları, varsayılan sistem prompt'u davranışını ezer.
Kullanıcının doğrudan talepleri her şeyi ezer.
Sizin özel prompt'unuz varsayılan prompt'u ezer.

Dinamik Enjeksiyon Mekanizmaları

<system-reminder> — modele kritik kuralları hatırlatmak için sohbetin ortasında herhangi bir mesaja enjekte edin.
CLAUDE.md / AGENTS.md — çalışma zamanında dosyalardan yüklenir, sistem prompt'una eklenir.
Skills / SKILL.md — tool çağrıları aracılığıyla ihtiyaç anında yüklenir, sistem prompt'unda sıfır ayak izi bırakır.

8. Sohbet Ortası Enjeksiyonu — Gizli Silah

Sistem prompt'u mesajlar dizisinin (messages array) en başında sadece bir kez görünür. Ancak LLM'ler tam mesaj dizisini (sırayla kullanıcı / asistan / tool mesajları) girdi olarak kabul eder ve kullanıcı mesajlarına ve tool sonuçlarına da prompt enjekte edebilirsiniz. Claude Code bu tekniği prodüksiyonda yoğun bir şekilde kullanır.

Neden Gerekli?

Context çürümesiyle savaşmak. Konuşmalar uzadıkça, modelin sistem prompt'u talimatlarına uyumu azalır (80K+ token'da fark edilir hale gelir). Sohbet ortasında hatırlatıcılar enjekte etmek = yakınlık önyargısı (recency bias) yoluyla kuralları tazelemek demektir.

Zihinsel model:

Sistem prompt'u = anayasa (bir kez oluşturulur, uzun vadeli otorite)
Kullanıcı mesajı hatırlatıcıları = genelgeler (periyodik olarak gönderilir, yürütmeyi sürdürür)

Mesajlar Dizisindeki Üç Enjeksiyon Noktası

Messages Array:
┌─────────────────────────────────────┐
│ System Prompt                       │ ← Appears once, primacy effect
│   (identity, safety, workflow...)   │
├─────────────────────────────────────┤
│ User Message 1                      │
│ Assistant Message 1                 │
│ User Message 2 + <system-reminder>  │ ← Mid-conversation injection
│ Assistant Message 2                 │
│ Tool Result + <system-reminder>     │ ← Can inject into tool results too
│ ...                                 │
│ User Message N + <system-reminder>  │ ← Latest message, strongest recency
└─────────────────────────────────────┘

Konum	Avantaj	Dezavantaj
Sistem prompt'u	Öncelik etkisi, ilk okunur	Bir kez görünür, uzun sohbetlerde "unutulur"
Kullanıcı mesajı enjeksiyonu	Yakınlık önyargısı, periyodik yenileme	Her enjeksiyon token harcar
Tool sonucu enjeksiyonu	En doğal enjeksiyon noktası	Sadece tool'lar çağrıldığında çalışır

Claude Code Bunu Gerçekte Nasıl Kullanıyor?

Ön koşul — etiketleri sistem prompt'unda deklare edin:

Tool results and user messages may include <system-reminder> tags.
<system-reminder> tags contain useful information and reminders.
They are automatically added by the system, and bear no direct
relation to the specific tool results or user messages in which they appear.

Bu adım kritiktir: Modele bu etiketlerin kullanıcı söylemi değil, sistem tarafından enjekte edildiğini söyler.

Kullanım 1: Davranışsal Hatırlatıcılar (periyodik kural yenileme)

<system-reminder>
The task tools haven't been used recently. If you're working on tasks
that would benefit from tracking progress, consider using TaskCreate...
</system-reminder>

Claude Code bunu modele TodoWrite ile plan yapmasını hatırlatmak için kullanır — çünkü modeller planlamayı "unutma" ve doğrudan kod yazmaya başlama eğilimindedir.

Kullanım 2: Mod Değiştirme (Plan Modu)

<system-reminder>
Plan mode is active. The user indicated that they do not want you to
execute yet -- you MUST NOT make any edits, run any non-readonly tools,
or otherwise make any changes to the system.
</system-reminder>

Plan modu sistem prompt'unda uygulanmaz. Bir sonraki kullanıcı mesajına enjekte edilen bir etikettir. Bu, sistem prompt'unu değiştirmeden modları dinamik olarak değiştirmenizi sağlar. Zekice.

Kullanım 3: Dosya Değişikliği Bildirimleri

<system-reminder>
Note: /path/to/file.ts was modified, either by the user or by a linter.
This change was intentional, so make sure to take it into account.
</system-reminder>

Harici bir süreç (linter, formatter, manuel düzenleme) bir dosyayı değiştirdiğinde, sistem modeli bir hatırlatıcı aracılığıyla bilgilendirir — böylece bayat dosya içeriklerine dayalı kararlar alınması önlenir.

Kullanım 4: Dinamik Context (tarihler, proje kuralları)

<system-reminder>
Today's date is 2026-03-21.
Current branch: dev
claudeMd: [CLAUDE.md content injected here]
</system-reminder>

Çalışma zamanı bağlamı (tarih, git durumu, proje kuralları) sistem prompt'unda hardcode edilmez, kullanıcı mesajları aracılığıyla enjekte edilir.

Hatırlatıcılar İçin Yazım Kuralları

XML etiketleriyle sarın (<system-reminder>) — model sistem enjeksiyonunu kullanıcı söyleminden ayırt edebilir.
Etiketleri sistem prompt'unda önceden deklare edin — aksi takdirde model hatırlatıcıya yanıt vermeye çalışabilir.
Her mesaja enjekte etmeyin — her enjeksiyon token harcar, sadece gerektiğinde enjekte edin.
Kısa tutun — bir hatırlatıcı ikinci bir sistem prompt'u değildir, sadece 1-2 kritik kuraldır.
Sistem prompt'uyla çelişmeyin — hatırlatıcılar destekler ve pekiştirir, ezmez.
Dinamik geçişler için kullanın — plan modu, salt okunur (readonly) mod, feature flag'ler.

Ne Zaman Sistem Prompt'u, Ne Zaman Kullanıcı Mesajı Hatırlatıcısı Kullanılmalı?

Senaryo	Sistem Prompt'u	Kullanıcı Mesajı Hatırlatıcısı
Rol tanımı	✅	❌
Güvenlik kısıtlamaları	✅ İlk bildirim	✅ Periyodik tekrar
İş akışı metodolojisi	✅	❌
Mod değiştirme (plan modu)	❌	✅
Dosya değişikliği bildirimleri	❌	✅
Tarih / ortam bilgisi	✅ İlk değer	✅ Güncellenmiş değer
Davranışsal düzeltme	❌	✅
Tool kullanım hatırlatıcıları	✅ Kural tanımı	✅ Yürütme dürtmeleri

9. Prompt Cache — Tekrarlanan Token'larda %90 Tasarruf Edin

Anthropic'in prompt caching özelliği, mesajlar dizinizin statik önekini (prefix) önbelleğe almanızı sağlar. Sonraki istekler aynı öneki paylaştığında, önbellek isabeti (cache hit) gerçekleşir — bu da hem para tasarrufu sağlar hem de gecikmeyi (latency) azaltır.

Agent'lar için bu çok önemlidir: Bir sohbet içindeki her bir LLM çağrısında sistem prompt'unu + tool tanımlarını tekrar tekrar gönderiyorsunuz.

Önemli Rakamlar

Metrik	Değer
Cache hit maliyeti	Normal fiyatın %10'u (%90 tasarruf)
Cache yazma maliyeti	Normal fiyatın %125'i (ilk yazımda %25 prim)
Cache TTL	5 dakika (istek olmazsa süresi dolar)
Minimum önbelleklenebilir uzunluk	1.024 token (Claude 3.5+)
Cache granülaritesi	Önek eşleştirme (Prefix matching) — baştan işaretli bir breakpoint'e kadar
Maksimum breakpoint	4

Bu Durum Prompt Tasarımını Nasıl Değiştiriyor?

Temel prensip: Önce statik içerik, sonra dinamik içerik.

✅ Cache-friendly layout:
  System prompt (static)      ← Cache breakpoint 1
  Tool definitions (static)   ← Cache breakpoint 2
  CLAUDE.md / project rules   ← Cache breakpoint 3 (changes occasionally)
  Conversation history         ← Breakpoint 4 for rolling window

❌ Cache-destroying layout:
  System prompt
  DYNAMIC TIMESTAMP            ← Changes every request, everything after = cache miss
  Tool definitions
  Conversation history

Kimsenin sizi uyarmadığı o tuzak: Sistem prompt'unuzun ortasına dinamik bir zaman damgası (timestamp) koyarsanız, ondan sonraki her şey bir cache miss (önbellek ıskalaması) olur. Her. Tek. İstekte. Yanlış yerdeki tek bir zaman damgası yüzünden binlerce token için tam fiyat ödersiniz.

API Kullanımı

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    {
      type: "text",
      text: "You are a startup advisor...",
      cache_control: { type: "ephemeral" }  // ← marks a cache breakpoint
    }
  ],
  messages: [...]
});

Çoklu Breakpoint Stratejisi

Breakpoint 1: System prompt           ← Almost never changes
Breakpoint 2: Tool definitions         ← Almost never changes
Breakpoint 3: Project rules / CLAUDE.md ← Changes occasionally
Breakpoint 4: First N history messages  ← Rolling window cache

Konuşma geçmişi değişse bile, ilk 3 breakpoint hala isabet eder (cache hit). 10 turluk bir konuşma, girdi token maliyetlerinde yaklaşık %40-60 tasarruf sağlar.

Tasarım Önerileri

Sistem prompt'unda yüksek frekanslı dinamik değerler kullanmayın — tarih sorun değil (günlük değişir), ancak kesin zaman damgaları (timestamps) kullanmayın.
Dinamik bağlamı (git durumu vb.) kullanıcı mesajı enjeksiyonlarına koyun — sistem prompt'una değil, yoksa cache'i mahvedersiniz.
Tool tanımlarını sabit tutun — çalışma zamanında dinamik olarak tool ekleyip çıkarmayın.
Konuşma geçmişi için kayan pencere (rolling window) kullanın — ilk N mesajı önbelleğe alın, sadece en yeni mesaj cache miss olur.

10. Kontrol Listesi

Sistem prompt'unuzu yazdıktan sonra, bu kontrol listesine göre gözden geçirin:

Yapı

Kimlik (Identity) en üstte mi?
Güvenlik kısıtlamaları IMPORTANT ile işaretlenip en sonda tekrarlandı mı?
Başlıklarla net bölüm ayrımları yapıldı mı?
Örnekler <example> etiketleriyle sarıldı mı?

Token Bütçesi

Sizin yazdığınız kısım < 6.000 token mı?
Tool tanımlarında zaten var olan bilgiler tekrarlanmıyor mu?
Alan bilgisi baştan yüklenmek yerine ihtiyaç anında mı yükleniyor?
Gereksiz uzun hikayeler veya karakter arka planı yok mu?

Kural Kalitesi

Her kural doğru/yanlış olarak test edilebilir mi?
Kesin kısıtlamalar mutlak bir dil (NEVER/MUST) kullanıyor mu?
Esnek öneriler tavsiye dili (recommended/prefer) kullanıyor mu?
Kritik kurallar sadece ne olduğunu değil, nedenini de açıklıyor mu?
Çift yönlü kısıtlamalar (bunu yap + bunu yapma) var mı?

Agent Davranışı

Katı adım adım prosedürler yerine prensipler mi verildi?
"Tool çağrısı reddedildi" senaryosu ele alındı mı?
"Engelle karşılaşıldı" stratejisi ele alındı mı (kaba kuvvetle tekrar deneme yapmaması için)?
Context yönetimi stratejisi devrede mi (özetleme eşiği)?

Neler YAPILMAMALI

Dalkavukluk veya abartılı sıfatlar yok mu?
Gereksiz "sen yardımsever bir yapay zekasın" beyanları yok mu?
Bir prompt zinciri gibi yazılmamış mı?
Aşırı mühendislik (kimsenin istemediği özellikler) yok mu?

Bugün Sıfırdan Başlıyor Olsaydım

Tam olarak şunları yapardım:

İlk 3 satırda kimlik + güvenlik ile başlayın. Agent'ın kim olduğu için iki cümle. NEVER/MUST ile kesin kısıtlamalar. Güvenlik kurallarını en sonda tekrarlayın.
Temel iş akışınızı adımlar olarak değil, prensipler olarak yazın. Maksimum 4-5 madde. Esnek kurallar için "recommended" ve "prefer", kesin kurallar için "NEVER" ve "MUST" kullanın.
Kendi kısmınız için 1.500-6.000 token bütçe ayırın. Tool tanımları 5.000-15.000 daha ekleyecektir. Eğer 6K'nın üzerindeyseniz, muhtemelen ihtiyaç anında yüklenmesi gereken bilgileri baştan yığıyorsunuzdur.
Her şeyi yapılandırın. Markdown başlıkları, madde işaretli listeler, örnekler için XML etiketleri. Yapılandırılmış bir prompt, doğal dilde yazılmış düz metinden her zaman daha iyi performans gösterir.
İlk günden itibaren sohbet ortası hatırlatıcıları (mid-conversation reminders) kurun. Sistem prompt'unuzda <system-reminder> etiketini deklare edin. Kritik kurallar, mod geçişleri ve context güncellemeleri için hatırlatıcılar enjekte edin.
Cache için tasarlayın. Önce statik içerik, sonra dinamik içerik. Değişen değerleri asla sistem prompt'unuzun gövdesine koymayın.

Tüm bu çabanın ironisi ne biliyor musunuz? En iyi sistem prompt'ları kısa olanlardır. Claude Code'un özel talimatları (tool tanımları hariç) şaşırtıcı derecede kısadır. Her satır orada olmayı hak eder.

Eskiden prompt mühendisliğinin zekice numaralar bulmakla ilgili olduğunu düşünürdüm. Şimdi ise bunun bir disiplin meselesi olduğunu düşünüyorum — daha az şey söylemek, bunu kesin bir dille ifade etmek ve geri kalanını çözmesi için modele güvenmek. Model sizin prompt'unuzdan daha zeki. Davranışı değil, ortamı tasarlayın.

Referanslar

Kaynak	Temel İçgörü
Claude Code v2.0.14 System Prompt	Tam prodüksiyon agent prompt yapısı referansı
Reddit: Understanding Claude Code's 3 System Prompt Methods	Output Styles / --append / --system-prompt derinlemesine incelemesi, context çürümesi gerçek dünya verileri
shareAI-lab/learn-claude-code	"Model agent'ın kendisidir" felsefesi, harness mühendisliği metodolojisi
Anthropic Prompt Engineering Docs	Resmi prompt en iyi pratikleri
DeepAgents Framework	Özetleme middleware'i, yeteneklerin kademeli açıklaması (progressive disclosure)