Repositories für autonome Agents: Der Agent ist nur so gut wie sein Repo

Im ersten Teil dieser Serie haben wir gezeigt, welche Aufgaben unser Agent Muro bereits erledigt. Im zweiten Teil ging es um Sessions, Tools, Skills und Execution Environments.

Jetzt drehen wir die Perspektive um: In was für einem Repository lassen wir diesen Agenten arbeiten?

Denn Coding Agents sind längst gut genug für viele echte Tasks. Was ihnen oft fehlt, ist kein besseres Modell. Es ist ein besseres Repository.

Du gibst einem Agenten ein Ticket. Er liest den Code, verändert ein paar Files, startet Tests und bereitet einen Pull Request vor. Im nächsten Projekt produziert derselbe Agent drei neue Patterns für ein längst gelöstes Problem. Dazu einen Button, der fast aussieht wie alle anderen Buttons.

Das Modell ist dasselbe. Der Unterschied ist das Repository.

Unsere kurze Antwort: Der Agent braucht Kontext, Grenzen und schnelles Feedback.

Context. Constraints. Feedback.

Autonom? Ganz ruhig. 🤖

Mit einem autonomen Repository meinen wir kein GitHub-Repo, das nachts heimlich Features entwickelt und morgens stolz deployed.

Wäre praktisch. Sind wir noch nicht.

Wir meinen ein Repository, in dem ein Coding Agent möglichst selbstständig und zuverlässig arbeiten kann. Dafür muss er drei Fragen beantworten können:

1. Context: Wie funktioniert dieses System?
2. Constraints: Welche Regeln darf ich nicht verletzen?
3. Feedback: Woran erkenne ich, dass meine Änderung funktioniert?

Je mehr Antworten im Repository stecken, desto weniger muss der Agent raten. Raten ist teuer. Besonders bei Architektur, Berechtigungen und Datenzugriff.

Kontext muss explizit sein

Menschen arbeiten erstaunlich gut mit implizitem Wissen. Nach ein paar Monaten im Projekt weiss eine Entwicklerin, wo API-Calls hingehören, wie wir Formulare aufbauen und warum legacy-utils-old-final-v2.ts auf keinen Fall als Vorlage taugt.

Ein Coding Agent weiss davon nichts. Er sieht Code und zieht Schlüsse daraus.

Darum machen wir relevantes Wissen explizit. Nicht als Roman, sondern dort, wo es gebraucht wird:

• AGENTS.md beschreibt dauerhafte Regeln und Grenzen.
• Architektur-Dokumente erklären Entscheidungen, bei denen das Warum zählt.
• Ein generierter API-Contract definiert, was das Backend wirklich kann.
• Skills führen durch wiederkehrende Arbeitsabläufe.
• Typen, Linting und CI erzwingen maschinenprüfbare Regeln.

Das ist wichtig: Nicht jede Information gehört in Markdown. Wenn der Agent eine Regel gar nicht verletzen kann, ist das stärker als jede freundliche Erinnerung.

Auch Anforderungen leben selten vollständig im Repository. Scope, Status und Entscheidungen liegen oft in einem Planungssystem. Die technische Wahrheit steckt vielleicht im API-Contract oder Backend-Code.

Darum holen wir den relevanten Kontext automatisiert und read-only in die Arbeitsumgebung. Die externe Quelle bleibt zuständig. Der Agent erhält eine aktuelle, maschinenlesbare Sicht darauf.

Bevor er startet, prüft er:

Task
  ↓
Anforderungen und Entscheidungen
  ↓
Status und offene Fragen
  ↓
Technische Abhängigkeiten
  ↓
API-Contract
  ↓
Starten oder blockieren

Fehlt eine Operation oder ein Feld im Contract, gilt die Capability als nicht vorhanden. Kein erfundener Endpoint. Kein Mock, der eine schöne Parallelwelt baut.

Stattdessen: Blocker benennen. Entscheidung einfordern.

Autonomie bedeutet nicht, mutiger zu raten. Sie bedeutet, selbstständig zu erkennen, wann Raten tabu ist.

Skills machen Abläufe reproduzierbar

Docs erklären, wie das System funktioniert. Skills erklären, wie wir eine Aufgabe erledigen.

Ein Entwicklungs-Skill verbindet Task, Kontext und Code. Er prüft den API-Contract, sucht bestehende Patterns, leitet Tests aus den Acceptance Criteria ab und führt den Agenten durch Implementierung und Verifikation.

Design braucht einen anderen Einstieg. Eine Exploration darf mit klar getrennten Mock-Daten beginnen, obwohl die produktive API noch fehlt. Entwicklung ist strenger: Sie startet erst, wenn Status, Blocker und technische Capabilities passen.

Ein weiterer Skill kann den lokalen Entwicklungs-Loop beschreiben:

1. App und Route prüfen.
2. Änderung implementieren.
3. Compilation Errors, Logs und Browserfehler auslesen.
4. Verhalten im Browser testen.
5. Korrigieren und wiederholen.

Die Anzahl der Skills war nie das Ziel. Unsere Regel ist einfacher:

Wenn wir einem Agenten zum fünften Mal denselben Ablauf erklären, verdient er einen Skill.

Der stärkste Satz im Repo beginnt mit «verboten»

Nehmen wir eine Architekturregel:

«Die Anwendung greift nur über den generierten Client auf die API zu.»

Als Satz ist das gut. Als Gate ist es besser.

Eine projektspezifische Lint-Regel verbietet direkte fetch()-Aufrufe ausserhalb des API-Pakets. Die Fehlermeldung nennt direkt das erlaubte Pattern.

Dasselbe Prinzip gilt für weitere Regeln:

• Auth-Checks gehören an den Datenzugriff, nicht ins Layout.
• URL-State läuft durch typisierte Parser statt rohe URLSearchParams.
• Production Code importiert keine Preview-Komponenten.
• Tailwind-Palettenfarben sind tabu. Das Design System liefert semantische Tokens.

Aus «Bitte denk daran» wird: «Das Repository akzeptiert diese Änderung nicht.»

Das hilft Menschen. Agents noch mehr.

Taucht ein Fehler wiederholt im Review auf, machen wir daraus Infrastruktur. Zuerst fragen wir: Kann der Typ die falsche Variante unmöglich machen? Falls nicht, folgen Lint-Regel, bestehender Code-Doctor oder CI-Gate.

Danach beweisen wir die Regel in beide Richtungen. Ein absichtlicher Verstoss muss den Check auslösen. Der erlaubte Code muss grün bleiben.

Der Agent lernt nicht nur im Chat. Das Repository lernt mit.

Auch Dead Code gehört zu diesen Grenzen. Ein Mensch erkennt eine alte Datei vielleicht als historischen Chabis. Ein Agent sieht ein Beispiel und baut das Pattern nochmals.

Für Menschen ist Dead Code Unordnung. Für Agents ist er potenziell falsche Dokumentation. Was ersetzt wird, verschwindet deshalb im selben Pull Request. Git ist das Archiv.

Der Agent braucht Augen

Ein Agent, der nur Files verändern kann, arbeitet blind. Ein Agent, der die Anwendung ausführen und beobachten kann, bekommt eine Feedback-Schleife:

Task
  ↓
Implementieren
  ↓
App ausführen
  ↓
Browser + Logs + Runtime prüfen
  ↓
Fehler erkennen
  ↓
Korrigieren
  ↺

Dafür haben sich zwei lokale Umgebungen bewährt.

Die Design-System-Workbench zeigt Tokens und Komponenten isoliert. Neue oder visuell veränderte Komponenten erhalten dort eine Demo mit ihren relevanten States.

Die Anwendungs-Sandbox rendert echte Routes und die echte App-Shell gegen Mock-Auth und Mock-API. Wechselbare Personas machen Rollen, Berechtigungen und Empty States sichtbar.

Eine Komponente ist nicht fertig, nur weil TypeScript zufrieden ist. Sie muss sichtbar funktionieren.

Tests geben dem Agenten zusätzlich maschinenlesbares Feedback: Unit Tests für tragende Logik, typisierte Fixtures gegen den API-Contract und Browser-Tests für Routes, Rollen und Datenflüsse.

Bei Pull Requests laufen nur die wahrscheinlich betroffenen Browser-Tests. Kann das Mapping eine Änderung nicht zuverlässig einordnen, läuft als konservativer Fallback die ganze Suite. Auf main und nachts ebenfalls.

Kurze Loops, aber nicht auf Kosten des Sicherheitsnetzes.

Umsetzung und Bewertung bleiben getrennt

Menschen schauen weiterhin Pull Requests an. Besonders bei Architektur, Security, Auth und Datenisolation.

Trotzdem automatisieren wir einen Teil der Verifikation. Nicht als Multi-Agent-Zirkus mit zehn Bots, die sich gegenseitig «Great point!» schreiben.

Vor der Implementierung leitet ein Research-Agent Testszenarien aus Task, Kontext und Contract ab. Nach der Umsetzung prüft ein separater Verify-Agent dieselben Anforderungen gegen Diff und Tests. Der zweite Agent darf nichts verändern. Er sucht Fehler.

Task + Kontext + Contract
       ↓
Scenario Research
       ↓
Implementierung
       ↓
Types / Lint / Tests / Browser
       ↓
Unabhängige Verifikation
       ↓
Fix Loop
       ↓
Human Review

Der Gedanke dahinter ist simpel:

Der Doer benotet nicht seine eigene Hausaufgabe.

So sieht ein kompletter Task aus

Nehmen wir eine kleine Aufgabe:

«Füge einer Übersicht einen Statusfilter hinzu.»

In einem autonomiefähigen Repository läuft sie so:

1. Der Agent lädt Task, Acceptance Criteria und relevante Entscheidungen.
2. Er prüft Blocker und verifiziert die benötigten Felder im API-Contract.
3. Er sucht das ähnlichste bestehende Pattern und leitet Testszenarien ab.
4. Er implementiert die kleinste sinnvolle Änderung.
5. Typen, Linting, Unit- und Browser-Tests geben Feedback.
6. Der Agent prüft den Flow in der Sandbox und zeigt visuelle Änderungen als Screenshot.
7. Eine unabhängige Verifikation prüft Anforderungen, Diff und Evidenz. Danach folgt das menschliche Review.

Das Modell ist wichtig. Aber sehr viel Qualität entsteht rundherum.

Das kostet Arbeit. Punkt.

Ein Repository wird nicht autonomiefähig, weil wir ein AGENTS.md hineinwerfen und ein Raketen-Emoji ergänzen. 🚀

Docs müssen aktuell bleiben. Skills können sich widersprechen. Lint-Regeln brauchen hilfreiche Fehlermeldungen. Tests dürfen nicht langsam und redundant werden. Mocks müssen den echten Contract respektieren. Dead Code muss wirklich weg.

Kontext hat Kosten. Veralteter Kontext kostet doppelt.

Darum behandeln wir das Repository wie ein Produkt: Wiederkehrende Fehler werden zu Gates, veraltete Regeln verschwinden, doppelte Tests werden konsolidiert und Skills entstehen aus realen Abläufen statt aus Sammeltrieb.

Autonomie ist kein Setup-Sprint. Sie ist laufende Produktpflege.

Vielleicht ist agent-friendly Engineering einfach gutes Engineering

Fast alles, was ein Repository für Agents besser macht, hilft auch Menschen:

• klare Architektur
• sichtbare Sources of Truth
• aktuelle Dokumentation
• wenig Dead Code
• hilfreiche Fehlermeldungen
• typisierte Verträge
• automatisierte Tests
• explizite Grenzen
• reproduzierbare Abläufe

Coding Agents erfinden diese Disziplinen nicht neu. Sie machen brutal sichtbar, wo wir bisher von implizitem Wissen gelebt haben.

Das Modell der Zukunft wird besser. Ziemlich sicher sogar sehr viel besser.

Wir warten trotzdem nicht darauf, dass es jede Eigenheit unseres Projekts intuitiv errät. Wir bauen lieber Repositories, in denen Wahrscheinlichkeit keine Rolle mehr spielt.