Orta · ~2 dk okuma #harness #agent #claude-code

Agent Harness

Modelin etrafındaki yazılım katmanı

Bir dil modelini iş yapan bir ajana dönüştüren çevre yazılım: araç döngüsü, araçlar, bağlam yönetimi, izinler ve arayüz.

Tanım

Bir dil modeli tek başına sadece metin alır ve metin üretir. Dosya açamaz, komut çalıştıramaz, bir önceki adımda ne olduğunu hatırlamaz. Onu gerçek iş yapan bir ajana dönüştüren her şeye harness denir (kelime anlamıyla: atın gücünü işe çeviren koşum takımı).

Bir harness'ın tipik parçaları: - Döngü — modeli çağırır, araç isteğini çalıştırır, sonucu geri verir, iş bitene kadar tekrarlar. - Araçlar — dosya okuma/düzenleme, bash, web araması, MCP sunucuları; hem tanımları hem de gerçekten çalıştıran kod. - Bağlam yönetimi — system prompt, proje talimat dosyaları (CLAUDE.md, AGENTS.md), pencere dolunca özetleme (compaction). - İzinler ve güvenlik — hangi komut sormadan çalışır, hangisi onay ister, hangisi yasaktır; sandbox. - Arayüz — terminal, IDE eklentisi, masaüstü uygulaması ya da SDK.

Anthropic'in Claude Code dokümantasyonu bunu açıkça söyler: Claude Code, modelin etrafında araçları sağlayan ve modelin gördüğü bağlamı yöneten katmandır; agentic harness terimi bu katmanı anlatır. Claude Code, OpenAI'ın Codex CLI'ı ve Cursor'un agent modu hazır harness örnekleridir. Claude Agent SDK Claude Code'un harness'ını kütüphane olarak sunar; OpenAI Agents SDK ise kendi araçlarınla döngüyü kurmanı sağlar.

Asıl ders şu ayrımdır: model ≠ harness. Aynı model, farklı bir harness'ta bambaşka performans gösterebilir. Bir ajan başarısız olduğunda ilk soru “model mi yetersiz?” değil, “ona doğru araçları, doğru bağlamı ve doğru izinleri verdik mi?” olmalıdır.

Benzetme

Motor ile otomobil farkı. Model, güçlü bir motordur; harness ise şasi, direksiyon, fren, gösterge paneli ve emniyet kemeri. Sehpaya bağlı bir Formula 1 motoru gürültü çıkarır ama bir yere gitmez.

Aynı motoru bir kamyona da, bir yarış arabasına da takabilirsin; ortaya çıkan araç tamamen farklıdır. Ajanlarda da öyle: Claude'u bir sohbet penceresinde kullanmakla bir terminal ajanında kullanmak, aynı motorla iki farklı araç sürmektir.

Gerçek dünyadan örnek

Aynı Claude modeline iki farklı yerden “bu depodaki başarısız testleri düzelt” diyorsun.

Sohbet arayüzünde: model koda erişemez. Muhtemel nedenleri sıralar, sana “şu dosyayı yapıştırır mısın?” diye sorar. Testleri çalıştırmak, düzeltmeyi uygulamak ve tekrar denemek sana kalır.

Claude Code'da: harness modele Bash, Read, Edit, Grep gibi araçlar verir. Model npm test çalıştırır, hatayı görür, ilgili dosyayı okur, düzeltir, testleri tekrar koşar. Bu sırada harness .claude/settings.json içindeki kurallara bakar: npm run test sormadan çalışır, .env dosyasını okumak ise yasaktır.

Model aynı; fark tamamen harness'ta.

Kod örnekleri

                                            Claude Agent SDK · hazır harness'ı kütüphane olarak kullanmak
                                            python
                                        
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Testleri çalıştır ve başarısız olanları düzelt",
        options=ClaudeAgentOptions(
            # Sormadan onaylanacak araçlar (kısıtlama değil!)
            allowed_tools=["Read", "Grep", "Glob", "Edit", "Bash"],
            # Bu araçlar modelin önünden tamamen kaldırılır
            disallowed_tools=["WebFetch"],
            permission_mode="acceptEdits",  # dosya düzenlemelerini otomatik kabul et
            max_turns=30,                   # döngü için tur sınırı
        ),
    ):
        # Döngü, araçlar, bağlam yönetimi SDK'nın içinde;
        # sen sadece sonucu okursun.
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

                                            Claude Code · harness'ın izin katmanı
                                            json
                                        
// ~/.claude/settings.json  (ya da projede .claude/settings.json)
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Ne zaman kullan

Kodlama, dosya düzenleme, terminal işleri gibi genel amaçlı ajan görevleri — hazır bir harness (Claude Code, Codex CLI) çoğu zaman yeter
Kendi ürününe ajan gömerken — Agent SDK ile döngüyü, araçları ve bağlam yönetimini sıfırdan yazmadan alırsın
Bir ajan başarısız olduğunda teşhis yaparken — sorun modelde mi, yoksa araç, bağlam ya da izin katmanında mı?
Denetim, loglama ve onay akışı gerektiğinde — bu kararların hepsi harness'ta verilir

Ne zaman kullanma

Tek çağrılık sınıflandırma, özetleme, çeviri — düz bir API çağrısı yeter, harness ek yük olur
Adımları önceden belli, deterministik bir iş akışı — kod kontrollü bir pipeline daha öngörülebilir ve ucuzdur
Hazır harness'ın araçları (kabuk, dosya yazma) ortamın için fazla yetkiliyse ve bunları kısıtlayamıyorsan

Sık yapılan hatalar

Her başarısızlığı modele yüklemek

Ajanın takıldığı yerlerin çoğunda sebep eksik bir araç, belirsiz bir araç açıklaması, şişmiş bir bağlam ya da yanlış bir izin kuralıdır. Model değiştirmeden önce harness'ın modele ne gösterdiğine bak.

Harness'ı baştan yazmaya kalkmak

Temel döngü 20 satırdır; ama bağlam taşınca özetleme, izin kuralları, hata kurtarma, oturum kaydı ve kesintiye dayanıklılık haftalar sürer. Önce hazır bir harness ya da SDK dene.

Skorları harness'tan bağımsız sanmak

Bir ajan benchmark'ındaki skor, modelle birlikte kullanılan araç setine ve döngüye de bağlıdır. İki modeli karşılaştırırken harness'ı sabit tut.

allowed_tools'u kısıtlama sanmak

Claude Agent SDK'da allowed_tools listesi araçları sormadan onaylar; listede olmayan araçları yasaklamaz. Bir aracı modelin önünden kaldırmak için disallowed_tools kullan.