Spickzettel

Spickzettel Agent-Harness: Komponenten, Dateien, Probleme und Startcheckliste

Aktualisiert: 12.10.2026 · Skillaria.Top

Das Harness eines Agenten besteht aus fünf Teilsystemen: Anweisungen, Werkzeuge, Umgebung, Zustand und Rückmeldung. Die minimale Dateiauswahl sind eine AGENTS.md als kurzer Router, ein Prüfskript (make check, verify.sh), eine Fortschrittsdatei und eine Feature-Liste mit Status; den Fertigstellungsstatus setzt ein Skript, nicht der Agent.

Fünf Teilsysteme des Harness

Teilsystem	Was es ist	Artefakte	Anzeichen eines Defekts
Anweisungen	Was der Agent über das Projekt wissen muss	AGENTS.md / CLAUDE.md, Skills, docs/, ADRs	Verletzt bekannte Konventionen
Werkzeuge	Was der Agent tun kann	Shell, Tests, Linter, Browser, MCP-Server	„Will, kann aber nicht“
Umgebung	Wo der Agent arbeitet	Lock-Dateien, Docker/Devcontainer, Git-Worktree, Sandbox, init.sh	Die Sitzung beginnt mit der Reparatur der Umgebung
Zustand	Was einen Neustart übersteht	PROGRESS.md, DECISIONS.md, feature_list.json, Commits	Eine neue Sitzung weiß nicht, wo es aufgehört hat
Rückmeldung	Wie der Agent von einem Fehler erfährt	make check, E2E, Hooks, arch-check, Bewerter	„Fertig“, funktioniert aber nicht

Reihenfolge beim Aufbau von Grund auf: Rückmeldung → Anweisungen → Zustand → Umgebung → Werkzeuge.

Dateien des Harness

Datei	Zweck	Regel
AGENTS.md / CLAUDE.md	Einstiegspunkt: worum es im Projekt geht, wie man es startet, wie man es prüft	Ein kurzer Router (etwa 80 Zeilen) mit Verweisen auf Dokumente mit der Bedingung „wann lesen“
docs/*.md	Details nach Themen	Bei Bedarf lesen, nicht komplett
.claude/skills/*/SKILL.md	Wiederkehrende Abläufe (Deployment, Review)	Werden geladen, wenn die Aufgabe zur Beschreibung passt
PROGRESS.md	Zustand, Erledigtes, Blocker, nächste Schritte	Am Ende jeder Sitzung aktualisieren
DECISIONS.md	Entscheidung, Begründung, verworfene Optionen	Den Weg festhalten, nicht nur das Ergebnis
feature_list.json	Features: Verhalten, Prüfung, Zustand	Genau ein Feature aktiv (WIP=1)
scripts/verify.sh	Prüft ein Feature und setzt es auf passing	Einziger, der passing setzt, mit dem SHA des Commits
scripts/arch-check.sh	Architekturgrenzen	Exit-Code 1 + WARUM und FIX in der Ausgabe
scripts/init.sh	Prüfung der Umgebung vor der Arbeit	Umgebung, sauberes Git, grünes make check, ein aktives Feature
Sprint-Vertrag	Vertrag für ein Feature vor dem Code	Im Umfang / außerhalb des Umfangs / offene Fragen
.claude/settings.json	Berechtigungen und Hooks von Claude Code	Prüfungen an Ereignissen, nicht im Gedächtnis des Agenten

Skelett der AGENTS.md

# Projekt: Zahlungs-Backend (FastAPI, PostgreSQL)

## Starten
docker compose up -d && ./scripts/init.sh

## Prüfen
make check   # Lint, Typen, Unit-Tests, arch-check
make e2e     # Ende-zu-Ende-Szenarien

## Definition of Done
- make check und make e2e — Exit-Code 0
- Feature per Skript scripts/verify.sh auf passing gesetzt
- PROGRESS.md aktualisiert

## MUST
- Datenbankabfragen nur über Repositories
- Geheimnisse nur aus Umgebungsvariablen

## Dokumente
- docs/payments.md — wenn die Aufgabe Zahlungen und Rückerstattungen betrifft
- docs/migrations.md — wenn sich das Datenbankschema ändert

Zustände eines Features

Zustand	Bedeutung	Wer ändert ihn
pending	In der Warteschlange	Planer
active	In Arbeit (nur eines)	Agent beim Start
passing	Prüfung bestanden	Nur verify.sh
blocked	Braucht eine Entscheidung eines Menschen	Agent mit Beschreibung des Grundes

Prüfstufen

Stufe	Was	Wann
1	Lint, Typen	Immer
2	Unit- und Integrationstests	Immer
3	E2E	Änderung über mehr als eine Schicht; vor „fertig“
4	arch-check	Neue schichtübergreifende Importe

Das Recht, „fertig“ zu sagen, besteht erst nach der obersten Stufe. Grüne Unit-Tests bedeuten noch keine Fertigstellung.

Regeln mechanisch durchsetzen

Stufe	Werkzeug	Aufwand
grep-Guard	Skript, das nach einem Muster sucht und WARUM/FIX ausgibt	Minuten
Linter-Regel	import-linter (Python), dependency-cruiser, eslint-plugin-boundaries (JS/TS)	Eine Stunde
Architekturtest	Ein Test im CI, der bei Verletzung der Schichten fehlschlägt	Mehr Aufwand, aber sichtbar in make check

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WARUM: Services greifen nicht direkt auf die Datenbank zu"
  echo "FIX: Nutzen Sie ein Repository aus app/repositories/"
  fail=1
fi
exit $fail

Typische Probleme und Lösungen

Problem	Teilsystem	Lösung
Eine Regel in CLAUDE.md wird nicht befolgt	Anweisungen	Datei kürzen, Regel in eine Prüfung oder einen Hook umwandeln
Der Agent kann die Tests nicht ausführen	Werkzeuge	Befehl erlauben, Abhängigkeiten ins Image installieren
Unterschiedliches Verhalten auf verschiedenen Rechnern	Umgebung	Lock-Dateien, Docker/Devcontainer, feste Laufzeitversionen
Amnesie zwischen Sitzungen	Zustand	PROGRESS.md, Übergabe der Sitzung, Lesen zu Beginn der Sitzung
Drei Features begonnen, keines beendet	Zustand	WIP=1 in feature_list.json
„Fertig“, funktioniert aber nicht	Rückmeldung	DoD, E2E, verify.sh, unabhängiger Bewerter
Tests sind grün, das Feature ist kaputt	Rückmeldung	E2E mit echter Datenbank und echter Konfiguration
Der Agent übernimmt schlechte Muster	Rückmeldung	arch-check von Anfang an
Unklar, was der Agent getan hat	Zustand	Kleine Commits, Bericht in PROGRESS.md, DECISIONS.md
Der Agent hat über Nacht die Umgebung zerstört	Umgebung	Sandbox, Git-Worktree, Checkpoints, Rollback über init.sh
Derselbe Review-Kommentar zweimal	Harness insgesamt	In eine Prüfung in make check umwandeln, Text aus den Anweisungen entfernen

Rollen für lange Aufgaben

Rolle	Tut	Tut nicht
Planer	Features mit Abnahmekriterien	Schreibt keinen Code
Generator	Setzt ein Feature um, führt die Tests aus	Entscheidet nicht, ob es fertig ist
Bewerter	Urteil nach Raster, mit Verweis auf Datei, Zeile oder Log	Sieht die Überlegungen des Generators nicht
Merge	Committet bei review == pass	Das ist Code, kein Agent

Budget für autonome Arbeit

Das Ziel ist ein Satz (zum Beispiel: alle Features auf passing bringen).
WIP=1, eine Zeit- und Versuchsgrenze pro Feature.
Die Metrik wächst monoton; eine Regression bedeutet sofortigen Rollback.
Migrationen, Infrastruktur, Geld — Eskalation an einen Menschen.
Nach mehreren fehlgeschlagenen Reviews das Feature mit einem sauberen Kontext neu beginnen.

Checkliste für den Start des Agenten

Es gibt eine AGENTS.md: Stack, Start, Prüfbefehl, DoD.
make check läuft auf einem sauberen Klon durch.
Die Umgebung ist reproduzierbar: Lock-Dateien, Docker oder Devcontainer.
Der Agent hat die nötigen Befehle; gefährliche sind verboten oder in einer Sandbox.
Es gibt ein E2E-Szenario mindestens für das Hauptszenario.
Es gibt eine PROGRESS.md und die Regel, sie zu Beginn der Sitzung zu lesen.
Features stehen in einer Liste mit Status, genau eines ist aktiv.
Den Status passing setzt ein Skript.
Prüfmeldungen enthalten WARUM und FIX.
Die Aufgabe ist mit Abnahmekriterien und einer Grenze des Umfangs formuliert.
Festgelegt ist, was eine Entscheidung eines Menschen erfordert.
Die Verifikationslücke ist vor den Änderungen gemessen, als Vergleichsbasis.

Metriken des Harness

Metrik	Berechnung
Verifikationslücke	Anteil der „fertig“-Meldungen ohne Bestätigung durch eine Prüfung, auf 10 Aufgaben
MTTR	Zeit vom Ausfall bis zur Wiederherstellung eines funktionierenden Zustands
Kaltstart	Ob eine neue Sitzung die Fragen „wo stehen wir, was kommt als Nächstes“ ohne Raten beantwortet
Ablation	Einbruch, wenn ein Teilsystem bei einem festen Aufgabensatz abgeschaltet wird

Kurz gesagt

Das Harness ist ein Kreislauf, keine Datei: Anweisungen, Werkzeuge, Umgebung, Zustand und Rückmeldung. Beginnen Sie mit Prüfungen, halten Sie die AGENTS.md kurz, übergeben Sie den Fertigstellungsstatus einem Skript und überprüfen Sie das Harness regelmäßig. Das alles wird im Kurs zum Harness Engineering an einem durchgängigen Projekt als Ganzes zusammengesetzt.

Häufige Fragen

Worin unterscheidet sich AGENTS.md von CLAUDE.md?

Dem Zweck nach ist es dasselbe: eine Anweisungsdatei für den Agenten. CLAUDE.md liest Claude Code, AGENTS.md ist ein gemeinsames Format für verschiedene Agenten; in CLAUDE.md können Sie einfach auf AGENTS.md verweisen.

Wie viele Zeilen sollte die AGENTS.md haben?

Eine feste Grenze gibt es nicht, aber die Einstiegsdatei sollte kurz bleiben, etwa einhundert Zeilen wie ein Inhaltsverzeichnis. Details lagert man in eigene Dokumente aus.

Brauche ich feature_list.json für ein kleines Projekt?

Für einzelne Korrekturen nicht. Sie lohnt sich, wenn der Agent mehrere Features hintereinander oder über mehrere Sitzungen bearbeitet.

Wo bewahre ich Geheimnisse auf, auf die der Agent zugreifen muss?

In Umgebungsvariablen oder einem Geheimnisverwalter, nicht in Anweisungsdateien und nicht im Code. Dem Agenten gibt man Zugriff auf die Umgebung, nicht auf die Werte im Text.

Das Thema im Video lernen

Dieses Thema wird im Kurs „Harness Engineering: инженерия надёжности AI-агентов“ ausführlich mit Praxis behandelt.

Zum Kurs