Guillaume Duvernay

Dein Agent hat deinen Ordner nicht gelesen

7 Min. Lesezeit

agentscontextworkspaces

Wer zum ersten Mal mit einem Agenten in einem Ordner arbeitet, nimmt oft an, dass er alles darin kennt. Deine Notizen, die Dateien zu deinen Kunden, der Ablauf, den du letzten Monat festgehalten hast. Alles liegt direkt dort, also muss der Agent es doch gelesen haben.

Hat er aber nicht. Wenn du ein neues Gespräch beginnst, weiß der Agent fast nichts über den Inhalt deines Ordners. Er weiß, dass der Ordner existiert und dass er hineinschauen kann.

Was der Agent zu Beginn tatsächlich weiß

Bei der ersten Nachricht erhält das Modell eine kurze Liste von Dingen:

  • die Anweisungen der App an den Agenten (wie er sich verhalten und die einzelnen Tools verwenden soll),
  • die Beschreibungen der Tools, die er aufrufen kann,
  • eine Datei von dir, falls du eine geschrieben hast: AGENTS.md,
  • und deine Nachricht.

Das ist alles. Alles andere im Ordner muss der Agent erst finden: Dateien auflisten, durchsuchen und die passenden öffnen. Jeder dieser Schritte ist ein Tool-Aufruf, genau wie bei einer Websuche.

In meinem Workshop zeige ich das anhand eines Ordners mit 20 Aufgabendateien. In einem neuen Gespräch frage ich, worum es bei Aufgabe 10 geht. Der Agent antwortet nicht sofort. Er durchsucht den Ordner, findet die Datei, liest sie und antwortet dann. Das funktioniert, aber er musste die Information erst holen.

Die Größenangaben dienen nur der Veranschaulichung und unterscheiden sich je nach App. Entscheidend ist, was fehlt: Von den 20 Aufgabendateien im Ordner gelangt nur die geöffnete ins Modell.

Warum das gut ist

Am Anfang ist das frustrierend. Es wäre bequem, wenn der Agent einfach alles wüsste.

Aber überleg dir, was das kosten würde. Jede Nachricht, die du sendest, umfasst alles, was das Modell erhält: die Anweisungen der App, die Tool-Beschreibungen, deine Dateien und den gesamten bisherigen Gesprächsverlauf. Würde dein Ordner bei jeder Nachricht geladen, müsstest du jedes Mal für all das bezahlen. Und das Modell müsste deinen einen relevanten Absatz zwischen all den anderen Informationen finden.

Aktuelle Modelle können sehr viel Text verarbeiten, manche bis zu etwa einer Million Tokens. Mehr Platz bedeutet aber nicht, dass alles nützlich ist. Zusätzlicher Text ist Ballast und kann das Modell genauso verwirren wie dich. Ich achte darauf, dass jedes Token im Kontext einen guten Grund hat.

Dass der Agent deinen Ordner nicht kennt, gibt dir also Kontrolle. Du entscheidest, was er immer wissen soll, und organisierst den Rest so, dass er schnell findet, was er braucht.

AGENTS.md ist dein fester Platz

AGENTS.md ist eine einfache Textdatei im Stammverzeichnis deines Ordners. Die App liest sie zu Beginn jedes Gesprächs und fügt sie neben ihren eigenen Anweisungen zum Kontext des Modells hinzu. Hier wird etwas garantiert berücksichtigt.

Mein Test: Öffne ein neues Gespräch und frage: “Wer bin ich?” Steht deine Rolle in AGENTS.md, antwortet der Agent sofort, ohne eine einzige Datei zu öffnen. Dasselbe gilt für eine Regel wie “Antworte immer in drei Aufzählungspunkten”. Schreib sie dort hinein, und jede Antwort hält sich daran.

Dasselbe Gespräch, zwei Fragen. Die erste Antwort stammt aus AGENTS.md. Die zweite muss erst abgerufen werden.

Claude Code las früher nur eine Datei namens CLAUDE.md. In neueren Versionen wird auch AGENTS.md gelesen. Diese Bezeichnung verwenden Codex und die meisten anderen Tools, sodass eine Datei für alle reicht. Falls deine Datei nicht berücksichtigt zu werden scheint, frag den Agenten, welche Anweisungen er geladen hat. Mehr dazu, wie du eine Datei für alle Tools pflegst, steht in Repos unabhängig vom Agenten-Framework halten.

Was hineingehört und was nicht

Meine Regel ist einfach: Wenn etwas nicht für fast jede Nachricht nützlich ist, gehört es nicht in AGENTS.md. Eine lange Datei kostet bei jeder einzelnen Nachricht Tokens und verdrängt die wichtigen Regeln.

AGENTS.md ist ein Einseiter. Darin steht, was immer gilt und wo alles andere zu finden ist.

Die zweite Spalte ist nicht weniger wichtig. Sie wird nur nicht bei jeder Nachricht gebraucht. AGENTS.md verweist darauf („Bei allem, was einen Kunden betrifft, lies zuerst dessen information.md“), und der Agent öffnet die Datei, wenn die Aufgabe es erfordert. So lässt sich auch in einem großen Ordner schnell arbeiten.

Probiere es aus

Öffne in deinem Ordner eine neue Unterhaltung und frage: „Wer bin ich, und welche Anweisungen hast du zu Beginn dieser Unterhaltung geladen?“

Wenn die Antwort vage ist, fehlt deine AGENTS.md oder sie enthält nicht die wichtigen Informationen. Bitte den Agenten, dir beim Schreiben zu helfen. Halte sie anschließend auf einer Seite.