Pourquoi les diagrammes de votre IA vous mentent
Les agents IA mentent souvent lorsqu'ils cartographient votre base de code. Demandez à un agent de codage de créer le diagramme d'un dépôt, et vous pourriez voir apparaître Kafka, Redis ou une passerelle API qui n'existent pas réellement. Ces diagrammes semblent souvent plausibles, mais ils hallucinent des composants, rendant l'ensemble du visuel indigne de confiance et inutile pour le développement réel. Vous ne pouvez pas vous fier à des visuels nés de la fiction.
Archify s'attaque directement à ce problème. Son agent IA ne dessine rien ; au lieu de cela, il décrit le système sous forme de JSON typé structuré. Ce changement fondamental sépare la description précise du système de sa représentation visuelle. Archify valide ensuite rigoureusement ce JSON avant même qu'un diagramme n'apparaisse, garantissant ainsi l'exactitude dès le départ.
Considérez Archify comme un LLVM pour les cartes système. L'agent de codage IA agit comme le frontend, générant la description initiale du système. Cette description devient une représentation intermédiaire (IR) JSON validée, qui doit respecter des schémas stricts. Ce n'est qu'après avoir passé ces vérifications qu'un compilateur local transforme l'IR en HTML final et interactif, garantissant une sortie vérifiable en plusieurs étapes au lieu de simples suppositions.
Du JSON à la confiance : le pipeline de validation
Archify ne se contente pas de laisser une IA « dessiner » un diagramme. Au lieu de cela, il exige que l'agent IA produise une représentation intermédiaire (IR) JSON structurée et typée. Cette IR entre ensuite dans un pipeline de validation rigoureux et déterministe. Archify la vérifie par rapport à des schémas stricts et des portes atomiques pour garantir son intégrité, assurant ainsi la fiabilité de la description du système.
Il est crucial de noter qu'un mauvais JSON ne devient pas par magie un diagramme défectueux. Si le graphe est invalide, Archify interrompt le processus en fournissant des diagnostics clairs et des codes de règle. Cela signifie que vous obtenez des messages d'erreur exploitables, plutôt que de faire confiance à une représentation visuelle silencieusement erronée. Cette approche de « fail closed » établit une fiabilité fondamentale.
Ensuite, Archify ajoute une puissante couche de preuve vérifiable avec sa fonctionnalité Repo Evidence. Les nœuds d'un diagramme peuvent afficher un badge « SRC ». Cliquez dessus, et vous accédez directement au code spécifique, au commit, et même à la plage de lignes exacte au sein de votre dépôt qui prouve l'existence du composant. L'architecture est donc prouvée comme étant réelle, et non simplement plausible.
Considérez des outils comme Mermaid : vous pouvez écrire du code de diagramme syntaxiquement correct, mais il peut tout de même générer un diagramme logiquement défectueux ou incluant des composants absents de votre base de code réelle. La couche de validation complète d'Archify, couplée à ses preuves par lien direct vers le code, ajoute une dimension critique de confiance sémantique qui manque tout simplement aux autres outils.
Plus qu'une image : une carte système interactive
Une fois que le compilateur d'Archify a validé le JSON, il produit un fichier HTML autonome. Ce n'est pas une image statique ; c'est une carte système interactive qui offre une utilité réelle. Vous pouvez rechercher n'importe quel service, révélant instantanément ses dépendances amont et aval. Ensuite, tracez de manière interactive des flux complexes, comme suivre un chemin de « cache miss » à travers tout votre système, étape par étape, au lieu de simplement regarder un diagramme statique.
Pour les pull requests, la fonctionnalité de diff d'architecture offre un avantage crucial. Archify compare deux instantanés validés de votre système, générant une comparaison visuelle « Avant, Delta, Après ». Cela met clairement en évidence chaque changement architectural : quels composants ont été ajoutés, supprimés ou redirigés, rendant les revues de code beaucoup plus robustes et évitant les changements involontaires.
Bien que le fichier HTML interactif soit l'artefact principal et la fonctionnalité la plus puissante d'Archify, il offre également de solides capacités d'exportation. Vous pouvez facilement générer des images statiques dans des formats tels que PNG, JPEG, WebP, SVG et WebM. Il crée également des cartes de partage pratiques de 1200x630 pour une communication rapide. Cependant, gardez à l'esprit que ces exportations sont secondaires ; la véritable valeur réside dans le HTML dynamique et explorable. Pour une plongée plus approfondie dans les capacités d'Archify, visitez son dépôt GitHub : tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained HTML with motion and crisp export. - GitHub.
Cet article vous plaît ? Recevez-en un comme celui-ci chaque matin.
un e-mail par jour · désinscription en deux clics · aucun traqueur tiers
Maîtriser Archify : Prompts, pièges et PRs
Archify excelle lorsque vous lui posez des questions spécifiques et délimitées. Évitez les instructions vagues comme "cartographie ce dépôt" ; cela renvoie généralement une quantité de données inutiles. Posez plutôt une question précise, telle que : "Diagramme le flux d'authentification utilisateur pour un cache miss", en le limitant peut-être à 8-12 nœuds pour plus de clarté et de concentration. Cette approche ciblée garantit un résultat significatif et validé.
Cependant, Archify n'est pas une solution universelle. Il n'est pas idéal pour les diagrammes simples intégrés directement dans les README GitHub, car GitHub ne rend pas son contenu HTML interactif. L'outil nécessite également un workflow d'agent IA existant utilisant des plateformes comme Claude Code ou Cursor, s'intégrant comme une compétence d'agent plutôt que comme une application autonome.
Pour les situations à enjeux élevés, Archify brille vraiment. Son résultat validé et interactif crée des artefacts vérifiables pour les étapes de développement cruciales. Ceux-ci incluent :
- La génération de diagrammes d'architecture pour les revues de PR, offrant un delta clair des changements.
- L'architecture de nouvelles fonctionnalités au sein des documents de conception.
- L'établissement d'une source de vérité fiable et prête à être commitée pour les composants système de votre dépôt.
Cette approche transforme les diagrammes d'images statiques en cartes système fiables et modifiables, en faisant une partie indispensable de votre processus d'ingénierie.
Questions fréquemment posées
Qu'est-ce qu'Archify ?
Archify est une compétence d'agent open-source qui permet aux agents de codage IA comme Claude de générer des diagrammes d'architecture vérifiables et interactifs. Il fonctionne en demandant à l'agent de produire une représentation JSON structurée d'un système, qu'Archify valide et compile ensuite en un fichier HTML autonome.
Comment Archify empêche-t-il les diagrammes inexacts ?
Au lieu de laisser une IA "dessiner" une image, Archify impose un pipeline de validation strict. L'IA doit générer un graphe JSON typé qui respecte un schéma. Si le JSON est invalide ou décrit un état impossible, le processus échoue avec des diagnostics clairs, empêchant la création d'un diagramme trompeur.
Quels agents IA fonctionnent avec Archify ?
Archify est conçu comme une compétence d'agent et s'intègre avec plusieurs assistants de codage populaires, notamment Claude Code, Cursor, Codex CLI, OpenCode et DeepSeek Harness.
Archify remplace-t-il Mermaid ?
Pour les diagrammes générés par IA, interactifs et vérifiables utilisés dans les PR ou les revues de conception, Archify offre des fonctionnalités supérieures. Cependant, pour les diagrammes simples intégrés directement dans un README GitHub, Mermaid est souvent un choix plus simple car son rendu est pris en charge nativement par GitHub.