OpenCode Agents Guide: 7 Prüfungen für Subagents und AGENTS.md

Kurz gesagt: Nutze AGENTS.md für Repository-Regeln und OpenCode agents für eine benannte Spezialrolle mit eigenem Prompt, Modell, Werkzeugen und Grenzen.

AGENTS.md hält dauerhafte Repository-Regeln fest: Testbefehle, Stil, generierte Ordner und Warnungen. Der Agent beschreibt das Verhalten einer bestimmten Rolle.

Wer beide Ebenen mischt, erzeugt doppelte und widersprüchliche Anweisungen.

Ein Subagent hilft, wenn er ein echtes Teilproblem trennt: großen Ordner prüfen, riskanten Diff lesen oder eine API recherchieren.

Lege einen Ausgabe-Vertrag fest, etwa Befunde mit Datei, Patchplan oder Risikoliste.

Das Modell folgt dem Risiko. Review, Architektur und Migration brauchen mehr Schlussfolgerung; Zusammenfassung und Notizen dürfen leichter sein.

Werkzeuge und Pfade sollten so eng wie möglich bleiben.

Team-Konfiguration gehört lesbar in Git, Geheimnisse gehören in Umgebungsvariablen oder Anbieterflüsse.

Stabile Namen wie reviewer oder docs-editor machen Protokolle verständlich.

Beginne mit einer Prüfung ohne Schreibzugriff. Kontrolliere Rolle, Umfang und Ausgabeformat.

Erlaube dann eine kleine Änderung und lies den Diff.

1. Rolle benennenNutze reviewer, planner oder docs-editor.
2. Ausgabe festlegenBeschreibe Ergebnis und Verbote.
3. Modell wählenPasse Denken und Kosten dem Risiko an.
4. Werkzeuge begrenzenStarte mit dem Minimum.
5. Ohne Schreiben prüfenZuerst Inspektion oder Review.
6. Diff lesenErst nach sauberem Diff erweitern.
7. Regel dokumentierenErkläre, wann der Agent passt.

Zu viele Agents verwirren die Aufgabensteuerung. Starte mit einem wiederholten Problem.

Dupliziere Regeln nicht zwischen AGENTS.md und Agent.

MCP, Hooks und Skills erhöhen den Nutzen, aber auch die Risikofläche.

Prüfe nacheinander Prompt, Werkzeug und Schreibpfad.

Bevor der Agent im Team genutzt wird, dokumentiere eine erfolgreiche Beispielaufgabe: Ziel, gelesene Dateien, ausgeführte Befehle, Ergebnis und geprüfter Diff. Diese Spur macht die Rolle überprüfbar und zeigt später, ob Änderungen die Qualität verschlechtern.

Lege außerdem eine Stoppregel fest. Wenn Kontext fehlt, soll der Agent die konkrete Datei oder den Befehl anfordern, statt zu raten. Wenn Secrets, Produktion oder breite Schreibrechte auftauchen, soll er anhalten und Risiken auflisten. So bleibt der normale Arbeitsfluss schnell, ohne gefährliche Fälle zu verdecken.

Für kleine Teams reichen meist zwei Rollen: reviewer und docs-editor. Der reviewer schützt Codeänderungen, docs-editor hält README, Anleitungen und Migrationsnotizen aktuell. Weitere Rollen wie research agent oder migration-checker lohnen sich erst bei wiederholtem Bedarf.

Plane nach der ersten Woche eine kurze Wartung. Prüfe, welche Aufgaben wirklich an den Agent gingen, welche Prompts angepasst wurden, ob Werkzeuge zu breit waren und ob die Ausgabe noch dem Vertrag entspricht. Entferne Rollen, die niemand nutzt, statt sie aus Gewohnheit in der Konfiguration zu behalten.

Halte außerdem einen einfachen Rollback bereit. Der Entwickler sollte wissen, wie der Agent deaktiviert wird, welche Datei die Rolle definiert, welche Umgebungsvariable optional ist und welcher letzte Commit die geprüfte Version enthält. Diese kleinen Betriebsdaten sind wichtiger als eine lange Rollenbeschreibung.

Lösche einen Agent auch aktiv, wenn er drei oder vier Wochen keine klare Aufgabe mehr erfüllt. Eine kleinere Liste erhöht die Chance, dass Entwickler die richtige Rolle wählen und Ergebnisse ernsthaft prüfen.

Neue Rollen sollten standardmäßig nicht automatisch aktiv sein; erst die dokumentierte Beispielaufgabe macht sie bereit für den Alltag.

Achte besonders auf sprechende Namen. reviewer, docs-editor, release-checker oder migration-planner zeigen im Log, welcher Auftrag gemeint war. Kreative Namen erschweren später die Prüfung, weil niemand mehr sicher weiß, welches Risiko oder welches Ausgabeformat zur Rolle gehörte.

Erhöhe Berechtigungen schrittweise. Ein lesender Agent darf ein großes Modul untersuchen und Empfehlungen geben; ein schreibender Agent braucht engere Pfade, bekannte Testbefehle und eine Ausgabe, die geänderte Dateien, offene Annahmen und nicht ausgeführte Prüfungen nennt.

Führe für jede aktive Rolle eine kurze Prüfnotiz. Sie sollte Zweck, erlaubte Werkzeuge, ausgeschlossene Ordner, Beispielprompt, erwartetes Ergebnis und letzten erfolgreichen Test enthalten. Wenn eine Rolle diese Notiz nicht mehr erfüllt, wird sie angepasst oder entfernt. Dadurch bleibt die Agent-Liste ein Arbeitsmittel und wird nicht zu einem veralteten Prompt-Archiv.

Diese Prüfung passt gut in die normale Sprint-Routine und braucht nur wenige Minuten.

{
  "agents": {
    "reviewer": {
      "model": "provider/reasoning-model",
      "description": "Review diffs and return concrete findings only",
      "tools": ["read", "grep"]
    },
    "docs-editor": {
      "model": "provider/fast-model",
      "description": "Update documentation after source changes",
      "tools": ["read", "edit"]
    }
  }
}

Team-Konfiguration gehört lesbar in Git, Geheimnisse gehören in Umgebungsvariablen oder Anbieterflüsse.