Claude CodeでBTPのソリューションダイアグラムを描く

はじめに

この記事では、Claude CodeでBTPのソリューションダイアグラムを書けるようにするために作成したプロジェクトについて説明します。「こんなものを作った」というより、試行錯誤の記録を残すことが目的です。

経緯

drawio-mcp-serverを使ってClaude Desktopからdraw.ioを操作できるという記事を読んで、BTPのソリューションダイアグラムも書けるのではないかと考えました。

このツールはブラウザのプラグインとMCPサーバの2本立てで、ブラウザのプラグインを介してdraw.ioを操作します。draw.ioに図形を追加する方法として、以下があります。

1. add-cell-of-shapeツールにより指定したシェイプを追加する
2. import-diagramツールによりXMLを一括投入

SAPのダイアグラムのパーツはadd-cell-of-shapeで投入できる図形に含まれていなかったため、2番目の方法を試してみました。しかし、一括投入は時間がかかり、タイムアウトする場合もあったので、「Claude CodeにXMLを作成してもらい、Extras > Edit Diagramから人間がXMLを貼り付ける」という方法に落ち着きました。

また、drawio-mcp-serverは「すでに決まった図形を配置する」ことを目的としていますが、ダイアグラム作成で重要なのは「何をどのように配置するか」を決める部分です。そこで、「こういうコンポーネントを使ったダイアグラムを作成したい」というと、ダイアグラムのXMLを生成してくれるプロジェクト（プロンプト）を作ってみよう、という方向になりました。

以降、MCPサーバは使わずにClaude Codeへの指示のみで進みます

最初に試みたこと

BTP Solution Diagramsのページにあった以下の画像を提示して、「こんなダイアグラムを描いて」と依頼しました。

出来上がったものは以下でした。色やアイコンは合っていますが、End UserとApplication Clients両方から矢印が出ているし、全体的に違うぞ・・・といった感じ。コンポーネント同士の関連を考慮せずに雰囲気で線をつないでいるように見えました。

アプローチを変更

そこで、アプローチを以下のように変更しました。

1. 人間がやりたいことを説明する
2. Claude CodeがMermaidダイアグラムを作成し、人間がチェックする（設計）
3. 合意が取れたらClaude CodeにXMLを生成してもらう（実装）

以下がMermaidダイアグラムのイメージです（最初の例とは別のもの）。スタイルに気を取られず、構成が合っているかに集中できるのでよかったです。

ダイアグラムを作成する際のルールを守らせる

ここがこのプロジェクトの肝になります。プロジェクトの構成は以下のようになっています。各ファイルに公式ガイドラインのルールやルールには記載されていない慣例を盛り込みました。

.
claude-drawio
├── .claude
│   ├── CLAUDE.md
│   └── skills
│       └── diagram-review
│           └── SKILL.md
└── docs
    ├── GUIDELINES.md
    ├── README.md
    ├── WORKFLOW.md
    ├── rules
    │   └── conventions.md
    └── styles
        ├── elements.md
        └── layout.md

1. GUIDELINES.md：公式ガイドライン

BTPのソリューションダイアグラムの場合、ガイドラインで使用する図形の形、色などが細かく決められています。ここに記載のスタイルをGUIDELINES.mdに取り込みました。

GUIDELINES.md（抜粋）

# SAP 公式 BTP Solution Diagram ガイドライン（要約）

このドキュメントは SAP 公式ガイドライン [SAP/btp-solution-diagrams](https://github.com/SAP/btp-solution-diagrams) の主要ルールを日本語で要約し、オフラインで参照できるようにしたもの。
...

### 色（Colors）

Horizon は SAP プロダクトの既定ビジュアルスタイル。"Its color balance helps to draw the user's attention to the essential information and functions."（配色バランスがユーザーの注意を本質的な情報と機能に向ける）

#### Primary Colors

| 用途 | Border | Fill |
|---|---|---|
| **SAP / BTP Area** | `#0070F2` | `#EBF8FF` |
| **Non-SAP Area** | `#475E75` | `#F5F6F7` |

| 用途 | 色 |
|---|---|
| **Text — Title** | `#1D2D3E` |
| **Text — Body** | `#556B82` |

...

2. rules/conventions.md: ダイアグラムとしての「慣例」

公式ガイドラインにはスタイルに関する定めはあるものの、コンポーネントをどのように配置するかについての取り決めはありません。様々なダイアグラムを見ていると「慣例」のようなものはありますが、明文化はされていない。
そこで、Claude Codeに作成してもらったダイアグラムをレビューして「違うな」と思ったもの（人間は知っているがClaudeは知らないこと）をrules/conventions.mdに追加していきました。このファイルはClaude CodeがMermaidダイアグラムを作成する際に参照します。

例：

• End User → Application Clients は常にセットで配置する（縦並び）
• SAP Cloud Identity Services は Subaccount の下に配置する
• BTP Subaccount からオンプレミスまたは Private Cloud システムへ接続する場合は、Destination Service → Connectivity Service → Cloud Connectorをセットで配置する

rules/conventions.md（抜粋）

# ダイアグラム設計規約

ダイアグラムの構成要素をどう組み合わせるか、どう配置するか、ラベルや言語をどうするかといった**設計上の規約**を定義する。Mermaid（論理構造）の段階から適用する。

...
---

## 1. 言語

特に指示がない限り、ダイアグラム上の要素名は**全て英語**とする。

---

## 2. 矢印ラベル

矢印にラベルは**原則つけない**。以下のように特別な意味を持つ関係のみラベルを設定する:

| ラベル | 用途 |
|---|---|
| `trust` | Subaccount ↔ Cloud Identity Services 間の信頼関係 |
| `authenticate` | 認証フロー |
| `delegates auth` | 認証委譲（CIS ↔ 3rd-party IdP） |

...

3. styles: SAPのパーツを扱う際のポイント

SAPのパーツを扱う際のポイントには以下のようなものがあります。これらのルールについては、styles配置下のlayout.mdおよびelements.mdに記載しました。

矩形、線、テキスト

これらは標準の矩形や線、テキストへのスタイルの指定で作成できます。スタイルは「ガイドライン」を参照します。

サービスアイコン

draw.io上でアイコンを右クリック>Edit Styleをクリックすると、アイコンに適用されているスタイルを確認できます。最後のSAPIcon=<サービス名>がサービスによって変わるので、ここを指定することで任意のサービスアイコンを作成可能です（サービス名は事前に確認が必要）。

ジェネリックアイコン

サービス以外のジェネリックアイコン（以下）は、Edit Styleで確認するとbase64 エンコードされた SVGが指定されていました。1アイコンあたり数KBになるため、Claude Codeで扱おうとするとトークン消費・応答時間が膨れます。したがって、ジェネリックアイコンはプレースホルダーのみ作成してもらい、人があとで配置する方針としました。

レビュースキル

Claude Codeにはスキルを使い、生成されたXMLの品質チェックを2段階で自動実行するようにしました。スキルはdiagram-reviewで定義しています。

Phase 1: 構造レビュー（XML生成直後）

XMLが生成された直後に自動で実行されます。Mermaidダイアグラムに定義した全ノード・エッジがXMLに存在するか、conventions.mdやstyles/のルールに沿っているかをチェックし、問題があれば報告してくれます。

Phase 2: ビジュアルレビュー（draw.ioに貼り付けた後）

人間がdraw.ioにXMLを貼り付けてスクリーンショットを共有すると、画像を見てラベルのはみ出しや矢印の折れ曲がりなどを確認します。XMLだけでは気づけない見た目の問題を拾ってくれるので、修正の往復が減ることが期待できます。

使用の流れ

1. Claude Codeにプロンプトを与える

以下のプロンプトを作成します。このあと、Claude Code側から確認事項を聞いてくるので、それに答えます（Claude Codeが事前知識をもとに質問してきます）。

新しいダイアグラムを作成します。一緒に必要なコンポーネントを洗い出してください
※これまで作成したダイアグラムは参照せず、新規のつもりで作成してください

シナリオ：
Build Process Automationを使った購買依頼承認シナリオ。
ユーザはBuild Work Zoneからログインし、UI5アプリから申請を行う。
申請を受けてワークフローが起動し、承認完了するとS/4HANAへ購買発注を登録する。

2. 作成されたMermaidダイアグラムを確認

作成されたMermaidダイアグラムを確認します。構成やラベルで直して欲しい点があれば依頼します。

3. 作成されたXMLをdraw.ioに貼り付けて確認

XMLが出力されるまでにはかなり時間がかかるので、気長に待ちます。生成されたダイアグラムは以下です。

4. 人間が修正

人間は以下を修正します。

• ジェネリックアイコン用のプレースホルダーにアイコンを配置
• 細かい位置の調整

最終的な成果物は以下のようになります。

感想

Claude Codeにソリューションダイアグラムを描いてもらった場合、手で描くよりも時間がかかります（ステップが多い、座標の計算に時間がかかる）。良い点としては、自分では見過ごしがちな公式のルールをしっかり踏襲してくれるので、何度作っても「ちゃんとしたダイアグラムに見える」ことがあります。
さらに、気になった点があればドキュメントに反映するようにClaude Codeに依頼すれば次回からそれも考慮して作成してくれるので、どんどん精度が上がっていきます。これが、「育てるの楽しい！」につながっています。
この記事の冒頭で「試行錯誤の記録を残す」と書きましたが、振り返ってみると試行錯誤の大半は「Claudeに何を伝えれば意図通りのダイアグラムになるか」を言語化する作業でした。その言語化の積み重ねがドキュメントとして残り、次のダイアグラムに活きる。人間側の理解も一緒に育っていく感覚があります。