AI Agentlarına Öğretmeyi Bırak - Hata Yapamaz Hale Getir

AI agentlarına öğretmeyi bırak, hata yapamaz hale getir. Stateless sistemlerde yatırım agenta değil sisteme yapılır - Hook, Skill, MCP ile guardrails kur.

r/ClaudeAI • r/ClaudeCode

Kod üretimi için AI agentlarla çalışıyorum, sürekli aynı duvara tosladım: agent her oturumda aynı hataları yapıyor. Yanlış isimlendirme, unutulan kısıtlar, daha önce düzelttiğim kalıpları tekrar bozuyor.

Sonra anladım: hafızası olan bir sisteme davranıyordum, oysa sistem hafızasız.

Asıl Sorun: Yatırım Kalıcı Değil

İnsan developerlarla:

• Bir kere anlatırsın → hatırlar

• Hata yapar → öğrenir

• Kişiye yaptığın yatırım kalıcı

AI agentlarla:

• Bir şey anlatırsın → oturum biter, unutur

• Hata yapar → düzeltirsin, sonraki sefere tekrarlar

• Agenta yaptığın yatırım buharlaşır

Bu, çalışma biçimini altüst eder.

Geçiş: Yatırım → Sistem, Agent Değil

Agenta öğretmeyi bırak. Onun yerine, sistemin istediğini zorla.

Claude Code sana üç araç veriyor. Her biri hafızasızlık sorununu farklı seviyede çözer:

Araçlar: Otomatik vs Workflow

Hook'lar (Otomatik)

• Olay tetikler (her prompt'ta, araç kullanımından önce, vs.)

• Shell script direkt çalıştırır

• Agent çıktıyı alır, yorumlamaz

• Kullan: Context enjeksiyonu, validation, güvenlik

Skill'ler (Workflow)

• Görev çıkınca tetiklenir (agent karar verir)

• Agent talimatları okur ve yorumlar

• Workflow içinde kararlar verir

• Kullan: Çok adımlı prosedürler, karmaşık mantık

MCP (Data Erişimi)

• Dış kaynaklara bağlanır (Drive, Slack, GitHub)

• Agent çalışırken sorgular

• Hardcode yok

• Kullan: Değişen dinamik veri

Basit Kural

İhtiyacın...	Kullan...
Her seferinde aynı şey	Hook
Çok adımlı workflow	Skill
Dış veri erişimi	MCP

Örnek: Git commit'ler Hook kullanır (otomatik template "commit" deyince). Post yayınlama Skill kullanır (karmaşık workflow: oku → kalıpları tara → uyarla → paylaş).

Bu araçları çalıştıran 4 prensip:

---

1. ARAYÜZ AÇIK (Convention-Based Değil)

Sorun:

İnsan developerla:

Sen: "İsimlendirme kuralını takip et"
Dev: [öğrenir, hatırlar]

AI agentla:

Sen: "Naming convention'ı takip et"
Agent: [oturum biter]
Sen: [sonraki oturum] "Naming convention'ı takip et"
Agent: "Hangi convention?"

Çözüm: Yanlış yapmayı imkansız kıl

// ✗ Implicit (agent unutur)
// "Port'lar src/ports/'ta naming convention X ile"

// ✓ Explicit (sistem zorlar)
export const PORT_CONFIG = {
  directory: 'src/ports/',
  pattern: '{serviceName}/adapter.ts',
  requiredExports: ['handler', 'schema']
} as const;

// Runtime validation ihlalleri anında yakalar
validatePortStructure(PORT_CONFIG);

Araç: MCP runtime discovery'yi halleder

Agent endpoint'leri ve port'ları ezberlemek yerine, MCP server'lar bunları dinamik açar:

// ✗ Agent hardcode eder (unutur veya yanlış alır)
const WHISPER_PORT = 8770;

// ✓ MCP server sağlar (agent runtime'da sorgular)
const services = await fetch('http://localhost:8772/api/services').then(r => r.json());
// Döner: { whisper: { endpoint: '/transcribe', port: 8772 } }

Agent yanlış bilgiyi hardcode edemez çünkü her şeyi runtime'da keşfeder. Google Drive, Slack, GitHub için MCP server'lar aynı şekilde çalışır - agent sorar, server cevaplar.

---

2. CONTEXT GÖMÜLMÜŞ (Dışarıda Değil)

Sorun:

README.md: "Her zaman TypeScript strict mode kullan"
Agent: [asla okumaz veya unutur]

Çözüm: WHY'ı kodun içine göm

/**
 * NEDEN STRICT MODE:
 * - Runtime hatalar compile-time hata olur
 * - Operational debugging cost → 0
 * - KAPATMA: Type safety garantilerini kırar
 *
 * Initial cost: +500 LOC type definitions
 * Operational cost: 0 runtime bug (compiler yakalar)
 */
{
  "compilerOptions": {
    "strict": true
  }
}

Agent dosyaya her dokunduğunda bunu görür. Context kod ile birlikte gezer.

Araç: Hook'lar otomatik context enjekte eder

Dosyalar henüz yokken, hook'lar agent'ın ihtiyacı olan context'i sağlar:

# UserPromptSubmit hook - agent prompt'unu görmeden önce çalışır
# Otomatik olarak proje context'i ekler

#!/bin/bash
cat << EOF
Şu anki context:
- Git branch: $(git branch --show-current)
- Son commit: $(git log -1 --oneline)
- Değişen dosyalar: $(git status --short)
EOF

Agent bu context'i her oturum başında enjekte edilmiş olarak alır, sen bir şey anlatmadan. Hafıza gerekmez.

---

3. KISIT OTOMATIK (Güvenilmez)

Sorun:

İnsan collaboration:

Sen: "Input'ları validate ettiğinden emin ol"
Dev: [review eder, sorunları yakalar]

AI collaboration:

Sen: "Input'ları validate ettiğinden emin ol"
Agent: [unutur veya yanlış anlar]
Sonuç: Production'da runtime crash

Çözüm: Atlanamaz validation

// ✗ Agent'a güven
// "Doğru type'ları kullan"

// ✓ Otomatik validation
import { z } from 'zod';

const RequestSchema = z.object({
  method: z.enum(['transcribe', 'translate']),
  input: z.string().min(1)
});

// Agent literal olarak invalid data gönderemez
RequestSchema.parse(request); // yanlışsa anında fırlatır

Araç: Hook'lar validate eder ve tehlikeli aksiyonları bloklar

# PreToolUse hook - agent herhangi bir tool çalıştırmadan önce çalışır
#!/bin/bash

command=$(echo "$HOOK_INPUT" | jq -r '.tool_input.command // empty')

# Tehlikeli komutları blokla
if echo "$command" | grep -qE "rm -rf|dd if=|mkfs|> /dev/"; then
  echo '{"permissionDecision": "deny", "reason": "Tehlikeli komut engellendi"}'
  exit 0
fi

echo '{"permissionDecision": "allow"}'

Agent rm -rf çalıştıramaz denemesine denese. Hook yapısal olarak bloklar. Güvenlik sistem seviyesinde olur, agent'ın takdirine kalmaz.

---

4. İTERASYON PROTOKOLÜ (Hata → Sistem Patch'i)

Sorun: Bozuk döngü

Agent hata yapar → Düzeltirsin → Oturum biter → Agent hatayı tekrarlar

Çözüm: Düzeltilmiş döngü

Agent hata yapar → Sistemi patch'lersin → Agent o hatayı artık yapamaz

Örnek:

// ✗ Geçici fix (agent'a söyle)
// "Port isimleri snake_case olmalı"

// ✓ Kalıcı fix (sistemi güncelle)
function validatePortName(name: string) {
  if (!/^[a-z_]+$/.test(name)) {
    throw new Error(
      `Port ismi snake_case olmalı: "${name}"

      Geçerli:   whisper_port
      Geçersiz: whisperPort, Whisper-Port, whisper-port`
    );
  }
}

Artık agent yanlış isimli port oluşturamaz. Hata yapısal olarak imkansız.

Araç: Skill'ler workflow'ları yeniden kullanılabilir yapar

Agent çalışan bir workflow öğrenince, onu Skill olarak yakala:

---
name: setup-typescript-project
description: TypeScript projesi kur strict mode ve validation ile
---

1. `npm init -y` çalıştır
2. Dependency'leri kur: `npm install -D typescript @types/node`
3. tsconfig.json oluştur strict: true ile
4. src/ dizini oluştur
5. package.json'a validation script ekle

Sonraki oturum, agent prompt'unda "TypeScript projesi kur" algıladığında bu Skill'i otomatik kullanır. Yeniden öğretme yok. Workflow oturumlar arası kalıcı.

---

Gerçek Örnek: AI-Friendly Mimari

Pratikte şöyle görünüyor:

// Self-validating, self-documenting, self-discovering

export const PORTS = {
  whisper: {
    endpoint: '/transcribe',
    method: 'POST' as const,
    input: z.object({ audio: z.string() }),
    output: z.object({ text: z.string(), duration: z.number() })
  },
  // ... diğer portlar
} as const;

// Agent port'u çağırmak istediğinde:
// ✓ Endpoint'ler enumerated (typo yapamaz) [MCP]
// ✓ Schema'lar auto-validate (yanlış data gönderemez) [Constraint]
// ✓ Type'lar autocomplete (IDE agent'ı guide eder) [Interface]
// ✓ Method'lar constrained (yanlış HTTP verb kullanamaz) [Validation]

Implicit versiyonla karşılaştır:

// ✗ Agent hatırlamalı/tahmin etmeli
// "Whisper 8770 port'unda çalışıyor"
// "/transcribe'a POST kullan"
// "Audio'yu base64 string olarak gönder"

// Agent:
// - Yanlış port hardcode eder
// - Endpoint'i typo yapar
// - Yanlış data formatı gönderir

---

Araç Referansı: Ne Zaman Ne Kullanılır

İhtiyaç	Araç	Neden	Örnek
Her seferinde aynı	Hook	Otomatik, hızlı	Commit'te git status
Çok adımlı workflow	Skill	Agent karar verir, esnek	Post yayınlama workflow
Dış veri	MCP	Runtime discovery	Drive/Slack/GitHub sorgula

Hook'lar: Otomatik Davranışlar

• Tetikleyici: Event (her prompt'ta, tool'dan önce, vs.)

• Örnek: "commit" dediğinde commit template görünür

• Pattern: Bir kere kur, sonsuza kadar otomatik olur

Skill'ler: Karmaşık Workflow'lar

• Tetikleyici: Task relevance (agent ihtiyacı algılar)

• Örnek: Post yayınlama (oku → tara → adapte et → paylaş)

• Pattern: Çok adımlı prosedür agent yorumlar

MCP: Veri Bağlantıları

• Tetikleyici: Agent dış veriye ihtiyaç duyunca

• Örnek: Hardcode yerine mevcut servisleri sorgula

• Pattern: Runtime discovery, hardcode değer yok

Birlikte nasıl çalışır:

User: "Bu post'u yayınla"
→ Hook git context ekler (otomatik)
→ Skill publishing workflow yükler (agent task'ı algılar)
→ Agent adımları takip eder, gerekirse MCP kullanır (dış veri)
→ Hook final output'u validate eder (otomatik)

Setup:

Hook'lar: .claude/hooks/ dizininde shell script'ler

# Örnek: .claude/hooks/commit.sh
echo "Git status: $(git status --short)"

Skill'ler: ~/.claude/skills/{name}/SKILL.md'de markdown workflow'lar

---
name: publish-post
description: Yayınlama workflow'u
---
1. Content oku
2. Geçmiş post'ları tara
3. Adapte et ve yayınla

MCP: claude_desktop_config.json ile server'lar kur

{
  "mcpServers": {
    "filesystem": {...},
    "github": {...}
  }
}

Üçü de Claude Code ve Claude API'de mevcut. Doküman: https://docs.claude.com

---

Temel Prensipler

Amnesia İçin Tasarla

• Her oturum sıfırdan başlar

• Context'i artifact'lere göm, konuşmaya değil

• Validate et, güvenme

Yatırım → Sistem

• Agent'a öğretme, sistemi değiştir

• Implicit convention'ları explicit enforcement ile değiştir

• Self-documenting kod > dış dokümantasyon

Arayüz = Single Source of Truth

• Agent şunlardan öğrenir: Type'lar + Schema'lar + Runtime introspection (MCP)

• Agent şunları kıramaz: Validation + Constraint'ler + Fail-fast (Hook'lar)

• Agent şunları yeniden kullanır: Workflow'lar oturumlar arası kalıcı (Skill'ler)

Hata = Sistem Açığı

• Agent hatası → sistem fazla permissive

• Fix: Agent'ı düzeltme, sistemi patch'le

• Hedef: Hatayı yapısal olarak imkansız kıl

---

Mental Model Kayması

Eski yol: AI agent = Eğitime ihtiyaç duyan junior developer

Yeni yol: AI agent = Guardrail'e ihtiyaç duyan stateless worker

Agent öğrenmiyor. Sistem öğreniyor.

Yaptığın her düzeltme sistemi sertleştirmeli, agent'ı eğitmemeli. Zamanla, yanlış kullanılması imkansız bir mimari inşa edersin.

---

TL;DR

AI agent'larına öğretmeyi bırak. Her şeyi unutuyorlar.

Onun yerine:

1. Explicit arayüzler - MCP ile runtime discovery, hardcode yok

2. Gömülü context - Hook'lar otomatik state enjekte eder

3. Otomatik kısıtlar - Hook'lar validate eder, tehlikeli aksiyonları bloklar

4. Yeniden kullanılabilir workflow'lar - Skill'ler bilgiyi oturumlar arası kalıcı kılar

Karşılığı: Initial cost yüksek (guardrail kurma), operational cost → 0 (agent hata yapamaz).

---

İlgili: Kod üretimi, agent orchestration, veya LLM-powered workflow'larla çalışıyorsan. Aynı prensipler geçerli.

Başka pattern'lere rastlayanınız var mı merak ediyorum.