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

[r/ClaudeAI](https://reddit.com/r/ClaudeAI/comments/1orz53c/) • [r/ClaudeCode](https://reddit.com/r/ClaudeCode/comments/1orz5as/)

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**

```typescript
// ✗ 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:

```typescript
// ✗ 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**

```typescript
/**
 * 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:

```bash
# 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**

```typescript
// ✗ 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**

```bash
# 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:**

```typescript
// ✗ 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:

```markdown
---
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:

```typescript
// 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:

```typescript
// ✗ 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

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

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

```markdown
---
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

```json
{
  "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.