Kopya kâğıdı

AI ajan harness kopya kağıdı: bileşenler, dosyalar, sorunlar ve başlangıç kontrol listesi

Güncellendi: 12.10.2026 · Skillaria.Top

AI ajanın harness'i beş bileşenden oluşur: talimatlar, araçlar, ortam, durum ve geri bildirim. Asgari dosya seti şunlardır: yönlendirici bir giriş olarak AGENTS.md, kontrol betikleri (make check, verify.sh), ilerleme dosyası ve durumlu bir özellik listesi. Hazır işaretini ajan değil, betik koyar.

AI ajanın harness'inin beş bileşeni

Bileşen	Nedir	Eserler	Bozulma belirtisi
Talimatlar	Ajanın proje hakkında bilmesi gerekenler	AGENTS.md / CLAUDE.md, skills, docs/, ADR	Bilinen gelenekleri çiğner
Araçlar	Ajanın neler yapabildiği	shell, testler, linter, tarayıcı, MCP sunucuları	"Yapmak istiyor, yapamıyor"
Ortam	Ajanın nerede çalıştığı	lock dosyaları, Docker/devcontainer, git worktree, sandbox, init.sh	Oturum ortamı onarmakla başlar
Durum	Yeniden başlatmayı atlatan şeyler	PROGRESS.md, DECISIONS.md, feature_list.json, commit'ler	Yeni oturum nerede kaldığını bilmiyor
Geri bildirim	Ajanın hatasını nasıl öğrendiği	make check, E2E, hook'lar, arch-check, değerlendirici	"Hazır", ama çalışmıyor

Sıfırdan kurulum sırası: geri bildirim → talimatlar → durum → ortam → araçlar.

Harness dosyaları

Dosya	Görevi	Kural
AGENTS.md / CLAUDE.md	Giriş noktası: proje nedir, nasıl çalıştırılır, nasıl kontrol edilir	Kısa yönlendirici (yaklaşık 80 satır), "ne zaman okunmalı" koşullu belge bağlantıları
docs/*.md	Konuların ayrıntıları	İhtiyaç anında okunur, tamamı değil
.claude/skills/*/SKILL.md	Tekrarlanan süreçler (deploy, inceleme)	Görev açıklamasıyla eşleşince yüklenir
PROGRESS.md	Durum, yapılanlar, engeller, sonraki adımlar	Her oturumun sonunda güncellenir
DECISIONS.md	Karar, gerekçe, reddedilen seçenekler	Yalnızca sonucu değil, yolu da yazın
feature_list.json	Özellikler: behavior, verification, state	Tam olarak bir özellik active (WIP=1)
scripts/verify.sh	Özelliği kontrol edip passing yapar	Passing işaretini koyan tek kişi, commit SHA ile
scripts/arch-check.sh	Mimari sınırlar	Çıkış kodu 1 + çıktıda WHY ve FIX
scripts/init.sh	İş başlamadan ortam kontrolü	Ortam, temiz git, yeşil make check, aktif özellik
sprint contract	Koddan önce özellik sözleşmesi	Kapsamda / kapsam dışında / açık sorular
.claude/settings.json	Claude Code izinleri ve hook'ları	Kontroller olaylarda çalışır, ajanın hafızasında değil

AGENTS.md iskeleti

# Proje: ödeme backend'i (FastAPI, PostgreSQL)

## Çalıştırma
docker compose up -d && ./scripts/init.sh

## Kontrol
make check   # lint, tipler, unit, arch-check
make e2e     # uçtan uca senaryolar

## Definition of Done
- make check ve make e2e — kod 0
- özellik scripts/verify.sh ile passing yapıldı
- PROGRESS.md güncellendi

## MUST
- Veritabanı istekleri yalnızca repository'ler üzerinden
- Gizli bilgiler yalnızca ortam değişkenlerinden

## Belgeler
- docs/payments.md — iş ödeme ve iadelerle ilgiliyse
- docs/migrations.md — veritabanı şeması değişiyorsa

Özellik durumları

Durum	Anlamı	Kim değiştirir
pending	Sırada bekliyor	Planlayıcı
active	Üzerinde çalışılıyor (yalnızca bir tane)	Başlarken ajan
passing	Kontrol geçti	Yalnızca verify.sh
blocked	İnsan kararı gerekiyor	Ajan, nedeniyle birlikte

Doğrulama seviyeleri

Seviye	Ne	Ne zaman
1	Lint, tipler	Her zaman
2	Unit ve integration testleri	Her zaman
3	E2E	Birden fazla katman etkilendiğinde; "hazır" demeden önce
4	arch-check	Yeni katmanlar arası import'lar

"Hazır" deme yetkisi yalnızca en üst seviyeden sonra. Yeşil unit testler hazırlık değildir.

Kuralların mekanizasyonu

Seviye	Araç	Maliyet
grep-guard	Pattern arayan, WHY/FIX mesajı veren betik	Dakikalar
Linter kuralı	import-linter (Python), dependency-cruiser, eslint-plugin-boundaries (JS/TS)	Bir saat
Mimari test	Katmanlar bozulunca CI'da düşen test	Daha fazla, ama make check içinde görünür

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: servisler veritabanıyla doğrudan konuşmaz"
  echo "FIX: app/repositories/ içindeki repository'yi kullanın"
  fail=1
fi
exit $fail

Sık sorunlar ve çözümleri

Sorun	Bileşen	Çözüm
CLAUDE.md'deki kural uygulanmıyor	Talimatlar	Dosyayı kısaltın, kuralı kontrole veya hook'a dönüştürün
Ajan testleri çalıştıramıyor	Araçlar	Komuta izin verin, bağımlılıkları image'a ekleyin
Farklı makinelerde farklı davranış	Ortam	Lock dosyaları, Docker/devcontainer, sabit runtime sürümleri
Oturumlar arası unutkanlık	Durum	PROGRESS.md, session handoff, oturum başında okuma
Üç özellik başlatıldı, hiçbiri bitmedi	Durum	feature_list.json içinde WIP=1
"Hazır", ama çalışmıyor	Geri bildirim	DoD, E2E, verify.sh, bağımsız değerlendirici
Testler yeşil, özellik bozuk	Geri bildirim	Gerçek veritabanı ve yapılandırmayla E2E
Ajan kötü desenleri kopyalıyor	Geri bildirim	İlk günden arch-check
Ajanın ne yaptığı anlaşılmıyor	Durum	Küçük commit'ler, PROGRESS.md ve DECISIONS.md raporu
Ajan gece ortamı bozdu	Ortam	Sandbox, git worktree, checkpoint'ler, init.sh ile geri dönüş
Aynı yorum incelemede iki kez geldi	Tüm harness	make check içinde kontrole çevirin, metni talimatlardan çıkarın

Uzun görevlerdeki roller

Rol	Yapar	Yapmaz
Planlayıcı	Kabul kriterleriyle özellikler	Kod yazmaz
Üretici	Bir özelliği uygular, testleri çalıştırır	Hazır olup olmadığına karar vermez
Değerlendirici	Rubrikle hüküm verir, dosya, satır, log atfıyla	Üreticinin gerekçelerini görmez
Merge	review == pass olunca commit	Bu bir koddur, ajan değil

Özerk çalışma bütçesi

Hedef tek cümle olsun (örneğin tüm özellikleri passing yapmak).
WIP=1, özellik başına süre ve deneme sınırı.
Ölçüt yalnızca artsın, gerileme anında geri alma.
Migration'lar, altyapı, para: insana eskalasyon.
Birkaç başarısız incelemeden sonra özellik temiz context ile yeniden başlatılır.

Ajan başlatma kontrol listesi

AGENTS.md var: stack, çalıştırma, kontrol komutu, DoD.
make check temiz bir klonda geçiyor.
Ortam tekrarlanabilir: lock dosyaları, Docker veya devcontainer.
Ajanın gerekli komutlara erişimi var, tehlikeli olanlar kapalı veya sandbox'ta.
En azından ana senaryo için bir E2E var.
PROGRESS.md var ve oturum başında okunması kuralı konmuş.
Özellikler durumlarıyla listede, aktif olan yalnızca bir tane.
Passing işaretini betik koyuyor.
Kontrol mesajlarında WHY ve FIX var.
İş kabul kriterleri ve kapsam sınırlarıyla yazılmış.
İnsan kararı gerektiren konular belirlenmiş.
Değişikliklerden önce verification gap ölçülmüş, karşılaştırma için.

Harness metrikleri

Metrik	Nasıl hesaplanır
Verification gap	10 görevde "hazır" denip kontrolle doğrulanmayanların oranı
MTTR	Bozulmadan çalışır duruma dönüşe kadar geçen süre
Soğuk başlangıç	Yeni oturum "neredeyiz, sırada ne var" sorularını tahmin etmeden yanıtlayabiliyor mu
Ablation	Sabit görev kümesinde bir bileşen kapatıldığında düşüş

Özet

Harness bir dosya değil, bir döngüdür: talimatlar, araçlar, ortam, durum ve geri bildirim. Kontrolle başlayın, AGENTS.md'yi kısa tutun, hazır işaretini betiğe bırakın ve harness'i düzenli olarak gözden geçirin. Bütün bunlar gerçek bir proje üzerinde, tek bir harness içinde birleştirilerek uygulamalı bir kursta öğretilmektedir.

Sık sorulan sorular

AGENTS.md ile CLAUDE.md arasındaki fark nedir?

Amaç aynıdır: ajan için talimat dosyası. CLAUDE.md'yi Claude Code okur, AGENTS.md ise birçok ajanın ortak formatıdır. CLAUDE.md içine yalnızca <code>@AGENTS.md</code> yazarak ikisini bağlayabilirsiniz.

AGENTS.md kaç satır olmalı?

Kesin bir sınır yok, ama giriş dosyasını bir içindekiler gibi kısa tutun; yaklaşık yüz satır civarı. Ayrıntılar ayrı belgelere taşınır.

Küçük bir projede feature_list.json gerekir mi?

Tek seferlik küçük değişiklikler için gerekmez. Ajan art arda birçok özellik üzerinde ya da birçok oturumda çalışıyorsa değeri ortaya çıkar.

Ajanın erişmesi gereken gizli bilgileri nerede tutmalıyım?

Ortam değişkenlerinde veya bir secrets yöneticisinde; talimat dosyalarında ve kodda değil. Ajana ortama erişim verin, değerleri metinde vermeyin.

Bu konuyu videoyla öğrenin

Bu konu “Harness Engineering: AI Ajanları İçin Güvenilirlik Mühendisliği” kursunda uygulamalı olarak ayrıntılı işleniyor.

Kursa git