Subagenten in der Praxis: Rollen, Budgets, Sperrungen und stille Fehler

Unter all dem befindet sich die Berechtigungsstufe, die tatsächlich die Vorgaben durchsetzt. Der unüberwachte Implementierer hat seine Datei- und Shell-Befehle in den Projekt-Einstellungen in der Erlaubnisliste aufgeführt, und alles, was außerhalb dieser Liste liegt, muss zur Genehmigung angehalten werden. Was die Anweisung besagt, ist die Richtlinie; die Erlaubnisliste ist der Zaun.

Eine weitere Zeile in diesem Agenten existiert aufgrund des teuersten Fehlers: Die nummerierten Aufgaben sollen als serielle Warteschlange, von oben nach unten, in einer einzigen Durchlaufphase bearbeitet werden, ohne parallele Arbeiter und ohne Unterbrechung zur Berichterstattung nach jeder Aufgabe.

Parallel agierende Agenten klingen nach höherer Geschwindigkeit, sind aber keineswegs so. Jeder von ihnen gibt schließlich seine gesamte Ausgabe in den Kontext zurück, der ihn erstellt hat, und eine anscheinend clevere Verteilung der Daten kann die Sitzung überlasten, die alles lesen muss. Auf diese Weise geht echte Arbeit verloren. Die parallele Ausführung über separate Dateien sollte nur für bestimmte Aufgaben aktiviert werden, niemals als Standard. Der Standard ist, dass ein Worker nacheinander eine Warteschlange durchläuft.

Ohne Budget gibt es alles aus

Jeder Unteragent mit Werkzeugen wie Suchfunktionen, Abruffunktionen oder einer Shell wird weiterarbeiten, bis etwas ihn stoppt, und „das reicht“ ist keine Schlussfolgerung, zu der ein Modell allein zuverlässig gelangt. Ein Forschungsagent ohne Budget verbringt einen Nachmittag mit einer Menge versteckter Browsertabellen und liefert anschließend eine Zusammenfassung, die bereits aus den ersten drei Ergebnissen gewonnen werden könnte.

Daher startet der Web-Suchagent mit strengen Grenzen, die über seiner Methodik und über allem anderen liegen. Die zur Laufzeit geladenen Playbooks pro Quelle, die Listen der Quellen sowie Suchstrategien für jede Domain enthalten, erhalten einen eigenen Abschnitt weiter unten.

Vier Lehren aus dieser Tabelle der Grenzen sind wichtiger als die darin angegebenen Zahlen, die Sie entsprechend Ihrer eigenen Arbeit anpassen sollten.

Bieten Sie einen Tiefe-Einstellknopf an anstelle einer festen Obergrenze. Jede einzelne Einstellung ist meist falsch: zu streng für schwierige Fragen, zu großzügig für schnelle Fakten. Mit drei benannten Ebenen und einer festgelegten Standard-Einstellung wird die Auswahl von deep zu einer bewussten Entscheidung statt zu einem Zufall. Die Reihenfolge der Prioritäten ist ebenfalls klar definiert: Zuerst gelten die vom Benutzer angegebenen Werte, danach eine im Prompt genannte Ebene, anschließend die Projektkonfiguration und schließlich standard.

Ein Budget lädt zum Spielen ein, da ein Modell es als Ziel betrachtet, weshalb Beschränkungen dagegen notwendig sind. Die wichtigen Bestimmungen besagen, dass pro URL nur eine Abfrage durchgeführt werden darf, eine bereits gelesene Seite nie erneut gelesen werden darf, die Suche sofort beendet werden muss, sobald die Fragen des Anfragers beantwortet sind, und dass das verbleibende Budget nicht als Quota gilt. Eine tiefe Suche, die nach sechs Abfragen abgeschlossen wird, gilt als Erfolg und nicht als Verschwendung.

Der letzte Satz wurde hinzugefügt, nachdem eine Suche die Frage bereits bei der vierten Abfrage beantwortet hatte, aber dennoch weitergeführt wurde, weil zwanzig die vorgegebene Anzahl war. Man muss laut aussprechen, dass ein frühes Beenden ein Sieg ist.

Zählen Sie die Dinge, die Kosten verursachen. Das Abrufbudget umfasst jede Netzwerkabfrage – von nativen Abrufen über jede Stufe der Verarbeitung blockierter Seiten bis hin zu jeder HTTP-Anfrage in einem Hilfsskript – wobei jede 429-Wiederholungsanfrage in diesem Hilfsskript gesondert mitgezählt wird. Eine frühere Version zählte nur die „Abrufaufrufe“ und ließ den Agenten dadurch unbeabsichtigt durch die Lücke schlüpfen. Das war kein Betrug; es wurde lediglich eine schlecht formulierte Regel getreulich befolgt.

Stellen Sie sicher, dass es Ausgaben meldet. Nach jeder Phase gibt der Agent eine Zeile wie [deep: 3/20 Suchvorgänge, 5/30 Abfragen] an. Ohne diese Meldung kann man nicht unterscheiden, ob eine sorgfältige Suche stattfindet oder alles außer Kontrolle gerät, bis es vorbei ist. Wenn das Budget mit unbeantworteten Fragen aufgebraucht ist, stoppt der Agent und gibt genau an, was noch unbekannt ist, welche URL am ehesten eine Antwort liefern könnte, und dass ein erneuter, tiefergehender Versuch eine Option ist. Das einzige verbotene Vorgehen ist, weiterzumachen, ohne dies anzugeben, da der Anrufer das Niveau ausgewählt hat und eine Überschreitung dieses Budgets diese Wahl außer Kraft setzt.

Sperrmechanismen bilden den größten Teil eines ausgereiften Agents

Öffnet man die am häufigsten genutzte Agentendatei, fällt sofort das Verhältnis ins Auge. Die Beschreibung der Aufgabe umfasst nur einen Absatz, während die Verbote eine ganze Liste einnehmen. Diese Ungleichverteilung ist kein Platzhalter. Ein Agent mit echten Werkzeugen verfügt über weitaus mehr Möglichkeiten, technisch gesehen die Vorgaben einzuhalten, als irgendjemand vorhersagen kann.

Ein Beispiel zeigt, warum gerade die zusätzlichen Hinweise entscheidend sind. Dem Agenten wird ausdrücklich untersagt, Browser-Automatisierung zu verwenden: weder einfache Browser, noch eingebettete Vorschauen, kein Playwright, keine Chrome-Erweiterungen, keine Öffnung von Tabs oder Fenstern – und falls ein Browser-Tool angeboten wird, ist es nicht für diese Aufgabe bestimmt. Der Grund wird direkt genannt: Das Öffnen von Tabs zum Lesen der Seiten führte bereits einmal zu etwa hundert Tabs und machte eine Aufgabe damit unmöglich.

Ein weiterer Beleg stammt vom Implementierer im research-agent-Repo, wo das jeweilige Mechanismus der eigentliche Grund ist, warum jemand die Regel respektieren würde. Es darf auf keinen Fall Dateien unter agents/ oder skills/ erstellen, da agents/ zum mitgelieferten Inhalt gehört und der Paketmanager bei der Installation jedes darunter liegende .md-Datei in einen separaten obersten Agenten umwandelt. Eine versehentlich dort abgelegte Datei würde in jedem Verbraucherprojekt landen.

Das ist das Prinzip, das man herausfiltern muss: jede Beschränkung nennt ihren Mechanismus. Der Agent muss nicht überzeugt werden. Der Grund muss aufgeschrieben werden, denn eine Beschränkung ohne Grund wird überschrieben. Nach sechs Wochen, während man den Text strafft, stößt man auf einen Satz wie „Erstelle hier niemals Dateien“ – er erscheint willkürlich – und man generalisiert ihn hilfreich. Der Satz bezüglich der Verflachung durch den Installer in jedes Endbenutzerprojekt sorgt dafür, dass man ihn in Zukunft in Ruhe lässt.

Noch einige weitere Formen, die diese Beschränkungen nach längerer Zeit annehmen können:

Verbiete die Kategorie und liste die Einzelfälle auf. Ein einfacher Satz wie „Keine Browserautomatisierung“ lässt den Agenten entscheiden, ob ein Vorschaufenster erlaubt ist. Die Aufzählung von sechs bestimmten Tools, die er nicht verwenden darf, schließt die Tür, durch die er sonst einen Weg finden würde.

Nennen Sie das Verhalten, nicht nur das Tool. Die beste Zeile im Dokument verhindert eine Neigung statt einen Befehl: Wenn Sie feststellen, dass Sie einen Scraper oder einen Berichtsgenerator schreiben, hören Sie auf – denn Sie umgehen die Aufgabe, anstatt sie wirklich zu erledigen. Fähige Agenten umgehen Einschränkungen, indem sie Tools entwickeln. Das ist die Kategorie, und genau das muss verboten werden.

Bieten Sie Notfalllösungen an, sonst wird es zur Autobahn. Einige Seiten lassen sich tatsächlich nicht abrufen, weshalb es eine Reihe von Ersatzmöglichkeiten für blockierte URLs gibt. Diese werden erst dann aktiviert, wenn der normale Weg für genau diese URL fehlschlägt. Sie sichern keinen zusätzlichen Abrufvorgang, prüfen auf eine installierte Hilfsmittel ohne eine zu installieren und begrenzen die Ausgabe, damit ein vollständiger Seitenausdruck den Kontext nicht überflutet. Danach kommt der endgültige Stopp: Wenn die URL auch nach Verwendung aller verfügbaren Ersatzmöglichkeiten weiterhin unerreichbar bleibt, ist alles vorbei. Protokollieren Sie es und gehen Sie weiter – ohne weitere Versuche, ohne zusätzliche Hilfsmittel und ohne kreative Alternativen.

Erklären Sie ausführlich, warum die Ausnahme kein Schlupfloch darstellt. Ein kurzer Absatz im Dokument erklärt, dass ein einmaliger, headless durchgeführter Abruf von reinem Text die Browser-Verbotsregel nicht verletzt, da dieses Verbot darauf abzielt, dass ein Benutzer einen Browser nutzt und anschließend Tabellen offen lässt, die von jemand anderem geschlossen werden müssen. Wenn dieser Absatz weggelassen wird, scheinen die Ausnahme und das Verbot miteinander zu kollidieren, und ein Modell, das mit einer solchen Kollision konfrontiert wird, wählt die Interpretation, die mehr zulässt.

Sie versagen leise – und mit Selbstvertrauen

Zwei Forschungsexperimente lieferten einst nicht nur gute, sondern sogar ausgezeichnete Ergebnisse: klare Erkenntnisse, echte Quellen sowie einen zusammenhängenden Bericht. Beide nannten Reddit als Hauptquelle. Dabei hatte keines der Experimente auch nur etwas von Reddit abgerufen.

Es kam dazu, dass eine mit site:reddit.com eingeschränkte WebSearch-Anfrage zehn saubere, plausible Ergebnisse von anderen Domains zurückgab, darunter ein Community-Forum für Handwerkermärkte, eine Regierungsseite für kleine Unternehmen sowie eine Plattform zum Teilen von Präsentationen – ohne jeglichen Fehler. Kein 403-Fehler, keine leere Ergebnisliste, keine Warnung. Der Domänenfilter wurde stillschweigend ignoriert, und in den Ausgabeergebnissen wurde das nicht erwähnt. Der Agent erhielt eine ordentliche Liste nutzbarer Seiten von den falschen Orten und handelte wie jeder vernünftige Mitarbeiter mit einer solchen Liste: Er nutzte sie und meldete Erfolg.

Die an diesem Tag festgehaltene Regel bildet nun die Grundlage des gesamten Projekts: Wenn eine benannte Quelle nicht erreichbar ist, muss das System dies angeben, und es darf auf keinen Fall stillschweigend mit dem weitermachen, was das Tool stattdessen liefert. Ein Bericht, der Reddit als Hauptquelle angibt, während er Erfolg von Marktplatz-Forums angibt, ist schlimmer als ein klarer Misserfolg, da niemand, der ihn liest, das erkennen kann.

Ein fehlgeschlagener Versuch erfordert einen Neversuch. Ein Versuch, der stillschweigend seine Quellen austauscht, führt zu einer Entscheidung, die auf Beweisen beruht, von denen man annimmt, sie stammen von einer Stelle, an der sie nicht wirklich sind. Das isolierte Kontextfenster – genau diese Funktion – ist der Grund, warum man nicht mitbekommt, was vor sich geht: Es erreicht einen keine Transkription, nur die Zusammenfassung, die das System für angemessen hält.

Drei Lösungen beheben dieses Problem, und keine davon besteht darin, dem System mitzuteilen, es solle vorsichtig sein.

Unterziehen Sie es einem mechanischen Test. Es wurden keine Fehler festgestellt, weshalb der Agent keinen Grund sah, etwas zu überprüfen. Die Lösung besteht aus einem Satz, der kein Urteil erfordert: Wenn eine Suche auf eine Domain beschränkt wurde und keine der zurückgegebenen URLs dazu gehören, sollte dies als null Ergebnisse und nicht als Ergebnismenge betrachtet werden. Dafür sind weder zusätzliche Tools noch Abfragen oder Berechtigungen nötig, da die URLs bereits vorhanden sind. „Seien Sie misstrauisch gegenüber Ihren Quellen“ gibt dem Agenten nichts zu tun. „Überprüfen Sie den Hostnamen im Vergleich zu dem, nach dem Sie gefiltert haben“, tut dies hingegen.

Betrachten Sie die Herkunft als einen erforderlichen Ausgabekanal mit einem Schema. Hier hört die Form der Ausgabe auf, eine Reihe von Abschnittsüberschriften zu sein, und verhält sich stattdessen wie ein Typ. Zwei Arrays werden an ihre Schlüsselnamen gebunden.

• unreachable[] enthält einen Eintrag pro Wand, wobei die Schlüssel genau source, url und reason sind. Er umfasst sowohl fehlerhafte Abrufversuche als auch stille Ersetzungen.
• sources[] enthält einen Eintrag pro Quelle, die tatsächlich eine Antwort bereitgestellt hat, wobei die Schlüssel genau source, url und fields sind. Seiten, die geöffnet wurden, aber keine Informationen lieferten, werden nicht erfasst. Eine Quelle, die vier Felder beantwortet hat, ergibt einen Eintrag mit vier Namen, nicht vier Einträge.

Der subtile Ansatz, der anfangs falsch war: Die Herkunftsangabe dient zur Kennzeichnung und blockiert niemals. Wenn ein dokumentierter Ersatz die Frage beantwortet hat, gilt das Feld als beantwortet, und der Eintrag unreachable vermerkt lediglich, dass die Antwort nicht von der genannten Quelle stammt. Wenn ein Fehler das Feld unbrauchbar machen würde, würde dies den Ablauf genau in der Situation, in der es eine Workaround-Lösung gibt, lautstark stören.

Ein Misserfolg birgt eine Lektion, die man sich aneignen sollte. Der erste Entwurf dieses Agenten wies ihn an, an vier verschiedenen Stellen „als unerreichbar zu erfassen“, nannte jedoch weder ein Feld noch ein Array noch einen Ausgabepfad. Diese Anweisung führte zu nichts. Der Agent musste etwas erfassen, hatte aber keinen Ort dafür – daher erfasste er nichts, und niemand beschwerte sich. Immer wenn Sie eine Anweisung für einen Unteragenten schreiben, stellen Sie sicher, dass die beschriebene Aktion ein Ziel hat. „Bericht über X“ ohne einen benannten Slot für X bewirkt nichts und fühlt sich dabei in Ordnung.

Überprüfen Sie von außerhalb des Agenten aus. Ob der Agent seinen Ausgabevertrag einhält, wird durch ein danach ausgeführtes Skript entschieden – nicht durch die Zusicherung des Agenten selbst. Etwa 180 Zeilen Python prüfen den JSON-Daten gegen die deklarierten Felder, und das ist wertvoller als jede Betonung im Prompt.

Dieselbe Idee taucht bei der Umsetzung für ein Repository ohne verfügbare Testsuite auf. Die Anweisung besagt, dass es keine Testsuite gibt; der Abschnitt „Tests“ der Aufgabe listet die Prüfungen auf, die diese ersetzen, wobei jede davon ausgeführt und die Ergebnisse konkret gemeldet werden müssen. Wenn eine Prüfung besagt „Diese URL ist aufrufbar“, bedeutet das, dass sie tatsächlich abgerufen wird. Eine nicht überprüfbare URL kommt nicht in eine Datei – sie wird als unüberprüft gemeldet zusammen mit der Erklärung, was passiert ist. Denn ein Leser, der einem von niemandem überprüften Link vertraut, verschwendet Ressourcen mit einem Abruf einer 404-Seite, die durch eine einfache Suche vermieden werden könnte. Dadurch ist eine unüberprüfte URL eine schlechtere Wahl als ihr vollständiges Auslassen.

Agenten behaupten gerne eine Überprüfung, die sie nie durchgeführt haben, denn eine glaubwürdige Behauptung und eine tatsächlich durchgeführte Überprüfung erscheinen in der Zusammenfassung gleich. Für jede wichtige Prüfung soll die konkrete physische Aktion genannt werden, die als Durchführung gilt.

Eine Aufgabe pro Agent – und die Gewohnheiten, die die Dateien vergrößern

Die besten Unteragenten haben nur eine einzige Aufgabe. Hier werdet ihr wahrscheinlich Einwände erheben, denn die oben zitierten Dateien sind nicht klein, und die Forschungsagenten umfassen bis zu 188 Zeilen. Der entscheidende Unterschied: Die Aufgabe blieb dabei immer eine einzige Aussage, während die Datei an Größe zunahm. Was sich ansammelte, waren Einschränkungen, Erkennungsregeln sowie Ausgabevorgaben – sozusagen „Narbengewebe“ um ein festes Gerüst –, ohne dass im Laufe eines Jahres eine neue Verantwortung hinzukam. Zeilen, die hinzugefügt wurden, weil etwas kaputtging, bedeuten, dass die Datei ihre Aufgabe erfüllt. Zeilen, die hinzugefügt wurden, um eine neue Art von Arbeit abzudecken, sind lediglich Übergrößerung – und die Lösung besteht darin, den Agenten aufzuteilen, anstatt einfach einen weiteren Abschnitt hinzuzufügen.

Die überdimensionierten Versionen sehen alle gleich aus, und jede von ihnen wurde zu irgendeinem Zeitpunkt veröffentlicht. Es gibt den „Everything-Reviewer“, der durchschnittliche Werte aus fünf Kriterien berechnet, in keinem davon jedoch hervorsticht. Es gibt das Etikett „Senior Engineer“, hinter dem sich jedoch kein konkretes Verhalten verbirgt. Es gibt den Agenten, der Ihren CLAUDE.md neu formuliert, dabei jedoch Kosten statt konkreter Funktionalitäten hinzufügt, sowie den Agenten, der eine Fähigkeit dupliziert, bis sich die beiden voneinander entfernen. Alle teilen denselben grundlegenden Fehler: eine Aufgabe, die zu umfangreich für einen Satz wurde.

Die offensichtliche nächste Frage ist, was nach einem Jahr so etwas tatsächlich noch übrig bleibt.

Die beiden, die überlebt haben

Die meisten Beiträge zum Thema liefern Ihnen ein Organigramm von Agententypen, die Sie erstellen sollen. Die tatsächlichen Überreste nach einem Jahr sind jedoch nur zwei Agenten – und das ist’s auch schon.

Eine Offenlegung, da die eigene Regel des Artikels darauf anwendbar ist: Der Web-Suchagent entstand als Ableitung eines Open-Source-Projekts für tiefgehende Forschungsfähigkeiten. Das Skelett des Ausgabevertrags – also die Zusammenfassungsteile sowie die stets erforderliche Quellenliste – stammt nahezu wortwörtlich aus der ursprünglichen Quelle. Die darauf aufgesetzte Steuerungsstruktur, die Budgets, Sperrungen, das Herkunftsmodell sowie die Eskalationsleiter umfasst, ist eigenständig entwickelt und macht die Hälfte der Zeilenanzahl aus. Alles, was in diesem Artikel zu den „Spuren“ beziehungsweise Einschränkungen gesagt wird, betrifft genau diese Hälfte.

Der Web-Suchagent führt begrenzte Webrecherchen durch und liefert die Ergebnisse zusammen mit ihren Quellen zurück. Er ist derzeit in etwa einem Dutzend Repositories installiert, darunter eine statische Blog-Seite, einige Pipelines sowie Forschungsprojekte. Alle Informationen zu Budgets, Sperrungen und stillen Ersatzlösungen stammen aus der Überarbeitungshistorie dieser einen Datei.

Der Implementierer führt eine vollständig definierte Aufgabenwarteschlange aus, während die Planung an anderer Stelle weitergeht. Vier Projekte verfügen über eine solche. Diese vier lieferten die Lektionen zu Übergabeverträgen, Ausführungszuständen sowie den wirtschaftlichen Aspekten der Delegation.

Der Rest der Inhalte in den Agentenordnern kam zusammen mit Frameworks und fungiert wie eine „Schublade für Unnötiges“ mit besserer Markenpräsentation als eine echte. Die Spezialisten, die als notwendig erachtet wurden – ein Investigator für Flaky-Tests, ein Agent für PR-Arbeit, ein Dokumentenverfasser sowie ein Agent zur Betreuung von Codebasen für aufgegebene Projekte – klangen alle plausibel, doch fast keiner wurde tatsächlich entwickelt. Diejenigen, die übrig blieben, sind nicht unbedingt die nützlichsten. Es handelt sich dabei um Fälle, in denen derselbe spezifische Problembereich immer wieder im falschen Kontext oder bei der falschen Person auftrat.

Überspringen Sie also die Organisationsstruktur. Konzentrieren Sie sich auf die Arbeiten, die Sie lieber woanders ausführen möchten, und speichern Sie diese.

Zuerst das Template, dann die Spezialisierung

Das Muster, das dazu führte, dass die zweiten, dritten und vierten Umsetzer günstig waren, ist folgendes: Der Agent wird aus einem Template generiert und anschließend dort abgewandelt, wo das Projekt abweicht.

Die Planungsfähigkeit liefert ein Umsetzer-Template mit Platzhaltern, und beim Aufbau eines neuen Projekts werden der Agent, das Planungsdokument sowie das Aufgaben-Dokument gemeinsam erstellt. Das Ergebnis ist ein Protokoll: Lesen Sie den Vertrag, nehmen Sie die Elemente in der richtigen Reihenfolge, überspringen Sie alles, was blockiert ist, halten Sie den Ausführungszustand aktuell, bleiben Sie im Rahmen des Auftrags und berichten Sie am Ende. Diese Regeln ändern sich zwischen Projekten nie, da sie die Delegation selbst beschreiben und nichts über Ihren Code aussagen.

Danach entwickelt jede Kopie ihren eigenen Abschnitt für ihre eigene Fehlermöglichkeit, und es ist aufschlussreich, zwei davon nebeneinander zu platzieren. Das Template weist den Agenten an, den Testumfang grün zu halten. Ein Projekt verfügt überhaupt keinen Testumfang – es handelt sich dabei um ein Repository mit Prompten, wobei die einzige ausführbare Datei der Validator ist. Der Implementierer dieses Projekts sagt daher etwas völlig anderes: Das Repository enthält Prompte und Daten statt Code; das Bearbeiten einer Datei bedeutet das Bearbeiten eines Prompts; Formulierung, Reihenfolge und Betonung bilden die Implementierung; eine Überarbeitung, die besser lesbar ist, während eine strenge Einschränkung wegfällt, stellt eine Regression dar, die nicht erkannt wird, da weder Builds noch Tests vorhanden sind.

Die Kopie eines anderen Projekts erhielt die Anweisung, vor dem Programmieren die in PLAN.md aufgeführten Entscheidungen zu prüfen, sowie eine Meldemöglichkeit für alles, was eine Entscheidung durch Opus oder einen Menschen erfordert. Das Protokoll bleibt dasselbe, die Risiken unterscheiden sich jedoch.

Das ist die Aufteilung, die man sich merken sollte. Der wiederverwendbare Teil eines Sub-Agenten ist sein Protokoll, der projektbezogene Teil hingegen seine Fehlermöglichkeiten. Das Protokoll sollte als Vorlage verwendet werden, die Fehlermöglichkeiten müssen von Hand geschrieben werden – versuchen Sie nicht, mit einer einzigen Datei beides abzudecken.

Weisen Sie dem Agenten das Wissen zu und kleben Sie es nicht hinein

Hier treffen Fähigkeiten und Sub-Agenten aufeinander, und die Idee wurde viel konkreter, als davon ein echter Ablauf abhing.

Mein früherer Rat wäre gewesen, die entsprechende Fähigkeit innerhalb des Agentenkörpers zu benennen. Besser funktioniert es jedoch strenger: der Agent liest das Wissen zur Laufzeit ein, bevor er handeln kann, und die Anweisung erklärt den Grund dafür.

Der Forschungsagent kann keine Suche durchführen, bevor er eine in einer Fähigkeit gespeicherte Routentabelle gelesen hat. Die Anweisung ist als verpflichtend gekennzeichnet und besagt: Bevor jede Suche oder Abfrage durchgeführt wird, muss die Tabelle am ersten vorhandenen Pfad darunter gelesen werden; überspringen Sie dies nicht, und leiten Sie nicht aufgrund von Erinnerungen – schließlich ändern sich die Module, während die Anfrage unverändert bleibt: Eines, an das Sie sich erinnern, könnte bereits verschwunden sein, und eines, das Sie benötigen, könnte noch gar nicht existieren.

Diese Bemerkung darüber, dass sich die Liste ändert, während die Anfrage unverändert bleibt, ist der vollständige Grund für dieses Muster. Das Wissen darüber, welche Quellen welche Arten von Fragen beantworten, wie man jede davon abfragt und was als blockiert gilt, ändert sich monatlich, während die Methode konstant bleibt. Wenn man eine Quellenliste in den Agentenkörper einbaut, zwingt jede neue Quelle zu einer Änderung der Anfrage, die sonst unverändert bliebe, wodurch der Agent zuversichtlich auf ein im März gelöschtes Modul weiterleitet.

Zwei Mechanismen waren wichtiger als erwartet.

Kandidaten in Reihenfolge, anstatt eines einzigen Pfads. Der Agent läuft in Projekten, die unterschiedlich strukturiert sind, auf zwei Maschinen unter verschiedenen Benutzernamen, die von verschiedenen Installatoren eingerichtet wurden. Daher listet die Anleitung die Kandidatenorte nacheinander auf und weist an, den ersten verfügbaren zu verwenden, wobei projektbezogene Kopien Vorrang vor benutzerbezogenen haben. Wenn ein einziger Pfad fest codiert wird, funktioniert alles nur auf einer Maschine.

Literale Namen verbinden die Schichten miteinander, und nichts überprüft sie. Das Design setzt sich aus drei Ebenen zusammen: Fähigkeiten koordinieren, ein Agent erledigt die Arbeit, und Datenmodule speichern das Wissen. Es gibt überall keine Importe. Eine Fähigkeit aktiviert den Agenten unter seinem genau registrierten Namen, während der Agent die Module über den Pfad findet. Das verleiht dem Repository seinen gewöhnlichsten und gefährlichsten Satz – eine Erinnerung, den Web-Such-Agenten nicht umzubenennen, da bestehende Nutzer ihn direkt aufrufen.

Der Name eines Agents fungiert als öffentliche API, und kein Tool weist darauf hin: kein Compiler, kein Test, keine Warnung. Ein Umbenennen erscheint wie ein ordentlicher Commit, bricht jedoch alle Aufrufer in jedem Repository, das den Agenten installiert hat, und die Entdeckung erfolgt beim nächsten Mal, wenn Sie eine Suche anfordern und ein Allrounder antwortet.

Wo sich die Dateien befinden: persönlich, projektbezogen, verpackt

Es gibt drei Ebenen, und auf der dritten leben alle echten Agenten.

• Personal (~/.claude/agents/) dient allgemeinen Spezialisten, die in jedem Projekt benötigt werden. Betrachten Sie es als Werkstatt, in der es in Ordnung ist, Dinge zu zerstören.
• Project (.claude/agents/, kommittiert) ist für Spezialisten, die nur in einer bestimmten Codebasis sinnvoll sind – wie zum Beispiel ein Implementierer, der weiß, dass dieses Projekt keine Tests hat. Wenn Sie es kommittieren, wartet es darauf, dass Sie zurückkehren, selbst vier Monate später, wenn das Projekt Ihnen entfallen ist.
• Packaged (von einem Paketmanager installiert und an ein Commit gebunden) macht einen Agenten zu einer Abhängigkeit. Das ist die Ebene, von der niemand weiß, dass sie benötigt wird, bis derselbe Agent in Dutzenden Repositories vorhanden ist und dreizehn Kopien auseinanderdriften.

Die dritte Stufe ändert einige Dinge, und es ist besser, diese im Voraus zu kennen.

Bündeln Sie den Agenten mit den Fähigkeiten, die ihn aufrufen. Das Paket enthält beides als eine Einheit – aus einem einfachen Grund: Fähigkeiten, die ohne ihre Agenten installiert werden, erzeugen eine Pipeline, die bereits beim ersten Gebrauch fehlschlägt. Eine Fähigkeit, die per Name auf einen fehlenden Agenten verweist, ist eine fehlerhafte Installation, bei der bestenfalls eine klare Fehlermeldung angezeigt wird. Sie bilden eine Einheit, weil es sich um einen einzigen Vertrag handelt.

Erfahren Sie, was Ihr Installer mit Dateien macht. Dieses Paket wird über Microsofts APM installiert, wodurch jede .md-Datei innerhalb eines agents/-Verzeichnisses in einen eigenen obersten Agenten umgewandelt wird. Diese Standardkonfiguration ist sinnvoll, führt aber dennoch zu Problemen. Legen Sie eine Datendatei in dieses Verzeichnis, erhält jedes Verbrauchsprojekt einen falschen registrierten Agenten. Schreiben Sie hingegen einen projektbezogenen Agenten dorthin, installiert er sich in den Repositorien aller Nutzer. Aus diesem Grund befinden sich die Suchstrategiemodule unter skills/ und nicht im agents/-Ordner, wo sie eigentlich hingehören würden: Unter agents/ würden sie bei der Installation ihre Struktur verlieren und für jedes Verbrauchsprojekt fünf phantomhafte Agenten registrieren.

Markieren Sie einen Commit – und denken Sie daran, dass die Nutzer hinterherhinken. Die Nutzer sind von einem SHA abhängig, daher ist eine Korrektur für niemanden verfügbar, solange der Pin nicht geändert und die Installation nicht erneut ausgeführt wird. Eine Korrektur zu schreiben bedeutet noch nicht, dass sie tatsächlich bereitgestellt wird. Das klingt auf der Seite offensichtlich – ist aber um 23 Uhr, wenn der letzte Woche behobene Fehler wieder auftaucht, alles andere als das.

Trotzdem: Pflegen Sie die Strukturen. Ein Ordner, der mit überschneidenden, halb vergessenen Agenten vollgestopft ist, erzeugt nur Lärm statt nützlicher Tools. Führen Sie zwei Agenten zusammen, die zur gleichen Aufgabe gehören. Löschen Sie einen, der seit Monaten nicht mehr ausgeführt wurde – schließlich behält git die Historie bei, falls das Löschen falsch ist. Das ist auch gutes Lebensrat, wird aber bei dem eigentlichen „Müllschrank“ zu Hause ignoriert.

Dieselbe Idee in anderen Tools

Claude Code ist nicht die einzige Plattform für dieses Konzept. Wenn Sie zwischen verschiedenen Tools wechseln, übertragen sich die Ideen sogar dann, wenn die Dateiformate nicht kompatibel sind.

GitHub Copilot und VS Code bezeichnen diese als Custom Agents, die als .agent.md-Dateien gespeichert werden, in der Regel unter .github/agents/, wobei es auch die Möglichkeit gibt, eine persönliche Bibliothek im Benutzerverzeichnis zu nutzen. Der Frontmatter enthält mehr Felder als bei Claude: Neben name, description und tools gibt es außerdem argument-hint, model, user-invocable, disable-model-invocation sowie, was am besten ist, handoffs. Ein fertiger Agent kann einen Button anzeigen, der die Aufgabe an einen anderen Agent weiterleitet, wobei der nächste Prompt bereits vorgefüllt ist – so werden Planung, Umsetzung und Überprüfung nahtlos miteinander verbunden, ohne dass alles in einem unübersichtlichen Agent zusammenfällt. Eine Falle, wenn man ältere Beispiele liest: Das frühere Feld infer wurde in zwei separate Felder, user-invocable und disable-model-invocation, aufgeteilt – eine Änderung, die im Nachhinein übersichtlich ist, anfangs aber verwirrend wirkt.

Eine weitere Behauptung, auf die man stößt, ist, dass VS Code .claude/agents/-Dateien erkennt und Toolnamen übersetzt, sodass ein Agent beide Tools kostenlos bereitstellt. Das stimmt zwar, kann aber in die Irre führen. Die Tool-Vokabulare stimmen nicht überein, und eine Anfrage, die Tools nach Namen ausschließt – wie es jeder ausgereifte Agent hier tut – bleibt durch die automatische Übersetzung unverändert erhalten.

Stattdessen wird eine kanonische Anfrage zusammen mit einem einfachen, nativen Wrapper für jedes Tool bereitgestellt. Der gesamte Copilot-Agent im Paket umfasst elf Zeilen: