AI kod ajanlarını güvenilir kılan çevreyi tasarla.
Modeli değil — modeli kuşatan düzeneği (harness).

Tez · İçerik · Hızlı başlangıç · Öğrenme yolu · Kaynaklar · Katkı

---

Tez

Modern AI kod ajanları — Claude, GPT, Gemini — bir vakum içinde çalışmaz. Bir düzenek (harness) içinde çalışır: repo, durum, geri bildirim, doğrulama ve gözlemlenebilirlik. Bir görev başarısız olduğunda refleks, modeli değiştirmek olur; çoğu zaman yanlış katman.

Aynı model, farklı düzenek, farklı sonuç. Modeli değil; modeli kuşatan düzeneği bir mühendislik problemi olarak ele al.

Bu repo, o düzeneği inşa etmenin Türkçe açık kaynak müfredatıdır. 12 teorik ders, 6 kümülatif proje, 8 üretime hazır şablon, ve bir skill paketi. Hedef kitle: Claude Code, Codex ve benzeri AI ajanlarla üretim yapan yazılım mühendisleri.

İçerik

12 Ders Her ders bir anti-örüntü teşhisi: yetkin ajanlar neden başarısız olur, hangi mekanizma çözer, hangi saha kanıtıyla. "Aynı Model, Farklı Sonuç" → "Temiz Teslim" dersler/01..12	6 Proje Kümülatif Notes API üzerinde starter/ + solution/ zinciri. Her proje önceki çözümün üzerine bir aparat ekler. Kural önceliği → Capstone projeler/01..06
8 Şablon Kopyala-kullan iskelet: AGENTS.md, PROGRESS.md+DECISIONS.md, Makefile+init.sh, features.json, verifier.md+DoD, sprint+rubrik, OTel trace, session-close. kutuphane/	Skill Pack Claude Code / OpenClaw uyumlu yetenek paketi. Workflow + recipe + template + script — ajanın kendi reposunda düzenek kurabilmesi için. skill-pack/duzenek-yaratici/

Düzeneğin temel mekanizması

Bir düzenek, modeli çevre yoluyla yönlendirir. Beş aparatı vardır:

Aparat	Sorumluluk
Repo	Tek hakikat kaynağı. Talimat, kod ve karar tarihçesi burada yaşar.
Durum (state)	Oturumlar arası süreklilik. PROGRESS.md, DECISIONS.md, init script'leri.
Çalışma zamanı geri bildirimi	Ajan kendi kodunu test eder, hataları görür, düzeltir.
Öz-doğrulama (self-verification)	Bağımsız rol ayrımı; halüsinasyon ve "erken zafer ilanı" engellenir.
Gözlemlenebilirlik (observability)	Her eylem izlenebilir; başarısızlık sessizce gerçekleşmez.

Hızlı başlangıç

git clone https://github.com/komunite/harness-docs.git
cd harness-docs

# Mintlify CLI ile yerel önizleme
npm install -g mint
mint dev
# → http://localhost:3000

Search ve AI assistant'ı yerelde etkinleştirmek için mint login. İçerik bütünlüğünü doğrulamak için:

mint validate         # MDX + frontmatter + nav
mint broken-links     # iç linkler çözülüyor mu

Öğrenme yolu

       teorik zemin          uygulama          sentez
            │                    │                │
   ┌────────┴────────┐  ┌────────┴────────┐  ┌────┴─────┐
   │   12 Ders       │→ │   6 Proje       │→ │ Capstone │
   │   (dersler/)    │  │   (projeler/)   │  │  Proje 6 │
   └─────────────────┘  └─────────────────┘  └──────────┘
            │                    │
            └──── 8 Şablon ──────┘
                (kutuphane/)

1. Ders 01 — Yetkin Ajanlar Neden Hâlâ Başarısız Oluyor ile teorik zemini kur.
2. Proje 01 — Kural Öncelikli ile farkı kendi gözünle gör.
3. Her dersi karşılığındaki projeyle eşleştir. Capstone'a kadar düzenek üzerine düzenek inşa et.

Repo yapısı

.
├── index.mdx                       # giriş
├── dersler/        01..12          # 12 teorik ders
├── projeler/       01..06          # 6 proje (her biri *.mdx + 0N/{starter,solution}/)
├── kutuphane/                      # 8 şablon + genel bakış
├── skill-pack/duzenek-yaratici/    # Claude Code / OpenClaw uyumlu yetenek paketi
├── images/                         # OG cover + brand assets
├── logo/                           # marka logosu
├── style.css                       # marka paleti override
└── docs.json                       # Mintlify konfigürasyonu + SEO/OG

Deploy

Site, Mintlify'ın açık CLI'ındaki mint export komutuyla statik siteye çevrilir ve Vercel üzerinde self-host edilir. main dalına push olduğunda Vercel, scripts/build-static.sh betiğini koşar (bkz. vercel.json) ve çıktıyı yayınlar.

• Özel alan adı: harness.komunite.com.tr
• TLS sertifikası Vercel tarafından otomatik yönetilir
• Eski adres harness.lokomotif.ai kalıcı (301) olarak yeni adrese yönlenir
• Statik modda Mintlify'ın hosted search ve AI assistant özellikleri çalışmaz; arama UI'ı build sırasında gizlenir

Mintlify yapılandırması docs.json dosyasındadır; SEO ve Open Graph yapılandırması aynı dosyadaki seo.metatags bloğundadır.

Kaynaklar

Müfredat, birincil kaynaklara dayanır. Her ders kullandığı kaynakları cite eder.

• Anthropic — Effective Harnesses for Long-Running Agents, Harness Design for Long-Running Apps, Infrastructure Noise
• OpenAI — Harness Engineering for Codex
• HumanLayer — Skill Issue, Writing a Good CLAUDE.md, 12-Factor Agents
• Thoughtworks / Martin Fowler — düzenek mühendisliği üzerine
• Manus — Context Engineering
• OpenHands, LangChain, OpenTelemetry GenAI semconv
• walkinglabs — Learn Harness Engineering (ilham veren müfredat, CC0)

AI ajanlar için

Bu repo aynı zamanda AI kod ajanları için bir referans projedir. Kendi reposunda çalışan bir ajan şu üç dosyayı okur:

• CLAUDE.md — yönlendirici talimat dosyası (sıkı kısıtlar, konu dokümanları haritası, vardiya rutinleri)
• MEMORY.md — projenin yapım hikâyesi, alınmış kararlar, terim haritası, sıradaki adımlar
• skill-pack/duzenek-yaratici/ — başka bir repoda kullanılmak üzere kopyalanabilen yetenek paketi

Katkı

Hata raporu, geliştirme önerisi, çeviri — her şey memnuniyetle karşılanır.

Konu	Yer
Hata raporu / öneri	GitHub Issues
Pull request kuralları	CONTRIBUTING.md
Davranış kuralları	CODE_OF_CONDUCT.md
Güvenlik bildirimi	SECURITY.md

Lisans

CC0 1.0 Universal — kamu malı. Atıf zorunlu değildir; takdir edilir.

Düzenek Mühendisliği (Harness Engineering) — Lokomotif.ai
https://harness.komunite.com.tr

Bağlantılar

• Site: harness.komunite.com.tr
• GitHub: github.com/komunite/harness-docs
• İlham veren müfredat: walkinglabs/learn-harness-engineering (CC0)
• İlgili koleksiyon: walkinglabs/awesome-harness-engineering (CC0)

_{Düzenek Mühendisliği · Lokomotif.ai · 2026}