Ein Repository für Coding-Agenten vorbereiten, mit Checks als Nachweis

Was Ihre Engineers haben und ein Agent nicht

Jede Claude-Code-Sitzung beginnt mit einem leeren Kontextfenster, und andere Coding-Agenten arbeiten ähnlich. Abgesehen von organisationsweiten oder persönlichen Anweisungen und einem Gedächtnis, die zu Beginn geladen werden, weiß der Agent über Ihr Repository das, was das Repository ihm sagt, plus das, was er durch Suchen findet. Den Rest tragen Ihre Engineers im Kopf, etwa die Umgebungsvariable, die gesetzt sein muss, den Dienst, der vor den Integrationstests laufen muss, und den Test, der montags fehlschlägt.

Fehlt dieses Wissen, rät der Agent. GitHubs Dokumentation zum eigenen Cloud Agent sagt, dass Copilot Abhängigkeiten durch Ausprobieren finden und installieren kann, dass dies aber langsam und unzuverlässig ist und bei privaten Abhängigkeiten ganz scheitern kann. Vermutungen, die kompilieren, landen trotzdem im Review und sehen dort aus wie gewöhnlicher Code.

Sechs Fragen, die ein frischer Checkout beantworten muss

Wir stellen diese Fragen an einen sauberen Clone in einem Container oder auf einer Maschine, die das Repository noch nie gesehen hat. Ein Ja braucht einen Beleg: Der Befehl ist gelaufen.

• Installiert ein dokumentierter Befehl die Abhängigkeiten aus dem Lockfile, ohne Rückfragen und ohne Tools, die es nur auf Laptops gibt?
• Startet ein Befehl einen schnellen Testsatz, der jedes Mal dasselbe Ergebnis liefert, während langsame oder instabile Suites gekennzeichnet und ausgeklammert sind?
• Starten Datenbanken, Queues und andere Dienste aus einem Skript oder einer Container-Definition, mit den Testdaten, die die Tests erwarten?
• Ist festgehalten, welche Zugangsdaten das Setup braucht und welche die Agenten-Sitzung nie erhalten darf?
• Nennt eine Anweisungsdatei die Befehle, die Pfade, die der Agent nicht ändern darf, und die Konventionen, auf denen Reviewer bestehen?
• Hat diese Datei, samt der Agenten-Konfiguration drumherum, eine namentlich benannte verantwortliche Person?

Die dokumentierten Befehle zum CI-Job machen

Anweisungen veralten unbemerkt. Jemand benennt ein Skript um, und die Anweisungsdatei nennt noch das alte. Abhilfe schafft ein einziger Einstiegspunkt, den die Anweisungsdatei nennt und den ein CI-Job von einem sauberen Checkout aus ausführt. So bricht eine veraltete Anweisung einen Build statt eines Agentenlaufs.

#!/usr/bin/env bash
# The one command agents and CI both run from a clean checkout.
# Named in AGENTS.md; CI runs it on every change to setup files.
set -euo pipefail
pnpm install --frozen-lockfile
pnpm build
pnpm lint
pnpm test:unit

Gehostete Agenten bringen eine eigene Setup-Schicht mit, die dieselbe Behandlung braucht. GitHub führt vor dem Start seines Cloud Agents einen Workflow copilot-setup-steps.yml aus, und zwar nur aus dem Default-Branch. Schlägt ein Setup-Schritt fehl, überspringt der Agent die restlichen Schritte und beginnt im aktuellen Zustand der Umgebung zu arbeiten. Ein kaputtes Setup zeigt sich dann als seltsames Verhalten des Agenten, nicht als roter Build. Der Workflow läuft bei Änderungen auch als normaler Check und lässt sich manuell starten, er ist also testbar.

In OpenAIs Codex Cloud bereitet Codex eine Umgebung gemeinsam mit Ihnen vor und testet sie, und die Veröffentlichung hält das vorbereitete Dateisystem fest, von dem neue Aufgaben starten. Änderungen an diesem vorbereiteten Setup erreichen neue Aufgaben nach erneuter Veröffentlichung, und bestehende Aufgaben behalten ihre eigenen Dateien. Manche gespeicherte Konfiguration gilt sofort für das aktive Setup, prüfen Sie also vor dem Test, welche Art von Änderung Sie vorgenommen haben.

Was in die Anweisungsdatei gehört und was nicht

Die Claude-Code-Dokumentation verlangt Anweisungen, die konkret genug sind, um sie zu überprüfen, etwa den exakten Testbefehl, und empfiehlt, jede CLAUDE.md unter 200 Zeilen zu halten, weil längere Dateien Kontext kosten und die Befolgung verschlechtern. Die Cursor-Dokumentation zu Rules rät davon ab, Styleguides zu kopieren, die ein Linter durchsetzen kann. Was die Datei braucht, ist kurz:

• Befehle für Installation, Build, Lint und schnelle Tests, genau so, wie die CI sie ausführt
• Pfade, die der Agent nicht ändern darf, etwa generierter Code, eingebundene Abhängigkeiten und bereits gemergte Migrationen
• Konventionen, auf denen Reviewer bestehen und die von üblichen Standards abweichen
• Was fertig bedeutet: welche Checks bestehen müssen und was die Beschreibung des Pull Requests enthält

Mehrere Tools lesen inzwischen AGENTS.md. Claude Code liest sie, wenn keine CLAUDE.md vorhanden ist, Cursor unterstützt sie im Wurzelverzeichnis und in Unterverzeichnissen, und GitHubs Cloud Agent liest AGENTS.md-Dateien neben seinen eigenen Anweisungsdateien. Eine gemeinsame Datei mit schlanken tool-spezifischen Ergänzungen verhindert, dass drei Kopien auseinanderlaufen. Durchsetzen kann keine dieser Dateien etwas: Laut Claude-Code-Dokumentation behandelt das Tool sie als Kontext. Eine Regel, die gelten muss, gehört deshalb in Berechtigungen, Hooks oder die CI.

Von den Antworten zu einer Arbeitsregel

Die Antworten entscheiden, wie Agenten in einem Repository arbeiten dürfen. Diese Regel wenden wir an:

• Alle sechs mit Ja beantwortet: Kandidaten für delegierte Aufgaben, die ein Reviewer prüfen kann, bei unverändertem Review und unveränderten Pflicht-Checks.
• Setup funktioniert, aber Tests sind instabil oder langsam: nur interaktive Arbeit, bei der ein Engineer die Testausgabe liest, bis der schnelle Testsatz stabil ist.
• Ein sauberer Checkout baut nicht: Das wird zuerst behoben, weil ein Agent dort sein Budget mit dem Wiederentdecken des Setups verbraucht.

In einem hypothetischen Service-Repository braucht ein Checkout eine lokale Postgres-Instanz, die Engineers vor Monaten gestartet haben, und ein Token für eine private Paket-Registry. Die Abhilfe sind eine Container-Definition für die Datenbank, ein Registry-Zugang, der nur dem Setup zur Verfügung steht, und das obige agent-check-Skript, jeweils als eine prüfbare Änderung.

Was Bereitschaft nicht löst

Ein vorbereitetes Repository beendet das Raten über die Umgebung. Es macht unklare Aufgaben nicht klar, schafft keine Review-Kapazität und macht Agenten nicht geeignet für Arbeit, die tiefes fachliches Urteil verlangt. Repositories, die von lizenzierten Tools, spezieller Hardware oder internen Systemen abhängen, passen vielleicht nicht in eine gemeinsam genutzte gehostete Sandbox, doch das schließt Delegation nicht aus. GitHubs Cloud Agent kann auf selbst gehosteten Runnern mit Zugriff auf interne Ressourcen laufen, empfohlen als kurzlebige Runner für jeweils einen Job, und ein selbst gehostetes oder lokales Setup funktioniert, wenn es reproduzierbar ist und dieselben Berechtigungen, Checks und Reviews hat. Erst wenn nichts davon möglich ist, bleibt interaktive lokale Nutzung als Ausweg.

Wenn Agenten-Änderungen lokal bestehen und in der CI scheiternHarness Engineering