AWS Architecture Diagram Auto-Update System

Claude Code と AWS MCP Server を組み合わせて、staging / 本番環境の
AWSアーキテクチャ図をセキュアに自動更新するシステム。

---

システム概要

開発者が「stagingを更新して」と入力するだけで、以下が自動で走る。

開発者の入力
    ↓ UserPromptSubmit hook（キーワード検出）
Claude が /update-diagram を実行
    ↓
AWS MCP Server（ReadOnlyロールで情報取得）
    ↓ PostToolUse hook（取得後に警告注入）
scripts/filter.py（機密情報マスク＋必要情報のみ抽出）
    ↓
scripts/generate_diagram.py（Draw.io XML生成）
    ↓
envs/{env}/diagram.drawio（ファイル更新）

AWS MCP Server のAPI呼び出しは CloudTrail に自動記録される（監査目的）。

---

ディレクトリ構成と各ファイルの役割

.
├── CLAUDE.md                          # Claudeへの指示書（セッション毎に読み込まれる）
├── .mcp.json                          # MCP Serverの接続設定
├── .claude/
│   ├── settings.json                  # permissions・hooks設定
│   ├── rules/
│   │   ├── security.md                # 機密情報マスクルール（Claudeが毎回参照）
│   │   └── aws-arch.md                # 図の更新手順・レイアウト規則
│   └── commands/
│       └── update-diagram.md          # /update-diagram コマンド定義
├── scripts/
│   ├── filter.py                      # 機密情報フィルタリング
│   ├── generate_diagram.py            # Draw.io XML生成
│   └── hooks/
│       └── on-update-trigger.sh       # UserPromptSubmit hookスクリプト
├── iam/
│   └── claude-mcp-readonly-policy.json  # IAMポリシー定義（ReadOnlyのみ）
└── envs/
    ├── staging/
    │   └── diagram.drawio             # stagingのアーキテクチャ図
    └── production/
        └── diagram.drawio             # 本番のアーキテクチャ図

各ファイルの詳細

ファイル	役割
CLAUDE.md	Claudeが毎セッション読む指示書。ドキュメントではなくClaudeへの命令文として記述
.mcp.json	AWS MCP・Draw.io MCPの起動設定。AWSはReadOnlyプロファイルを指定
.claude/settings.json	Write系API全拒否のpermissions設定 + hookの定義
.claude/rules/security.md	ARN・アカウントID・プライベートIP等のマスクルール。Claudeとfilter.pyの両方が参照
.claude/rules/aws-arch.md	図の更新順序・レイアウト・カラーパレットのルール
.claude/commands/update-diagram.md	/update-diagramコマンドの実行手順。$ARGUMENTSで環境を受け取る
scripts/filter.py	AWS MCPの生データから機密情報を除去し、Draw.io用データだけを抽出
scripts/generate_diagram.py	filter.pyの出力を受け取り .drawio XMLを生成。外部依存ゼロ
scripts/hooks/on-update-trigger.sh	「更新して」を検出するとClaudeのコンテキストに環境情報を注入するhook
iam/claude-mcp-readonly-policy.json	AWSに適用するIAMポリシー。Describe*/List*/Get*のみ許可

---

なぜこの構成にしたか

Claude Code の機能を最大限に使う

機能	使い方	理由
CLAUDE.md	Claudeへの行動指示書	セッション毎に自動で読まれるため、人間が伝え忘れるルールをClaude自身に持たせられる
rules/	セキュリティ・更新ルールを分離	CLAUDE.mdが肥大化しないよう関心ごとで分割
commands/	/update-diagram コマンド化	開発者が手順を覚えなくてもワンコマンドで実行できる
hooks	キーワード検出 → 自動実行	「更新して」という自然な言葉をトリガーにでき、コマンドを知らなくても使える
permissions.deny	Write系API全拒否	Claudeがうっかり書き込み系のAPIを呼んでも settings.json レベルで止まる

ローカルスクリプト方式（Draw.io）

Draw.io用の外部MCPパッケージを使わず、generate_diagram.py をプロジェクト内に持つ構成にした。

• 外部npmパッケージのサプライチェーンリスクがゼロ
• 全コードがリポジトリ内にあるため監査できる
• envs/ 配下以外への書き込みをコードで強制できる

フィルタリングをパイプラインの境界に置く

AWS（信頼できない生データ） → filter.py → generate_diagram.py（安全なデータのみ）

AWS MCPの出力は生のAWSレスポンスのためアカウントIDやIPが含まれる。 Draw.io生成スクリプトに到達する前に必ずフィルタリングを通すことで、 機密情報が図ファイルや会話ログに混入するリスクを構造的に防いでいる。

---

セキュリティ面の工夫と注意点

工夫した点

1. 多層防御

層	手段
IAM	claude-mcp-readonly ロールでReadOnly APIのみ許可
settings.json	permissions.deny でWrite系API呼び出しを拒否
CLAUDE.md / rules	Claudeの判断レベルで「書き込み系APIを呼ぶな」と指示
filter.py	データレベルで機密情報を除去（アカウントID・IP・ARN等）
generate_diagram.py	出力先を envs/ 配下に限定するコードチェック

いずれか1層が抜けても他の層で止まる設計。

2. CloudTrailによる監査

AWS MCP Serverが発行したAPI呼び出しはすべて claude-mcp-readonly ロールの操作として CloudTrail に記録される。「いつ・何のAPIを叩いたか」が後から追跡できる。

3. hooks による強制チェック

PostToolUse hookでAWS MCP呼び出し後に必ず「機密情報を確認せよ」という警告をClaudeのコンテキストに注入する。Claudeが確認をスキップしようとしても、hookが毎回リマインドする。

4. production環境のダブルチェック

/update-diagram production 実行時はコマンド定義・CLAUDE.mdの両方で「ユーザーに yes の確認を取れ」と指示している。どちらかが機能すれば誤更新を防げる。

注意すべき点

IAMポリシーの定期見直し
Describe* で許可している対象リソースは必要最小限に絞ること。
不要なサービスへのDescribeが許可されていると、意図しない情報が取得される。

filter.py の正規表現は完全ではない
アカウントIDのマスクは12桁の数字を対象にしているが、他の12桁数字もマスクされる。
逆に、エンコードされた値や特殊なフォーマットの機密情報は検出できない場合がある。
filter.py を通過した後もClaudeが目視確認する手順を維持すること。

claude-mcp-readonly プロファイルの認証情報管理
~/.aws/credentials に保存するプロファイルの認証情報は定期的にローテーションすること。
可能であればIAM Identity Center（SSO）またはIAM Roles Anywhereを使用する。

diagram.drawio のコミット管理
envs/ 配下のファイルをGit管理する場合、diagram.drawio にリソース名などが含まれることに注意。
社内・非公開リポジトリでの管理を推奨する。

---

セットアップ手順

1. IAMロールの作成

# AWSコンソール または CLI でロール・ポリシーを作成
aws iam create-policy \
  --policy-name claude-mcp-readonly-policy \
  --policy-document file://iam/claude-mcp-readonly-policy.json

2. AWS Profile の設定

# ~/.aws/config
[profile claude-mcp-readonly]
role_arn = arn:aws:iam::[ACCOUNT_ID]:role/claude-mcp-readonly
source_profile = default
region = ap-northeast-1

3. AWS MCP Server のインストール

npm install -g @awslabs/mcp-server-aws

4. 動作確認

Claude Code でこのディレクトリを開き、以下を入力する。

stagingを更新して

---

使い方

入力	動作
stagingを更新して	staging環境の図を更新
本番を更新して	確認後、production環境の図を更新
/update-diagram staging	コマンドで直接実行
何が変わった？	図の更新はせず差分のみ報告