hellices/flow-atlas

Que fait flow-atlas ?

Le fichier AGENTS.md du dépôt, les documents de conception et les tests de gouvernance prévalent sur cette compétence.

Trois parties

atlas génère ce que le code décide. Vous écrivez ce qui nécessite de l'intention, et atlas le vérifie. Entre les deux, vous interprétez quel travail appartient à quel composant, selon les critères dans references/boundaries.md. Tout ce que vous décidez est placé dans un fichier qu'atlas lit (fichiers de flux, fichier d'exceptions, configuration, retour), afin que la prochaine exécution et le prochain agent le voient.

atlas génère : ne jamais écrire ces éléments à la main

Fait	Commande
surfaces, appels, arêtes, operationIds, registres, versions de contrat	scan
surfaces et appels par chemin, méthode ou composant	query
les appelants en amont d'une surface et les services qu'elle atteint en aval	trace
un brouillon de Flow : nom, étapes le long du chemin du code, entrée quand un composant l'appelle, candidats là où il bifurque	draft flow
si un Flow tient dans le code, et si ses champs d'auteur sont renseignés	flows (conditions)
résultats avec emplacements et chemins proches	check, explain
ce qui a changé entre les révisions	diff
candidats de configuration et à quel point la configuration couvre	inventory, scan
les descriptions OpenAPI de chaque composant, à quel point celles validées concordent avec le code, et laquelle est celle du composant quand le code le décide	scan, inventory

Ne greppez pas graph.json, ne devinez pas les appelants par recherche textuelle, et ne tapez pas d'identifiants de surface de mémoire : copiez-les depuis la sortie d'atlas.

Vous écrivez : atlas le vérifie

Quoi	Vérifié par
le title d'un Flow et le role de chaque étape	Documented
owner, labels, sources, lifecycle (planned quand une étape n'est pas construite)	schéma ; Resolved compte les étapes planifiées à part
generated: { by: <tool>/<model>, at } une fois que vous avez rédigé l'intention d'un flux ; stale_after quand il doit être révisé (OKF)	schéma ; Fresh
le composant d'entrée quand plusieurs appellent la première étape ; l'étape suivante où le gestionnaire bifurque	EntryCalled, Connected
produces	ProducesListed
exceptions : raison, decidedBy, reviewBy	l'expiration ramène le résultat
faux positifs, avec la raison	stats
la configuration	couverture de scan
le document OpenAPI que le framework génère, pour un composant qu'atlas ne peut pas analyser (routes[].openapi, references/openapi.md)	couverture de scan et lignes limit:
origins : l'URL de base à laquelle chaque composant s'exécute dans un environnement, à partir des fichiers de déploiement	export arazzo note une absence
openapi.<component> quand atlas rapporte sa description ambiguous	export arazzo refuse tant qu'il n'est pas défini

Ne confiez pas votre part à l'outil : pas de mise à jour de publicSurfaces, d'exception ou de base de référence sans une raison qu'une personne accepterait. N'écrivez jamais une entrée verified avec un acteur human: : cela enregistre une révision humaine, et le niveau de confiance du flux (unverified, machine-confirmed, human-reviewed) en dépend.

Vous interprétez : les limites

Si un saut appartient au composant dans lequel il se trouve, si une surface similaire fait déjà le travail, si un écart est un défaut, un plan ou un faux positif, à quel point faire confiance à une arête, et où un flux commence et se termine. Suivez references/boundaries.md ; il ordonne les sources (règles du dépôt, puis rôles du flux, puis code) et donne les critères.

Configuration

• Exécutez atlas --help. Si atlas n'est pas installé, exécutez-le via npx (npx github:hellices/flow-atlas --help) ou demandez à l'utilisateur de l'installer ; ne réimplémentez pas ses lectures à la main.
• La configuration est <root>/atlas.config.yaml, <out>/atlas.config.yaml, ou --config <fichier>. S'il n'y en a pas, suivez « Configuration initiale » ci-dessous.
• Si le dépôt ne doit pas être modifié, passez --out <répertoire en dehors>. Toutes les écritures y sont placées.

Conception d'un changement

1. atlas query --path <chemin ou fragment> et atlas query --component <nom> pour voir ce qui existe déjà.
2. atlas trace <surface la plus proche> pour voir la chaîne : appel client, route BFF, les méthodes de port que son gestionnaire atteint, la route de service que chacune correspond.
3. Décidez : réutiliser, étendre ou ajouter. Notez les clés de surface que vous allez ajouter ou modifier et quel composant possède chaque saut. Si deux composants finiraient par faire la même étape, réglez cela avant d'écrire du code.
4. Si le dépôt conserve des flux (flows/*.flow.yaml), mettez à jour le Flow, ou démarrez-en un nouveau avec atlas draft flow <surface> (voir « Écrire un flux »). Marquez les étapes qui n'existent pas encore avec lifecycle: planned.

Pendant l'implémentation

Après avoir ajouté une route ou un appel client, exécutez atlas trace <surface>. L'amont devrait montrer l'appelant que vous avez prévu et l'aval les appels que vous avez prévus. Un côté vide signifie soit pas encore câblé, soit câblé d'une manière que l'outil ne peut pas lire (un chemin construit loin de l'appel, un gestionnaire dans un autre langage) ; ouvrez le code et dites-le.

Lorsque vous ajoutez, supprimez ou modifiez une route d'un composant dont les routes proviennent d'un document OpenAPI généré, régénérez le document dans le même changement. Un appel client seul ne le change pas.

Écrire un flux

1. atlas draft flow <première surface> imprime un Flow avec tout ce que le code décide ; ajoutez --to <surface> pour suivre le code jusqu'à une fin donnée. Sauvegardez-le sous flows/<nom>.flow.yaml (ou <out>/flows/ pour un dépôt que vous ne devez pas modifier).
2. Remplissez chaque commentaire agent: : title, le role de chaque étape (ce que le composant fait et laisse aux autres), owner, lifecycle, produces ; choisissez l'entrée et les prochaines étapes là où le brouillon liste des candidats. Conservez les valeurs sans marqueur ; elles viennent du code.
3. atlas flows jusqu'à ce que le flux soit Ready=True. Un Resolved, Connected ou EntryCalled à False signifie que le code ou le flux est erroné : décidez lequel avec references/boundaries.md. Un Documented à False signifie qu'un champ d'auteur est vide.

Un fichier peut contenir plusieurs flux séparés par ---. Les identifiants de surface écrivent les paramètres de chemin comme des modèles OpenAPI ({id}). Ne copiez pas les emplacements, les arêtes ou les conditions dans le fichier ; atlas les calcule à chaque exécution. Le format est schema/flow.schema.json dans le paquet flow-atlas, dont docs/schema.md et docs/responsibilities.md l'expliquent.

Avant de terminer

1. atlas check --since <révision à partir de laquelle vous avez commencé>. Seuls les résultats introduits par votre changement apparaissent.
2. Pour chacun : atlas explain <clé> montre les emplacements et les chemins similaires. Ensuite, corrigez-le, ou enregistrez une exception, ou enregistrez un faux positif. Voir « Gérer un résultat ».
3. Mettez atlas diff <base>..WORKTREE --format markdown (ou <base>..HEAD) et la trace de chaque nouvelle surface dans la description de la PR ou la note de transfert.

Quand la configuration a pris du retard

Signes : lignes limit: sur stderr (les fichiers configurés ne correspondent à rien, une source donne moins de la moitié de sa base de référence), ou FA001 sur des routes que vous savez être appelées. Exécutez atlas inventory, comparez avec la configuration, corrigez-la (references/config.md), et vérifiez à nouveau la couverture de atlas scan. Demandez à une personne avant atlas baseline update.

Configuration initiale

atlas inventory liste les candidats sans rien décider. Écrivez la configuration à partir de cela (references/config.md) ; pour un framework serveur qu'atlas n'analyse pas (Spring, Django, Flask et autres), générez son document OpenAPI et pointez les routes vers lui (references/openapi.md), exécutez atlas scan jusqu'à ce que chaque source produise ce que vous attendez, exécutez atlas check, et parcourez un échantillon de résultats avec une personne. Ce n'est qu'alors que vous enregistrez la base de référence.

Gérer un résultat

Décidez d'abord s'il s'agit d'un défaut, d'un plan ou d'un faux positif (references/boundaries.md), puis :

• Corrigez-le quand le résultat est le bogue : câblez l'appelant manquant, supprimez la route morte, ajoutez le producteur, pointez l'appel vers le chemin servi. references/rules.md liste les causes habituelles par règle.

• Quand le code est correct à dessein, ajoutez une exception qui nomme la décision :

  # flows/atlas-exceptions.yaml (ou <out>/exceptions.yaml)
  - rule: FA001
    key: FA001|orders|GET /orders/{id}/history
    reason: Le service est livré en premier ; l'écran de l'application suit dans la prochaine version.
    decidedBy: docs/orders.md#history
    reviewBy: 2026-12-31
  

  Les surfaces servies à des clients en dehors du dépôt vont dans publicSurfaces dans la configuration.

• Quand le résultat est erroné : atlas feedback <clé> false-positive --note "<pourquoi>". Si l'extracteur a mal lu un fichier, dites quel fichier et comment.

N'exécutez jamais atlas baseline update sauf si une personne le demande. Ne modifiez jamais le code généré pour satisfaire un résultat.

Sortie lisible par machine

--format json ou --format yaml imprime des documents qui suivent le schéma schema/*.schema.json du paquet flow-atlas, chacun avec apiVersion, kind et provenance (le commit et les fichiers lus, avec des condensés). Lisez-les plutôt que d'analyser la sortie texte ; dérivez sur reason d'une condition, pas sur son message. atlas check --format sarif donne les résultats au format SARIF 2.1.0 pour le scan de code et les visionneuses IDE ; atlas export arazzo donne les flux au format Arazzo 1.0 pour les workflows API et les outils e2e, qui nécessitent encore des paramètres, des corps de requête et des critères de succès à remplir.

Lecture de la sortie

• Statut du résultat : new est le vôtre ; baseline est une dette acceptée ; excepted est couvert ; expired-exception nécessite une personne.
• Dans une trace, = relie un appel à une surface par méthode et chemin ; ~ relie une route à un appel sortant que son gestionnaire exécute : écrit dans le code propre du gestionnaire ou les fonctions qu'il appelle (preuve static), ou conservé dans une méthode d'un nom que le gestionnaire appelle (preuve name), ou, pour une page Spring, réalisé par le modèle que son nom de vue rend (via view <nom>). Un ~ par nom via un nom générique (get, send) nécessite un regard sur le code.
• L'in <nom> d'un appel est la fonction contenant la chaîne. Une chaîne dans une étiquette d'erreur ou un message de log n'est pas une requête même si elle ressemble à un chemin ; le contexte le montre généralement.
• Seuls les fichiers configurés sont lus, et en eux seulement ce qui est écrit pour certain : chemins littéraux, avec le sens que la norme ou le framework leur donne. Une URL provenant d'une variable, d'un autre moteur de template, ou d'attributs htmx et Vue n'est pas lue et n'est pas devinée. Donc « pas d'appelant » signifie aucun qu'atlas peut lire ; vérifiez le code avant de supprimer quoi que ce soit, et déclarez les surfaces servies en dehors du dépôt dans publicSurfaces. Aucun résultat ne prouve qu'un flux est complet.

Références

• Interprétation des limites, décision défaut/plan/faux positif : references/boundaries.md
• Règles, causes, résolutions, quand une exception convient : references/rules.md
• Écrire ou corriger la configuration : references/config.md
• Lire les routes à partir du document OpenAPI généré par un framework, et comment le générer : references/openapi.md