Archify
Desplegar Archify: builds deterministas de diagramas en CI
Fija skill y hechos, usa last-good, valida exports, limita permisos y prepara rollback.
Qué aprenderás
- Version Archify inputs and compiler
- Design CI validation and last-good gates
- Operate safe export and rollback paths
Antes de empezar
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Conclusiones clave
- Pin compiler and authored facts together.
- Make validation and last-good previews release gates.
- Treat exports, permissions, and visual diffs as operational surfaces.
Pin the compiler and the facts
Un build reproducible fija el compilador/skill y la revisión que contiene los hechos. CI debe bloquear errores de esquema o layout, comparar candidato con last-good, verificar exports autocontenidos y conservar una revisión y artefacto de rollback.
Keep secrets and private source out of the rendered artifact unless the repository policy explicitly permits them. Prefer a sanitized architecture fixture for public CI and link back to the private evidence system when necessary.
Use last-good as an explicit release boundary
The README describes validation and last-good preview behavior. In CI, render the candidate beside the last accepted artifact, fail the job on schema or layout errors, and keep the last-good output available for reviewers. Do not replace a trustworthy diagram with a partially rendered candidate just because the export step produced a file.
Compare normalized JSON and visual diffs for a fixed input. A changed edge, missing source trace, or unexpected animation should be reviewed as a semantic change, not dismissed as cosmetic noise.
Harden exports and permissions
Run diagram generation with least-privilege access to the repository and an isolated output directory. Check that HTML is self-contained, external requests are expected, and generated media cannot escape the artifact root. Treat agent-produced JSON and source descriptions as untrusted input to the renderer.
Collect duration, node/edge counts, validation status, export format, artifact checksum, and input revision. These fields help distinguish a real architecture change from a toolchain or environment drift.
Upgrade and rollback
Canary a new Archify release on representative diagrams, including sequence and lifecycle cases, and compare validation, render, export, and source-trace results. Keep the previous skill revision and last-good artifacts available so rollback is a versioned change rather than a manual redraw.
Cómo elegir
| Criterio | Opción A | Opción B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Pasos de implementación
- 1
Pin the Archify skill and input revision.
- 2
Run validation and candidate/last-good comparisons in an isolated job.
- 3
Verify self-contained exports, permissions, checksums, and source traces.
- 4
Canary upgrades and retain a rollback revision and artifact.
Ejemplo para copiar
archify:
skill_revision: <commit>
input_revision: <commit>
validation: required
last_good: artifacts/architecture-last-good.html
output_sha256: <recorded-hash>Preguntas frecuentes
Should CI publish every render even when validation fails?
Keep failed output as a review artifact, but publish it as failed and preserve the last-good diagram as the trusted release surface.
What belongs in the build record?
Record skill/compiler revision, input revision, host, validation status, node/edge counts, export format, duration, and checksum.
Fuentes
- Archify README (captured 2026-08-31)Fuente verificada 2026-08-31
- Archify repositoryFuente verificada 2026-08-31