Grundwahrheiten: KI-Agenten in der Realität verankern

Die Zahlen in diesem Beitrag spiegeln den Stand des Systems zum Veröffentlichungszeitpunkt (Januar 2026) wider. Aktuelle Zahlen findest du auf unserer Team-Seite.

KI-Agenten sind bemerkenswert leistungsfähig. Sie können schlussfolgern, synthetisieren und generieren. Aber sie haben eine grundlegende Schwäche: Sie erfinden Dinge. Nicht böswillig, aber mit großer Überzeugung. Ein Agent könnte API-Parameter erfinden, die nicht existieren, Konfigurationen referenzieren, die nie definiert wurden, oder Muster aus seinen Trainingsdaten anwenden, die deiner tatsächlichen Architektur widersprechen.

Die Standardlösung lautet „gib dem Agenten mehr Kontext“. Aber Kontext kann widersprüchlich sein. Dokumentation driftet von der Implementierung ab. Kommentare lügen. Selbst Code kann irreführen, wenn er ohne Verständnis der Intention gelesen wird.

Wir brauchten etwas Expliziteres. Etwas, das nicht ignoriert oder falsch interpretiert werden konnte. Etwas, das Agenten an überprüfbarer Realität verankert.

Wir nennen sie Grundwahrheiten.

Was ist ein Ground Truth?

Ein Ground Truth ist eine explizite, versionierte Tatsachenaussage, die Agenten respektieren müssen. Es ist keine Dokumentation. Es ist kein Kommentar. Es ist eine erstklassige Entität im System mit:

• Einer eindeutigen ID (wie GT-MAG-015 oder GT-MAG-036)
• Einem Lifecycle-Status (current, tentative oder deprecated)
• Einem Scope (plattformweit, paketspezifisch oder domänengebunden)
• Evidenz (Dateipfade, URLs oder Referenzen, die die Aussage belegen)
• Agent-Guidance (explizite Do/Avoid-Anweisungen)

Hier ist ein Beispiel aus unserer Maguyva-Code-Intelligence-Plattform:

- 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

Das ist keine Prosa. Es ist ein Vertrag. Wenn ein Agent auf diesen Ground Truth trifft, weiß er:

1. Der Standard ist deterministisch (leere Ergebnisse, keine unscharfen Vermutungen)
2. Es gibt bestimmte Parameter (find_similar, exact_match) mit definiertem Verhalten
3. Es gibt Evidenz in bestimmten Dateien, die überprüft werden kann
4. Die Aussage wurde an einem bestimmten Datum verifiziert

Die Anatomie einer Ground-Truth-Registry

Grundwahrheiten leben in YAML-Registries unter ai_assets/reference/ground_truths.yaml. Jedes Paket oder jede Domäne kann seine eigene Registry haben. Die Struktur ist:

metadata:
  title: "Maguyva Grundwahrheiten"
  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..."
    ...

Die Registry enthält Metadaten über die Sammlung selbst, eine Render-Konfiguration für die Dokumentationsgenerierung, und die Aussagen selbst. Jede Aussage folgt einem strikten, durch Pydantic-Modelle validierten Schema:

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

Wie Agenten auf Grundwahrheiten zugreifen

Grundwahrheiten werden über mehrere Kanäle bereitgestellt:

1. Gerenderte Dokumentation

Der Befehl orkestra sync wandelt YAML-Registries in lesbares Markdown um:

uv run orkestra sync

Das erzeugt GROUND_TRUTHS.md-Dateien, die in den Agent-Kontext einbezogen werden. Die gerenderte Ausgabe gruppiert Aussagen nach Status und Kategorie:

## Current
### Produktprinzipien
- 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-Suche

Agenten mit Shell-Zugriff können Grundwahrheiten programmatisch durchsuchen:

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

Die Suchfunktion bewertet Treffer über mehrere Felder hinweg mit gewichteter Relevanz:

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. Kontext-Komposition

Wenn Agenten aus YAML-Definitionen gerendert werden, kann ihr Kontext auf Ground-Truth-Registries verweisen:

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

Das stellt sicher, dass relevante Grundwahrheiten geladen werden, bevor der Agent mit der Arbeit beginnt.

Kategorien von Grundwahrheiten

Betrachtet man unsere Registries im Ganzen, clustern sich Grundwahrheiten in mehrere Muster:

Produktprinzipien

Einschränkungen darüber, was das Produkt ist und was nicht:

„Maguyva ist gegenüber Nutzer-Repositories rein lesend; das einzige nicht wiederherstellbare Asset ist der bezahlte Embeddings-Cache.“ (GT-MAG-001)

Architekturgrenzen

Wo Verantwortlichkeiten liegen und warum:

„Die Grenzen zwischen Pipeline und Maguyva sind beabsichtigt: Pipeline ist wiederverwendbar, Maguyva enthält codespezifische Logik, und CQRS trennt Stage-Writes von Server-Reads.“ (GT-MAG-006)

Anti-Halluzinations-Regeln

Explizite Vorgaben, die Tool-Contracts deterministisch statt erraten halten:

„Unscharfes Symbol-Matching ist über find_similar=true Opt-in. Das Standardverhalten liefert leere Ergebnisse für nicht existierende Symbole; exact_match=true erzwingt striktes Matching und deaktiviert alle Fuzzy-Fallbacks.“ (GT-MAG-015)

Qualitätsgates

Standards, die eingehalten werden müssen:

„Änderungen an gemeinsam genutzter Infrastruktur (post_filters.py, Relationship-Extraktoren, gemeinsame Handler) MÜSSEN vor dem Commit per Full-Manifest-Generierung gegen ALLE unterstützten Sprachen validiert werden. Eine Einzelsprachen-Validierung reicht für gemeinsam genutzten Code nicht aus.“ (GT-MAG-036)

Code-Muster

Implementierungsanforderungen:

„Verwende asyncio.to_thread() für CPU-lastige Arbeit in Async-Kontexten; das veraltete loop.run_in_executor()-Muster sollte in neuem Code nicht mehr verwendet werden.“ (GT-MAG-018)

Der Lebenszyklus eines Ground Truth

Grundwahrheiten sind nicht statisch. Sie durchlaufen einen definierten Lebenszyklus:

Tentative

Eine vorgeschlagene Wahrheit unter Bewertung. Die Aussage ist festgehalten, kann sich aber noch ändern:

- 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.

Current

Eine verifizierte Wahrheit, die Agenten respektieren müssen. Die Evidenz wurde validiert:

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

Deprecated

Eine Wahrheit, die nicht mehr gilt. Zur historischen Referenz aufbewahrt, mit einem Verweis darauf, was sie ersetzt hat:

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

Warum nicht einfach Dokumentation?

Dokumentation dient einem anderen Zweck. Sie erklärt. Sie lehrt. Sie kann vage sein, kann Qualifizierer wie „im Allgemeinen“ oder „typischerweise“ verwenden.

Grundwahrheiten dürfen nicht vage sein. Sie sind Behauptungen. Sie gelten entweder, oder sie gelten nicht.

Betrachte den Unterschied:

Dokumentation: „Die API liefert im Allgemeinen leere Ergebnisse, wenn ein Symbol nicht gefunden wird, obwohl in manchen Konfigurationen Fuzzy-Matching aktiviert sein kann.“

Ground Truth: „Das Standardverhalten liefert leere Ergebnisse für nicht existierende Symbole; exact_match=true erzwingt striktes Matching und deaktiviert alle Fuzzy-Fallbacks.“

Die erste ist hilfreich für Menschen, die das System lernen. Die zweite ist umsetzbar für Agenten, die Entscheidungen treffen.

Agent-Guidance: Do und Avoid

Manche Grundwahrheiten enthalten explizite Agent-Guidance:

- 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"

Das entfernt Mehrdeutigkeit. Ein Agent, der das liest, weiß nicht nur, was wahr ist, sondern auch, welche Handlungen diese Wahrheit impliziert.

Verifikation und Wartung

Grundwahrheiten brauchen Wartung. Wir verfolgen:

• last_verified: Wann jemand bestätigt hat, dass die Aussage noch gilt
• evidence: Dateien, die die Aussage belegen (können auf Existenz geprüft werden)
• source: Wo die Wahrheit herstammt (CLI-Inspektion, Architektur-Review, Learning nach einem Vorfall)

Ein Ground Truth mit veralteten Verifikationsdaten oder defekten Evidenz-Links ist ein Signal zum Nachforschen. Entweder ist die Wahrheit noch gültig und braucht erneute Verifikation, oder die Realität hat sich geändert und die Wahrheit muss aktualisiert werden.

Echte Beispiele aus der Produktion

Sicherheitsgrenze

- 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.

Dieser Ground Truth verhindert eine Klasse von fehlgeleiteten „Sicherheitsverbesserungen“, die das Produkt kaputt machen würden.

Genauigkeit zur Extraktionszeit

- 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.

Das kam aus schmerzhafter Erfahrung. Agenten patchten fehlschlagende Language-Packs, indem sie nur-Validator-Filter hinzufügten, die den Testharness grüner aussehen ließen, während der Live-Maguyva-Extraktor weiterhin die falschen Kanten ausgab. Die Regel zwingt Fixes zurück in den echten Pfad: YAML-Konfiguration, Queries oder Handler.

Mehrstufiges Filtering

- 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).

Das verhindert, dass Agenten Filter am falschen Ort hinzufügen — ein häufiger Fehler, der Genauigkeits-Regressionen verursacht hat.

Integration mit dem Orchestrierungssystem

Grundwahrheiten sind eine Schicht eines größeren Kontextsystems:

1. Architekturentscheidungen (ADRs) – Dokumentieren, warum wir Ansatz A statt B gewählt haben
2. Grundwahrheiten – Sagen aus, was gerade definitiv wahr ist
3. Domain Patterns – Beschreiben, wie man Dinge richtig macht
4. Anti-Patterns – Beschreiben, was zu vermeiden ist und warum

Ein Agent, der im System arbeitet, hat Zugriff auf alle vier. Grundwahrheiten liefern den faktischen Anker, während Decisions die Geschichte erklären, Patterns die Implementierung anleiten und Anti-Patterns vor Fallstricken warnen.

Wirkung messen

Seit der Einführung von Grundwahrheiten haben wir beobachtet:

• Weniger „den halluzinierten Fix reparieren“-Zyklen
• Selbstbewusstere Agent-Entscheidungen, wenn Fakten klar sind
• Bessere PR-Reviews, weil Erwartungen explizit sind
• Kürzere Onboarding-Zeit für neue Agenten (und Menschen)

Die Investition in die Pflege von Grundwahrheiten zahlt sich in weniger Debugging und klareren Systemgrenzen aus.

Erste Schritte

Um einen Ground Truth zu deinem System hinzuzufügen:

1. Erstelle ein ground_truths.yaml im ai_assets/reference/-Verzeichnis deines Pakets
2. Definiere Metadaten und Render-Konfiguration
3. Füge Aussagen nach dem Schema hinzu
4. Führe uv run orkestra sync aus, um Dokumentation zu generieren
5. Binde die Registry in die Agent-Kontext-Komposition ein

Beginne mit den Fakten, die die meiste Verwirrung stiften, oder den Einschränkungen, die am häufigsten verletzt werden. Das sind deine wertvollsten Grundwahrheiten.

Fazit

KI-Agenten werden halluzinieren. Das liegt in ihrer Natur. Aber wir können Umgebungen schaffen, in denen Halluzination eingegrenzt ist, in denen bestimmte Fakten nicht verhandelbar sind, in denen Agenten ihre Annahmen gegen verifizierte Realität abgleichen können.

Grundwahrheiten sind keine vollständige Lösung. Sie brauchen Wartung. Sie können veralten. Sie fügen dem Entwicklungsprozess Overhead hinzu.

Aber sie liefern etwas Wertvolles: ein gemeinsames Vokabular an Fakten, dem sowohl Menschen als auch Agenten vertrauen können. In einer Welt, in der Agenten zunehmend an der Softwareentwicklung teilnehmen, wird dieses gemeinsame Fundament essenziell.

Die Alternative sind endlose Zyklen, in denen Agenten selbstbewusst Fehler machen und Menschen sie korrigieren. Grundwahrheiten durchbrechen diesen Zyklus, indem sie die Korrekturen explizit und dauerhaft machen.

Deine Agenten haben es verdient zu wissen, was wahr ist. Sag es ihnen.