Temel Gerçekler: Yapay Zeka Ajanlarını Gerçekliğe Sabitlemek

Bu yazıdaki sayılar, yayınlandığı tarihteki (Ocak 2026) sistemi yansıtır. Güncel rakamlar için ekip sayfamıza bakın.

Yapay zeka ajanları dikkat çekici derecede yeteneklidir. Akıl yürütebilir, sentezleyebilir ve üretebilirler. Ama temel bir zayıflıkları vardır: bir şeyler uydururlar. Kötü niyetle değil, ama kendinden eminlikle. Bir ajan var olmayan API parametreleri icat edebilir, hiç tanımlanmamış yapılandırmalara başvurabilir veya eğitim verisinden gerçek mimarinizle çelişen desenler uygulayabilir.

Standart çözüm “ajana daha fazla bağlam ver”dir. Ama bağlam çelişkili olabilir. Dokümantasyon uygulamadan sapar. Yorumlar yalan söyler. Niyeti anlamadan okunduğunda kod bile yanıltıcı olabilir.

Daha açık bir şeye ihtiyacımız vardı. Görmezden gelinemeyecek veya yanlış yorumlanamayacak bir şeye. Ajanları doğrulanabilir gerçekliğe sabitleyecek bir şeye.

Bunlara Temel Gerçekler diyoruz.

Bir Temel Gerçek nedir?

Bir temel gerçek, ajanların saygı göstermesi gereken açık, sürümlenmiş bir gerçek ifadesidir. Dokümantasyon değildir. Yorum değildir. Sistemde şunlara sahip birinci sınıf bir varlıktır:

• Benzersiz bir tanımlayıcı (GT-MAG-015 veya GT-MAG-036 gibi)
• Bir yaşam döngüsü durumu (güncel, geçici veya kullanımdan kaldırılmış)
• Bir kapsam (platform geneli, pakete özgü veya alana bağlı)
• Kanıt (ifadeyi kanıtlayan dosya yolları, URL’ler veya referanslar)
• Ajan rehberliği (açık yap/yapma talimatları)

İşte Maguyva kod zekâsı platformumuzdan bir örnek:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Bu düz yazı değildir. Bir sözleşmedir. Bir ajan bu temel gerçekle karşılaştığında şunu bilir:

1. Varsayılan deterministiktir (bulanık tahminler değil, boş sonuçlar)
2. Tanımlanmış davranışlara sahip belirli parametreler vardır (find_similar, exact_match)
3. Doğrulanabilecek belirli dosyalarda kanıt vardır
4. İfade belirli bir tarihte doğrulanmıştır

Bir Temel Gerçek Kayıt Defterinin Anatomisi

Temel gerçekler, ai_assets/reference/ground_truths.yaml altındaki YAML kayıt defterlerinde yaşar. Her paket veya alan kendi kayıt defterine sahip olabilir. Yapı şöyledir:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Kayıt defteri, koleksiyonun kendisi hakkında meta veriler, dokümantasyon üretimi için render yapılandırması ve ifadelerin kendisini içerir. Her ifade, Pydantic modelleri tarafından doğrulanan katı bir şemayı izler:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Ajanlar Temel Gerçeklere Nasıl Erişir

Temel gerçekler birden fazla kanal üzerinden sunulur:

1. Render Edilmiş Dokümantasyon

orkestra sync komutu, YAML kayıt defterlerini okunabilir markdown’a dönüştürür:

uv run orkestra sync

Bu, ajan bağlamına dahil edilen GROUND_TRUTHS.md dosyaları üretir. Render edilen çıktı, ifadeleri duruma ve kategoriye göre gruplar:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI Araması

Kabuk erişimine sahip ajanlar, temel gerçekleri programatik olarak arayabilir:

uv run orkestra context ground-truths search "embedding"
uv run orkestra context ground-truths search --tag security
uv run orkestra context ground-truths list --status current

Arama fonksiyonu, birden fazla alan genelinde eşleşmeleri ağırlıklı alaka düzeyiyle puanlar:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Bağlam Kompozisyonu

Ajanlar YAML tanımlarından render edildiğinde, bağlamları temel gerçek kayıt defterlerine başvurabilir:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Bu, ilgili temel gerçeklerin ajan işe başlamadan önce yüklenmesini sağlar.

Temel Gerçek Kategorileri

Kayıt defterlerimize baktığımızda, temel gerçekler birkaç desende kümelenir:

Ürün İlkeleri

Ürünün ne olduğu ve ne olmadığı konusundaki kısıtlamalar:

“Maguyva, kullanıcı depoları açısından salt okunurdur; yeniden oluşturulamayan tek varlık ücretli gömme (embedding) önbelleğidir.” (GT-MAG-001)

Mimari Sınırlar

Sorumlulukların nerede yaşadığı ve nedeni:

“Pipeline ve Maguyva sınırları kasıtlıdır: pipeline yeniden kullanılabilirdir, Maguyva koda özgü mantığı tutar ve CQRS, aşama yazmalarını sunucu okumalarından ayırır.” (GT-MAG-006)

Halüsinasyon Karşıtı Kurallar

Araç sözleşmelerini çıkarımsal yerine deterministik tutan açık zorunluluklar:

“Bulanık sembol eşleştirme find_similar=true üzerinden isteğe bağlıdır. Varsayılan davranış, var olmayan semboller için boş sonuçlar döndürür; exact_match=true katı eşleştirmeyi zorunlu kılar ve tüm bulanık yedekleri devre dışı bırakır.” (GT-MAG-015)

Kalite Kapıları

Korunması gereken standartlar:

“Paylaşılan altyapıdaki değişiklikler (post_filters.py, ilişki çıkarıcıları, paylaşılan handler’lar), commit’ten önce tam manifest üretimi yoluyla DESTEKLENEN TÜM dillere karşı doğrulanMALIDIR. Tek dilli bir doğrulama, paylaşılan kod için yetersizdir.” (GT-MAG-036)

Kod Desenleri

Uygulama gereksinimleri:

“Asenkron bağlamlarda CPU ağırlıklı işler için asyncio.to_thread() kullanın; kullanımdan kaldırılan loop.run_in_executor() deseni yeni kodda kullanılmamalıdır.” (GT-MAG-018)

Bir Temel Gerçeğin Yaşam Döngüsü

Temel gerçekler statik değildir. Tanımlı bir yaşam döngüsü boyunca evrilirler:

Geçici

Değerlendirme aşamasında önerilen bir gerçek. İfade kayıt altına alınmıştır ama değişebilir:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Güncel

Ajanların saygı göstermesi gereken doğrulanmış bir gerçek. Kanıt doğrulanmıştır:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Kullanımdan Kaldırılmış

Artık geçerli olmayan bir gerçek. Neyin yerini aldığına dair bir işaretle birlikte tarihsel referans için tutulur:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Neden Sadece Dokümantasyon Değil?

Dokümantasyon farklı bir amaca hizmet eder. Açıklar. Öğretir. Belirsiz olabilir, “genellikle” veya “tipik olarak” gibi niteleyiciler kullanabilir.

Temel gerçekler belirsiz olamaz. Onlar iddialardır. Ya geçerlidirler ya da değildirler.

Farkı düşünün:

Dokümantasyon: “API, bir sembol bulunamadığında genellikle boş sonuçlar döndürür, ancak bazı yapılandırmalarda bulanık eşleştirme etkinleştirilmiş olabilir.”

Temel Gerçek: “Varsayılan davranış, var olmayan semboller için boş sonuçlar döndürür; exact_match=true katı eşleştirmeyi zorunlu kılar ve tüm bulanık yedekleri devre dışı bırakır.”

Birincisi, sistemi öğrenen insanlar için yardımcıdır. İkincisi, karar veren ajanlar için eyleme geçirilebilirdir.

Ajan Rehberliği: Yap ve Yapma

Bazı temel gerçekler açık ajan rehberliği içerir:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Bu, belirsizliği ortadan kaldırır. Bunu okuyan bir ajan yalnızca neyin doğru olduğunu değil, o gerçeğin hangi eylemleri ima ettiğini de bilir.

Doğrulama ve Bakım

Temel gerçekler bakım gerektirir. Şunları takip ederiz:

• last_verified: Birinin ifadenin hâlâ geçerli olduğunu ne zaman doğruladığı
• evidence: İfadeyi kanıtlayan dosyalar (varlığı kontrol edilebilir)
• source: Gerçeğin nereden kaynaklandığı (CLI incelemesi, mimari inceleme, olay sonrası öğrenme)

Eskimiş doğrulama tarihlerine veya bozuk kanıt bağlantılarına sahip bir temel gerçek, araştırılması gereken bir sinyaldir. Ya gerçek hâlâ geçerlidir ve yeniden doğrulama gerektirir, ya da gerçeklik değişmiştir ve gerçeğin güncellenmesi gerekir.

Üretimden Gerçek Örnekler

Güvenlik Sınırı

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Bu temel gerçek, ürünü bozacak bir sınıf yanlış yönlendirilmiş “güvenlik iyileştirmesini” önler.

Çıkarım Zamanı Doğruluğu

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Bu, acı verici bir deneyimden geldi. Ajanlar, başarısız olan dil paketlerini, test düzeneğini daha yeşil gösteren yalnızca doğrulayıcıya özgü filtreler ekleyerek yamalarken, canlı Maguyva çıkarıcısı hâlâ yanlış kenarlar yayınlıyordu. Kural, düzeltmeleri gerçek yola geri zorlar: YAML yapılandırması, sorgular veya handler’lar.

Çok Katmanlı Filtreleme

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Bu, ajanların filtreleri yanlış yere eklemesini önler; bu, doğruluk regresyonlarına neden olan yaygın bir hatadır.

Orkestrasyon Sistemiyle Entegrasyon

Temel gerçekler, daha geniş bir bağlam sisteminin bir katmanıdır:

1. Mimari Kararlar (ADR’ler) - A yaklaşımını B yerine neden seçtiğimizi kaydeder
2. Temel Gerçekler - Şu anda kesin olarak doğru olanı belirtir
3. Alan Desenleri - Bir şeylerin doğru şekilde nasıl yapılacağını açıklar
4. Anti-Desenler - Nelerden kaçınılması gerektiğini ve nedenini açıklar

Sistemde çalışan bir ajanın dördüne de erişimi vardır. Temel gerçekler olgusal çapayı sağlar, kararlar geçmişi açıklar, desenler uygulamaya rehberlik eder ve anti-desenler tuzaklara karşı uyarır.

Etkiyi Ölçmek

Temel gerçekleri tanıttığımızdan beri şunları gözlemledik:

• Daha az “halüsinasyonlu düzeltmeyi düzelt” döngüsü
• Gerçekler net olduğunda daha kendinden emin ajan karar verme
• Beklentiler açık olduğu için daha iyi PR incelemeleri
• Yeni ajanlar (ve insanlar) için azalan katılım süresi

Temel gerçekleri sürdürmeye yapılan yatırım, azalan hata ayıklama ve daha net sistem sınırları olarak geri döner.

Başlarken

Sisteminize bir temel gerçek eklemek için:

1. Paketinizin ai_assets/reference/ dizininde bir ground_truths.yaml oluşturun
2. Meta veriyi ve render yapılandırmasını tanımlayın
3. Şemayı izleyen ifadeler ekleyin
4. Dokümantasyon üretmek için uv run orkestra sync komutunu çalıştırın
5. Kayıt defterini ajan bağlam kompozisyonuna dahil edin

En çok kafa karışıklığına neden olan gerçeklerle veya en sık ihlal edilen kısıtlamalarla başlayın. Bunlar en yüksek değere sahip temel gerçeklerinizdir.

Sonuç

Yapay zeka ajanları halüsinasyon görecektir. Bu onların doğasıdır. Ama halüsinasyonun kısıtlandığı, belirli gerçeklerin pazarlık konusu olmadığı, ajanların varsayımlarını doğrulanmış gerçekliğe karşı kontrol edebildiği ortamlar yaratabiliriz.

Temel gerçekler eksiksiz bir çözüm değildir. Bakım gerektirirler. Eskiyebilirler. Geliştirme sürecine ek yük getirirler.

Ama değerli bir şey sağlarlar: hem insanların hem de ajanların güvenebileceği ortak bir gerçekler sözlüğü. Ajanların yazılım geliştirmeye giderek daha fazla katıldığı bir dünyada, bu paylaşılan temel vazgeçilmez hale gelir.

Alternatif, ajanların kendinden emin hatalar yapmasının ve insanların bunları düzeltmesinin sonsuz döngüleridir. Temel gerçekler, düzeltmeleri açık ve kalıcı hale getirerek bu döngüyü kırar.

Ajanlarınız neyin doğru olduğunu bilmeyi hak ediyor. Onlara söyleyin.