DeepSeek Harness: AGENTS.md wird nicht geladen

Die öffentliche Projektdokumentation nennt 873 bestandene Tests, eine lokale SQLite-Sitzungsspeicherung und einen Arbeitsbereichsschutz für Dateioperationen. (github.com) Wenn DeepSeek Harness AGENTS.md nicht lädt, sollten Sie deshalb nicht zuerst den Inhalt der Datei umschreiben. Prüfen Sie in dieser Reihenfolge: Sitzungs-Arbeitsverzeichnis, erkannte Projektwurzel, gefundene Kandidatendateien, Kontextbudget und anschließend eine neue Sitzung. Erst wenn diese Punkte belegt sind, lohnt sich die Analyse von Regelkonflikten.

Diese Anleitung ist für Sie gedacht, wenn Sie bereits eine AGENTS.md angelegt haben, der Agent Ihre Projektvorgaben aber ignoriert. Sie richtet sich außerdem an technische Verantwortliche mit Monorepos oder mehreren Projekt­ebenen sowie an Betreiber, bei denen sich das Verhalten nach einer Migration auf einen entfernten Mac verändert hat.

Das erste Symptom richtig einordnen

Ein typischer Fehler sieht so aus: Die Datei liegt sichtbar im Repository, eine neue Sitzung startet scheinbar normal, und trotzdem verwendet der Agent die vorgeschriebene Testausführung, den erlaubten Änderungsbereich oder die gewünschte Sprache nicht. Daraus folgt zunächst nur, dass die Regel im beobachteten Verhalten nicht nachweisbar ist. Es folgt nicht automatisch, dass DeepSeek Harness die Datei gelesen und anschließend „ignoriert“ hat.

Für die Diagnose müssen Sie drei Zustände auseinanderhalten:

• Datei vorhanden: Das Betriebssystem kann die Datei unter einem bestimmten Pfad anzeigen.
• Datei gefunden: Der Harness hat sie als mögliche Anweisungsquelle in seiner Kandidatenprüfung berücksichtigt.
• Datei im Kontext: Ihr Inhalt wurde tatsächlich in die Sitzung übernommen oder für den Agenten verfügbar gemacht.

Die öffentliche Chat-Dokumentation zeigt beispielsweise eine explizite Leseoperation für AGENTS.md; außerdem unterstützt der Agent Sitzungen, die fortgesetzt werden können. (github.com) Beides ist für die Fehlersuche wichtig: Eine sichtbare Datei ist kein Beweis für eine geladene Datei, und eine fortgesetzte Sitzung kann weiterhin mit einem früher zusammengestellten Kontext arbeiten.

Vor dem Sitzungsstart: Arbeitsverzeichnis und Projektwurzel

Beginnen Sie nicht mit der Regeldatei, sondern mit dem Ort, an dem die Sitzung tatsächlich startet. Bei der CLI ist das der Startordner des Prozesses. Bei einer Weboberfläche oder einem entfernten Mac kann zusätzlich ein ausgewählter Workspace eine andere Bedeutung haben als der Ordner, in dem das Repository tatsächlich liegt.

Notieren Sie vor jeder neuen Prüfung:

1. den Ordner, aus dem dsh beziehungsweise der Harness-Prozess gestartet wird;
2. den in der Oberfläche ausgewählten Workspace;
3. den absoluten Pfad des Repositorys;
4. den Pfad, den Sie als Projektwurzel erwarten;
5. das Projektwurzel-Merkmal, das der aktuelle Harness für diese Zuordnung verwendet.

Nutzen Sie dafür zunächst ein möglichst kleines Test-Repository. Es sollte nur ein Wurzel-Merkmal, eine AGENTS.md, einen Unterordner und eine harmlose Prüfvorgabe enthalten. Verzichten Sie auf echte Zugangsdaten, private Quelltexte und Shell-Befehle mit Nebenwirkungen. Damit entfernen Sie drei häufige Störquellen: ein falsch geöffnetes Monorepo, eine übergeordnete Regeldatei und ein Geschäftsprojekt, dessen Struktur den Agenten zu anderen Dateien führt.

Ein sinnvoller Testtext ist eine ungewöhnliche, aber ungefährliche Vorgabe, etwa eine bestimmte Antwortformulierung bei einer ausschließlich lesenden Prüfaufgabe. Die Formulierung darf nicht mit einer allgemeinen Modellpräferenz verwechselt werden. Sie muss so eindeutig sein, dass Sie später erkennen können, ob sie im workspace context angekommen ist.

Wiederherstellung gilt als erreicht, wenn die neue Sitzung im erwarteten Projekt startet, die erkannte Projektwurzel mit Ihrem Testpfad übereinstimmt und der Agent die absichtlich einzigartige Regel reproduzierbar nennt oder anwendet. Wenn bereits hier ein anderer Pfad erscheint, sind spätere Änderungen an AGENTS.md noch nicht aussagekräftig.

Wird AGENTS.md automatisch gelesen?

Behandeln Sie die automatische Erkennung nicht als sprachübergreifenden Standard. AGENTS.md ist ein verbreitetes Format für dauerhafte Agentenregeln, aber jeder Harness definiert selbst, welche Dateien er sucht, in welcher Reihenfolge er Kandidaten prüft und wie er Inhalte in den Kontext einfügt. Die offizielle Konfigurations- und Architektur­dokumentation von DeepSeek Harness beschreibt globale und projektbezogene Anweisungen, Projektwurzel-Marker, Kandidatendateien und ein Kontextbudget; konkrete Standardwerte können sich jedoch mit der installierten Version ändern.

Prüfen Sie deshalb während des ersten Ladens nicht nur die Existenz, sondern die vollständige Kandidatenkette:

• Gibt es eine globale Regeldatei für den Benutzer?
• Gibt es eine projektweite AGENTS.md?
• Liegt eine weitere Anweisung in einem lokalen Unterordner?
• Existiert zusätzlich eine CLAUDE.md?
• Werden symbolische Links, Groß-/Kleinschreibung und Dateiendung auf dem Zielsystem genauso aufgelöst?
• Ist die Datei für den Prozess lesbar?
• Wurde die Sitzung mit einer Option gestartet, die benutzerdefinierte Anweisungen deaktiviert oder einschränkt?

Die eigentliche Prüfung sollte beobachtbar sein. Bitten Sie den Agenten nicht nur um „Befolgung der Regeln“, sondern um eine lesende Bestandsaufnahme:

• Welche Projektwurzel wurde erkannt?
• Welche Anweisungsdateien wurden gefunden?
• Welche eindeutige Testregel stammt aus der Projektdatei?
• Welche Regel gilt für den aktuellen Unterordner?

Wenn die Oberfläche keine Ladeübersicht bietet, verwenden Sie eine zweistufige Prüfung: Zuerst lassen Sie den Agenten die Datei ausdrücklich suchen oder lesen, ohne Änderungen zu erlauben. Danach starten Sie eine neue Sitzung und prüfen, ob die eindeutige Regel ohne erneute Dateianweisung bekannt ist. Die erste Prüfung belegt nur den Dateizugriff; die zweite prüft, ob die Anweisung in den Sitzungs­kontext gelangt.

Die Dokumentation des öffentlichen Projekts zeigt, dass Dateioperationen über Werkzeuge wie Lesen, Schreiben und Suchen erfolgen und dass Sitzungen persistent gespeichert werden. (github.com) Das ist kein Beleg dafür, dass jede Datei automatisch geladen wird. Es ist vielmehr ein Grund, Werkzeugzugriff, Anweisungsladen und Sitzungshistorie getrennt zu testen.

CLAUDE.md und lokale Überschreibungen

Wenn AGENTS.md und CLAUDE.md gleichzeitig vorhanden sind, dürfen Sie keine Priorität vermuten, die nicht in der aktuell installierten Harness-Version dokumentiert oder im Quellcode nachvollziehbar ist. Je nach Integrationsschicht können beide Dateien zusammengeführt, eine davon bevorzugt, doppelte Abschnitte zusammengefasst oder nur eine bestimmte Kandidatenquelle berücksichtigt werden.

Die offizielle Dokumentation eines vergleichbaren Agenten-SDKs beschreibt beispielsweise, dass CLAUDE.md als Projektkontext in die Unterhaltung eingefügt wird und dass Projekt- sowie Benutzerquellen getrennt aktiviert werden können. (code.claude.com) Das lässt sich nicht automatisch auf DeepSeek Harness übertragen, liefert aber eine wichtige Prüfregel: „Datei existiert“ und „Datei ist für diese Quelle aktiviert“ sind unterschiedliche Aussagen.

Gehen Sie bei parallelen Dateien so vor:

1. Benennen Sie die eindeutige Testregel in AGENTS.md um, ohne andere Regeln zu verändern.
2. Entfernen Sie für den Test alle doppelten Abschnitte aus CLAUDE.md oder verschieben Sie die Datei vorübergehend außerhalb des Kandidatenpfads.
3. Starten Sie eine neue Sitzung im identischen Arbeitsverzeichnis.
4. Wiederholen Sie den Test mit der eindeutigen Regel aus CLAUDE.md.
5. Legen Sie anschließend fest, welche Datei die gemeinsame Grundregel und welche Datei die integrationsspezifische Ergänzung enthält.

Als dauerhafte Struktur ist meist robuster: eine kurze, toolübergreifende Grundregel in AGENTS.md; spezielle Ergänzungen nur dort, wo die DeepSeek-Harness-Konfiguration sie tatsächlich erwartet. Vermeiden Sie zwei vollständige Kopien. Bei Änderungen müssen Sie sonst nicht nur widersprüchliche Vorgaben, sondern auch veraltete Duplikate pflegen.

Achtung: Eine scheinbar „ignorierte“ Regel kann in Wahrheit durch eine spätere, engere Anweisung für den aktuellen Pfad überlagert werden. Prüfen Sie daher immer den konkreten Zielordner und nicht nur die Repository-Wurzel.

Unterordner und Monorepo-Kontext

Nach dem Wurzeltest wechseln Sie bewusst in einen Unterordner. Dieser Schritt ist entscheidend, weil sich in einem Monorepo der effektive Regelbestand mit dem Pfad verändern kann. Eine Regel für das gesamte Repository ist nicht zwingend identisch mit einer zusätzlichen Vorgabe für apps/web, packages/api oder ein separates eingebettetes Projekt.

Vergleichen Sie zwei neue Sitzungen:

• Sitzung A startet im Repository-Stamm.
• Sitzung B startet direkt im relevanten Unterordner.

Verwenden Sie dieselbe lesende Prüfaufgabe und dieselbe eindeutige Testregel. Halten Sie fest:

• erkannte Projektwurzel;
• gefundene Kandidaten;
• zusätzliche lokale Regeln;
• Widersprüche;
• Verhalten bei einer Dateiänderung im Unterordner.

Achten Sie auf zwei schwer erkennbare Fälle. Erstens können gleiche Textabschnitte zusammengeführt oder in der Darstellung eingekürzt werden. Dann sieht es so aus, als fehle eine Datei, obwohl nur der wiederholte Inhalt nicht nochmals sichtbar erscheint. Zweitens kann ein verschachteltes Repository eine eigene Wurzel bilden. Der Agent arbeitet dann möglicherweise mit den Regeln des inneren Projekts, während Sie die Datei des äußeren Repositorys kontrollieren.

Die allgemeine Dokumentation zu agentischen Anweisungen zeigt, dass der nächstgelegene AGENTS.md-Pfad in manchen Umgebungen Vorrang vor einer weiter entfernten Datei erhält. (docs.github.com) Diese Regel ist kein automatischer DeepSeek-Harness-Vertrag, aber sie erklärt, warum eine Datei im Stamm nicht genügt, wenn Sie aus einem tieferen Projekt starten. Für DeepSeek Harness zählt die installierte Konfiguration; Ihr Test muss den tatsächlichen Pfad nachweisen.

Inhalt, Format und Kontextbudget

Wenn der Kandidat korrekt gefunden wird, prüfen Sie als Nächstes den Inhalt. Eine große Regeldatei ist nicht automatisch besser. DeepSeek Harness verwaltet den Anweisungstext innerhalb eines begrenzten Gesamtkontexts; die genaue Grenze darf nicht durch eine unbestätigte feste Byte- oder Zeilenzahl ersetzt werden. Der relevante Wert hängt von Version, Konfiguration, Modell und bereits geladenem Sitzungsinhalt ab.

Trennen Sie daher drei Materialarten:

• Stabile Ausführungsregeln: Tests, Dateigrenzen, Freigaben, Sicherheitsvorgaben.
• Projektwissen: Architektur, Abhängigkeiten, historische Entscheidungen.
• Aufgabenmaterial: aktuelle Tickets, lange Beispiele, Logs und Designentwürfe.

Nur die erste Gruppe gehört vollständig in die dauerhaft geladene Regeldatei. Projektwissen kann in klar benannte Dokumente ausgelagert und bei Bedarf angefordert werden. Aufgabenmaterial sollte in die jeweilige Sitzung oder eine gezielte Referenz, nicht in jede Sitzung, die das Repository öffnet.

Prüfen Sie außerdem:

• UTF-8-Kodierung ohne unerwartete Steuerzeichen;
• normale Zeilenenden;
• lesbare Dateirechte;
• keine leere Datei nach einer fehlerhaften Synchronisation;
• keine Markdown-Struktur, bei der eine wichtige Regel nur als Beispiel oder Kommentar erscheint;
• keine widersprüchlichen Imperative in mehreren Ebenen;
• keine geheimen Werte, Tokens oder personenbezogenen Daten.

Ein brauchbarer Test ist die schrittweise Kürzung: Kopieren Sie die Datei in eine temporäre Version, behalten Sie nur fünf bis zehn eindeutig formulierte Regeln und starten Sie eine neue Sitzung. Wird diese Minimalversion geladen, lag die Ursache wahrscheinlich im Umfang, in einer Formatbesonderheit oder in einer Konfliktkette. Wird auch sie nicht geladen, kehren Sie zu Pfad, Projektwurzel und Aktivierung zurück.

Die Empfehlung, dauerhafte Anweisungen kurz und auf konkrete Arbeitsweisen zu begrenzen, entspricht auch den offiziellen Leitlinien anderer Agentenplattformen: Wiederkehrende Repository-Regeln gehören in Anweisungsdateien, ausführliche, nur gelegentlich benötigte Abläufe eher in Skills oder separate Dokumentation. (docs.github.com)

Nach der Änderung: alte Sitzung oder neues Kontextfenster?

Ändern Sie AGENTS.md niemals und bewerten Sie das Ergebnis anschließend nur in einer fortgesetzten Sitzung. Die Sitzung kann bereits zusammengestellten Kontext, frühere Antworten oder eine Zusammenfassung enthalten. Das beweist weder ein fehlerhaftes Datei-Monitoring noch eine sofortige Neuladung.

Führen Sie drei getrennte Tests durch:

1. Alte Sitzung fortsetzen: Prüfen Sie, ob die alte Regel weiterhin verwendet wird.
2. Neue Sitzung im selben Prozess: Prüfen Sie, ob der Startkontext neu aufgebaut wird.
3. Prozess vollständig neu starten: Prüfen Sie, ob Konfiguration, Workspace und Anweisungsdateien erneut ermittelt werden.

Speichern Sie für jeden Test den Zeitpunkt, den Commit oder Dateistand, den Startpfad, die verwendete Regeldatei und die beobachtbare Antwort. Bitten Sie den Agenten, die neue Testregel wörtlich zu nennen oder eine sichere, überprüfbare Entscheidung danach zu treffen. Vermeiden Sie Aufgaben, bei denen mehrere Lösungen gleichermaßen plausibel sind.

Die Sitzungsverwaltung ist keine Nebensache: Das öffentliche Projekt beschreibt sowohl --resume als auch persistente Sitzungen und den Befehl zum Leeren des Transkripts. (github.com) Wenn ein alter Verlauf weiterhin aktiv ist, kann ein Test mit --resume absichtlich den vorherigen Kontext reproduzieren. Das ist für Wiederaufnahme­funktionen korrekt, aber für die Prüfung einer geänderten AGENTS.md ungeeignet.

Prüfliste für eine belastbare Freigabe

• [ ] Startverzeichnis von CLI oder Weboberfläche dokumentiert
• [ ] Tatsächlicher Workspace-Pfad mit dem Repository-Pfad verglichen
• [ ] Projektwurzel anhand eines vorhandenen Merkmals bestätigt
• [ ] Temporäres Minimal-Repository ohne Geschäftslogik getestet
• [ ] Globale, projektweite und lokale Kandidaten aufgelistet
• [ ] AGENTS.md und CLAUDE.md getrennt geprüft
• [ ] Eindeutige, ungefährliche Testregel verwendet
• [ ] Dateikodierung und Leserechte kontrolliert
• [ ] Regeltext von Hintergrundmaterial getrennt
• [ ] Alte Sitzung, neue Sitzung und Prozessneustart verglichen
• [ ] Vorherige und nachherige Antworten gespeichert
• [ ] Unterordner- und Monorepo-Verhalten separat geprüft

Remote-Mac-Migration und Wiederanlauf

Wenn die Regeln lokal funktionieren, nach einer Migration aber nicht, behandeln Sie den entfernten Mac wie eine neue Laufzeitumgebung. Prüfen Sie nicht nur den Repository-Checkout. Kontrollieren Sie auch DSH_HOME, den Benutzer, unter dem der Prozess läuft, den Workspace-Pfad, die Besitzrechte und die Frage, ob symbolische Links auf dem Zielsystem gültig bleiben.

Gehen Sie in fünf Schritten vor:

1. Ermitteln Sie die effektive Umgebungsvariable DSH_HOME innerhalb des gestarteten Prozesses, nicht nur in Ihrer interaktiven Shell.
2. Vergleichen Sie den absoluten Repository-Pfad lokal und remote.
3. Prüfen Sie Eigentümer und Leserechte von AGENTS.md, CLAUDE.md sowie den übergeordneten Verzeichnissen.
4. Starten Sie den Harness im entfernten System mit demselben Minimal-Repository und derselben Testregel.
5. Vergleichen Sie die Ergebnisse erst danach mit dem produktiven Monorepo.

Datenschutz und Stabilität gehören in diese Prüfung. Regeldateien enthalten oft interne Pfade, Testdaten, Architekturentscheidungen oder Zugangshinweise. Übertragen Sie nur, was die Remote-Sitzung benötigt, und trennen Sie private Projektdokumentation von allgemein notwendigen Agentenregeln. Hinweise zum Umgang mit personenbezogenen oder vertraulichen Daten sollten Sie zusätzlich in Ihrer Datenschutzdokumentation für Remote-Mac-Arbeitsplätze gegenprüfen.

Wenn der Vergleich nicht reproduzierbar ist, definieren Sie eine Rückfallumgebung: ein bekanntes Arbeitsverzeichnis, eine minimale Regeldatei und eine vollständig neue Sitzung. Erst wenn diese Kombination funktioniert, fügen Sie lokale Überschreibungen, Monorepo-Unterordner und längere Hintergrunddokumente wieder einzeln hinzu. So verhindern Sie, dass mehrere Änderungen gleichzeitig die Ursache verdecken.

Für die Auswahl einer geeigneten entfernten Mac-Umgebung ist außerdem die Übersicht der Mac-Einsatzszenarien hilfreicher als ein wiederholtes Umschreiben von Prompts. Entscheidend sind reproduzierbarer Workspace-Pfad, stabile Benutzerrechte und ein klarer Neustartprozess; reine Rechenleistung repariert keine falsche Projektwurzel.

Wenn DeepSeek Harness AGENTS.md weiterhin nicht lädt

Nach dieser Reihenfolge sollte die Ursache einer von vier Klassen zugeordnet werden können:

• Pfadfehler: Die Sitzung startet außerhalb der erwarteten Projektwurzel oder verwendet einen anderen Workspace.
• Kandidatenfehler: Die Datei liegt nicht in einem vom aktuellen Harness berücksichtigten Pfad oder wird durch eine andere Quelle ersetzt.
• Inhaltsfehler: Kodierung, Umfang, Format oder widersprüchliche Regeln verhindern eine verlässliche Übernahme.
• Sitzungsfehler: Die Datei wurde geändert, aber der alte Kontext wird fortgesetzt.

Die richtige Reaktion ist jeweils unterschiedlich. Bei einem Pfadfehler korrigieren Sie Workspace und Root-Marker. Bei einem Kandidatenfehler prüfen Sie die installierte Konfiguration und die tatsächliche Suchkette. Bei einem Inhaltsfehler kürzen und strukturieren Sie die Regeln. Bei einem Sitzungsfehler erstellen Sie ein frisches Kontextfenster oder starten den Prozess neu.

Ein unbegrenzt wachsendes AGENTS.md ist keine nachhaltige Reparatur. Wenn der Agent wiederholt dieselbe Regel verfehlt, machen Sie die Regel zunächst kürzer, eindeutiger und testbar. Legen Sie anschließend fest, ob sie dauerhaft, pfadbezogen oder nur für einen bestimmten Arbeitsablauf gilt.

Wenn Ihr aktueller Mac- oder Cloud-Aufbau wechselnde Pfade, unklare Benutzerrechte und nicht reproduzierbare Sitzungsstarts verursacht, entstehen drei konkrete Nachteile: Sie können einen Regel­fehler nicht sauber von einem Umgebungsfehler trennen, Remote-Ergebnisse lassen sich nur schwer vergleichen, und jede neue Sitzung verbraucht zusätzliche Prüfzeit. Für kurzfristige Tests, Team-Onboarding oder die Validierung eines neuen DeepSeek-Harness-Workspaces kann ein gemieteter Mac daher die bessere Option sein, sofern Sie keine dauerhafte Hochlastumgebung und keine exklusiven physischen Schnittstellen benötigen. Prüfen Sie vorab die Mietoptionen für Mac-Arbeitsumgebungen und verwenden Sie die Umgebung anschließend mit einem festen Workspace-, DSH_HOME- und Berechtigungsprotokoll.

Entscheidend ist nicht, ob Ihre AGENTS.md groß genug ist. Entscheidend ist, ob Sie für jede Sitzung nachweisen können, wo sie startet, welche Regeldateien gefunden werden und wann der Kontext neu aufgebaut wurde.

Weiterlesen

• DeepSeek Harness in GitHub Actions: Einrichtung und Fehlersuche
• Agent-Plugins und der neue Standard für KI-Entwicklungsumgebungen