hellices/flow-atlas

Was macht flow-atlas?

Das eigene AGENTS.md des Repositorys, die Entwurfsdokumente und die Governance-Tests haben Vorrang vor dieser Fähigkeit.

Drei Teile

atlas generiert, was der Code festlegt. Sie schreiben, was Absicht erfordert, und atlas überprüft es. Dazwischen interpretieren Sie, welche Arbeit zu welcher Komponente gehört, mit den Kriterien in references/boundaries.md. Alles, was Sie entscheiden, wird in eine Datei geschrieben, die atlas liest (Flow-Dateien, die Ausnahmedatei, die Konfiguration, Feedback), damit der nächste Durchlauf und der nächste Agent es sehen.

atlas generiert: Schreiben Sie diese niemals von Hand

Fakt	Befehl
Oberflächen, Aufrufe, Kanten, operationIds, Registrys, Vertragsversionen	scan
Oberflächen und Aufrufe nach Pfad, Methode oder Komponente	query
Die Aufrufer einer Oberfläche stromaufwärts und die Dienste, die sie stromabwärts erreicht	trace
Ein Flow-Entwurf: Name, Schritte entlang des Codepfads, Einstieg, wenn eine Komponente ihn aufruft, Kandidaten, wo er verzweigt	draft flow
Ob ein Flow im Code Bestand hat und ob seine Autorenfelder geschrieben sind	flows (Bedingungen)
Ergebnisse mit Orten und nahegelegenen Pfaden	check, explain
Was sich zwischen Revisionen geändert hat	diff
Konfigurationskandidaten und wie gut die Konfiguration abdeckt	inventory, scan
Die OpenAPI-Beschreibungen jeder Komponente, wie weit die festgelegten mit dem Code übereinstimmen und welche die Komponente ist, wenn der Code sie bestimmt	scan, inventory

Versuchen Sie nicht, graph.json zu durchsuchen, Aufrufer durch Textsuche zu erraten oder Oberflächen-IDs aus dem Gedächtnis einzugeben: Kopieren Sie sie aus der atlas-Ausgabe.

Sie schreiben: atlas überprüft es

Was	Überprüft durch
Den title eines Flows und die role jedes Schritts	Documented
owner, labels, sources, lifecycle (planned, wenn ein Schritt nicht gebaut ist)	Schema; Resolved zählt geplante Schritte separat
generated: { by: <tool>/<model>, at }, sobald Sie die Absicht eines Flows geschrieben haben; stale_after, wenn es überprüft werden sollte (OKF)	Schema; Fresh
Die Einstiegskomponente, wenn mehrere den ersten Schritt aufrufen; den nächsten Schritt, wo der Handler verzweigt	EntryCalled, Connected
produces	ProducesListed
Ausnahmen: Grund, decidedBy, reviewBy	Ablauf bringt den Befund zurück
Falschpositive mit Begründung	stats
Die Konfiguration	scan-Abdeckung
Das OpenAPI-Dokument, das das Framework generiert, für eine Komponente, die atlas nicht parsen kann (routes[].openapi, references/openapi.md)	scan-Abdeckung und limit:-Zeilen
origins: Die Basis-URL, unter der jede Komponente in einer Umgebung läuft, aus den Bereitstellungsdateien	export arazzo notiert eine fehlende
openapi.<component>, wenn atlas seine Beschreibung als ambiguous meldet	export arazzo verweigert, bis es gesetzt ist

Übergeben Sie Ihren Teil nicht an das Tool: Keine publicSurfaces, Ausnahme oder Basislinienaktualisierung ohne einen Grund, den eine Person akzeptieren würde. Schreiben Sie niemals einen verified-Eintrag mit einem human:-Akteur: Das zeichnet eine Überprüfung durch eine Person auf, und die Vertrauensstufe des Flows (unverified, machine-confirmed, human-reviewed) hängt davon ab.

Sie interpretieren: Grenzen

Ob ein Sprung zu der Komponente gehört, in der er sich befindet, ob eine ähnliche Oberfläche die Arbeit bereits erledigt, ob eine Lücke ein Fehler, ein Plan oder ein falsch Positives ist, wie weit man einer Kante vertrauen kann und wo ein Flow beginnt und endet. Folgen Sie references/boundaries.md; es ordnet die Quellen (Repository-Regeln, dann Flow-Rollen, dann Code) und gibt die Kriterien an.

Einrichtung

• Führen Sie atlas --help aus. Wenn atlas nicht installiert ist, führen Sie es über npx aus (npx github:hellices/flow-atlas --help) oder bitten Sie den Benutzer, es zu installieren; implementieren Sie seine Messwerte nicht von Hand neu.
• Die Konfiguration ist <root>/atlas.config.yaml, <out>/atlas.config.yaml oder --config <datei>. Wenn es keine gibt, folgen Sie dem Abschnitt "Einrichten" unten.
• Wenn das Repository nicht beschrieben werden darf, übergeben Sie --out <verzeichnis außerhalb>. Jeder Schreibvorgang erfolgt dorthin.

Entwerfen einer Änderung

1. atlas query --path <pfad oder fragment> und atlas query --component <name>, um zu sehen, was bereits existiert.
2. atlas trace <nächste oberfläche>, um die Kette zu sehen: Client-Aufruf, BFF-Route, die Port-Methoden, die sein Handler erreicht, die Dienst-Route, die jede davon abgleicht.
3. Entscheiden: Wiederverwenden, erweitern oder hinzufügen. Notieren Sie die Oberflächenschlüssel, die Sie hinzufügen oder ändern werden, und welche Komponente jeden Sprung besitzt. Wenn zwei Komponenten am Ende denselben Schritt ausführen würden, klären Sie das, bevor Sie Code schreiben.
4. Wenn das Repository Flows führt (flows/*.flow.yaml), aktualisieren Sie den Flow oder beginnen Sie einen neuen mit atlas draft flow <oberfläche> (siehe "Schreiben eines Flows"). Markieren Sie Schritte, die noch nicht existieren, mit lifecycle: planned.

Während der Implementierung

Fügen Sie nach dem Hinzufügen einer Route oder eines Client-Aufrufs atlas trace <oberfläche> aus. Stromaufwärts sollte der von Ihnen beabsichtigte Aufrufer und stromabwärts die von Ihnen beabsichtigten Aufrufe angezeigt werden. Eine leere Seite bedeutet entweder noch nicht verdrahtet oder auf eine Weise verdrahtet, die das Tool nicht lesen kann (ein Pfad, der weit vom Aufruf entfernt aufgebaut ist, ein Handler in einer anderen Sprache); öffnen Sie den Code und geben Sie an, was.

Wenn Sie eine Route einer Komponente hinzufügen, entfernen oder ändern, deren Routen aus einem generierten OpenAPI-Dokument stammen, generieren Sie das Dokument in derselben Änderung neu. Ein Client-Aufruf allein ändert es nicht.

Schreiben eines Flows

1. atlas draft flow <erste oberfläche> gibt einen Flow mit allem aus, was der Code festlegt; fügen Sie --to <oberfläche> hinzu, um dem Code zu einem bestimmten Ende zu folgen. Speichern Sie ihn unter flows/<name>.flow.yaml (oder <out>/flows/ für ein Repository, das Sie nicht ändern dürfen).
2. Füllen Sie jeden agent:-Kommentar aus: title, die role jedes Schritts (was die Komponente tut und anderen überlässt), owner, lifecycle, produces; wählen Sie den Einstieg und die nächsten Schritte, wo der Entwurf Kandidaten auflistet. Lassen Sie die Werte ohne Markierung; sie stammen aus dem Code.
3. atlas flows, bis der Flow Ready=True ist. Ein False Resolved, Connected oder EntryCalled bedeutet, dass der Code oder der Flow falsch ist: Entscheiden Sie mit references/boundaries.md, was. Ein False Documented bedeutet, dass ein Autorenfeld leer ist.

Eine Datei kann mehrere Flows enthalten, getrennt durch ---. Oberflächen-IDs schreiben Pfadparameter als OpenAPI-Vorlagen ({id}). Kopieren Sie keine Orte, Kanten oder Bedingungen in die Datei; atlas berechnet sie bei jedem Durchlauf. Das Format ist schema/flow.schema.json im flow-atlas-Paket, dessen docs/schema.md und docs/responsibilities.md es erklären.

Vor dem Abschluss

1. atlas check --since <revision von der sie gestartet sind>. Nur Befunde, die Ihre Änderung eingeführt hat, werden angezeigt.
2. Für jeden: atlas explain <schlüssel> zeigt die Orte und ähnliche Pfade. Beheben Sie ihn dann oder zeichnen Sie eine Ausnahme oder ein falsch Positives auf. Siehe "Behandlung eines Befundes".
3. Fügen Sie atlas diff <basis>..WORKTREE --format markdown (oder <basis>..HEAD) und den trace jeder neuen Oberfläche in die PR-Beschreibung oder den Übergabevermerk ein.

Wenn die Konfiguration hinterherhinkt

Anzeichen: limit:-Zeilen auf stderr (konfigurierte Dateien stimmen mit nichts überein, eine Quelle liefert weniger als die Hälfte ihrer Basislinie) oder FA001 für Routen, von denen Sie wissen, dass sie aufgerufen werden. Führen Sie atlas inventory aus, vergleichen Sie mit der Konfiguration, korrigieren Sie sie (references/config.md) und überprüfen Sie die atlas scan-Abdeckung erneut. Fragen Sie eine Person, bevor Sie atlas baseline update ausführen.

Einrichten

atlas inventory listet Kandidaten auf, ohne etwas zu entscheiden. Schreiben Sie die Konfiguration daraus (references/config.md); generieren Sie für ein Server-Framework, das atlas nicht parst (Spring, Django, Flask und andere), dessen OpenAPI-Dokument und verweisen Sie die Routen darauf (references/openapi.md), führen Sie atlas scan aus, bis jede Quelle das liefert, was Sie erwarten, führen Sie atlas check aus und gehen Sie eine Stichprobe von Befunden mit einer Person durch. Erst dann zeichnen Sie die Basislinie auf.

Behandlung eines Befundes

Entscheiden Sie zuerst, ob es sich um einen Fehler, einen Plan oder ein falsch Positives handelt (references/boundaries.md), dann:

• Beheben Sie ihn, wenn der Befund der Fehler ist: Verdrahten Sie den fehlenden Aufrufer, entfernen Sie die tote Route, fügen Sie den Produzenten hinzu, verweisen Sie den Aufruf auf den bedienten Pfad. references/rules.md listet die üblichen Ursachen pro Regel auf.

• Wenn der Code absichtlich richtig ist, fügen Sie eine Ausnahme hinzu, die die Entscheidung benennt:

  # flows/atlas-exceptions.yaml (oder <out>/exceptions.yaml)
  - rule: FA001
    key: FA001|orders|GET /orders/{id}/history
    reason: Der Dienst wird zuerst ausgeliefert; der App-Bildschirm folgt im nächsten Release.
    decidedBy: docs/orders.md#history
    reviewBy: 2026-12-31
  

  Oberflächen, die an Clients außerhalb des Repositorys bedient werden, kommen in publicSurfaces in der Konfiguration.

• Wenn der Befund falsch ist: atlas feedback <schlüssel> false-positive --note "<warum>". Wenn der Extraktor eine Datei falsch gelesen hat, geben Sie an, welche Datei und wie.

Führen Sie niemals atlas baseline update aus, es sei denn, eine Person fordert es an. Bearbeiten Sie niemals generierten Code, um einen Befund zu befriedigen.

Maschinenlesbare Ausgabe

--format json oder --format yaml gibt Dokumente aus, die dem schema/*.schema.json des flow-atlas-Pakets folgen, jedes mit apiVersion, kind und provenance (Commit und gelesene Dateien mit Digests). Lesen Sie diese anstelle des Textausgabe-Parsings; verzweigen Sie auf den reason einer Bedingung, nicht auf ihre message. atlas check --format sarif gibt die Befunde als SARIF 2.1.0 für Code-Scanning und IDE-Viewer aus; atlas export arazzo gibt die Flows als Arazzo 1.0 für API-Workflow und E2E-Tools aus, die noch Parameter, Anforderungskörper und Erfolgskriterien ausgefüllt benötigen.

Lesen der Ausgabe

• Befundstatus: new ist Ihrer; baseline ist akzeptierte Schuld; excepted ist abgedeckt; expired-exception benötigt eine Person.
• In einem Trace verbindet = einen Aufruf mit einer Oberfläche nach Methode und Pfad; ~ verbindet eine Route mit einem ausgehenden Aufruf, den ihr Handler ausführt: geschrieben im eigenen Code des Handlers oder den Funktionen, die er aufruft (Nachweis static), oder gehalten in einer Methode eines Namens, den der Handler aufruft (Nachweis name), oder, für eine Spring-Seite, erstellt durch die Vorlage, die sein Ansichtsname rendert (via view <name>). Ein ~ nach Namen durch einen generischen Namen (get, send) erfordert einen Blick in den Code.
• Der in <name> eines Aufrufs ist die Funktion, die den String enthält. Ein String in einem Fehlerlabel oder einer Logmeldung ist keine Anfrage, selbst wenn er wie ein Pfad aussieht; der Gültigkeitsbereich zeigt das normalerweise.
• Es werden nur konfigurierte Dateien gelesen, und darin nur das, was mit Sicherheit geschrieben ist: literale Pfade, mit der Bedeutung, die ein Standard oder das Framework ihnen gibt. Eine URL aus einer Variable, einer anderen Template-Engine oder htmx- und Vue-Attributen wird nicht gelesen und nicht geraten. Daher bedeutet "kein Aufrufer", dass atlas keinen lesen kann; überprüfen Sie den Code, bevor Sie etwas entfernen, und deklarieren Sie Oberflächen, die außerhalb des Repositorys bedient werden, in publicSurfaces. Kein Befund beweist nicht, dass ein Flow vollständig ist.

Referenzen

• Interpretation von Grenzen, Entscheidung über Fehler, Plan oder falsch Positives: references/boundaries.md
• Regeln, Ursachen, Lösungen, wann eine Ausnahme passt: references/rules.md
• Schreiben oder Korrigieren der Konfiguration: references/config.md
• Lesen von Routen aus einem generierten OpenAPI-Dokument eines Frameworks und wie man es generiert: references/openapi.md