Automating Architecture Diagrams with Claude Code: Practical Guide from ZOZO Case

System architecture diagrams are essential documents for development teams, but manually creating and updating them is time-consuming. In the ZOZO TECH BLOG case study, they automated this process using Claude Code. This article explains the background and specific methods.

📑Table of Contents

1. Background and Challenges of Manual Architecture Diagram Creation with Claude Code
2. Role and Creation Method of Intermediate Files (Conventions and Structure Files)
3. CI-Integrated Automatic Update Workflow
4. Actual Effects, Insights, and Precautions
5. Comparison Table and FAQ for Introduction Decision
6. Summary and Recommended Next Actions for Readers

---

Background and Challenges of Manual Architecture Diagram Creation with Claude Code

Traditionally, AWS system architecture diagrams were drawn manually. Engineers used tools like Visio or draw.io to create them from scratch and updated them manually whenever code changed. This approach had several challenges:

• It took a lot of time to create
• Diagrams often diverged from the actual code
• Consistency was lost when multiple people maintained them

Claude Code solves these issues by generating diagrams from code or specifications simply by giving natural language instructions. In the ZOZO case, introducing Claude Code significantly reduced the time spent on diagram creation.

---

Role and Creation Method of Intermediate Files (Conventions and Structure Files)

The key to automation is creating intermediate files. First, create files that define the project structure and conventions. For example, describe service relationships in JSON or YAML format as shown below.

{
  "services": [
    {"name": "WebServer", "type": "EC2", "connections": ["Database"]},
    {"name": "Database", "type": "RDS", "connections": []}
  ]
}

By passing this intermediate file to Claude Code, it automatically generates diagrams in Mermaid or PlantUML format. The convention file should be shared within the team, and update rules should be clearly defined.

---

CI-Integrated Automatic Update Workflow

By integrating the generated diagrams with a CI/CD pipeline, diagrams can be automatically updated when code changes. In a GitHub Actions example, the following steps are incorporated:

1. Detect repository changes
2. Execute prompts to update intermediate files with Claude Code
3. Commit the generated diagrams to the repository
4. Reflect them on the documentation site

This workflow prevents diagrams from becoming outdated. In the ZOZO case, CI integration ensures that the latest architecture diagrams are always maintained.

---

Actual Effects, Insights, and Precautions

The effects of introduction include reports that diagram creation time was reduced to less than half. Additionally, consistency between code and diagrams was maintained, improving review efficiency.

As a precaution, always have humans review the generated diagrams. Claude Code outputs may contain errors, so check for security issues and dependency errors. Also, be careful when generating diagrams that include confidential information.

---

Comparison Table and FAQ for Introduction Decision

Item	Manual Creation	Claude Code Automatic Generation
Creation Time	Several hours	Several minutes
Update Frequency	Manual	Automatic (CI integration)
Consistency	Low	High
Cost	Human cost	AI usage fee + initial setup

FAQ

Q: Is a special plan required to use Claude Code?

It is available with Pro plan or higher. Please check the official documentation for details.

Q: Can the format of generated diagrams be customized?

Yes, you can specify the desired format such as Mermaid or PlantUML.

Q: How do I update existing diagrams with Claude Code?

Pass the source of the existing diagram as an intermediate file to Claude Code and give update instructions.

---

Summary and Recommended Next Actions for Readers

Automating architecture diagram generation using Claude Code is a method that greatly improves development efficiency. Start by creating intermediate files and try CI integration.

We recommend the following actions for readers: – Read the ZOZO TECH BLOG case study article to check the details – Try creating intermediate files in your own project – Refer to the official Claude Code documentation to set it up

This will free you from manual work and allow you to focus on more creative development.

Related articles:

• How Department Heads Build a Second Brain Using Claude Code and Obsidian
• Claude Fable 5 Agent SOP Setup Guide: Timing, Steps, and Decision Criteria Before Access Ends
• How pxpipe Cuts Claude API Costs by Treating System Prompts as Images

Related new article:

• How to Run Claude Code with Local LLMs on 16GB PCs — Tool Call Stability via CodeRouter (2026) – This published update adds current operational context for Automating Architecture Diagrams with Claude Code: Practical Guide from ZOZO Case.