AGENTS.md: eine Datei im offenen Format mit Anleitungen für KI-programmierte Intelligenzen

AGENTS.md ist ein einfaches, quelloffenes Format, das von OpenAI und anderen zusammengestellt wurde. Es wurde entwickelt, um Anleitungen für die Programmierung von KI-Intelligenzen (Kodieragenten) zu geben, und funktioniert ähnlich wie das speziell entwickelte KI-LeseprogrammREADME.mdDokumentation. Bei Softwareprojekten ist dieREADME.mdDie Dokumentation wird in der Regel für menschliche Entwickler geschrieben und umfasst Dinge wie Projektbeschreibungen, Anleitungen für den Einstieg und Richtlinien für Beiträge. WährendAGENTS.mdStattdessen liegt der Schwerpunkt auf der Bereitstellung spezifischerer technischer Anweisungen, die KI-Intelligenzen benötigen, um ein Projekt zu verstehen und sich daran zu beteiligen, z. B. detaillierte Build-Schritte, Testbefehle und codebasisspezifische Spezifikationen. Durch die Ausgliederung dieser Anweisungen für die KI in eine spezielleAGENTS.mdDatei, ist es möglich, dieREADME.mdHalten Sie es einfach und stellen Sie gleichzeitig eine klare, vorhersehbare Quelle von Anweisungen für KI-Intelligenzen bereit, damit diese ihre Codierungsaufgaben effizienter und genauer ausführen können.

Funktionsliste

• Klare Anweisungen erteilenAls Datei, die speziell für KI-Intelligenzen entwickelt wurde, bietet sie einen zentralen und klar definierten Ort für alle Anweisungen und Zusammenhänge, die die KI bei der Verarbeitung von Code befolgen muss.
• Rationalisierung der ProjektdokumentationEntfernen Sie KI-spezifische technische Anweisungen (z. B. Bau- und Testdetails) aus dem HauptteilREADME.mdDatei abgetrennt wird, wodurch dieREADME.mdKann sich mehr auf die Bereitstellung von Kerninformationen für menschliche Entwickler konzentrieren.
• Standardisiertes Format:: Als offenes Format.AGENTS.mdDurch die Verwendung der standardmäßigen Markdown-Syntax gibt es keine zwingenden Feldanforderungen, und die Entwickler können den Inhalt je nach Projektbedarf frei organisieren.
• Unterstützung für komplexe Projekte: In großen Monorepo-Repositories ist es zulässig, separate Unterprojekte innerhalb desAGENTS.mdDateien. Die Intelligenz liest automatisch das Verzeichnis, das dem aktuellen Arbeitsverzeichnis am nächsten liegt, und ermöglicht so eine feinkörnige Anleitung für verschiedene Module.
• Ökosystem-kompatibelDieses Format ist so konzipiert, dass es mit dem wachsenden Ökosystem von KI-Programmiertools kompatibel ist, einschließlich einer breiten Palette von KI-Programmierintelligenzen von OpenAI, Google und anderen.

Hilfe verwenden

AGENTS.mdDie Dokumentation ist als "Bedienungsanleitung" für KI-Programmierintelligenzen gedacht, um die Codebasis zu verstehen und zu manipulieren. Sie hilft KIs, Aufgaben von der Einrichtung der Umgebung bis zur Übermittlung des Codes effizient zu erledigen, indem sie klare Anweisungen gibt. Nachstehend finden Sie eine ausführliche Beschreibung der Verwendung und der Bedienung des Programms.

Schritt 1: Erstellen Sie die Datei AGENTS.md

Erstellen Sie im Stammverzeichnis Ihrer Codebasis manuell eine Datei namensAGENTS.mdDie Datei. Diese Datei ist der Ort, an dem die KI-Intelligenzen nach Anweisungen suchen. Die meisten KI-Programmierintelligenzen sind so konzipiert, dass sie diese Datei automatisch erkennen und lesen.

Schritt 2: Schreiben von Kerninhalten

AGENTS.mdMithilfe des Standardformats Markdown können Sie Überschriften und Listen erstellen, wie Sie es auch in einem normalen Dokument tun würden. Der Inhalt sollte sich darauf konzentrieren, klare, umsetzbare Schritte für AI zu liefern. Hier sind einige Vorschläge für die wichtigsten Abschnitte, die Sie abdecken sollten:

1. tipps zur Dev-Umgebung
In diesem Abschnitt erfährt AI, wie man eine lokale Entwicklungsumgebung vorbereitet, insbesondere für Projekte, die einen bestimmten Paketmanager verwenden.

• Beispielcode (Rechnen)::

  # AGENTS.md 示例
  ## 开发环境提示
  - 使用 `pnpm dlx turbo run where <project_name>` 命令跳转到特定包的目录，而不是用 `ls` 扫描。
  - 运行 `pnpm install --filter <project_name>` 为工作区添加依赖，确保Vite、ESLint和TypeScript能够识别它。
  - 使用 `pnpm create vite@latest <project_name> -- --template react-ts` 快速创建一个包含TypeScript配置的React + Vite新包。
  - 检查每个包内 `package.json` 文件中的 `name` 字段来确认包的正确名称，忽略顶层的 `package.json`。
  

2. die Prüfanweisungen
In diesem Abschnitt wird die KI angewiesen, Tests durchzuführen, um sicherzustellen, dass der von ihr erzeugte Code den Qualitätsstandards des Projekts entspricht. Die KI versucht, diese Befehle auszuführen und korrigiert den Code auf der Grundlage der Testergebnisse.

• Beispielcode (Rechnen)::

  ## 测试指令
  - CI计划文件位于 `.github/workflows` 文件夹中。
  - 运行 `pnpm turbo run test --filter <project_name>` 来执行该包定义的所有检查。
  - 在包的根目录中，可以直接调用 `pnpm test`。合并代码前必须通过所有测试。
  - 若要专注于某个特定的测试，可以添加Vitest匹配模式：`pnpm vitest run -t "<test name>"`。
  - 修复所有测试或类型错误，直到整个测试套件全部通过。
  - 修改文件或导入后，运行 `pnpm lint --filter <project_name>` 来确保ESLint和TypeScript规则仍然通过。
  - 即使没有被要求，也为你修改的代码添加或更新测试。
  

3. die Anweisungen für Pull-Anfragen (PR-Anweisungen)
Wenn Sie möchten, dass die KI-Beiträge den Spezifikationen des Teams entsprechen, können Sie dies hier ausdrücklich angeben.

• Beispielcode (Rechnen)::

  ## PR 指令
  - 标题格式: [<project_name>] <标题>
  - 在提交（commit）之前，务必运行 `pnpm lint` 和 `pnpm test`。
  

Schritt 3: Spezielle Konfigurationen für große Projekte

Wenn Ihr Projekt eine einzelne Codebasis (Monorepo) ist, die mehrere unabhängige Unterprojekte oder Pakete enthält, können Sie in der Wurzel jedes Unterprojekts eineAGENTS.mdDokumentation.

• ArbeitsprinzipWenn eine KI-Intelligenz in einem Unterverzeichnis arbeitet, wird sie bevorzugt das nächstgelegene Verzeichnis lesen.AGENTS.mdDatei. Dies bedeutet, dass die Datei des StammverzeichnissesAGENTS.mdEs können globale Befehle angegeben werden, und die Befehle jedes UnterprojektsAGENTS.mdDann können spezifischere Anweisungen, die ausschließlich für dieses Modul gelten, gegeben werden.
• typisches Beispiel:: Es wird davon ausgegangen, dass das Projekt wie folgt strukturiert ist:

  /my-monorepo
  ├── AGENTS.md         # 全局指令
  ├── /packages
  │   ├── /frontend
  │   │   ├── AGENTS.md # 前端专用指令
  │   │   └── ...
  │   └── /backend
  │       ├── AGENTS.md # 后端专用指令
  │       └── ...
  └── ...
  

  Wenn die KI in/packages/frontendVerzeichnis, folgt es demAGENTS.mdAnweisungen in der Datei.

Schritt 4: Kontinuierliche Aktualisierung

AGENTS.mdEs sollte als ein dynamisches "lebendes Dokument" behandelt werden. Denken Sie daran, dieses Dokument zu synchronisieren und zu aktualisieren, wenn sich der Erstellungsprozess, die Testbefehle oder die Codierungsspezifikationen Ihres Projekts ändern, damit die KI-Intelligenzen immer über die genauesten Anweisungen verfügen.

Anwendungsszenario

1. Neues Projekt und AI-Zusammenarbeit
   Wenn ein neues Projekt gestartet wird, ist es möglich, von Anfang an eineAGENTS.mdDokumentation. In der Datei können der Technologie-Stack des Projekts, die Befehle zum Aufbau der Umgebung, der Code-Stil und der Testprozess definiert werden. Auf diese Weise können nachfolgende KI-Programmierintelligenzen, die an dem Projekt beteiligt sind, die Projektspezifikationen sofort "lesen und verstehen" und direkt mit der Codierungsaufgabe beginnen, was die Standardisierung und Konsistenz der anfänglichen Codebasis gewährleistet.
2. Pflege einer großen einheitlichen Codebasis (Monorepo)
   In großen Codebasen, die mehrere Front-End-Anwendungen, Back-End-Dienste und gemeinsam genutzte Bibliotheken enthalten, haben verschiedene Module oft unterschiedliche Build- und Testbefehle. Durch die Platzierung eines exklusivenAGENTS.mdDatei, die der KI-Intelligenz genaue kontextbezogene Hinweise darauf geben kann, welche spezifischen Befehle sie bei der Änderung eines bestimmten Moduls ausführen soll, um Verwirrung und Fehler zu vermeiden.
3. Automatisiertes Code-Refactoring und Migration
   Wenn ein umfangreiches Code-Refactoring erforderlich ist, wie z. B. die Aktualisierung einer Framework-Version oder das Ersetzen veralteter Bibliotheken, können detaillierte Schritte und zu beachtende Regeln in dieAGENTS.mdKI-Intelligenzen können die gesamte Codebasis auf der Grundlage dieses "Aktionshandbuchs" systematisch ändern und bestimmte Testbefehle ausführen, um die Korrektheit der einzelnen Schritte zu überprüfen, was die Effizienz des Refactoring erheblich verbessert.

QA

1. AGENTS.md Gibt es Pflichtfelder in dem Dokument?
   Nein.AGENTS.md Es wird das Standardformat Markdown verwendet, das sehr flexibel ist. Sie können beliebige Überschriften und Inhalte verwenden, und die KI-Intelligenz wird den von Ihnen bereitgestellten Text analysieren und die darin enthaltenen Anweisungen befolgen.
2. Wenn die Chat-Eingabeaufforderung des Benutzers nicht mit der AGENTS.md Was passiert, wenn die Anweisungen in der
   Die explizite Chat-Eingabeaufforderung (Prompt) des Benutzers hat die höchste Priorität und hat Vorrang vor allen Anweisungen in der Datei. Liegen keine direkten Benutzeranweisungen vor, folgt die KI derAGENTS.mdRegeln. Bei verschachtelten Dateien wird die der aktuell bearbeiteten Datei am nächsten liegende DateiAGENTS.mdDie Anweisungen des Testaments werden wirksam.
3. AI Intelligence wird automatisch ausgeführt AGENTS.md Möchten Sie die Befehle testen, die im Abschnitt
   Ja, wenn Sie die Testbefehle in der Datei auflisten, werden die KI-Intelligenzen versuchen, die entsprechenden Verfahrensprüfungen (z. B. Einheitstests, Typüberprüfung usw.) durchzuführen, bevor sie die Aufgabe abschließen und den Code auf der Grundlage der Ergebnisse der fehlgeschlagenen Tests korrigieren.
4. AGENTS.md Kann eine Datei geändert werden, nachdem sie erstellt worden ist?
   Ja, sicher. Sie sollten dieAGENTS.mdBetrachten Sie es als ein "lebendes Dokument", das dynamisch aktualisiert wird. Wenn sich das Projekt weiterentwickelt, wird das Dokument aktualisiert, um sicherzustellen, dass es den aktuellen Status und die Spezifikationen des Projekts genau wiedergibt.