Tutorial de Archify para diagramas de arquitectura: instalación, análisis del repositorio, validación y solución de problemas

Archify es un Agent Skill para Codex CLI, Claude Code, Cursor, OpenCode y Raven. Convierte una descripción del sistema o un repositorio de código en un diagrama técnico interactivo, en lugar de simplemente incluir un fragmento de texto en una plantilla de diagrama de flujo general.

El resultado generado utiliza el JSON IR escrito como fuente de hecho y entrega el HTML autónomo después de la verificación; Las tarjetas para compartir PNG, SVG, WebM y 1200×630 también se pueden exportar en el navegador. Es adecuado para revisión de arquitectura, diagramas README, descripciones de rutas de falla y comparación antes y después de los cambios, pero no puede reemplazar la revisión del código fuente, la configuración de implementación y los registros de operación.

Dirección del proyecto: tt-a1i/archify

Primero determine si Archify es adecuado para la tarea actual

Archify ofrece cinco tipos de gráficos principales:

No acumule toda la información en un diagrama de arquitectura. La reserva de caché de las solicitudes de inicio de sesión es adecuada para Sequence; la aprobación y reversión de CI es adecuada para Workflow; la transición del estado del pedido es más adecuada para el ciclo de vida.

Archify no es un tema de Mermaid, una plataforma de alojamiento en línea ni un editor WYSIWYG. Oficialmente, el análisis automático de Mermaid, el diseño automático general, el intercambio alojado y la edición WYSIWYG están claramente fuera del alcance actual.

Verifique Node.js y el directorio de trabajo antes de la instalación

El comando de instalación se ejecuta a través de npx, así que verifique Node.js y npm primero:

1
2
3

node --version
npm --version
npx --version

Si el comando no existe, instale primero el Node.js LTS actualmente compatible y luego vuelva a abrir la terminal. No atribuya errores de instalación a Codex o Claude Code cuando falta npx.

Confirme también qué repositorio desea analizar:

1
2

git rev-parse --show-toplevel
git status --short

Los espacios de trabajo con cambios no confirmados aún se pueden analizar, pero la evidencia del código fuente en el diagrama debe corresponder a una confirmación explícita. Para revisión formal, primer registro:

1

git rev-parse HEAD

Instalar Archify Skill globalmente

El comando oficial de instalación rápida es:

1

npx skills add tt-a1i/archify -g

-g representa una instalación global. Las ubicaciones de habilidades comunes de cada agente son diferentes:

El instalador procesará el directorio según el Agente de destino. No se recomienda copiar manualmente la misma habilidad en varias ubicaciones desconocidas. Una vez completada la instalación, reinicie el Agente y asegúrese de que la nueva sesión vuelva a analizar las Habilidades.

Si sólo quieres probarlo temporalmente en Codex, puedes ejecutar:

1

npx skills use tt-a1i/archify@archify --agent codex

Una prueba temporal sirve para evaluar el resultado. Para que el equipo pueda reproducirlo, estandarice el método de instalación y registre en la documentación la versión o el commit del repositorio de Archify.

Verificar si el Agente realmente llama a Archify

No juzgue la disponibilidad simplemente por “instalado correctamente”. Después de crear una nueva sesión, realice una solicitud claramente definida:

1
2
3

分析当前仓库，然后使用 archify 生成一张高层运行时架构图。
只保留 8–12 个核心组件，标出一条主请求路径、外部依赖和信任边界。
把补充说明放进卡片，不要继续增加连线。

Tres cosas para comprobar durante la aceptación:

1. El Agente selecciona y llama explícitamente a Archify en lugar de generar resultados de suplantación del código Mermaid.
2. La salida contiene HTML, que se puede abrir por separado, y los datos de origen escritos correspondientes.
3. Cada componente, relación y límite del diagrama puede rastrearse hasta el repositorio o la descripción de entrada, sin añadir servicios sin fundamento.

Si el Agente solo devuelve una explicación, primero déjele que explique si se ha encontrado la Skill y luego verifique el directorio de instalación y el estado de la nueva sesión.

Generar el primer diagrama de arquitectura del repositorio

Los resultados de alta calidad dependen del alcance. Puede utilizar las siguientes palabras clave:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Use archify to map this repository's runtime architecture.

Scope:
- entry points and long-running processes
- API, worker, database, cache and external services
- one primary request path
- authentication and trust boundaries

Constraints:
- 8–12 main nodes
- do not infer services that are not present in source or configuration
- place evidence and secondary details in cards
- deliver the validated HTML and typed source together

Para un monorepo, el directorio debe calificarse primero:

1
2

只分析 apps/api、packages/auth 和 packages/database。
忽略 examples、generated、vendor 和构建产物。

Si el alcance no es limitado, el Agente puede generar pruebas, scripts e implementaciones históricas como componentes de producción, lo que resultará en demasiados nodos y significados poco claros de los bordes.

Seleccione Secuencia o Flujo de datos para un enlace específico

El respaldo de caché encaja en el diagrama de tiempo:

1
2
3
4

Use archify to draw this login sequence:
Browser -> Web App -> API -> JWT validation -> Redis session lookup.
When Redis misses, query PostgreSQL and repopulate Redis.
Show failure returns and timeout boundaries, but keep the happy path primary.

Cuando se trata de privacidad y manejo de datos, utilice Data Flow en su lugar:

1
2
3

画出用户上传文件后的数据流。
标出上传入口、病毒扫描、对象存储、元数据数据库、异步处理器和下载消费者。
明确包含个人信息的节点、跨边界传输和保留期限，不推测未提供的加密方式。

La diferencia es: la secuencia se centra en la secuencia de llamada; Data Flow se centra en el movimiento, la transformación, el almacenamiento y los límites sensibles de los datos.

Conservar JSON IR, no entregar solo capturas de pantalla

Archify usa JSON IR escrito para impulsar la representación. Los equipos también deben guardar:

• original JSON;
• Verificado HTML;
• SVG o PNG para documentación;
• El envío Git correspondiente cuando se genere;
• Revisión manual de registros.

Si mantiene solo PNG, perderá las capacidades repetibles de edición y validación. HTML es adecuado para la visualización interactiva, SVG es adecuado para la gestión de documentos y versiones, y PNG es adecuado para plataformas que no admiten SVG.

Ejemplo de directorio sugerido:

1
2
3
4
5

docs/architecture/
├── runtime.architecture.json
├── runtime.architecture.html
├── runtime.architecture.svg
└── README.md

Alcance del documento y confirmación en README.md:

1
2
3
4

Source revision: 4f2c1ab
Scope: apps/api, packages/auth, packages/database
Excluded: tests, generated, vendor
Review status: manually checked

Verificar y entregar usando el repositorio CLI

Si necesita ejecutar directamente el validador del repositorio de Archify, clone primero el proyecto y entre en su directorio:

1
2
3

git clone https://github.com/tt-a1i/archify.git
cd archify
node bin/archify.mjs doctor

Primero puede consultar los ejemplos integrados:

1
2

node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"

Verificar un Workflow JSON:

1
2
3
4

node bin/archify.mjs validate workflow \
  examples/agent-tool-call.workflow.json \
  --quality showcase \
  --json

Generar entregable único HTML:

1
2
3
4
5
6

node bin/archify.mjs deliver workflow \
  examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality showcase \
  --open \
  --json

En caso de error, lea diagnostics[], el código de regla, el objeto concreto y supportedFixes, y solo modifique el problema señalado. No permita que el agente reescriba el gráfico completo solo porque ocurre un error de validación.

Límites de seguridad para la vista previa local

Puedes usar preview cuando necesites modificar y leer al mismo tiempo:

1
2
3
4

node bin/archify.mjs preview workflow \
  examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality showcase

El modo de vista previa oficial solo vincula el puerto aleatorio de 127.0.0.1 y solo escucha el archivo JSON especificado. Cuando un archivo candidato no pasa la verificación, el navegador continúa mostrando el resultado de calificación anterior.

No cambie el servicio de vista previa a 0.0.0.0 para acceso remoto. Entregue HTML autónomo cuando necesite compartir o publicar archivos de exportación estáticos en un sistema de documentación controlado.

Revisar cambios con Architecture Delta

Un diseño o revisión de PR puede comparar dos instantáneas verificadas:

1
2
3
4
5

node archify/bin/archify.mjs compare architecture \
  base.json \
  head.json \
  architecture-delta.html \
  --json

Los resultados muestran Antes, Delta y Después, distinguiendo entre hechos que se han agregado, eliminado, modificado, movido o redireccionado. Compara dos estructuras escritas y validadas y no determina automáticamente el riesgo, el alcance o si se pueden combinar.

Por lo tanto, todavía se necesitan respuestas manuales:

• Si los cambios provienen del código y la configuración reales;
• Si cambia el límite del fideicomiso;
• Si se agregan recientemente almacenamiento de datos o dependencias externas;
• Si es necesario ajustar la secuencia de implementación y la reversión;
• Comprobar si el nuevo camino está recorrido.

Cómo validar el diagrama generado

Primero verifique los hechos, luego las imágenes:

Verificación de hechos

• Si la entrada es coherente con el comando de inicio real;
• Si la relación de servicio se puede encontrar en el código, la configuración o la documentación;
• Si se debe distinguir entre llamadas sincrónicas y mensajes asincrónicos;
• Las bases de datos, cachés y colas no se mezclan en el mismo almacenamiento;
• No se excluyen los límites de confianza y los sistemas externos;
• No hay “componentes comunes” que el Agente pueda agregar por sí solo en la imagen.

Inspección visual

• Los caminos principales se pueden identificar en segundos;
• Los nodos no se bloquean entre sí;
• La línea de conexión no pasa por la etiqueta;
• La información secundaria no abruma las relaciones primarias;
• Legible tanto en temas oscuros como claros;
• Las expresiones exportadas de SVG, PNG y HTML son consistentes.

Verificación de capacidad de entrega

• HTML se puede abrir en un entorno desconectado;
• JSON y HTML usan la misma versión;
• El nombre del archivo es estable y no contiene nombres aleatorios temporales;
• El diagrama no contiene claves, direcciones de intranet ni datos de clientes;
• Git Los alcances de confirmación y compilación están documentados.

Solución de problemas comunes

El agente no puede encontrar Archify

Reconfirmar instalación y sesión:

1

npx skills add tt-a1i/archify -g

Luego salga por completo y reinicie Codex o Claude Code. Si hay varios directorios de Skill al mismo tiempo, verifique cuál lee realmente el Agente y no continúe repitiendo la instalación.

Se genera Mermaid en lugar de Archify HTML

Escriba explícitamente “usar archify” en el mensaje y solicite la entrega de HTML validado y fuente escrita. Si aún no se llama, significa que la Habilidad no ha sido descubierta o está cubierta por otras reglas.

Hay demasiados componentes en la imagen.

Limite las solicitudes a una única ruta de tiempo de ejecución, limite de 8 a 12 nodos maestros y mueva registros, métricas, pruebas y scripts auxiliares a tarjetas de descripción.

La estructura del diagrama no coincide con el código fuente.

Registre primero el commit de Git y el directorio analizado; después elimine uno por uno los nodos sin evidencia. No complete el repositorio real con suposiciones como «normalmente hay Redis».

La verificación falló pero la imagen anterior aún se muestra

Este es el último mecanismo de vista previa bueno. Marque diagnostics[] y corrija el candidato actual; No juzgues mal el hecho de que la imagen antigua todavía es visible ya que la nueva versión se ha verificado con éxito.

SVG no se muestra correctamente en la plataforma de documentación

Primero abra SVG directamente en el navegador para verificar la fuente, los recursos externos y el rango de recorte. Utilice PNG cuando la visualización no pueda ser estable, pero continúe conservando los archivos fuente SVG y JSON.

Una lista de verificación de aceptación reutilizable

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[ ] 已记录 Archify 安装方式和版本
[ ] 已记录仓库 Git 提交与分析范围
[ ] 图表类型与问题匹配
[ ] 主路径、外部依赖和信任边界明确
[ ] JSON IR 与 HTML 同时保存
[ ] validate 或 deliver 返回成功
[ ] 图中每个关键关系都有输入或源码依据
[ ] 深色与浅色主题可读
[ ] SVG/PNG 导出可打开
[ ] 不包含密钥、内网地址或客户数据
[ ] 人工评审没有把图当作运行时事实证明

Resumen

El valor de Archify no es “dibujar automáticamente en una oración”, sino organizar descripciones técnicas en entregables escritos, verificables e interactivos. Un proceso confiable debe ser: limitar el alcance, seleccionar el tipo de imagen correcto, generar JSON IR, pasar la verificación, verificar manualmente los hechos y luego entregar HTML y exportación estática.

En particular, mantenga el alcance de confirmación y análisis Git para los repositorios de código. Los diagramas pueden ayudar a los equipos a discutir la arquitectura, pero el código fuente, la configuración, las pruebas y los datos operativos siguen siendo la base fundamental.