Architekturregeln gehören in den Harness.

Was gehört zu einem Agent-Harness?

Ein Agent-Harness ist die Umgebung, die einen Agenten mit Kontext, Werkzeugen, Ausführung und Rückmeldungen verbindet. Harness Engineering gestaltet diese Umgebung: Welche Entscheidungen darf der Agent treffen? Welche Zustände sieht er? Welche Prüfung muss eine Änderung bestehen?

Die folgende Aufteilung ist unser Arbeitsmodell, kein etablierter Standard. Die Ebenen ergänzen sich; ein Werkzeug kann mehrere abdecken.

Ein Plugin ist zunächst die Verpackung von Fähigkeiten. Ein Skill beschreibt einen Arbeitsablauf oder liefert Fachwissen. Beides kann zum Harness beitragen. Verbindlich wird eine Regel erst, wenn der ausführende Workflow sie prüft und auf das Ergebnis reagiert.

Superpowers · GitHub ↗

DATAMIMIC CE: eine Testdatenwelt aus der Spezifikation

Eine leere Datenbank lässt viele Anforderungen unsichtbar. Modelle können Beziehungen, Status, Grenzwerte und fachliche Ausnahmen ausdrücklich festhalten. Dadurch bekommt der Implementierungsagent konkrete Fälle, gegen die er arbeiten kann. Das Modell bleibt als versionierbare Datei für Menschen reviewbar, wartbar und erweiterbar.

DATAMIMIC CE unterstützt Agent-Authoring über CLI und einen optionalen MCP-Adapter. Neue Absichten bleiben in model.dm.json erhalten. Der Scaffold-Ablauf kompiliert das Modell, prüft es und führt einen begrenzten Probelauf mit deklarierten Erwartungen aus. Strukturierte Diagnosen helfen dem Agenten bei der nächsten Änderung.

verified=true gilt für die deklarierten Datenerwartungen. Es bestätigt weder eine vollständige Spezifikation noch das Verhalten deiner Anwendung. Der aktuelle Authoring-V1-Umfang umfasst Datei- und Memstore-Ziele mit einer Ebene verschachtelter Kindprodukte. Datenbankziele und weitergehende Modelle nutzen den separaten XML-Workflow.

Für wiederholbare Prüfungen versioniere Modell, Eingaben, Seed und Laufzeit. Die Determinismus-Aussage von CE gilt innerhalb der dokumentierten, getesteten Laufzeitprofile. Ein Seed allein macht beliebige externe Datenquellen nicht reproduzierbar.

Beispiel: 240 Minuten verfügbar, 300 Minuten verplant

Angenommen, die Spezifikation erlaubt keine Überplanung. Die Testwelt enthält einen Mitarbeiter mit 240 Minuten verfügbarer Kapazität und Aufträge über insgesamt 300 Minuten. Der Verhaltenstest verlangt, dass die Anwendung diesen Plan ablehnt. ArchKeel prüft separat die deklarierte Grenze zwischen Planungslogik und Datenzugriff.

Das ist ein illustratives Szenario, kein hier ausgeführter DATAMIMIC-Benchmark. Die Daten machen den Konflikt sichtbar. Die Erwartung definiert, welche Reaktion korrekt ist.

So wird aus einer Vorgabe verwertbares Feedback

1. Leite Architekturregeln, Testzustände und erwartetes Verhalten aus der Spezifikation ab. Reviewe diese Vorgaben, bevor sie zur Abnahme dienen.
2. Erzeuge die Testwelt und gib dem Agenten den relevanten Vertrag, die Szenarien und die Aufgabe.
3. Prüfe Datenbedingungen, Architektur und Laufzeitverhalten. Gib konkrete Verletzungen, Fundstellen und offene Belege zurück.
4. Lass den Agenten überarbeiten und prüfe erneut gegen dieselben akzeptierten Vorgaben. Änderungen an Vorgaben brauchen einen eigenen Review.

Das Ziel sind kurze Rückmeldeschleifen mit deterministischen Prüfungen: Abweichungen werden konkret und nachprüfbar. Ob eine Testdatenwelt die Implementierung messbar verbessert, muss ein Vergleich zeigen. Wenn Modell, Code und Tests dieselbe falsche Annahme übernehmen, können alle Checks grün bleiben.

Wie eng sollten die Grenzen sein?

Deklariere die Architekturentscheidungen, die der Agent nicht selbst umwerfen soll: Komponenten, Verantwortlichkeiten, Schnittstellen und erlaubte Abhängigkeiten. Innerhalb dieser Grenzen bleibt die Implementierung offen.

Die enge Jacke entsteht erst durch den Workflow: Checks müssen verpflichtend laufen. Änderungen am Vertrag, an Baselines und an CI-Gates brauchen einen kontrollierten Review. Kann der Agent seine eigenen Regeln abschwächen, ist das Gate schwach.

Was prüft ArchKeel tatsächlich?

ArchKeel vergleicht statischen Code mit deklarierten Grenzen. Es zeigt verbotene Imports, falsch platzierte Typen und fehlende Belege mit Quellstellen. Die Checks laufen lokal und ohne LLM. Ihr Umfang hängt vom Sprachprofil und vom Vertrag ab.

ArchKeel ist keine Agent-Sandbox und garantiert keine vollständige Korrektheit. Der Harness kontrolliert Werkzeuge und Ausführung. Tests prüfen Laufzeitverhalten. Menschen entscheiden, welche Architektur sinnvoll ist.

Reicht eine AGENTS.md mit guten Regeln?

Eine AGENTS.md gibt dem Agenten Anweisungen und Kontext. Ein ausführbarer Architekturvertrag macht unterstützte Regeln gegen den Code prüfbar. Nutze beides: Kontext vor der Änderung und konkrete Befunde danach.

OpenAI beschreibt dieses Muster im Harness-Engineering-Artikel: Architekturgrenzen werden mechanisch geprüft; innerhalb der Grenzen bleibt Spielraum. ArchKeel deckt diesen Architekturteil ab. Es ersetzt nicht den gesamten Harness.

Warum reichen grüne Tests nicht aus?

Ein Verhaltenstest prüft ausgewählte Eingaben und Effekte. Er prüft meist nicht, welche Komponente eine andere importiert oder ob die statische Analyse einen Aufruf noch auflösen kann.

Weniger Befunde können auch bedeuten, dass die Analyse weniger sieht. Das Beispiel unten zeigt einen solchen Fall mit aufgezeichneten Tests und Check-Ergebnissen.

Report, Vertragsprüfung oder Change-Gate?

Ein lokaler Replay prüft die übergebenen Aufzeichnungen, authentifiziert sie aber nicht.

CLI reference / exit codes

Fokussierter Kontext für den Agenten

Main bietet eine kompakte Architekturübersicht. Danach kann der Agent Komponenten oder Befunde aus dem gespeicherten Snapshot abfragen. Globale Ergebnisse und UNKNOWN bleiben erhalten. Die Abfrage prüft nicht den inzwischen veränderten Arbeitsbaum.

archkeel report --only architecture --json
archkeel report --input architecture.json --only violations --json

Wann ist die Änderung wirklich fertig?

Lege vor dem Lauf fest, welches Ergebnis vorliegen muss und welche Checks die Abnahme tragen. Der Agent kann einen Report schreiben. Der Workflow muss prüfen, ob die verlinkten Ergebnisse existieren und zum abgegebenen Stand gehören.

Ein Beispiel: Die Tests bestehen auf Stand A. Danach ändert der Agent den Code zu Stand B und übernimmt die alte Zusammenfassung. Der Testlauf belegt A. Für B müssen die betroffenen Checks erneut laufen. Nach einem Merge gilt das auch für den resultierenden Integrationsstand.

ArchKeel liefert Architekturbelege. DATAMIMIC prüft deklarierte Datenbedingungen. Verhaltenstests prüfen die Anwendung. Der Runner oder CI-Workflow ordnet diese Ergebnisse dem Kandidaten zu und setzt die Abnahmeregeln durch. Ein Hash identifiziert ein Artefakt; er bestätigt allein weder dessen Herkunft noch einen vertrauenswürdigen Prüflauf.

Ein Reviewer-Agent kann zusätzliche Fehler finden. Gib ihm Anforderungen, Diff und tatsächliche Prüfausgaben. Eine zweite Zusammenfassung ist noch kein unabhängiger Nachweis. Fehlende oder veraltete Belege müssen vor der Abnahme sichtbar bleiben.

Über mehrere Sessions weiterarbeiten

Dauerhafte Projektregeln gehören in AGENTS.md, CLAUDE.md oder passende Skills. Den aktuellen Arbeitsstand hält eine kurze Übergabe fest: Ziel, Dateien und Snapshot, ausgeführte Checks, akzeptierte Entscheidungen, offene Punkte und der nächste konkrete Schritt.

Teste diese Übergabe in einer frischen Session. Der Agent soll die referenzierten Dateien und den Git-Stand prüfen, passende Basischecks ausführen und am offenen Schritt weiterarbeiten. Eine progress.md kann veralten. Ihr Inhalt muss mit dem Workspace übereinstimmen.

Anthropic beschreibt Fortschrittsnotizen, Git-Historie und Prüfungen beim Session-Start als Bestandteile seines Long-Running-Agent-Harness. Long-running agent harnesses ↗

Anweisungen und Durchsetzung haben verschiedene Aufgaben

Skills und Projektdateien erklären, wie gearbeitet werden soll. Tool-Rechte, Sandbox und verpflichtende CI-Gates bestimmen, welche Aktionen möglich sind und welche Ergebnisse weiter dürfen. Prüfe die tatsächliche Konfiguration. Ein Prompt setzt weder ein hartes Zeitbudget noch Prozessrechte.

Die Claude-Code-Dokumentation nennt eine konkrete Grenze: Read-/Edit-Sperren decken nicht beliebige Python- oder Node-Prozesse ab, die Dateien selbst öffnen. Für solche Grenzen braucht es passende Sandbox- oder Betriebssystemregeln. Claude Code permissions ↗

Auch der Harness braucht einen Test

Prüfe an einer kleinen, bekannten Aufgabe, ob dein Workflow veraltete Testausgaben, einen ausgelassenen Pflichtcheck und eine unterstützte Architekturverletzung erkennt. Versuche außerdem, den Vertrag oder die Baseline abzuschwächen: Der Workflow sollte dafür den vorgesehenen Review verlangen.

Vergleiche Änderungen am Harness mit denselben Aufgaben und Abnahmekriterien über mehrere Läufe. Erfasse akzeptierte Ergebnisse, übersehene Fehler, menschliche Review-Zeit sowie Laufzeit und Kosten einschließlich Wiederholungen. Ändere möglichst eine Komponente pro Vergleich. Weniger Tokens sind nur dann ein Gewinn, wenn die Gesamtarbeit bis zum akzeptierten Ergebnis sinkt.

Anthropics Leitfaden zu Agent-Evals trennt den Gesprächsverlauf vom tatsächlichen Ergebnis in der Umgebung. Für unseren Engineering-Harness ist diese Trennung die Grundlage der Abnahme. Agent evals ↗

Ausgeführt / Python

Acht grüne Tests. Ein neu unaufgelöster Aufruf.

Eine kleine Funktion verarbeitet Gutschrift und Abbuchung in ganzzahligen Einheiten. Das Refactoring ersetzt explizite Verzweigungen durch Dictionary-Dispatch. Beide Versionen liefern dieselben getesteten Werte und denselben KeyError bei unbekannten Operationsnamen.

from sample.helpers import credit, debit


def run(key: str, amount: int) -> int:
    if key == 'credit':
        return credit(amount)
    if key == 'debit':
        return debit(amount)
    raise KeyError(key)

from sample.helpers import credit, debit


def run(key: str, amount: int) -> int:
    handlers = {'credit': credit, 'debit': debit}
    return handlers[key](amount)

Vor der Änderung löst der Analyzer beide Hilfsaufrufe und den expliziten KeyError-Konstruktor auf. Danach ist handlers[key] dynamisch. Die Zahlen zählen statische Aufrufstellen, keine Laufzeitausführungen. Es kommt kein Regelverstoß hinzu; die schlechtere Aufrufauflösung reicht zur Ablehnung des Kandidaten.

expectation_fulfilled: FAIL
regression check failed in calls_unresolved: 0->1
regression check failed in unresolved_ratio: 0/3->1/1

Vom Ergebnis zum Befund zum Quellcode

Öffne den tatsächlichen Check-Report und suche nach den Regressionsbefunden und unresolved_call_changes. Der Befund nennt sample.work.run, sample/work.py:6 und handlers[key], mit der Begründung „expression is dynamic“.

Das Ergebnis reproduzieren

Lade das vollständige Beispiel herunter, entpacke es und führe diese Befehle in seinem Verzeichnis aus. Python 3.12 und Git sind erforderlich; die Installation benötigt Netzwerkzugriff. Der dokumentierte Lauf nutzte CPython 3.12.14 unter Linux.

Quellcode und Nachweise herunterladen (.zip)

python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -B run.py --output ./replay

Das Ausgabeverzeichnis muss neu sein. Der Runner führt dieselben unittest-Tests in beiden Ständen aus, dokumentiert Git-Basis und Erwartung und ruft die echte ArchKeel-CLI auf. Der Runner endet mit Exit 0, wenn die erwarteten Ergebnisse bestätigt sind; der enthaltene ArchKeel-Check endet mit Exit 1.

Erwartet und beobachtet: 8/8 Tests vorher, 8/8 nachher; calls_unresolved 0 → 1; expectation_fulfilled FAIL. Eine Negativkontrolle mit falscher Abbuchung lässt 5 von 8 Tests scheitern. Diesen tatsächlichen Verhaltensfehler erkennen die Tests.

Das Ergebnis in seinem Prüfumfang lesen

Vollständigkeit der Beobachtung, deklarierte Regeln und Änderungserwartung haben getrennte Ergebnisse. Ein Scan kann vollständig durchlaufen, obwohl Aufrufe unaufgelöst bleiben. NOT CHECKED bedeutet, dass eine Prüfung nicht ausgeführt oder nicht abgeschlossen wurde. Lies Diagnosen und Exit-Status zusammen.

ArchKeel prüft die eigene Architektur

Der Main-Report vom 7. Oktober 2026 enthält 123 beobachtete Dateien und 32 Komponenten. 48 Regeln sind PASS, vier UNKNOWN, keine FAIL. Das Gesamtergebnis bleibt UNKNOWN. Öffne denselben Snapshot auf der Startseite oder den laufend veröffentlichten Report auf GitHub Pages.

Historische Belege: Reports zur exakten Modulzuordnung aus 0.8.4

Die älteren 0.8.4-Belege unten bleiben für den ursprünglichen Fall der Modulzuordnung verfügbar. Sie gehören weder zum aktuellen Main-Report noch zum Dispatch-Beispiel.

Version, Befehle und Nachweise

Am 2. Oktober 2026 gegen den zu diesem Zeitpunkt aktuellen Repository-Commit geprüft. Paketmetadaten: 0.8.5.dev1+g340176715, ein Entwicklungsstand nach Release 0.8.4. Das ist kein veröffentlichtes Release 0.8.5.

34017671559a19bfe5fd909689400fb5fb0a6317

Wer entscheidet über die Regeln?

Der Agent kann Grenzen vorschlagen und Befunde bearbeiten. Die Zielarchitektur braucht einen verantwortlichen Entscheider. Lege fest, wer Vertragsänderungen akzeptiert und wie dein Workflow FAIL und UNKNOWN behandelt. Sonst dokumentierst du Grenzen, ohne sie durchzusetzen.