Führen Sie eine AGENTS.md ein: Der Repo-Vertrag, den Ihre LLM-Bots jetzt brauchen

README.md, CONTRIBUTING.md und CODEOWNERS sind da. Aber Ihre LLM‑Agenten raten trotzdem. Dieses Rätselraten ist inzwischen ein Produktionsrisiko. Der HN‑Thread dieser Woche, der nach „AGENTS.md“ ruft, hat recht: Sie brauchen einen einfachen, durchsetzbaren Vertrag im Repo, der Bots sagt, was sie anfassen dürfen, was nicht, wie viel sie ausgeben dürfen und wie sie eskalieren, wenn sie unsicher sind.

Falls das nach Overkill klingt, erinnern Sie sich an das letzte Mal, als ein gutmeinender Bot einen „Quick‑Fix“-PR eröffnete, der die Infra brach oder das Token‑Budget sprengte. Der eigentliche Schaden war nicht der Revert – es war der Vertrauensverlust. Nach einem einzigen Vorfall drosseln oder verbieten Teams Bots und führen sie später stillschweigend ohne Struktur wieder ein. Dieser Zyklus kostet Quartale.

Was sich geändert hat: Bots sind keine Assistenten mehr – sie sind Akteure

Zwei frische Signale:

• Auf HN tauchten Feature‑Requests für eine standardisierte AGENTS.md auf – ein echtes Schmerzsignal: Agenten fehlt ein gemeinsamer, repo‑lokaler Vertrag.
• Agent‑Harnesses wie OneCLI und aufkommende native Agents (inklusive „fx“ auf HN) machen es trivial, Bots in CI/CD und Repos einzubinden. Das ist großartig für die Geschwindigkeit, aber fatal für die Konsistenz, wenn jeder Bot nach eigenen Regeln spielt.

Inzwischen sind Ihre Compliance‑Anforderungen nicht einfacher geworden. Ihre Agenten berühren regulierte Daten, kurzlebige Secrets, Third‑Party‑APIs und Produktions‑Workflows. Ohne Vertrag wird jeder PR zur Verhandlung.

AGENTS.md: der minimale Vertrag

Denken Sie an AGENTS.md wie an eine robots.txt für Ihr Repo – nur mit Budgets, Eskalationspfaden und Risikostufen. Halten Sie es knapp. Eine Seite, die ein LLM parsen kann und für die ein Mensch verantwortlich ist.

Was hineingehört (meinungsstarke Basis)

• Scope und Intention: Welche Probleme Agenten in diesem Repo lösen dürfen. Beispiel: „Dokumentationskorrekturen, Lint‑Regel‑Updates, Triage flaker Tests, sichere Refactorings unter 100 Zeilen.“
• Hochrisiko-Zonen: Pfade, die ohne explizite menschliche Freigabe geschützt oder verboten sind. Beispiel: „infra/ und migrations/ erfordern CODEOWNERS‑Freigabe, auch für von Bots erstellte PRs.“
• Datenklassifizierung: Welche Daten Agenten lesen oder generieren dürfen; was tabu ist. Beispiel: „Niemals Produktions‑PII in PRs oder Test‑Fixtures einbringen. Nur synthetische Daten verwenden.“
• Tools und Endpoints: Erlaubte externe Tools, MCP‑Server und interne Services. Beispiel: „Darf internen test-runner MCP aufrufen, darf keine Payment‑Gateways ansprechen.“
• Budgets und Ratenlimits: Ausgabenobergrenzen pro PR und pro Tag mit harten Stopps. Beispiel: „Deckel $10/PR Modellkosten, $100/Tag pro Repo. Abbrechen und eskalieren, wenn überschritten.“
• Secrets und Credentials: Wie kurzlebige Tokens bereitgestellt werden; niemals Menschen in PRs nach Secrets fragen. Beispiel: „Verwenden Sie kurzlebige, gescopte Tokens aus dem CI‑Vault. Keine statischen Tokens.“
• Sichere Defaults: Änderungsklassen, die bei bestandenen Tests auto‑merge‑fähig sind. Beispiel: „Lockfiles neu generieren + CI grün + unter 50 LOC = auto‑merge‑fähig nach 2 grünen Builds.“
• Unsichere Änderungen: Änderungen, die immer menschliches Review erfordern. Beispiel: „Datenbankschema, Auth‑Flows, Payment‑Logik, Infra‑IaC, Dependenz‑Adds/Upgrades über Patch‑Level.“
• Observability und Logs: Was aufgezeichnet wird, wie lange und wo es einsehbar ist. Beispiel: „Alle Agent‑Tool‑Calls werden in observability/agents mit 30‑Tage‑Aufbewahrung geloggt.“
• Eskalationspfad: Wen und wie pingen, wenn die Konfidenz gering ist. Beispiel: „Eröffne einen Draft‑PR mit Label needs-human und tagge @team-leads innerhalb von 30 Minuten.“
• Modell- und Quantisierungshinweise: Guidance zur Wahrung der Deterministik. Beispiel: „Nutze GPT‑4.1‑mini für Entwürfe, wechsle für das Finale zu Sonnet; vermeide aggressive Quantisierung bei tool‑call‑lastigen Tasks.“
• Memory‑Policy: Aufbewahrung, Autorität und Provenienz für Agent‑Memory. Beispiel: „Gewichte Memories nach Quelle und Alter; behandle menschliche Kommentare in CODEOWNERS als höher autoritativ als Modell‑Selbstnotizen; lösche Memories nach 14 Tagen.“

Das war’s. Eine Seite. Wenn Sie mehr brauchen, verlinken Sie auf tiefere Richtlinien, aber behalten Sie AGENTS.md als High‑Signal‑Interface – etwas, das ein Agent in einem einzigen Kontextfenster aufnehmen und ohne Ambiguität danach handeln kann.

Machen Sie es durchsetzbar: ein kleines, maschinenlesbares Pendant

AGENTS.md ist für Menschen und LLMs. Zusätzlich brauchen Sie eine minimale maschinenlesbare Datei (agents.yaml oder agents.json), damit CI und Harnesses Budgets, Ratenlimits, Pfadbeschränkungen und Eskalationsregeln durchsetzen können. Halten Sie das Schema winzig, sonst verrottet es.

Ein konkretes Minimal‑Schema (als Bullets, kein Code)

• version: 1
• allowed_paths: ["docs/**", "src/**", "tests/**"]
• guarded_paths: ["infra/**", "migrations/**", "auth/**"]
• deny_paths: ["secrets/**", ".github/workflows/prod-deploy.yml"]
• max_loc_change: 100
• budget_usd_per_pr: 10
• budget_usd_per_day: 100
• allowed_tools: ["test-runner-mcp", "lint-mcp"]
• denied_endpoints: ["/payments/*"]
• memory_ttl_days: 14
• escalate_labels: ["needs-human"]
• escalate_mentions: ["@team-leads"]

Egal ob OneCLI, ein Eigenbau‑Harness oder ein Marketplace‑Router: Diese Datei kann Verhalten gatekeepen. Überschreitet ein PR max_loc_change oder berührt einen geschützten Pfad, schaltet CI auto-merge ab und verlangt CODEOWNERS. Wenn das Modell budget_usd_per_pr verbrennt, bricht der Lauf ab und versieht den PR mit einem Label zur menschlichen Triage.

So integrieren Sie AGENTS.md in Ihren Stack

1) CI‑Check: Keine AGENTS.md, keine Bot‑PRs

Blockieren Sie von Agenten stammende PRs, sofern AGENTS.md und agents.yaml nicht vorhanden und valide sind. Das ist in etwa eine Stunde Implementierungsaufwand. Wenn eine Blockade nach Herkunft nicht möglich ist, erkennen Sie PRs, die mit Bot‑Tokens oder typischen Agent‑Metadaten erstellt wurden, und wenden Sie den Check an. Bei Fehlschlag sollte ein hilfreicher Kommentar mit Verweis auf ein Template hinzugefügt werden.

2) Budgets im Harness durchsetzen

Umschließen Sie Ihren LLM‑Client mit einem budgetbewussten Proxy. Für GitHub Actions können Sie die Ausgaben berechnen, indem Sie den Tokenverbrauch mit den Modellkosten multiplizieren (beides loggen). Harte Stopps an den Caps. Veröffentlichen Sie die Ausgaben in einem PR‑Kommentar, damit Reviewer eine einfache Übersicht sehen: $2.35 draft, $1.90 refine, $0.65 tests, insgesamt $4.90. Wenn Sie nearshore arbeiten und Zyklen über Pods teilen, verhindert diese Transparenz das Syndrom der unerklärlichen Cloud‑Rechnung.

3) Pfadbewusste Policies

Integrieren Sie Pfadregeln in Ihren PR‑Policy‑Bot. Wenn ein PR guarded_paths berührt, muss er CODEOWNERS‑Freigabe haben und darf nicht auto‑gemerged werden. Wenn er deny_paths berührt, muss der Bot den PR mit Begründung schließen und eskalieren. So wird aus „Guidance“ Verhalten – nicht nur ein Versprechen.

4) Tool‑Call‑Allowlists

Die meisten schädlichen Vorfälle entstehen durch unerwartete Tool‑Calls. Wenn Sie MCP‑Server nutzen, verdrahten Sie eine Allowlist aus agents.yaml und auditieren Sie die tatsächlichen Aufrufe. Ein verweigerter Call sollte einen PR‑Kommentar mit Call, Zweck und einem Link zu AGENTS.md erzeugen. Behandeln Sie Tool‑Call‑Diffs wie Dependency‑Diffs.

5) Gewichteter Speicher und TTL

Einer der klügeren Community‑Kritikpunkte: „Alles, was ein Agent sich merkt, hat die gleiche Autorität – und das ist der Bug.“ Bauen Sie eine gewichtete Memory‑Schicht: Menschlich verfasste Projektdocs und CODEOWNERS haben hohe Autorität; flüchtige LLM‑Selbstnotizen niedrige. Lassen Sie Erinnerungen mit dem Alter abklingen. Erzwingen Sie memory_ttl_days. Speichern Sie die Provenienz (wer/was, wann) zu jedem Eintrag. Ein Tag Engineering verhindert Monate subtilen Drifts.

6) Observability: Tool‑Call‑ und Kosten‑Traces

Speichern Sie jeden Tool‑Call mit Inputs, Outputs, Dauer und Kosten. Legen Sie sie in einem einfachen Ordner im Repo ab (für nicht sensible Traces) oder in Ihrem Observability‑Backend. Behalten Sie standardmäßig 30 Tage; erweitern Sie auf 90 für regulierte Repos. Wenn Ihre Agenten in Brazil und in den US laufen, versehen Sie Traces mit der Region für Audits zur Datenresidenz.

Rollout‑Plan: 30–60–90 Tage

Erste 30 Tage: den Vertrag etablieren

• Entwerfen Sie ein einseitiges AGENTS.md‑Template. Unter 25 Zeilen Policy plus Links halten.
• Definieren Sie das minimale agents.yaml‑Schema (die Bullets oben). Veröffentlichen Sie bei Bedarf ein JSON Schema zur Validierung.
• Fügen Sie einen CI‑Check hinzu, der Bot‑PRs in Repos ohne beide Dateien blockiert. Geben Sie in der Fehlermeldung einen „Create from template“-Button an.
• Instrumentieren Sie Ihren LLM‑Client mit Budget‑Caps und Tracing. Das ist eine 1–2‑Tage‑Aufgabe.

Tage 31–60: durchsetzen und feinjustieren

• Rollout auf Ihre Top‑10‑Repos nach PR‑Volumen. Rechnen Sie mit 5–10 kleinen Policy‑Ausnahmen, die explizit behandelt werden müssen (z. B. Migrations in einem Feature‑Branch).
• Schalten Sie pfadbewusstes Auto‑Merge für sichere Änderungen unter 50 LOC bei grüner CI ein. Messen Sie die Durchlaufzeitreduktion. Teams sehen typischerweise 20–30 % schnellere Merges für risikoarme Änderungen.
• Veröffentlichen Sie einen Support‑Pfad. 6–8 Stunden Overlap mit Brazil‑basierten Pods reichen aus, um Policy‑Streitfälle zügig zu klären.

Tage 61–90: skalieren und messen

• Auf 50+ Repos erweitern. „Policy Drift“ wöchentlich triagieren. Der häufigste Drift: guarded_paths fehlt bei einem neu hinzugefügten infra/‑Subtree.
• Quartalsziele setzen: weniger als 1 Revert pro 100 Bot‑PRs; unter $5 Median‑Ausgaben pro Bot‑PR; unter 24 Stunden Median Time‑to‑Merge für sichere Klassen.
• Ein vierteljährliches Fire‑Drill ansetzen: absichtlich einen deny_path verletzen und verifizieren, dass CI blockt und eskaliert.

Häufige Einwände – und Antworten

„Das bremst uns aus.“

Es beschleunigt die richtigen Änderungen. Sichere Klassen auto‑mergen schneller, weil Reviewer nicht nach Überraschungen suchen. Unsichere Klassen werden schneller, weil die Regeln sichtbar sind. Sie eliminieren Verhandlung pro PR.

„Das verrottet.“

Tut es – wenn es lang ist. Halten Sie AGENTS.md kurz und legen Sie verrottungsanfällige Details in agents.yaml mit CI‑Validierung. Machen Sie CODEOWNERS zum Owner beider Dateien. Wenn es niemand besitzt, ist es keine Policy.

„Unsere Agenten sind zu unterschiedlich für einen Standard.“

Genau deshalb ist das Schema minimal. Scope, Pfade, Budgets, Tools, Eskalation. Alles andere kann in tieferen Bot‑Docs leben. Der Punkt ist ein Vertrag, den das Repo durchsetzt – kein Nachschlagewerk.

„Wir haben das schon in Notion dokumentiert.“

Docs außerhalb des Repos sind für Agenten unsichtbar und von CI nicht durchsetzbar. Legen Sie den Vertrag neben den Code. Verweisen Sie bei Bedarf in Notion auf Langform‑Policy; der Gate bleibt lokal.

Brazilian Nearshore‑Angle: Wer übernimmt die unglamouröse Plumbing?

Die harte Arbeit ist nicht der Absatz, den Sie in AGENTS.md schreiben. Es ist die Durchsetzungs‑Plumbing – Budget‑Caps, pfadbewusstes Auto‑Merge, Tool‑Call‑Allowlists, Memory‑TTLs, Traces. Wenn Ihr Platform‑Team überlastet ist, kann ein nearshore Pod das in wenigen Wochen landen:

• CI‑Gate und Schema‑Validierung aufsetzen: 1–2 Tage.
• Wrapper für LLM‑Ausgaben‑Tracking und harte Caps: 2–4 Tage pro Sprache/Runtime.
• MCP/Tool‑Allowlist + Audit‑Logging: 3–5 Tage.
• Pfadbewusste PR‑Policies an CODEOWNERS binden: 2 Tage.
• Org‑weiter Rollout (50+ Repos), Training und Dashboards: 2–3 Wochen.

Sie bekommen 6–8 Stunden Zeitzonen‑Overlap mit US‑Teams und nach dem ersten Quartal eine saubere Übergabe an Ihr Platform‑Team – mit Runbooks, nicht mit einer Blackbox.

Reale Zielwerte

• Token‑Ausgaben: initial $10/PR und $100/Tag/Repo deckeln. Reife Teams liegen mit klarem Scope bei $3–$7 pro Bot‑PR.
• PR‑Velocity: Mit Auto‑Merge für sichere Klassen 20–30 % kürzere Cycle‑Times für Docs, Lint und kleine Refactorings.
• Incident‑Rate: Reverts unter 1 % für Bot‑PRs nach dem ersten Monat Tuning.
• Coverage: Top‑50‑Repos in 60 Tagen abgedeckt – machbar mit einem 2–3‑Personen‑Platform‑ oder Nearshore‑Pod.

Nicht auf einen Anbieter überoptimieren – portabel halten

Anbieter werden Bedingungen ändern, Features drosseln oder Fähigkeiten einschränken. Diese Geschichte kennen wir von Modellzugängen und Programmwechseln. AGENTS.md und agents.yaml sollten keine proprietären Features als harte Abhängigkeiten referenzieren. Behandeln Sie das Harness als austauschbar: OneCLI heute, morgen Ihr In‑House‑Runner. Der Vertrag lebt im Repo; der Executor kann wechseln.

Ein minimales Template, das Sie heute kopieren können

Halten Sie dies in AGENTS.md auf unter einer Seite. Verlinken Sie Details statt aufzublähen.

• Scope: Docs‑Edits, Lint‑Regeln, Tests, kleine Refactorings unter 100 LOC.
• High‑risk: infra/, migrations/, auth/ erfordern CODEOWNERS‑Freigabe. Prod‑Deploy‑Workflows nicht anfassen.
• Data: Keine PII in PRs oder Fixtures. Nur synthetische Daten.
• Tools: Erlaubte MCP‑Server: test‑runner, lint. Verboten: alle Payment‑ oder Secrets‑Endpoints.
• Budgets: $10/PR, $100/Tag Repo‑Cap. Abbrechen und needs-human labeln, wenn überschritten.
• Secrets: Nur kurzlebige CI‑Tokens verwenden. Niemals Credentials committen.
• Safe merges: Unter 50 LOC, CI zweimal grün, keine guarded paths: für Auto‑Merge geeignet.
• Unsafe: DB‑Schema, Auth, Payments, Infra – immer menschliches Review.
• Memory: Menschlich verfasste Docs am höchsten gewichten, Selbstnotizen abklingen lassen; nach 14 Tagen löschen.
• Escalation: Label needs-human setzen und @team-leads taggen, wenn unsicher oder blockiert.

Das ist keine Zeremonie – es ist ein SLO für Verhalten

Irgendwann in diesem Jahr werden bei Ihnen mehr Bots laufen als festangestellte Engineers. Ohne Vertrag verhandelt jeder dieser Bots sein Verhalten zur Laufzeit. Mit Vertrag übersetzen Sie Intention in Code: Budgets werden durchgesetzt, Pfade gated, Memory begrenzt und Menschen eingebunden, wenn die Maschine unsicher ist.

Fügen Sie AGENTS.md und sein kleines Pendant hinzu. Behandeln Sie beide als Teil Ihrer Qualitätskriterien. Wenn ein Repository nicht so aufbereitet ist, dass ein Bot es lesen und befolgen kann, ist es auch für einen Menschen ohne implizites Wissen schwer wartbar.

Kernaussagen

• AGENTS.md ist ein einseitiger, repo‑lokaler Vertrag, der LLM‑Bots sagt, was zu tun ist, was tabu ist, wie viel sie ausgeben dürfen und wie sie eskalieren.
• Paaren Sie es mit einem winzigen agents.yaml, damit CI und Harnesses Budgets, Pfadregeln und Tool‑Allowlists durchsetzen können.
• Starten Sie mit fünf Essentials: Scope, guarded/deny paths, Budget‑Caps, Tool‑Allowlists und einem Eskalationspfad.
• Instrumentieren Sie Ausgaben und Tool‑Calls; zielen Sie auf $3–$7 Median‑Ausgaben pro Bot‑PR und unter 1 % Revert‑Rate nach dem Tuning.
• Halten Sie es vendor‑ und harness‑portabel; der Vertrag lebt im Repo, nicht in einem SaaS‑Control‑Panel.
• Rollen Sie in 90 Tagen aus: neue Bot‑PRs gatekeepen, Top‑Repos abdecken und Velocity sowie Incident‑Raten messen.
• Wenn Ihr Platform‑Team ausgelastet ist, kann ein nearshore Pod die Plumbing in Wochen liefern – mit 6–8 Stunden Overlap und niedrigerem TCO.