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:

Explicit arayüzler - MCP ile runtime discovery, hardcode yok
Gömülü context - Hook'lar otomatik state enjekte eder
Otomatik kısıtlar - Hook'lar validate eder, tehlikeli aksiyonları bloklar
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.

PreviousClaude Code: Yapay Zeka ile Kodlama NextClaude Code'u Tamamen Kaldırmak (macOS)

Last updated 13 days ago

Was this helpful?

Good afternoon

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

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

Araçlar: Otomatik vs Workflow

Basit Kural

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

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

3. KISIT OTOMATIK (Güvenilmez)

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

Gerçek Örnek: AI-Friendly Mimari

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

Hook'lar: Otomatik Davranışlar

Skill'ler: Karmaşık Workflow'lar

MCP: Veri Bağlantıları

Temel Prensipler

Mental Model Kayması

TL;DR