I Compared 5 Ways to Make Claude Code Draw AWS Diagrams. The Prompt Mattered More Than the Tool

Ryota Sago — Fri, 02 Oct 2026 13:08:20 +0000

If you've asked an AI agent for an AWS architecture diagram, you've probably seen something like this: rounded icons and boxes, tangled lines, and a general feeling that nobody would ship it as is.

I wanted to know whether the fix was a better tool or a better prompt. So I gave the same architecture to five setups, including AWS's and draw.io's official MCP servers and skills, and kept adding instructions whenever something looked off. By the end, every setup had improved a lot, and a plain Claude Code session with no MCP server or skill did as well as any of them. This is the diagram it drew with the final prompt.

I ran everything in September 2026 on Claude Code 2.1.278 with Claude Opus 5. The prompts were in Japanese, and the prompts below are my English translations, minus the line that set the label language. For this post, I replaced the Japanese labels in the .drawio outputs with English ones and re-exported them; the layout and lines are unchanged. The Diagram MCP Server only outputs PNG, so the first image in this post is a new run of the same prompt in English (Claude Code 2.1.285, same model).

The five setups I compared

#	Setup	Output
1	AWS Diagram MCP Server 1.0.23 (MCP, deprecated)	PNG only
2	`aws-architecture-diagram` skill from AWS	.drawio (PNG, SVG, PDF on request)
3	draw.io's official MCP Tool Server	A URL that opens draw.io (can edit existing .drawio files)
4	draw.io's official Claude Code plugin (skill)	.drawio (PNG, SVG, PDF, URL on request)
5	Plain Claude Code, no MCP server or skill	Whatever you ask for

Links: AWS Diagram MCP Server, aws-architecture-diagram skill, draw.io MCP Tool Server, draw.io Claude Code plugin, Claude Code docs.

The first one is the reason I started. AWS deprecated the Diagram MCP Server in March 2026, and every release on PyPI has since been yanked. The notice says the diagram skill in the deploy-on-aws plugin "generates equivalent diagrams directly through Claude Code without requiring a running MCP server." Equivalent, not better. I wanted to see what that looks like in practice.

For setups 2 to 5, I asked for draw.io XML so I could compare .drawio files. Setup 1 can only produce PNG, so I changed the last line of its prompt to ask for a PNG.

What a usable diagram means

For a diagram I'd actually use at work, I looked at six things.

Reproducibility. The same prompt should give roughly the same diagram every time
Cost. Fewer tokens and less time
Faithfulness. Only what I asked for, with no extra numbering or explanation panels
Readability. Lines and labels don't overlap
Look. No rounded icons or decorative boxes that make it look AI-generated
Editability. Output I can fix by hand, which means a .drawio file

Keeping the comparison fair

Anything else loaded into Claude Code, such as my own skills, plugins, or CLAUDE.md, would affect the output. So I started each session with only the project settings and only the MCP server under test.

# AWS Diagram MCP Server, draw.io MCP Tool Server
claude --setting-sources project --strict-mcp-config --mcp-config mcp.json

# aws-architecture-diagram skill
claude --setting-sources project --strict-mcp-config --plugin-dir agent-plugins/plugins/deploy-on-aws

# draw.io Claude Code plugin
claude --setting-sources project --strict-mcp-config --plugin-dir drawio-mcp/plugins/claude-code

# Plain Claude Code
claude --setting-sources project --strict-mcp-config

Without --strict-mcp-config, MCP connectors I had set up in claude.ai (in my case, AWS documentation search) still show up in the session. I also tried --safe-mode, which turns off CLAUDE.md, skills, plugins, and MCP servers all at once, but it also turned off the plugins I wanted to compare, so it didn't work for this test.

Round 1: the same short prompt, five different problems

The first prompt only described the architecture.

Draw an architecture diagram of the following AWS setup.

- Put an ALB behind CloudFront
- The ALB targets an ECS Fargate service spread across two AZs
- The database is Aurora MySQL, with one writer and one reader in different AZs
- Static files are stored in S3 and delivered through CloudFront
- Logs and metrics are collected in CloudWatch
- The VPC spans two AZs, each with a public subnet and a private subnet
- The ALB is in the public subnets, ECS and Aurora are in the private subnets
- Each AZ has a NAT Gateway in its public subnet for outbound traffic from ECS
- Save the diagram as a draw.io XML file under out/

None of the five results was usable without edits, and each failed in its own way. The Diagram MCP Server gave me a tangled, rounded diagram like the one at the top of this post. AWS's skill added numbered badges and a data-flow panel I never asked for, and put a box around every service icon.

The draw.io MCP server and plugin were closer, but both had lines running over text. The MCP server also added notes I hadn't asked for, and the plugin rounded the corners of its lines. Plain Claude Code was fairly tidy, but colored S3 orange and printed service names both above and below the icons.

What I added to the prompt, and why

From there, I iterated round by round. Each time, I looked at all five outputs, picked what bothered me, and added one or two lines to the prompt. Some fixes caused new problems, which is why the list reads like a negotiation.

What went wrong	What I added
Lines crossed text	Don't let lines overlap labels
To avoid overlaps, it dropped icons and drew plain boxes	Use the official AWS icons
ECS was still a box	Always use icons. No text outside the diagram
Line labels disappeared too	Line labels are fine. Public subnets go above private ones
Short notes and color coding disappeared	Short notes attached to elements are fine
AZs were named "A" and "C"	Use the full AZ names
Users were sometimes at the top, sometimes on the left	Put users at the top
Old and new icon designs were mixed	Use the latest icon set (this didn't work, so I dropped it)
Aurora used an instance icon	Use service-level icons. Labels go below icons
Lines left icons from a different spot every time	Start lines from the middle of an icon's edge

The final prompt was the architecture plus these rules.

- Write AZ names in full, not as "A" or "B"
- Put users at the top of the diagram
- In each AZ, put the public subnet above the private subnet
- Always use the official AWS icons. Don't substitute boxes or circles. Use service-level icons, not icons for individual resources such as instances
- Put each icon's label below the icon
- Don't let lines cross icons or label text. Lines may start below a label. Lines must not run on top of each other, though they may cross
- Start lines from the middle of an icon's edge where possible
- No title, legend, or explanation panel outside the diagram. Line labels and short notes attached to elements are fine

Results

I ran the final prompt three times per setup. Time and tokens are averages across the three runs.

Setup	Time	Output tokens	Reproducibility
AWS Diagram MCP Server	5.5 min	23,393	Changes a lot between runs
`aws-architecture-diagram` skill	5.4 min	33,510	Changes in small ways
draw.io MCP Tool Server	4.1 min	25,439	Nearly identical, but the NAT Gateway icon differs every run
draw.io Claude Code plugin	5.8 min	34,544	Nearly identical, but S3 moves around
Plain Claude Code	5.4 min	32,805	Nearly identical

The Diagram MCP Server switched to curved lines and kept its rounded icons, and because it only outputs PNG, I couldn't fix anything by hand. AWS's skill produced a clean layout, but left out the lines to CloudWatch and the Aurora replication, and used the VPC icon for the NAT Gateways. The draw.io MCP server's lines were my personal favorite, but it made the same NAT Gateway mistake.

The draw.io plugin got the icons right with about the right amount of detail. Plain Claude Code had no crossing lines and varied the least across runs.

What I learned

Every setup improved a lot once the prompt said what a good diagram looks like. By the end, the draw.io MCP server, the draw.io plugin, and plain Claude Code were all at a level I'd use, and none of them clearly beat the others.

So the choice of MCP server or skill mattered less than being explicit about the result I wanted. It's the same with code. If you don't say what you want, you get comments you didn't need and abstractions you didn't ask for. Diagrams are no different.

Limits of this test

Diagram taste is personal. Whether users go at the top or on the left, what to group, what to leave out. These rules reflect mine
It's one architecture, a standard two-AZ web app. I didn't test multi-account, hybrid, or very large diagrams here
Three runs per setup is enough to see tendencies, not to measure variance precisely
The reproducibility column is a rough call from comparing the images (icon count, line count, and layout), not a precise metric

I turned the prompt into a skill

Writing that long prompt every time is tedious, so I packaged the rules into a Claude Code skill: sagochiko/aws-drawio-diagram-skill. With it, you only describe the architecture. I also tried it with English requests (four runs across two architectures), and it followed the same rules as it does with Japanese requests. This is what it drew from the Round 1 prompt above.

It also handles architectures without a VPC, such as an Amazon Bedrock AgentCore agent fronted by a Lambda function running Lambda Web Adapter.

I tested the skill later, on Claude Opus 5.5. There, one diagram took about 3 to 5 minutes and cost around US$1 or less. It's licensed under Apache 2.0 and builds on the official draw.io and AWS skills.

How do you get usable diagrams out of your AI agent? I'd like to hear what rules you've added.

This post was first published on AWS Builder Center. It is an English version of my original article in Japanese on Qiita. The diagrams use AWS Architecture Icons.

I wrote the Japanese original; this English version was rewritten with the help of AI.

DEV Community: Ryota Sago