AGENTS.md Guide: Open-Source-Format "Projektbeschreibung" für die Codierung von Agenten (KI-Agenten). AGENTS.md handelt es sich um ein Open-Source-Anweisungsformat für "KI-Codierungsagenten". Es ist wie die "Agent-Version" der README-Datei: Sie versorgt den Agenten mit wichtigen Informationen wie Builds, Tests, Codespezifikationen und Überlegungen und hilft dem Agent, Aufgaben in Ihrer Codebasis zuverlässiger auszuführen. Laut der Website hat eine große Anzahl von Open-Source-Projekten dieses Format übernommen. Das Designziel ist es, für mehrere Agenten und Tools einheitlich zu sein und sich für Teams und Open-Source-Repositories zu eignen, um sie schnell zu implementieren.
1. Was ist AGENTS.md
1) Positionierung: Ein Dokumentationsdokument für KI-Codieragenten, das eine funktionale Ergänzung zur README darstellt.
2) Ziel: Geben Sie den Agenten einen festen, vorhersehbaren Zugang, um den Kontext und die Anweisungen zu zentralisieren, um "Agenten effizient arbeiten zu lassen".
3) Formular: Reines Markdown, keine erzwungenen Felder; Write on Demand für langfristige Wartung und Versionsverwaltung.
2. Warum benötigen Sie AGENTS.md (Beziehung zu README)
1) README richtet sich an menschliche Leser und legt den Schwerpunkt auf Produktbeschreibungen, Schnellstarts und Beitragsleitfäden.
2) AGENTS.md Agent-orientiert, wobei der Schwerpunkt auf Build-/Testbefehlen, Codestil, CI-Anforderungen und Sicherheitspunkten liegt.
3) Vorteile der Trennung: Halten Sie die README-Datei kurz und geben Sie den Agenten ein spezielles Dokument, in dem es heißt: "Schauen Sie sich das einfach an und Sie können die Arbeit erledigen".
3. Kerndesign und ökologische Kompatibilität
1) Offenes Format: Verwenden Sie beliebige Unterabschnittstitel und Inhaltsstrukturen, Proxy-Parse nach Text, keine proprietäre Syntax.
2) Multi-Agenten-Kompatibilität: Die offizielle Liste der Anpassungsanweisungen für mehrere Agenten/Tools (wie Codex, Amp, Jules, Cursor, Factory, RooCode, etc.).
3) Prioritätsregel: Im Falle eines Befehlskonflikts greift die AGENTS.md, die der Zieldatei am nächsten liegt; Explizite Anweisungen für Benutzerdialoge haben Vorrang vor generischen Anweisungen.
4) Monorepo-freundlich: Unterstützung für das Platzieren von "nahegelegenen" AGENTS.md in Unterpackungen; Große Lager können Agentenbeschreibungen für verschiedene Teilprojekte in Ebenen verwalten.
4. Wie man übernimmt (vier Schritte)
1) Dateien hinzufügen: Erstellen Sie eine AGENTS.md im Stammverzeichnis der Codebasis; Legen Sie ggf. ein Exemplar in das Unterpack.
2) Abdeckungsfokus: Projektübersicht, Build- und Testbefehle, Codestil, Testspezifikationen, Sicherheits- und Compliancepunkte.
3) Ergänzende Regeln: Einreichungsinformationen und PR-Spezifikationen, Downloads von Daten- und Modellressourcen, Bereitstellungsschritte und häufige Fallstricke.
4) Iterative Wartung: Behandeln Sie es als "lebendes Dokument" und aktualisieren Sie es, wenn die CI-/Abhängigkeits-/Verzeichnisstruktur aktualisiert wird.
5. Die minimal verfügbare Vorlage
# AGENTS.md ## Projektübersicht - Monorepo + PNPM-Arbeitsbereich。 Die Hauptsprache ist TypeScript. ## Einrichtung & Aufbau - Installieren: pnpm install - Entwickler: pnpm dev - Prüfung: pnpm-Prüfung - Flusen: pnpm Flusen ## Code-Stil - TS strikter Modus; einfache Anführungszeichen, keine Semikolons; Funktionale Ausdrücke haben Vorrang. ## Testen - CI unter .github/workflows; Alle Anwendungsfälle müssen lokal übergeben werden, bevor ein Commit ausgeführt wird. ## PR-Regeln - Titel: [<pkg>] <Titel>; Sie müssen lint und test ausführen, bevor Sie einen Commit ausführen. ## Sicherheit - Reichen Sie .env nicht ein; Schlüssel werden mithilfe von Warehouse-Geheimnissen oder lokalen Injektionen injiziert.
6. Typische Anwendungsfälle
1) Open-Source-Repository: Lassen Sie den Agenten, der damit in Kontakt kommt, "out of the box and test" und führen Sie automatisch Build/Einzeltest/statische Prüfung durch.
2) Zusammenarbeit im Team: Explizite "implizite Konventionen" (Codierungsstil, Einreichungsprozess), um die Reibung zwischen Agenten und Personen zu reduzieren.
3) Verwaltung großer Lager: Aufteilung AGENTS.md nach Teilprojekten, um Anweisungen in der Nähe und differenzierte Prozesse zu erreichen.
4) Sicherheit und Compliance: Schreiben Sie deutlich die "nicht hochladbaren Daten/Modelle" und die rote Linie für die Sicherheit, um das Risiko automatisierter Vorgänge zu verringern.
7. Implementierungsvorschläge und Risikowarnungen
1) Beginnen Sie mit der "Mindestvorlage": Erstellen Sie nur Regeln, testen, gestalten und PR und verfeinern Sie sie dann schrittweise.
2) An CI anpassen: Synchronisieren Sie Tastaturkurzbefehle von CI zu AGENTS.md, um zu vermeiden, dass der Agent ausgeführt wird, CI jedoch nicht.
3) Explizite Konfliktbehandlung: Schreiben Sie am Anfang der Datei, dass "wenn es einen Konflikt mit der Benutzeranweisung gibt, hat die Benutzeranweisung Vorrang".
4) Unsichere Aussage: Wenn es um Indikatoren wie "wie viele Projekte wurden angenommen" geht, wird empfohlen, "gemäß der Selbsterklärung der Website" zu markieren, um Fehlinterpretationen der Daten zu vermeiden.
Häufig gestellte Fragen und Antworten
F: Gibt es Pflichtfelder oder Standardvorlagen für AGENTS.md?
A: Nein. Es handelt sich um eine generische Markdown-Anweisung, die die Organisation von Kapiteln entsprechend den tatsächlichen Bedürfnissen des Projekts fördert.
F: Wie teilen Sie die Arbeit mit der README auf?
A: README ist für Menschen; AGENTS.md Agentenorientiert. Ersteres spricht über "was/wie man anfängt" und letzteres spricht über "wie der Agent Builds/Tests/Spezifikationen ausführt".
F: Wie organisiert Monorepo mehrere AGENTS.md?
A: Legen Sie die allgemeine Beschreibung in das Stammverzeichnis und fügen Sie die nächstgelegene Beschreibung in das Unterpaket ein; Agenten priorisieren in der Regel das Lesen der nächstgelegenen Kopie der Zieldatei.
F: Unterstützen Sie mehrere Proxy-Tools?
A: Laut der Projektseite ist es so konzipiert, dass es mit mehreren Agenten und Tools kompatibel ist, und im Prinzip "ein Dokument, mehrere Agenten sind verfügbar".
