Diese Seite ist eine Übersetzung der englischen Dokumentation. Befehle, Bezeichner und Beispiele bleiben unverändert. Runtime 7.24.4 · SDK 2.6.7. Englische Fassung

Zusicherung von Zielen

Status: Aktuell Geltungsbereich: Prüfungen der Zielannahme und Aktualität der Quelle Zuletzt geprüft: 2026-09-14 Verantwortlich: Betreuende der Laufzeit von AX Code

Pläne für Codeänderungen, die der Zielplaner erzeugt, erklären ausführbare Annahmekontrollen. Jede Prüfung nennt das Ergebnis, das sie abdeckt, ihren genauen Befehl, ihren Zweck und die vorgesehene Umgebung. AX Code zeichnet Ausführungsnachweise auf, wenn der Agent verify_project mit der Kennung goalCheck der Prüfung ausführt.

{ "goalCheck": "invoice-parity" }

Der Befehl kommt aus dem eingefrorenen Zielplan. Der Agent kann ihn über diesen Aufruf nicht durch einen anderen Befehl ersetzen. Bestehende Bash-Berechtigungen gelten weiterhin. Das Ziel abzuschließen verlangt, dass der jüngste Versuch jeder erklärten Prüfung besteht, mit passendem Ziel, passender Sitzung, passendem Arbeitsbereich, passendem Vertrag und passendem Quellinhalt. Prosa zur Annahme erklärt das Ergebnis; sie ersetzt ausgeführte Prüfungen nicht. Gewöhnliche Shell-Läufe und Prüfungen, die vollständig übersprungen wurden, können diesen Nachweis nicht liefern.

Alte Zielpläne ohne Zusicherung behalten ihre früheren Abschlussregeln. Löschen Sie ein altes Ziel und legen Sie es neu an, wenn Sie den neuen Vertrag brauchen; die eingefrorenen Anforderungen an Ort und Stelle zu bearbeiten verursacht eine Vertragsabweichung. Ein Fork bewahrt den Vertrag, verlangt aber neue Prüfläufe in der neuen Sitzung.

Ein Migrationsprojekt vorbereiten

Stellen Sie maßgebliche Altquellen oder Exporte mit Revisionskennungen bereit, ein begrenztes Abdeckungsinventar und Prüfskripte, die fehlschlagen, wenn Zusicherungen nicht geprüft werden können. Behandeln Sie Kommentare und frühere Migrationsumsetzungen als Spuren, die untersucht werden müssen. Zeichnen Sie genehmigte Verhaltensänderungen getrennt von Anforderungen an die Gleichwertigkeit mit dem Altsystem auf.

Wählen Sie Prüfungen für die Schichten, die die angeforderte Änderung tatsächlich betrifft:

Skripte müssen die Zielidentität zusichern, bevor sie ihre Prüfungen ausführen. Bewahren Sie Zugangsdaten im bestehenden Mechanismus des Projekts auf, niemals im Plantext, in Befehlen oder in Zielbeschreibungen. Eine Prüfung sollte bei einer fehlgeschlagenen Zusicherung, einer fehlenden Umgebung oder einer übersprungenen erforderlichen Zusicherung einen Exit-Code ungleich null liefern. Vermeiden Sie Hüllen, die Fehlschläge verdecken. AX Code kann aus einem erfolgreichen Prozessende keine Zusicherungen ableiten.

Organisieren Sie große Migrationen in begrenzte Chargen nach Geschäftsablauf und pflegen Sie ein Inventar, das Formulare, Abhängigkeiten, Altverweise und Annahmeprüfungen verknüpft. Berichten Sie sowohl die angenommene Charge als auch die verbleibende Abdeckung. Eine bestandene Charge schließt die gesamte Migration nicht ab.

Was ein Plan aufzeichnet

Der Planer liefert ein Objekt assurance. Dieses erläuternde Fragment setzt voraus, dass das Projekt den genannten Quellenexport und das Prüfskript hat:

{
  "version": 1,
  "sourcePaths": ["src", "checks", "package.json"],
  "sources": [
    { "role": "legacy", "reference": "legacy/invoice-schema.sql at export-v1" },
    { "role": "requirement", "reference": "Invoice acceptance criteria supplied by the user" }
  ],
  "checks": [
    {
      "id": "invoice-parity",
      "acceptanceIds": ["AC1"],
      "command": "node checks/invoice-parity.cjs",
      "purpose": "Assert invoice behavior, database mappings and target identity",
      "environment": "Staging migration target, schema ERP"
    }
  ]
}

Alle Annahmekennungen müssen abgedeckt sein. Befehle werden vom Stamm des Arbeitsbereichs ausgeführt. Das Zusicherungsobjekt wird mit dem Annahmevertrag eingefroren. Der Agent erhält geprüften Umfang, Quellverweise, Prüfkennungen und erklärte Ziele in seinem fortlaufenden Zielkontext. Fehlende oder veränderte Verträge erzeugen einen Hinweis zur Wiederherstellung. Erzeugte Gesprächszusammenfassungen bleiben fehlbar; erklärte Verweise und Zielbeschriftungen sind Anforderungen, keine unabhängig beobachteten Tatsachen.

Git-Bereiche, die messen, was dieses Ziel geändert hat, müssen {BASELINE} als Zustand davor verwenden. Der Planer schreibt diesen Platzhalter in den HEAD-SHA um, der erfasst wird, wenn der Plan eingereicht wird, damit bereits vorhandene Commits vor origin/main oder ein unsauberer Arbeitsbaum das Ziel nicht unabschließbar machen. Verweise auf entfernte Nachverfolgung (origin/main, @{u}, refs/remotes/…) werden als dieser Zustand davor abgelehnt, sofern das Ziel die Gegenstelle nicht nennt. Zeichnen Sie bereits auseinandergelaufene oder unsaubere Pfade unter Risiken auf; frieren Sie keine sperrende Prüfung ein, die bereits fehlschlägt, sofern das Ziel nicht darin besteht, genau diesen Fehlschlag zu beheben.

Aktualität und Grenzen

Fingerabdrücke von Git-Quellen umfassen die tatsächlichen Bytes verfolgter und nicht ignorierter, nicht verfolgter Dateien innerhalb der erklärten sourcePaths. Ausdrückliche Dateipfade schließen auch ignorierte Konfigurationsdateien ein; Verzeichnispfade behalten die Ignorierregeln von Git. Veränderliche Checklisten des Zielplans sind ausgeschlossen; ihre eingefrorenen Anforderungen werden über den Vertragsdigest geprüft. Projekte ohne Git bilden rekursiv Fingerabdrücke der erklärten sourcePaths, einschließlich fehlender Pfade. Nehmen Sie jede relevante Quelle, jede Konfigurationsdatei und jedes Prüfskript in diesen Umfang auf.

Die Fingerabdrücke sind auf 20,000 Einträge und 128 MiB Dateiinhalt begrenzt. Verknüpfte Quellen, verschachtelte Git-Repositorys, besondere Dateien, ausbrechende Pfade, sich ändernde Dateien und nicht verfügbare Lesevorgänge können keine frischen Nachweise erzeugen. Solche Fehlschläge blockieren einen zugesicherten Abschluss. Artefakte der Prüfausgabe sollten an einen ignorierten Ort gehen, damit ein Bericht die geprüfte Quelle nicht verändert.

Ignorierte Dateien, die nicht ausdrücklich genannt sind, Abhängigkeiten außerhalb des Quellumfangs, Datenbanken und Bereitstellungen brauchen Zusicherungen im Projektbefehl. Ein Beleg zeichnet eine Beobachtung zu ihrem Ausführungszeitpunkt auf; er beweist nicht, dass ein externer Zustand unverändert geblieben ist. Führen Sie betroffene Prüfungen erneut aus, nachdem Sie Konfiguration, Datenbanken oder Bereitstellungen geändert haben. AX Code entdeckt nicht automatisch alles Altverhalten und bescheinigt keine Gleichwertigkeit der Migration.

Wann die Planung läuft

Die Planung ist auf beiden Oberflächen optional. /goal <objective> und create_goal ohne assure starten das Ziel sofort: Es trägt keine eingefrorenen Annahmekriterien, und der Abschluss wird nach dem Arbeitsplan (ausstehende Todos) plus einer bestehenden Prüfung nach der letzten Änderung beurteilt. /goal --assure <objective> und create_goal mit assure: true führen zuerst den Planschreiber aus. Das macht die unten genannten Belege ausgeführter Prüfungen zu einer Abschlussanforderung.

Ein Ziel ohne Vertrag sagt das überall, wo es gezeigt wird (/goal view, der Zieldialog, die Steuerungsmeldungen), sodass Sie seine Abschlussschranke nie erschließen müssen. /goal replace behält die Zusicherung, wenn das ersetzte Ziel einen gültigen Vertrag hat.

Planungskontext und Modellauswahl

Die Zielplanung erbt das gewählte Sitzungsmodell sowohl über /goal als auch über das Werkzeug create_goal. Verträgliche Varianten des Aufrufers bleiben erhalten. Der nur lesende Schreiber erhält jüngere ursprüngliche Benutzeranforderungen und Verweise auf Anhänge, mit einem Budget von 16 KiB je Aufzeichnung. Eine zu große Aufzeichnung stoppt die Aufnahme älterer Aufzeichnungen, mit einem Hinweis, damit ältere Anforderungen eine ausgelassene Korrektur nicht still ersetzen; eingebettete Medieninhalte gelten nicht als geprüfte Nachweise. Stellen Sie einsehbare Quelldateien für Anforderungen bereit, die nur in Medien vorliegen.

Fortschritt und Blocker

get_goal enthält den aktuellen Prüfstatus (bestanden, fehlgeschlagen, veraltet, laufend oder fehlend) und jüngere Kennungen von Werkzeugnachweisen. Die Abschlussschranke verlangt weiterhin aktuelle erfolgreiche Belege. Eine blockierte Aktualisierung verlangt eine Art des Blockers, einen Grund, die erforderliche externe Änderung, ursprüngliche Nachweis-Kennungen und die Bestätigung, dass keine unabhängige Arbeit bleibt. Gründe für Blocker sind Erklärungen des Modells, gestützt auf einsehbare Aufzeichnungen, keine Bescheinigung, dass ein externer Dienst unerreichbar bleibt.

Abgeschlossene Züge, die wiederholt keine neuen erfolgreichen Werkzeugnachweise erzeugen, erhalten eine Anleitung zur Wiederherstellung und pausieren dann das Ziel, wobei unfertige Arbeit offengelegt wird. Neue Forschungsergebnisse können zählen, ohne Quellbearbeitungen; Umschreiben von Todos und wiederholte identische Ergebnisse zählen nicht. Das ist eine begrenzte Heuristik, kein Beweis semantischen Fortschritts. /goal resume startet einen weiteren Versuch. Werkzeugaufrufe, die für ein früheres Ziel erzeugt wurden, können dessen Ersatz nicht beenden. Ein vom Werkzeug erzeugtes Ziel steht Statusaktualisierungen zur Verfügung, nachdem das Modell das Ergebnis der Erzeugung im nächsten Schritt erhalten hat.

Einen bestehenden Plan überarbeiten

Verwenden Sie /goal revise <correction>, um ein aktives, pausiertes oder blockiertes eingefrorenes Ziel ausdrücklich zu überarbeiten. Abgeschlossene Arbeit und ausgeschöpfte Budgets verlangen ein neues Ziel. Der vorherige Plan und der Digest bleiben unversehrt. Der überarbeitete Plan erhält eine neue Identität und eine lokale vorbereitete Revisionsaufzeichnung, die beide Digests und die Korrektur verknüpft. Die aktuelle Zielidentität bestimmt, welcher Kandidat tatsächlich installiert wurde; fehlgeschlagene gleichzeitige Kandidaten können zur Prüfung auf dem Datenträger bleiben. Alte Belege bleiben in der Historie und können die neue Revision nicht erfüllen. Token-Budget und aufgelaufene Nutzung werden übernommen; die Überarbeitung gewährt kein frisches Ausgabebudget.

Die Überarbeitung bricht den aktuellen Lauf ab und pausiert das Ziel, während der neue Plan vorbereitet wird. Scheitert die Planung, bleibt der vorherige Vertrag fortsetzbar; ein zuvor blockiertes Ziel behält diesen Status. Eine Pause oder ein Abbruch durch den Benutzer während der Planung verhindert die Aktivierung. Ein gleichzeitiger Ersatz verhindert, dass der Kandidat übernimmt. Modellwerkzeuge können eingefrorene Anforderungen nicht still überarbeiten. Prüfen Sie den entstandenen Plan und seine Annahmekriterien; ein ausführbarer Befehl allein belegt nicht, dass seine Zusicherungen die korrigierte Anfrage abdecken.

Prüfungsergebnisse und spätere Quelländerungen

Ein nicht leeres Prüfungsprotokoll belegt keine erfolgreiche Prüfung. Verwenden Sie für erforderliche externe Prüfende eine projekteigene Prüfung, die den tatsächlichen Exit-Code, den Abschluss im Terminal, die Identität von Quelle oder Diff und die endgültigen Befunde oder ein ausdrückliches Urteil ohne Befunde validiert. Protokolle nur mit Warnungen, teilweises Reasoning und Zeitüberschreitungen müssen fehlschlagen. Halten Sie fehlgeschlagene Versuche für die Diagnose getrennt fest.

Neue Einreichungen von Codeänderungen lehnen erkannte einfache Prüfungen auf Dateivorhandensein und Inspektion ab. Das ist eine enge Zulassungsschranke, kein semantischer Beweis beliebiger Shell- Befehle. Bestehende eingefrorene Verträge behalten ihr Schema und ihren Digest; Prüfpunkte warnen, wenn eine ältere Prüfung diese Schwäche hat.

Die Aktualität der Zielprüfung bildet außerdem Fingerabdrücke aufgelöster Dateipfade, die erfolgreiche dateibearbeitende Werkzeuge während des aktuellen Ziels melden, einschließlich jedes Ergebnisses multiedit und von Pfaden, die in der ursprünglichen Quellenliste fehlen. Spätere Bearbeitungen dieser Dateien machen frühere Belege ungültig. Vertrag und Digest bleiben unverändert eingefroren. Diese Verfolgung nutzt Metadaten der Dateiwerkzeug-Ergebnisse; sie leitet keine beliebigen Nebenwirkungen der Shell und keine Testabdeckung ab. Bestehende Grenzen für die Eingrenzung des Dateisystems, für Verknüpfungen, Größe und Dateizahl gelten weiterhin.

Ausgabe der Prüfung und Ziel-Prüfpunkte legen zusätzliche Pfade offen. Wenn ein eingefrorener Testbefehl nötige Regressionen auslässt, fordern Sie /goal revise <correction> an und führen die überarbeiteten Prüfungen aus. Eine Datei in einem Fingerabdruck zu haben beweist Aktualität, nicht dass ein Test diese Datei ausgeübt hat. Bevorzugen Sie begrenzte Quellverzeichnisse und Testbefehle, die neue Regressionen einschließen, wenn Sie eine offene Fehlersuche planen.

Aliase des Arbeitsbereichs werden für beobachtete Dateipfade normalisiert. Externe Entwurfsdateien werden keine Quelleneingaben des Arbeitsbereichs; Prüfpunkte legen offen, dass externer Inhalt keinen Fingerabdruck erhält. Erforderlicher externer Zustand braucht weiterhin eine projekteigene Prüfung.

Nachweise zum Commit-Umfang

Ein nicht leeres git log <baseline>..HEAD -- <paths> beweist nur, dass ein Commit zum Filter passt. Es schließt weder unabhängige Dateien in diesem Commit noch andere Commits aus. Neue Pläne für Codeänderungen lehnen erkannte eigenständige, nicht leere und nach Pfad gefilterte Git-Log-Zusicherungen ab; ältere eingefrorene Prüfungen erhalten eine Anleitung zur Überarbeitung, ohne dass sich ihr Digest oder die Prüfung beim Lesen ändert.

Verwenden Sie einen projekteigenen Prüfer, der die Abstammung von der Basis prüft, einen nicht leeren Bereich verlangt und jeden geänderten Pfad in jedem Commit ohne Pfadfilter untersucht. Schließen Sie gelöschte Dateien und beide Seiten von Umbenennungen ein, behandeln Sie Merge-Commits ausdrücklich und prüfen Sie erforderliche Eigenschaften von Branch oder Nachricht getrennt. Verwenden Sie /goal revise, um einen bestehenden Vertrag zu verstärken; bearbeiten Sie eingefrorene Anforderungen nicht.

Plangröße und vollständiges erneutes Einreichen

Der dargestellte Plan, einschließlich Markdown und JSON der Zusicherung, muss in 8,192 UTF-8-Byte passen. Zielen Sie auf unter 7,168 Byte. Überschreitet die Einreichung die Obergrenze, kürzen Sie wiederholte Prosa und reichen Sie das vollständige Objekt erneut ein, einschließlich kind und aller erforderlichen Felder. Bewahren Sie Annahmekennungen und Prüfungen; die Laufzeit kürzt Anforderungen nicht und hebt die Lesergrenze nicht an, um einen zu großen Plan anzunehmen.

Belege für die Prüfung der lokalen CLI-Animation

Die dem Repository gehörende Prüfung packages/ax-code/script/verify-cli-review-receipts.ts prüft Artefakte round-* unter der Belegwurzel, die mit --root gewählt wird. Jede Runde braucht revision.txt, und jedes von grok, claude und codex braucht exit.txt mit 0 und einem endgültigen Urteil in stdout.jsonl (Textereignisse von Grok) oder stdout.txt (Claude/Codex). Bewahren Sie fehlgeschlagene Versuche außerhalb abgeschlossener Rundenverzeichnisse auf; verwandeln Sie Fehlschläge nicht in Belege mit Exit-Code null.

dispositions.json enthält ein Array findings. Jeder Eintrag nennt round, cli, id, status (fixed oder rejected) und ein nicht leeres evidence. Einträge mit dem Status behoben verlangen zusätzlich ein Objekt regression mit einem wörtlichen Repository- Pfad file unter packages/ax-code/test/cli/tui/ und dem genauen Vitest- fullName. Doppelte Dispositionen oder mehrdeutige mehrere Urteile schlagen fehl.

Der Prüfer führt diese Dateien mit dem installierten Vitest aus, wobei die globale Wiederholung standardmäßig auf null steht (einzelne Testoptionen dürfen diese Voreinstellung überschreiben), und prüft danach, dass jede genannte Zusicherung genau einmal bestanden hat. Fehlende, übersprungene, fehlgeschlagene oder mehrdeutige Zusicherungen lassen die Prüfung scheitern. Das beweist, dass diese genannten Tests bestanden haben, nicht dass ihre Zusicherungen den Befund semantisch abdecken. Abgelehnte Dispositionen bleiben aufgezeichnete Urteile. Eine letzte Runde muss zum aktuellen HEAD passen; als behoben gekennzeichnete Befunde verlangen eine neuere Revision und eine Prüfungsrunde. Nicht committete Quellen, Tests oder Konfigurationsänderungen des Kernpakets verhindern die Prüfung. Halten Sie die unabhängige lokale Konfiguration ax-code.json aus Commits heraus.

Für dieses Repository bewahrt vitest run --dir test/cli/tui die Ausschlüsse der normalen Spur und durchsucht das TUI-Verzeichnis. Gruppenläufer dürfen weiterhin genaue Dateien mit AX_TEST_FILES wählen; die Verzeichniswahl schaltet Ausschlüsse nicht ab.