AGENTS.md-Prüfung (Audit)
Prüfe Anweisungen gegen den Projektzustand und die festgelegte Richtlinie. Priorisiere Behauptungen, die einen Agenten in die Irre führen könnten. Die Form oder Bearbeitungshäufigkeit allein begründet keinen Defekt. Melde keinen Defekt, wenn die Prüfungen keinen ergeben; eine kurze Bootstrapping-Dokumentation und unveränderte, korrekte Anweisungen können ausreichen.
Halte das Audit standardmäßig schreibgeschützt, einschließlich des Index und der Git-Historie. Bereite Korrekturen und eine Checkpoint-Nachricht zur Überprüfung vor. Wende Korrekturen an oder erstelle einen Checkpoint, wenn der Auftrag diese Aktion autorisiert; nutze die bestehende Autorisierung ohne erneute Nachfrage. Führe Prüfungen ohne automatische Korrektur oder andere quellschreibende Optionen aus und melde nicht verfügbare Ausführungsvoraussetzungen.
Abdeckung
Erfasse die Abdeckung als die tatsächlich untersuchten Dateien, Behauptungen, Historie und Prüfungen.
- Erfasse die Repository-Revision und den Arbeitsverzeichniszustand. Erfasse Anweisungsdateien, relevante übergeordnete Regeln, Überschreibungen, Importe, Links und Modulzuordnungen im Repository. Schließe bestehende CLAUDE.md-Systeme ein, anstatt davon auszugehen, dass AGENTS.md ihr aktiver Einstiegspunkt ist.
- Bestätige, welche Dateien die vorgesehene Umgebung erkennt und welche explizite Lesevorgänge erfordern. Überprüfe relevante Ladepfade und Größenbudgets anhand der verfügbaren Konfiguration oder der aktuellen Umgebungsdokumentation. Markiere unbekannte Auslieferung als unverifiziert; Dateinamen und Verzeichnisplatzierung allein belegen kein Laden.
- Gib die zu überprüfenden Dateien und Behauptungen an, etwaige Stichproben, Befehlsvoraussetzungen und die verfügbare Historie. Schränke das Urteil ein, wenn das Repository „dirty“ ist, die Historie flach oder nicht verfügbar ist oder Prüfungen nicht ausgeführt werden können. Prüfe lokale Änderungen getrennt von einem committed Snapshot; ordne sie nicht dessen SHA zu. Wenn eine Prüfung auf Dateien ausgeführt wird, die vom committed Snapshot abweichen (z. B. ein Arbeitsverzeichnis mit lokalen Änderungen), gib an, wo sie ausgeführt wurde und welche Pfade abwichen.
Historie und frühere Befunde
Wähle für ein Git-Repository die Basislinie (Baseline) aus, bevor zwischenzeitliche Änderungen überprüft werden. Ohne Git-Historie überprüfe den aktuellen Zustand und melde, dass eine historische Verifikation nicht verfügbar ist.
Eine abgeschlossene Prüfung hat ihre deklarierten Prüfungen des gesamten Repositorys abgeschlossen; sie kann Defekte, Stichproben und nicht verfügbare Prüfungen mit expliziten Grenzen melden. Ein sauberes Ergebnis bedeutet, dass innerhalb der abgeschlossenen Prüfungen kein Defekt nachgewiesen wurde. Eine Prüfung, die nicht abgeschlossen werden kann, erstellt einen Bericht, aber keinen Checkpoint.
Ein Checkpoint ist ein leerer, einfach-elterlicher Git-Commit, dessen Nachricht den Bericht einer abgeschlossenen Prüfung und die Trailer der Checkpoint-Nachricht-Vorlage enthält. Sein einziger Elternteil ist die geprüfte Revision, der von dieser Prüfung untersuchte committed Snapshot. Lokale Änderungen sind getrennt von diesem Snapshot. Ein Commit ist nur dann ein Checkpoint, wenn er jede Bedingung unter Basislinien-Auswahl erfüllt; jeder andere Commit ist ein gewöhnlicher Commit, unabhängig von seiner Nachricht.
Eine Basislinie (Baseline) ist der nächstgelegene Checkpoint auf der ersten-Eltern-Historie des Zielzweigs. Sie setzt die Historiegrenze, die Revision, nach der die Prüfung Änderungen bis zur geprüften Revision untersucht. Ihre neuen und übertragenen Befunde sind die vollständige Menge offener früherer Befunde. Eine Prüfung, die keinen Checkpoint erstellt, lässt die Basislinie unverändert.
Bootstrapping-Ausgabe bleibt vorläufige Dokumentation, bis sie verifiziert ist, und kann allein keine Basislinie liefern.
Basislinien-Auswahl
Gehe die erste-Eltern-Historie des Zielzweigs ab HEAD durch. Behandle Commits mit einem Agents-Audit-Version-Trailer als Kandidaten; identifiziere sie anhand des Trailers, nicht des Betreffs. Zum Beispiel:
git log --first-parent --format='%H' --grep='^Agents-Audit-Version: 1$' HEAD
git show -s --format=%B <candidate> | git interpret-trailers --parse
Diese Befehle finden Kandidaten. Ein Kandidat ist nur dann ein Checkpoint, wenn seine Nachricht und seine Git-Objekte alle diese Bedingungen erfüllen:
- Jeder Trailer in der Nachrichtenvorlage hat einen nicht-konfigierenden Wert, die Version wird unterstützt und die Fertigkeitsrevision oder der Inhalts-Hash ist identifizierbar.
- Der Commit hat genau einen Elternteil. Der vollständige SHA dieses Elternteils entspricht
Agents-Audit-Commit, und sowohl die Bäume des Elternteils als auch des Commits entsprechenAgents-Audit-Tree. Alleinige Baumgleichheit kann kein Replay auf eine andere Historie erkennen, die zufällig dieselben Dateien erzeugt. - Der Commit liegt auf der ersten-Eltern-Historie des Ziels.
Agents-Audit-Previousbenennt den nächstgelegenen früheren Checkpoint auf der ersten-Eltern-Historie der geprüften Revision, odernonefür eine explizit festgelegte anfängliche Historiegrenze. Der benannte Commit muss selbst ein Checkpoint sein.- Die Nachricht enthält jeden Berichtsabschnitt der Vorlage mit deklarierter Abdeckung. Sofern
Agents-Audit-Previousnichtnoneist, erscheint jede ID unter Neue Befunde oder Übertragene Befunde im benannten Checkpoint unter Übertragene Befunde oder Geschlossene Befunde.
Da jeder Vorgänger selbst ein Checkpoint sein muss, überprüfe die Kandidaten vom ältesten an aufwärts und verwende jedes Ergebnis erneut; jeder Commit wird dann einmal geprüft. Wähle den nächstgelegenen Kandidaten, der diese Bedingungen erfüllt, als Basislinie. Behandle jeden anderen Kandidaten als gewöhnlichen Commit im Historie-Fenster: lies keine Befunde oder Schließungen aus seiner Nachricht und lasse ihn aus dem Bericht und der Checkpoint-Nachricht heraus.
Wenn ein Vorgänger nicht verfügbar ist oder eine flache Historie diese Prüfungen verhindert, gib die Lücke an. Ersetze nicht stillschweigend eine bekannte Historiegrenze durch die letzten paar Commits oder erkläre die Arbeit zu einer Erstprüfung. Wenn keine Basislinie festgelegt werden kann, überprüfe den aktuellen Zustand innerhalb expliziter Grenzen und lasse die historische Abdeckung unverifiziert. Für eine echte Erstprüfung ohne früheren Checkpoint verifiziere den aktuellen Zustand und gib eine explizite anfängliche Historiegrenze an.
Rebase, Cherry-Pick und Squash geben Commits neue Elternteile, daher überprüfe die Bedingungen nach einer Umschreibung der Historie erneut. Erstelle beständige Checkpoints nach der Integration, wenn die Feature-Historie gesquasht wird.
Prüfungen
Genauigkeit und Richtlinie
- Überprüfe Befehle gegen die Projektkonfiguration und ihre Voraussetzungen. Führe durchführbare Prüfungen in einer geeigneten Umgebung aus. Ordne Fehler einer veralteten Ausführung, einem Implementierungsdefekt, einer nicht verfügbaren Voraussetzung oder einer unvollständigen Prüfung zu; ein gültiger Testbefehl, der eine Regression findet, ist nicht veraltet.
- Löse benannte Referenzen, Pfade, Importe und Modulzuordnungseinträge auf. Untersuche Umbenennungen, gemeinsame Eigentumsverhältnisse und anwendbare übergeordnete Regeln, bevor du eine Anweisung als fehlend bezeichnest. Demonstriere den Defekt und beurteile dann seine Schwere anhand der wahrscheinlichen Konsequenz für einen Agenten, der der Anweisung folgt, nicht anhand eines fehlenden Symbols allein.
- Überprüfe wichtige Invarianten gegen die Implementierung und Tests, behandle Docstrings und Kommentare als Behauptungen, nicht als Beweise. Überprüfe eine bedingte Behauptung mit Eingaben auf beiden Seiten ihrer Bedingung. Unterscheide Beschreibungen von Richtlinien: beabsichtigter Code kann dennoch eine festgelegte Grenze verletzen. Löse Konflikte mit der Autorität der Aufgabe und dokumentierten Entscheidungen; schreibe Richtlinien nicht nur um, um Code zu entsprechen, der sie verletzt.
- Untersuche Warnungen auf konkrete Fehler- oder Regressionspfade. Entferne veraltete oder oberflächliche Details, behalte eine nützliche Schutzmaßnahme, wenn deren Umgehung weiterhin ein realistisches Risiko darstellt, und kürze Erklärungen, die bereits durch Tests oder Durchsetzung angemessen getragen werden. Bevorzuge eine aktuelle Anleitung gegenüber einer Historie behobener Fehler.
Melde nachgewiesene Defekte als veraltet, widersprochen, fehlend, Richtlinienkonflikte oder veraltete Warnungen. Belasse unsichere Behauptungen unter unverifizierten Prüfungen. Gib die betroffene Anweisung, Repository-Evidenz, Konsequenz und vorgeschlagene Korrektur an.
Wartung
Untersuche Änderungen an Code, Konfiguration, Abhängigkeiten und Anweisungen seit der Historiegrenze. Ordne jede relevante Änderung Behauptungen zu, die sie ungültig machen könnte, einschließlich unveränderter Anweisungsdateien. Verwende Schlüsselwörter aus Commit-Nachrichten und optionale Zählungen von Commits, die Code und Anweisungen gemeinsam geändert haben, um Änderungen zur Prüfung auszuwählen, nicht um die Dokumentationsqualität zu beurteilen.
Melde einen Wartungsdefekt nur dann, wenn eine Änderung eine dokumentierte Behauptung ungültig gemacht oder eine notwendige Anweisung ausgelassen hat. Erlaube einer präzisen Invariante, viele unveränderte Änderungen zu überstehen. Behandle unabhängige Korrekturen, Bootstrapping-Commits, Audit-Reparaturen und Checkpoint-Commits als legitime Arbeit. Eine modulübergreifende Refaktorierung muss keine Anweisungen bearbeiten, deren Behauptungen weiterhin wahr sind.
Entscheidungen und Warnungen
Untersuche Architekturentscheidungen unabhängig von der Fehlersuche. Suche nach akzeptierten Entscheidungen, deren Konsequenz zukünftige Änderungen einschränken sollte und deren Grund nicht aus dem Code ersichtlich ist. Verwende eine dokumentierte Erklärung oder Bestätigung durch den Entscheidungsträger; ein Diff belegt eine Änderung, nicht deren Absicht. Formuliere die Regel, den Grund und die Bedingungen für eine erneute Überlegung nur, wenn sie belegt und noch nützlich sind. Lasse eine erwähnenswerte abgelehnte Alternative in einem Kommentar in der Quelle, die sie betrifft, wo ein Agent, der diesen Code ändert, sie finden wird. Verwende während des Bootstrapping weiterhin nur aktuelle Quellen; durchsuche die Git-Historie nicht nach Gründen oder erfinde eine Begründung.
Überprüfe bei signifikanten diagnostizierten Fehlern, ob die Lehre noch einen kostspieligen oder wiederholten Fehler verhindert. Schlage einen präzisen Eintrag vor, der Symptom, Mechanismus und Erkennung oder Vermeidung festhält, nur wenn er nützliche Anleitung hinzufügt. Wenn die Umgehung einer Abstraktion den Fehler erneut einführen könnte, formuliere die Warnung als präzise Schutzmaßnahme um und erkläre warum. Schlage Löschung vor, wenn der Mechanismus verschwunden ist, der Fehler oberflächlich ist oder die Durchsetzung die Lehre bereits angemessen trägt. Belasse unsichere Mechanismen als Vorschläge zur Bestätigung.
Form
Überprüfe die Form nach der Genauigkeit. Platziere repository-weite Regeln in der Wurzeldatei, von Modulen gemeinsam genutzte Regeln in einer Quellwurzel- oder Paketdatei (ein Hub) und unterschiedliche Modulregeln in einer lokalen Datei (ein Blatt). Verwende nur die Geltungsbereiche, die separate Anleitungen benötigen; erlaube Ein-Datei-Projekte, mehrere Hubs und ausgelassene leere Abschnitte. Behalte eine kanonische Erklärung und erlaube eine kurze, bereichsbezogene Erinnerung mit einem Link, wenn dies die Auffindbarkeit verbessert. Bewahre anwendbare Versionen, Prüfungsdaten, Plattformen und Messbedingungen. Entferne veraltete Fortschrittserzählungen, erfundene Begründungen, unnötige Duplikate und Anweisungen, die bei einer Änderung nicht mehr helfen. Beurteile die Spezifität anhand nützlicher Entscheidungen, nicht anhand der Häufigkeit von Textänderungen.
Bericht
Gib an, ob die geprüften Anweisungen korrekt sind, und schränke diese Schlussfolgerung auf die untersuchten Behauptungen ein. Erfasse die Revision, den „dirty“ oder ignorierten Inhalt, das Anweisungsinventar, die verifizierten oder stichprobenartig geprüften Behauptungen, die Historiegrenze, Befehlsergebnisse, relevante Umgebung und Versionen sowie ungelöste Prüfungen. Halte den Bericht aus dem Repository selbst interpretierbar, indem Du repository-relativer Pfade und Git-Revisionen als Beweise verwendest.
Überprüfe jeden offenen Befund aus der Basislinie erneut und platziere ihn unter Übertragene Befunde oder Geschlossene Befunde, bevor der Bericht finalisiert wird.
Unterteile die Befunde in diese Abschnitte; schreibe Keine, wenn einer leer ist:
- Erfasse neue Befunde mit frischen stabilen IDs, betroffenen Anweisungen, Beweisen, Konsequenzen und erforderlichen Korrekturen.
- Führe jeden ungelösten Befund aus der Basislinie fort, einschließlich derer, die sie als neu aufgeführt hat, mit seiner ID, seinem Quell-Checkpoint (dem Checkpoint, der ihn zuerst aufgezeichnet hat) und einer vollständigen Darstellung seiner Beweise, Konsequenz und erforderlichen Korrektur. Halte einen Befund offen, wenn seine Auflösung nicht verifiziert werden kann, und lege Beweise offen, die nicht validiert werden können.
- Schließe Befunde mit der verifizierten Auflösung oder Ablösung und unterstützenden Beweisen. Erfasse jede Schließung einmal und lasse sie dann aus späteren Berichten aus. Bewahre ihre Historie im früheren Checkpoint, anstatt ein Archiv in jedem Bericht aufzubauen.
Weise IDs zu, ohne ausgemusterte wiederzuverwenden; verwende zum Beispiel einen auditspezifischen UTC-Zeitstempel plus einen Zähler und behalte diese ID danach bei. Gib im Bericht an, ob das Audit abgeschlossen wurde; ein unterbrochenes oder unvollständiges Audit endet mit dem Bericht. Beanspruche ein sauberes Ergebnis nur innerhalb der Prüfungen, die es nachweisen.
Checkpoint-Nachricht
Bereite die folgende Nachricht als Teil des Ergebnisses einer abgeschlossenen Prüfung vor. Füge den Prüfungsbericht selbst ein, nicht Verweise auf einen externen Issue-Tracker, einen lokalen Bericht oder eine andere externe Quelle. Verwende den kopflosen Betreff und die Trailer genau wie gezeigt, mit ##-Überschriften und Leerzeilen für die Berichtsabschnitte. Erfasse vollständige Objekt-IDs und eine identifizierbare Fertigkeitsrevision oder einen Hash, anstatt sich auf einen installierten Pfad zu verlassen.
chore: Protokoll der Prüfung der Agentendokumentation
## Abdeckung
Untersucht <repository-relative Anweisungsdateien oder Verzeichnisse>.
Verifiziert <Behauptungen und Prüfungen, einschließlich etwaiger Stichproben>.
Historie von <Historiegrenze> bis zur geprüften Revision inspiziert.
Verwendet <relevante Umgebung und Tool-Versionen, und wo Prüfungen ausgeführt wurden>.
## Nicht verifizierte Prüfungen
<Nicht abgeschlossene Prüfungen und ihre Gründe, oder Keine.>
## Neue Befunde
<Stabile ID, betroffene Anweisung und Abschnitt, Befund, Beweis, Konsequenz und erforderliche Korrektur für jeden neuen Befund; oder Keine.>
## Übertragene Befunde
<Stabile ID, Quell-Checkpoint und eine eigenständige Darstellung jedes ungelösten Befunds, einschließlich Beweis, Konsequenz und erforderlicher Korrektur; oder Keine.>
## Geschlossene Befunde
<Stabile ID, Auflösung oder Ablösung und unterstützende Beweise für jeden Befund, den dieses Audit schließt; oder Keine.>
Agents-Audit-Version: 1
Agents-Audit-Commit: <vollständiger SHA des geprüften Eltern-Commits>
Agents-Audit-Tree: <SHA des geprüften Baums>
Agents-Audit-Skill-Revision: <Fertigkeitsrevision oder Inhalts-Hash>
Agents-Audit-Previous: <SHA des Basislinien-Checkpoints oder none>
Checkpoint-Erstellung
Erstelle einen Checkpoint nur für eine abgeschlossene Prüfung und nur mit Autorisierung für diesen Schreibvorgang. Verlange, dass die geprüfte Revision immer noch HEAD ist und die geprüften Anweisungen und der Code in ihrem Baum repräsentiert sind. Committe autorisierte Korrekturen zuerst und verifiziere den resultierenden Snapshot, bevor Du dessen Checkpoint aufzeichnest. Aktualisiere den Bericht und die Trailer, um diesen verifizierten Snapshot zu beschreiben, falls Korrekturen die geprüfte Revision geändert haben. Schließe nicht-committierte oder ignorierte Inhalte aus Behauptungen über den committed Snapshot aus und erfasse die resultierende Abdeckungsgrenze. Weigere dich, einen Checkpoint für einen beobachteten „dirty“ Zustand aufzuzeichnen, als ob …