# Best Practices for Using Archify: A Complete Guide to System Mapping > Master Archify with these best practices. Learn global installation, bounded prompts, JSON validation, and iterative diagram refinement for effective system mapping with the tt-a1i/archify repository. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: best-practices - Published: 2026-08-13 --- **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. ```bash 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: ```bash 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`: ```bash 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`](https://github.com/tt-a1i/archify/blob/main/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. ```bash 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`](https://github.com/tt-a1i/archify/blob/main/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: ```bash # 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: ```text 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** – Defines the formal skill contract, including schema requirements and renderer expectations for agent integration. - **[`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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 ` 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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) and suggests programmatic fixes.