architecture-diagrams

アーキテクチャ図

ポータブルな Claude エージェントスキル

Diagrams Python ライブラリを使用した、プロフェッショナルなアーキテクチャ図の生成ツールです。実際のクラウドプロバイダーのアイコン（AWS、Azure、GCP、K8s、OnPrem、Generic）を使って、出版品質の図を生成します。

ポータビリティ： architecture-diagrams/ フォルダー全体が自己完結しています。~/.claude/skills/ またはプロジェクトの .claude/skills/ ディレクトリにコピーしてください。各場所で一度、./scripts/setup.sh を実行します。

インストールとセットアップ

システム要件

Graphviz をシステム全体にインストールする必要があります（dot バイナリが提供されます）。

# Ubuntu/Debian
sudo apt install graphviz

# macOS
brew install graphviz

# RHEL/Fedora
sudo dnf install graphviz

初回セットアップ（インストール場所ごと）

cd <path-to>/architecture-diagrams/
chmod +x scripts/setup.sh
./scripts/setup.sh

これにより .venv/ が作成され、Python の依存関係がインストールされ、graphviz が検証されます。

自動セットアップの確認

cd <path-to>/architecture-diagrams/
if [ ! -d ".venv" ]; then
  ./scripts/setup.sh
fi
echo "Skill ready"

クイックスタート

# 1. Navigate to your project directory
cd ~/projects/my-project/

# 2. Set skill path for convenience
SKILL_DIR=~/.claude-wa/.claude/skills/architecture-diagrams

# 3. Verify setup
if [ ! -d "$SKILL_DIR/.venv" ]; then cd "$SKILL_DIR" && ./scripts/setup.sh && cd -; fi

# 4. Activate venv
source "$SKILL_DIR/.venv/bin/activate"

# 5. Create a diagram script in your project
cat > my-diagram.py << 'EOF'
from diagrams import Diagram, Cluster
from diagrams.aws.compute import EC2
from diagrams.aws.network import ELB

with Diagram("My Architecture", show=False):
    lb = ELB("Load Balancer")
    with Cluster("Web Tier"):
        web = [EC2("Web 1"), EC2("Web 2")]
    lb >> web
EOF

# 6. Generate PNG (output goes to ./output/png/ in current directory)
python "$SKILL_DIR/scripts/generate.py" my-diagram.py

# Output: ~/projects/my-project/output/png/my-diagram.png

ファイル構成

architecture-diagrams/        <-- Skill root (portable)
  SKILL.md                    # This file
  requirements.txt            # Python deps (diagrams, graphviz)
  .venv/                      # Python virtual environment (created by setup.sh)
  scripts/
    setup.sh                  # Creates .venv and installs deps
    generate.py               # Runs diagram script, outputs to cwd/output/png/
  src/
    templates/                # Starter templates — copy these
      basic-template.py       # Minimal template with TODOs
    examples/                 # Working example diagrams
      cisco-network.py        # Network topology with routers, switches, firewall
      aws-architecture.py     # AWS cloud architecture with VPC, ALB, RDS
      kubernetes-cluster.py   # K8s cluster with namespaces, services, monitoring
  docs/
    icon-reference.md         # Index with top icons + navigation (load this first)
    icons/                    # Provider-specific icon catalogs (load on demand, all ≤450 lines)
      generic.md              # Generic infrastructure (26 icons)
      aws.md                  # Amazon Web Services (562 icons)
      azure-compute-network.md # Azure: Compute, Network, Database, Storage (~400 icons)
      azure-app-devops.md     # Azure: App Services, DevOps, Identity, Integration, IoT (~240 icons)
      azure-web-security.md   # Azure: Management, Security, Web Services (~170 icons)
      gcp.md                  # Google Cloud Platform (144 icons)
      kubernetes.md           # Kubernetes (69 icons)
      onprem.md               # On-Premise tools (211 icons)
      saas.md                 # SaaS providers (42 icons)
      programming.md          # Languages & frameworks (81 icons)
      elastic-firebase.md     # Elastic Stack, Firebase (~109 icons)
      digitalocean-ibm.md     # DigitalOcean, IBM Cloud (~309 icons)
      oracle-openstack.md     # Oracle OCI, OpenStack (~415 icons)
      outscale-alibaba-misc.md # Outscale, Alibaba, GIS, Custom, C4 (~220 icons)

出力パスの動作

図は、スキルのディレクトリではなく、現在の作業ディレクトリからの相対パスである ./output/png/ に生成されます。そのため、出力はプロジェクトのフォルダー内に表示されます。

# From your project directory
cd ~/projects/my-project/
python <skill>/scripts/generate.py diagram.py
# Output: ~/projects/my-project/output/png/diagram.png

# Custom output directory
python <skill>/scripts/generate.py diagram.py --output-dir ./diagrams/
# Output: ~/projects/my-project/diagrams/diagram.png

# Absolute path
python <skill>/scripts/generate.py diagram.py --output-dir /tmp/diagrams/
# Output: /tmp/diagrams/diagram.png

アイコンリファレンス（段階的な開示）

17 のプロバイダーにまたがる 2634 個のアイコンを、効率的にコンテキストを読み込めるように整理しています。

1. まず docs/icon-reference.md を確認します — ナビゲーションテーブル、使用頻度の高いアイコン上位 30 個、クイックスタート用インポートを含むメインインデックス（約 130 行）
2. 必要に応じてプロバイダーファイルを読み込みます — docs/icons/ から、必要なプロバイダーのファイルだけを読み込みます（例：AWS アイコンには docs/icons/aws.md）

プロバイダーファイル	アイコン数	読み込みのタイミング
icons/generic.md	26	ネットワーク機器、OS、コンピューティング、ストレージ
icons/aws.md	562	AWS クラウドアーキテクチャ
Azure（分割）：	810	Microsoft Azure — 必要に応じて読み込み
icons/azure-compute-network.md	~400	Azure のコンピューティング、ネットワーク、データベース、ストレージ
icons/azure-app-devops.md	~240	Azure のアプリサービス、DevOps、ID、IoT
icons/azure-web-security.md	~170	Azure の管理、セキュリティ、ウェブ
icons/gcp.md	144	GCP アーキテクチャ
icons/kubernetes.md	69	K8s クラスター、ポッド、サービス
icons/onprem.md	211	セルフホスト型インフラ、データベース、CI/CD
icons/saas.md	42	SaaS プロバイダー
icons/programming.md	81	言語、フレームワーク
その他のクラウド（分割）：	689	その他のクラウドプロバイダー — 必要に応じて読み込み
icons/elastic-firebase.md	~109	Elastic Stack、Firebase
icons/digitalocean-ibm.md	~309	DigitalOcean、IBM Cloud
icons/oracle-openstack.md	~415	Oracle OCI、OpenStack
icons/outscale-alibaba-misc.md	~220	Outscale、Alibaba、GIS、Custom、C4

基本概念

ダイアグラムのコンテキストマネージャー

すべての図で Diagram コンテキストマネージャーを使用します。

from diagrams import Diagram, Cluster, Edge

with Diagram(
    "Diagram Title",          # Title shown on diagram
    filename="output-name",   # Output filename (no extension)
    outformat="png",          # png, jpg, svg, pdf, dot
    show=False,               # Don't auto-open
    direction="TB",           # TB, BT, LR, RL
    graph_attr={...},         # Graphviz attributes
):
    # nodes and connections here

方向

値	意味	適した用途
TB	上から下	階層型アーキテクチャ、ネットワークトポロジ
BT	下から上	上向きのデータフロー
LR	左から右	パイプライン、データフロー、タイムライン
RL	右から左	逆方向のフロー

グラフ属性

graph_attr = {
    "fontsize": "14",       # Title font size
    "bgcolor": "#ffffff",   # Background color
    "pad": "0.5",           # Padding around diagram
    "nodesep": "0.6",       # Horizontal spacing
    "ranksep": "0.8",       # Vertical spacing between ranks
    "splines": "spline",    # Edge routing: spline, ortho, curved, polyline
    "concentrate": "true",  # Merge parallel edges
}

ノードプロバイダーのクイックリファレンス

Generic（ネットワークインフラ）

from diagrams.generic.network import Firewall, Router, Switch, Subnet, VPN
from diagrams.generic.compute import Rack
from diagrams.generic.database import SQL
from diagrams.generic.storage import Storage
from diagrams.generic.device import Mobile, Tablet
from diagrams.generic.place import Datacenter
from diagrams.generic.os import Ubuntu, Windows, LinuxGeneral, Debian, RedHat, CentOS
from diagrams.generic.virtualization import Vmware, Virtualbox, Qemu
from diagrams.generic.blank import Blank  # Invisible node for layout control

AWS

# Compute
from diagrams.aws.compute import EC2, ECS, Lambda, Fargate, ElasticBeanstalk, Batch
# Database
from diagrams.aws.database import RDS, Aurora, Dynamodb, ElastiCache, Neptune, Redshift
# Network
from diagrams.aws.network import ELB, Route53, CloudFront, VPC, APIGateway, DirectConnect
# Storage
from diagrams.aws.storage import S3, EFS, FSx
# Security
from diagrams.aws.security import Cognito, WAF, IAM, KMS, CertificateManager
# Integration
from diagrams.aws.integration import SQS, SNS, Eventbridge, StepFunctions
# Management
from diagrams.aws.management import Cloudwatch, Cloudformation, Cloudtrail, AutoScaling
# Analytics
from diagrams.aws.analytics import Kinesis, Athena, Glue, EMR
# General
from diagrams.aws.general import Users, Client

Azure

from diagrams.azure.compute import VM, FunctionApps, ContainerInstances, KubernetesServices
from diagrams.azure.database import CosmosDb, SQLDatabases, CacheForRedis
from diagrams.azure.network import LoadBalancers, ApplicationGateway, DNS, VirtualNetworks
from diagrams.azure.storage import BlobStorage, StorageAccounts
from diagrams.azure.security import KeyVaults, ActiveDirectory
from diagrams.azure.integration import ServiceBus, EventGrid
from diagrams.azure.web import AppServices

GCP

from diagrams.gcp.compute import GCE, GKE, Functions, Run, AppEngine
from diagrams.gcp.database import SQL as GcpSQL, Spanner, Firestore, BigTable, Memorystore
from diagrams.gcp.network import LoadBalancing, CDN, DNS as GcpDNS, VPC as GcpVPC
from diagrams.gcp.storage import GCS
from diagrams.gcp.analytics import BigQuery, PubSub, Dataflow
from diagrams.gcp.security import IAP, KMS as GcpKMS

Kubernetes

from diagrams.k8s.compute import Pod, Deployment, StatefulSet, ReplicaSet, Job, CronJob, DaemonSet
from diagrams.k8s.network import Ingress, Service, NetworkPolicy
from diagrams.k8s.storage import PV, PVC, StorageClass
from diagrams.k8s.rbac import ServiceAccount, Role, ClusterRole
from diagrams.k8s.infra import Node as K8sNode, Master
from diagrams.k8s.clusterconfig import HPA, ConfigMap, Secret
from diagrams.k8s.podconfig import Container

オンプレミス

# Network
from diagrams.onprem.network import Nginx, HAProxy, Traefik, Istio, Envoy, Consul, Kong, Apache
# Database
from diagrams.onprem.database import PostgreSQL, MySQL, MongoDB, Cassandra, Redis as OnPremRedis
from diagrams.onprem.database import Neo4J, CockroachDB, InfluxDB, Clickhouse
# Queue
from diagrams.onprem.queue import Kafka, RabbitMQ, ActiveMQ, Celery, Nats
# Container
from diagrams.onprem.container import Docker
# CI/CD
from diagrams.onprem.ci import Jenkins, GithubActions, GitlabCI, CircleCI
from diagrams.onprem.cd import Spinnaker, Tekton
from diagrams.onprem.gitops import ArgoCD, Flux
# Monitoring
from diagrams.onprem.monitoring import Prometheus, Grafana, Datadog, Splunk, Nagios
from diagrams.onprem.logging import Loki, Fluentbit
from diagrams.onprem.tracing import Jaeger, Tempo
# IAC
from diagrams.onprem.iac import Terraform, Ansible
# VCS
from diagrams.onprem.vcs import Git, Github, Gitlab
# Analytics
from diagrams.onprem.analytics import Spark, Hadoop, Flink
# Auth/Security
from diagrams.onprem.security import Vault, Trivy
# Workflow
from diagrams.onprem.workflow import Airflow, Kubeflow, Nifi
# In-Memory
from diagrams.onprem.inmemory import Redis, Memcached
# Compute
from diagrams.onprem.compute import Server, Nomad

カスタムアイコン

from diagrams.custom import Custom

# Use any local PNG/JPG image as a node icon
my_service = Custom("My Service", "./path/to/icon.png")

クラスター（グループ化）

with Cluster("VPC"):
    with Cluster("Public Subnet"):
        web = EC2("Web")
    with Cluster("Private Subnet"):
        api = EC2("API")
        db = RDS("Database")

クラスター属性：

with Cluster("Styled Group", graph_attr={
    "bgcolor": "#e8f4fd",     # Background color
    "style": "dashed",        # solid, dashed, dotted, rounded
    "color": "#2196F3",       # Border color
    "penwidth": "2.0",        # Border width
    "fontsize": "12",         # Label font size
    "fontcolor": "#333333",   # Label color
    "labeljust": "l",         # Label alignment: l, r, c
}):
    pass

エッジ（接続）

基本的な接続

# Forward direction
node_a >> node_b

# Backward direction
node_a << node_b

# Bidirectional (no arrows)
node_a - node_b

# One-to-many
node_a >> [node_b, node_c, node_d]

# Chain
node_a >> node_b >> node_c

スタイル付きエッジ

from diagrams import Edge

node_a >> Edge(
    label="HTTPS",        # Text label on the edge
    color="blue",         # Edge color (name or hex)
    style="dashed",       # solid, dashed, dotted, bold
    minlen="2",           # Minimum edge length (ranks)
) >> node_b

エッジのスタイルパターン

接続タイプ	色	スタイル	例
同期 API	blue または navy	solid	REST/gRPC 呼び出し
非同期メッセージング	orange または green	dashed	Kafka、SQS、イベント
データベースアクセス	purple または red	solid	SQL クエリ
レプリケーション	gray	dashed	DB レプリケーション
モニタリング	gray	dotted	メトリクス／ログ
外部 API	brown または gold	solid	サードパーティー
キャッシュ	red	solid	Redis/Memcached
ストレージ	brown	dotted	S3、NFS、iSCSI

出力形式

形式	フラグ	用途
PNG	png（デフォルト）	ドキュメント、プレゼンテーション
SVG	svg	拡大縮小可能なウェブへの埋め込み
PDF	pdf	印刷品質のドキュメント
JPG	jpg	圧縮画像
DOT	dot	手動編集用の Graphviz ソース

# Single format
with Diagram("Title", outformat="svg"): ...

# Multiple formats at once
with Diagram("Title", outformat=["png", "svg", "pdf"]): ...

スクリプトの生成方法

# Set skill path
SKILL=~/.claude-wa/.claude/skills/architecture-diagrams

# Activate venv first
source "$SKILL/.venv/bin/activate"

# Generate from example (output in ./output/png/)
python "$SKILL/scripts/generate.py" "$SKILL/src/examples/cisco-network.py"

# Custom output name
python "$SKILL/scripts/generate.py" "$SKILL/src/examples/cisco-network.py" --name my-network

# SVG format
python "$SKILL/scripts/generate.py" "$SKILL/src/examples/aws-architecture.py" --outformat svg

# Custom output directory
python "$SKILL/scripts/generate.py" "$SKILL/src/examples/aws-architecture.py" --output-dir ./my-diagrams/

# Generate in a project directory
cd ~/projects/my-project/
python "$SKILL/scripts/generate.py" my-diagram.py
# Output: ~/projects/my-project/output/png/my-diagram.png

よくある図のパターン

ネットワークトポロジー

レイアウト：TB。ルーター、スイッチ、ファイアウォール、VPN、サブネットには diagrams.generic.network を使用します。DMZ、内部、管理の各ゾーンをクラスター化します。src/examples/cisco-network.py を参照してください。

クラウドアーキテクチャ

レイアウト：TB。AWS／Azure／GCP プロバイダーのアイコンを使用します。VPC、サブネット、AZ をクラスター化します。エッジラベルにプロトコルを指定します。src/examples/aws-architecture.py を参照してください。

Kubernetes クラスター

レイアウト：TB。Pod、Deployment、Service、Ingress には diagrams.k8s を使用します。名前空間をクラスター化します。モニタリングスタック（Prometheus、Grafana）には OnPrem を使用します。src/examples/kubernetes-cluster.py を参照してください。

マイクロサービス

レイアウト：TB または LR。プロバイダーを組み合わせます。サービスには OnPrem、インフラには AWS を使用します。サービスグループをクラスター化します。エッジのスタイルで同期／非同期／データのフローを区別します。

CI/CD パイプライン

レイアウト：LR。diagrams.onprem.ci と diagrams.onprem.cd を使用します。環境ごとの分岐を含む線形フローにします。

よくある間違い

間違い	修正方法
ModuleNotFoundError: diagrams	まず仮想環境を有効にします：source .venv/bin/activate
ExecutableNotFound: dot	graphviz をインストールします：sudo apt install graphviz
図がビューアーで開く	Diagram() で show=False を設定します
ファイルが間違ったディレクトリに保存される	出力先は cwd/output/png/ です。プロジェクトディレクトリから実行するか、--output-dir を使用します
プロバイダークラスのインポートエラー	diagrams.mingrammer.com/docs/nodes/ で正確なクラス名を確認します
エッジが重なり、見づらくなる	graph_attr で "splines": "ortho" または "concentrate": "true" を使用します
ノード同士が近すぎる	graph_attr の nodesep と ranksep を大きくします
図が大きすぎる／小さすぎる	pad、fontsize、クラスターごとのノード数を調整します
カスタムアイコンが見つからない	パスはスクリプトの作業ディレクトリからの相対パスにします
複数の出力形式が機能しない	outformat にリストを渡します：outformat=["png", "svg"]

トラブルシューティング

問題	解決策
setup.sh が失敗する	Python 3.7 以降と graphviz のバイナリがインストールされていることを確認します
.venv の作成に失敗する	python3 -m venv .venv --clear を試して再作成します
出力が空白／空になる	with Diagram() ブロック内でノードが定義されていることを確認します
出力先へのアクセスが拒否される	output/png/ ディレクトリへの書き込み権限を確認します
生成が遅い	ノードの多い大規模な図では通常のことです。クラスターまたはノードを減らします
dot がセグメンテーション違反を起こす	graphviz を更新します：sudo apt install --only-upgrade graphviz