Best Practices for Using Archify: A Complete Guide to System Mapping

The best practices for using Archify involve installing the skill globally with npx, writing bounded prompts for single diagram types, validating JSON IR with archify.mjs validate before delivery, and iteratively refining diagrams through chat-based commands.

Archify transforms codebases into polished, interactive system maps directly within chat interfaces like Raven, Cursor, Claude Code, Codex CLI, and OpenCode. Following these best practices for using Archify ensures you generate deterministic, shareable HTML or image artifacts that pass strict schema validation and accurately represent your system architecture.

Core Best Practices for Using Archify

Installation and Environment Setup

Install Archify once globally using the skill installer to guarantee you receive the latest stable version (v2.13.0) and avoid version drift across projects.

npx skills add tt-a1i/archify -g

For CI environments requiring reproducible builds, pin the specific version to prevent accidental upgrades that could change diagram semantics:

npx skills use tt-a1i/archify@archify

Verify your environment health before committing artifacts by running the diagnostic command found in archify/bin/archify.mjs:

node archify/bin/archify.mjs doctor

Prompt Design Strategies

Write bounded prompts that request a single diagram type with a clear scope. Specify core components, primary paths, or external dependencies, and ask for supporting details in "cards" rather than additional edges. This approach reduces hallucination and produces concise, reviewable artifacts that the agent can process efficiently.

Selecting the Right Diagram Type

Choose the diagram type that matches your review goal, as each type has a tailored schema that drives validation and visual presets:

• Architecture – Component-level view of your system structure
• Workflow – CI/CD pipelines or procedural steps
• Sequence – Call-order tracing between services
• Data Flow – Data lineage and PII boundary mapping
• Lifecycle – State-machine views of component transitions

According to the schema definitions in archify/schemas/README.md, selecting the correct type ensures the output is semantically correct and passes validation checks specific to that diagram mode.

Validation-First Workflow

Always validate the generated JSON IR before delivery. The archify.mjs validate command checks against bundled schemas and layout requirements.

node archify/bin/archify.mjs validate architecture arch.json --quality showcase --json

Run validation with --quality showcase to ensure visual polish and atomic output. If validation fails, the tool emits a single JSON receipt with supportedFixes that you can address programmatically. This guarantees that rendered artifacts pass all schema and layout checks before sharing.

Iterative Refinement in Chat

After generating an initial diagram, refine it with targeted requests such as "add Redis" or "move auth left." The typed source remains unchanged in the underlying JSON, so only the requested portion regenerates. This keeps the overall diagram stable while allowing rapid, focused edits without rebuilding the entire system map from scratch.

Export and Sharing Strategies

Use the Copy Share Card feature to generate a canonical 1200 × 630 PNG image suitable for README files and release notes. For path-specific sharing, utilize the Route Share Card or Reach Share Card options. These exports provide ready-to-publish graphics that retain full diagram context, avoiding ambiguous screenshots that lack structural information.

Optional Deployment Safety Checks

Enable the deployment-ownership profile when reviewing production deployments. This profile enforces owner, region, and boundary checks, failing closed on missing data. As documented in archify/SKILL.md, this safety net ensures release-engineered reviews maintain strict ownership contracts and never silently enable validation rules.

Essential CLI Commands and Usage Patterns

The primary CLI entry point at archify/bin/archify.mjs supports a complete workflow from generation to delivery:

# Generate a high-level architecture diagram from natural language

archify mjs guide "Show a runtime architecture with web app, API, Redis, and Postgres" --json > arch.json

# Validate with showcase quality standards

node archify/bin/archify.mjs validate architecture arch.json --quality showcase --json

# Preview locally with live reload (only refreshes on successful validation)

node archify/bin/archify.mjs preview architecture arch.json /tmp/arch.html --quality showcase

# Deliver final artifact with atomic replace

node archify/bin/archify.mjs deliver architecture arch.json /tmp/arch.html --quality showcase --open --json

# Generate a sandbox demo for testing

node archify/bin/archify.mjs demo /tmp/demo_output

Chat-based refinements follow this pattern:

User: Add a Redis cache layer between the Web App and the API.
Agent: Updated JSON with a Redis node and a new edge; re-validated and delivered.

Key Source Files and Schema References

Understanding the repository structure helps you debug issues and extend functionality:

• README.md – Contains the central documentation, quick start guides, and the "How it works" workflow table detailing the Generate → Validate → Preview → Deliver pipeline.
• archify/bin/archify.mjs – The CLI entry point implementing guide, validate, preview, deliver, doctor, and demo commands.
• archify/SKILL.md – Defines the formal skill contract, including schema requirements and renderer expectations for agent integration.
• archify/schemas/README.md – Reference documentation for the JSON-IR schemas governing each diagram mode (Architecture, Workflow, Sequence, Data Flow, Lifecycle).
• examples/web-app.html – Full-screen viewer demo showing live interactive architecture diagrams in the browser.

Summary

• Install globally with npx skills add tt-a1i/archify -g and pin versions in CI for reproducibility.
• Write bounded prompts targeting single diagram types to reduce hallucination and improve focus.
• Validate before delivery using archify.mjs validate with --quality showcase to guarantee schema compliance.
• Refine iteratively in chat to maintain diagram stability while making targeted updates.
• Export using share cards for consistent, context-rich 1200 × 630 images suitable for documentation.
• Enable deployment-ownership profiles for production reviews requiring strict boundary and ownership checks.

Frequently Asked Questions

How do I install Archify for team-wide use?

Install Archify globally using npx skills add tt-a1i/archify -g for a one-time setup that ensures all team members use the latest stable version (v2.13.0). For CI environments, use the non-interactive Cursor command or pin the version with npx skills use tt-a1i/archify@archify to guarantee reproducible builds across different machines and prevent version drift.

What makes a "bounded" prompt in Archify?

A bounded prompt requests a single diagram type with a clearly defined scope, such as "core components only" or "primary data flow path," and asks for supplementary information in node cards rather than additional edges. This constraint helps the agent focus on specific architectural aspects, reducing hallucination and producing concise, reviewable JSON IR that validates cleanly against the schema definitions in archify/schemas/README.md.

Why must I validate before delivering diagrams?

Validation ensures the generated JSON IR passes all schema and layout checks, guaranteeing that the rendered HTML or image artifact is atomic and visually correct. The archify.mjs validate command with --quality showcase flag emits diagnostic receipts with supportedFixes if issues exist, preventing broken or misleading diagrams from being shared. This step is critical because the preview loop only updates after validation passes, ensuring last-good diagrams remain stable.

How do I debug validation failures locally?

Run node archify/bin/archify.mjs doctor to verify environment health and check for missing dependencies. For sandbox testing, use node archify/bin/archify.mjs demo <output_path> to generate a sample diagram without affecting your production artifacts. If validation fails on your specific JSON, examine the error receipt returned by the validate command, which references the specific schema violations in archify/schemas/README.md and suggests programmatic fixes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}