ContextRail: Agentic Coding İçin Minimum Etkili Proje Hafızası

Agent session’ları arası hafıza kaybını, dosya karmaşasını ve context kirliliğini 5 Markdown katmanı ve 3 platform validator’ı ile çözen açık kaynak harness çerçevesi.

ContextRail, AI agent’ların bir yazılım projesinde uzun süreli, tutarlı ve denetlenebilir biçimde çalışabilmesi için tasarlanmış açık kaynak bir harness çerçevesidir. Agent yeni bir session başlattığında projenin neresinde kaldığını, aktif görevi, alınan kararları ve geçmiş denemeleri dosya karmaşasına veya context kirliliğine yol açmadan 5 Markdown katmanı ve platform doğrulayıcılarıyla koordine eder.

Proje Künyesi

Alan	Değer
Rol	Tasarım, mimari geliştirme, dokümantasyon
Durum	Stable
Kapsam	Agent ile yazılım geliştirme projeleri
Teknolojiler	Markdown, Bash, PowerShell, GitHub Actions
Lisans	MIT
Dağıtım	GitHub Template Repository + GitHub Release

Çıkış Noktası ve İhtiyaç

Agentic coding araçları (Codex, Claude Code, Gemini, Cursor vb.) hızla güçleniyor. Fakat hepsinin ortak bir zayıf noktası var: proje hafızası.

Agent tek bir session içinde iyi çalışabilir. Ama session bittiğinde:

Aktif görev kaybolur.
Alınan kararlar unutulur.
Sonraki session aynı keşfi yeniden yapar.
Aynı hata tekrar yapılabilir.
İnsanın her seferinde yeniden bağlam kurması gerekir.

Piyasada bunu çözmeye çalışan yaygın yaklaşım: devasa AGENTS.md dosyaları, yüzlerce küçük Markdown dosyası veya karmaşık planlama sistemleri. Bunların hepsinde aynı problem var: ya context’i şişiriyorlar ya da agent’ın neyi nerede bulacağını bilemediği bir karmaşıklık yaratıyorlar.

ContextRail’in hedefi farklı: Mümkün olan en az dosyayla, agent’ın nerede durduğunu, ne yapacağını ve neyi neden yaptığını bilmesini sağlamak.

Mimari Akış ve Yaşam Döngüsü

ContextRail bunu yaşam döngülerine göre ayrılmış 5 Markdown katmanıyla çözer:

AGENTS.md — Agent nasıl çalışmalı?
SYSTEM.md — Proje tanımı, sınırları ve değişmezleri (invariant’lar)
BOARD.md — Şu anda ne yapılacak?
NOTES.md — Neden böyle yapılacak?
HISTORY.md — Daha önce ne yapıldı, nasıl doğrulandı?

Bu 5 katmanın üstüne üç platformda çalışan native validator script’leri (Bash, PowerShell, GitHub Actions) eklenir. Framework, SDK veya kütüphane bağımlılığı yoktur; herhangi bir repoya doğrudan kopyalanabilir.

Kapsam ve Sınırlar

ContextRail şunları yapar:

Agent’a session başlangıcında net bir giriş noktası verir.
Aktif iş, karar gerekçesi ve geçmiş uygulamayı farklı lifecycle katmanlarına ayırır.
Agent’ı broad scan yerine hedefli bilgi erişimine yönlendirir.
Benzersiz ID’lerle karar ve görevleri adreslenebilir hale getirir.
Dış kaynaklardan gelen spesifikasyon, değerlendirme ve planları yapılandırılmış handoff süreci ile alır.
Kodda görev bağlantılı izleme yorumları (task-linked code trace) ile karar-kod ilişkisini sürdürür.
Metadata sözleşmesini üç işletim sisteminde mekanik olarak doğrular.
Projenin mevcut test/build/lint zincirine entegre olarak tek bir ana doğrulama komutu oluşturur.
Farklı agent platformlarıyla uyumlu çalışır (Codex, Claude Code, Gemini, Cursor, Copilot).

ContextRail şunları yapmaz:

Yeni bir programlama dili veya framework dayatmaz.
SDK veya kütüphane yüklemez.
Kendi test framework’ünü kurmaz; mevcut proje altyapısına bağlanır.
Semantic search, embedding veya graph database gerektirmez.
Proje yönetimi aracı, planlama derleyicisi veya multi-agent orchestration platformu değildir.
Agent’ın kendi planner’ını devre dışı bırakmaz.

Çözüm Mimarisi

Lifecycle Ayrımı

Bilgi dosya sayısına göre değil, yaşam döngüsüne göre ayrılır:

AGENTS.md → Çalışma kuralları ve navigation haritası
SYSTEM.md → Proje tanımı, bileşenler, sınırlar, invariant’lar
BOARD.md → Aktif görevler ve mevcut durum
NOTES.md → Karar gerekçeleri, teknik kısıtlamalar, kalıcı ürün hafızası
HISTORY.md → Tamamlanmış görevler ve doğrulama kanıtları

Agent, BOARD.md dosyasından aktif görevi bulur. Görevdeki karar kimliğiyle NOTES.md dosyasında yalnızca ilgili bölümü açar. HISTORY.md dosyasına ancak geçmiş bir uygulamayı doğrulaması gerekirse gider.

External Handoff Mekanizması

Dış kaynaklardan gelen ham spesifikasyonlar, değerlendirmeler ve planlar handoffs/incoming/ dizinine bırakılır. Agent, handoffs/HANDOFF.md dosyasındaki süreci izler: önce mevcut ID’lerde arama yapar, kalıcı anlamı Notes’a aktarır, bağımsız olarak doğrulanabilir Board görevleri türetir, çakışmaları raporlar, sonucu doğrular ve ancak o zaman kaynak paketi taşır veya kaldırır.

Görev Bağlantılı Kod İzlemesi

Kalıcı davranış sınırları kodda kısa bir native yorum ile işaretlenir:

ContextRail: TASK-0042
Invariant: Persistent mutation requires explicit authorization.

Görev, gerekçe ve ilişkilerin tamamını taşır. Kod yorumu yalnızca mevcut davranışı en iyi açıklayan görevi tanımlar; tüm tarihsel düzenlemeleri listelemez. Aynı işaret, görev test edilebilir çalışma zamanı davranışı oluşturuyorsa ilgili regresyon testine de eklenir.

Agent Uyumluluk Katmanı

Farklı platformların kendi konfigürasyon dosyaları desteklenir:

CLAUDE.md → Claude Code
GEMINI.md → Gemini
.github/copilot-instructions.md → GitHub Copilot
.cursor/rules/00-agents.mdc → Cursor

Hepsi aynı şeyi söyler: “Önce kökteki AGENTS.md dosyasını oku ve uygula.” Kural kopyalamaz, yönlendirir.

Cross-Platform Validator’lar

scripts/
  validate-linux.sh
  validate-macos.sh
  validate-windows.ps1

Validator’lar projenin dilinden bağımsız çalışır. Python, Node.js, Go veya herhangi bir proje runtime’ı gerektirmez. Yalnızca Markdown metadata sözleşmesini kontrol eder:

Zorunlu dosya ve SYSTEM.md bölümleri mevcut mu?
System dosyasına yanlışlıkla lifecycle kaydı yazılmış mı?
Aynı ID iki defa kullanılmış mı?
Aynı normalize edilmiş kayıt başlığı farklı kimliklerle tekrar edilmiş mi?
Aynı stabil kimliğin başlığı tutarsız mı?
Board’da geçersiz status var mı?
Board, Notes ve History kayıtlarında zorunlu alanlar eksik mi?
Tamamlanan veya iptal edilen görevde tarih eksik mi?
Tamamlanan görevde evidence veya outcome eksik mi?
Board ve History’de aynı görev aynı anda var mı?
Orphan görev detayı var mı?
Related, Supersedes ve Replacement referansları kırık mı?
Kabul edilmiş kararlar mevcut sistem doğrusuna yansıtılmış mı?
Koddaki task-linked yorumlar mevcut olmayan lifecycle veya Notes kaydına mı işaret ediyor?
Task-linked yorumların yanında boş olmayan invariant açıklaması var mı?
System haritası sınırlı boyutu aşmış mı?

Agent “işi tamamladım” dediğinde validator bunu mekanik olarak doğrular.

İki Repo, İki Dağıtım Kanalı, Tek Bakım Noktası

minimum-governed-harness geliştirme, dokümantasyon ve release deposudur.
contextrail-template kullanıcıya yönelik temiz template repository’dir.

Yeni projeler doğrudan template repository’den, mevcut projeler ise GitHub Release sayfasından versiyonlanmış ZIP ile kurulabilir. Her release’de ZIP checksum ve manifest dosyaları da yayımlanır.

Geliştirme Süreci ve Governance Kuralları

ContextRail yalnızca dosya yapısı değil, agent’ın çalışma disiplinini de tanımlar:

External Handoff Adoption: Dış kaynaklardan gelen paketler yapılandırılmış süreçle alınır; duplikasyon kontrolü yapılır, çakışmalar raporlanır.
Task-Linked Code Trace: Kalıcı davranış sınırları kodda ve ilgili regresyon testinde görev kimliğiyle işaretlenir.
Root Cause Before Patch: Agent, ihlal edilen invariant veya durum geçişini tespit etmeden yama eklemez. Testler bir davranış sınıfını kanıtlar.
Independent Review: Agent kendi diff’ini bağımsız reviewer gibi inceler. Tamamlama iddiaları nesnel çıktıya dayandırılır.
Controlled Incidental Findings: Görev sırasında görülen ilgisiz hatalar kanıtla raporlanır, sessizce düzeltilmez.
Ana Doğrulama Entegrasyonu: Agent, ilk önemli kullanımda projenin mevcut test, build ve lint zincirini keşfeder ve validator’ı bu zincire entegre eder.
Governed Delegation: Agent, sınırlı ve düşük riskli işleri alt agent’lara devredebilir; mimari kararlar ve hafıza güncellemeleri ana agent’ta kalır.
Version Awareness & User-Owned Instructions: .contextrail-version ve kullanıcıya ait talimat bloğu güncellemelerde korunur.
Reuse-First Engineering: Özel altyapı varsayılan başlangıç değildir; ekosistemdeki mevcut çözümler değerlendirilir.

Mevcut Durum ve Açık Kaynak Dağıtımı

Proje açık kaynak ve stabil sözleşme altındadır:

Ana Repo: github.com/muisik/minimum-governed-harness — Public, MIT lisanslı
Template Repo: github.com/muisik/contextrail-template — GitHub Template Repository
Sürümler: GitHub Releases üzerinden checksum ve manifest ile indirilebilir ZIP paketleri
Platform Uyumluluğu: Codex, Claude Code, Gemini, Cursor, GitHub Copilot

📋 İlgili Bağlantılar

🔗 Teknik Analiz: Agent’a Her Şeyi Anlatma, Nereye Bakacağını Öğret
📂 Ana Repo: github.com/muisik/minimum-governed-harness
🛠️ Template Repo: github.com/muisik/contextrail-template

Son güncelleme: Ekim 2026 | Versiyon: 1.0