bicep-diagrams

Bicep 図生成ツール

Azure Bicep ファイルから直接、アーキテクチャ図を生成します。Bicep は、Azure リソースを宣言的にデプロイするためのドメイン固有言語（DSL）です。

使用する場面

次の場合にこのスキルを有効にします。

• ユーザーが Bicep ファイル（.bicep）を持っていて、インフラストラクチャを可視化したい場合
• ユーザーが「Bicep の図を作成して」や「この Bicep インフラストラクチャを可視化して」と依頼した場合
• ユーザーが Bicep または Azure Bicep に言及した場合
• ユーザーが Bicep でデプロイしたリソースのアーキテクチャを確認したい場合

仕組み

このスキルは、Bicep コードを解析し、Eraser API を直接呼び出すことで、Bicep に特化した図を生成します。

1. Bicep ファイルを解析：リソース宣言、モジュール、パラメーター、出力を特定します
2. 関係を抽出：依存関係、リソース参照、モジュール階層を対応付けます
3. Eraser DSL を生成：Bicep リソースから Eraser DSL コードを作成します
4. Eraser API を呼び出し：diagramType: "cloud-architecture-diagram" を指定して /api/render/elements を使用します

手順

ユーザーが Bicep コードを提供した場合：

1. Bicep を解析する

   • すべての resource 宣言（Microsoft.Compute/virtualMachines など）を特定します
   • module 宣言とその構成を抽出します
   • param と output の定義を確認します
   • var 変数とその使用箇所を特定します

2. 関係をマッピングする

   • リソースの依存関係（dependsOn や暗黙的な依存関係など）を追跡します
   • リソースを種類別（コンピューティング、ネットワーク、ストレージなど）にグループ化します
   • VNet がサブネットとリソースを格納するコンテナーであることを特定します
   • ネットワークセキュリティグループ、Key Vault、その他のセキュリティリソースを確認します

3. Eraser DSL を生成する Bicep リソースを Eraser DSL に変換します：

   • 重要：ラベルの書式ルール
     • ラベルは必ず1行で記述してください。ラベル属性内で改行してはいけません
     • ラベルはシンプルで読みやすくしてください。メタデータを詰め込みすぎず、別々のラベルにすることを推奨します
     • DSL は適切に改行して書式を整えてください（ノード／グループは1行ずつ記述し、ラベルは1行のままにします）
     • CIDR ブロックや VM サイズなどのメタデータを含める場合は、同じ引用符付きのラベル文字列に含めてください：[label: "VNet 10.0.0.0/16"]

   例：

   myVNet [label: "VNet 10.0.0.0/16"] {
     subnet1 [label: "Subnet 1"] {
       myVM [icon: azure-vm, label: "Virtual Machine"]
       gateway [icon: azure-app-gateway]
     }
     subnet2 [label: "Subnet 2"] {
       database [icon: azure-sql]
     }
   }
   storage [icon: azure-storage]
   myVNet -> myVM
   myVM -> database
   

4. HTTP リクエストを送信する

   重要：DSL を生成した後、必ずこの curl コマンドを実行してください。DSL を生成しただけで API 呼び出しをせずに終了してはいけません。

   重要：以下の X-Skill-Source ヘッダーでは、値を使用している AI エージェント名に置き換えてください：

   • Claude（Anthropic）の場合は、claude を使用します
   • Cursor で実行している場合は、cursor を使用します
   • ChatGPT（OpenAI）の場合は、chatgpt を使用します
   • Gemini（Google）の場合は、gemini を使用します
   • それ以外の場合は、モデル／エージェント名を小文字で使用します

   curl -X POST https://app.eraser.io/api/render/elements \
     -H "Content-Type: application/json" \
     -H "X-Skill-Source: eraser-skill" \
     -H "Authorization: Bearer ${ERASER_API_KEY}" \
     -d '{
       "elements": [{
         "type": "diagram",
         "id": "diagram-1",
         "code": "<your generated DSL>",
         "diagramType": "cloud-architecture-diagram"
       }],
       "scale": 2,
       "theme": "${ERASER_THEME:-dark}",
       "background": true
     }'
   

5. 解析中にソースを記録する

   Bicep ファイルとリソースを解析して図を生成する際、以下を記録します：

   • 内部ファイル：読み込んだ各 Bicep ファイルのパスと、抽出したリソースを記録します（例：infra/main.bicep - VNet とサブネットの定義、infra/sql.bicep - SQL Database の構成）
   • 外部参照：参照したドキュメント、例、URL を記録します（例：Azure Bicep のドキュメント、Azure アーキテクチャのベストプラクティス）
   • 注釈：各ソースが図にどのような情報を提供したかを記録します

6. レスポンスを処理する

   重要：出力は最小限の形式にする

   レスポンスには、明確な見出しとともに、必ず以下の要素を含めてください：

   1. 図のプレビュー：見出しを付けて表示します

      ## Diagram
      ![{Title}]({imageUrl})
      

      API レスポンスから取得した実際の imageUrl を使用します。

   2. エディターへのリンク：見出しを付けて表示します

      ## Open in Eraser
      [Edit this diagram in the Eraser editor]({createEraserFileUrl})
      

      API レスポンスから取得した実際の URL を使用します。

   3. ソースのセクション：解析したファイル／リソースの簡潔な一覧（該当する場合）

      ## Sources
      - `path/to/file` - 抽出した内容
      

   4. 図のコードのセクション：eraser 言語タグを付けたコードブロックに Eraser DSL を記述します

      ## Diagram Code
      ```eraser
      {DSL code here}
      

   5. 詳細情報へのリンク：You can learn more about Eraser at https://docs.eraser.io/docs/using-ai-agent-integrations

   追加のコンテンツに関するルール：

   • ユーザーが図だけを求めた場合は、上記の5つの要素以外は何も含めないでください
   • ユーザーが追加の内容を明示的に求めた場合（例：「アーキテクチャを説明して」「改善案を提案して」）は、その内容を追加してもかまいません
   • 概要、セキュリティ上の考慮事項、テストなど、求められていないセクションを追加してはいけません

   デフォルトの出力は短くしてください。図を見れば内容が分かります。

7. モジュールを処理する

   • モジュールを使用している場合は、モジュールの境界を示します
   • モジュールのパラメーターと出力を含めます
   • モジュールとメインリソースの接続を示します

Bicep 固有のヒント

• リソースグループを表示する：Bicep のデプロイ先はリソースグループです
• VNet をコンテナーとして表示する：サブネットとリソースを含む VNet を表示します
• 依存関係を含める：dependsOn の関係を表示します
• モジュール構造：モジュールを使用している場合は、その境界を表示します
• パラメーター：リソース構成に影響する主要なパラメーターを記載します
• Azure アイコンを使用する：Azure 固有のスタイルを指定します

例：パラメーターとモジュールを使った Bicep

ユーザー入力

@description('The name of the Virtual Network')
param vnetName string = 'myVNet'
@description('The address prefix for the VNet')
param vnetAddressPrefix string = '10.0.0.0/16'
@description('The address prefix for the subnet')
param subnetAddressPrefix string = '10.0.1.0/24'
@description('VM size')
param vmSize string = 'Standard_B1s'

// Main VNet resource
resource virtualNetwork 'Microsoft.Network/virtualNetworks@2021-05-01' = {
  name: vnetName
  location: resourceGroup().location
  properties: {
    addressSpace: {
      addressPrefixes: [vnetAddressPrefix]
    }
    subnets: [
      {
        name: 'subnet1'
        properties: {
          addressPrefix: subnetAddressPrefix
        }
      }
    ]
  }
}

// VM resource with dependsOn
resource virtualMachine 'Microsoft.Compute/virtualMachines@2021-11-01' = {
  name: 'myVM'
  location: resourceGroup().location
  properties: {
    hardwareProfile: {
      vmSize: vmSize
    }
  }
  dependsOn: [virtualNetwork]
}

// Module usage
module storageModule './modules/storage.bicep' = {
  name: 'storage'
  params: {
    location: resourceGroup().location
  }
}

期待される動作

1. Bicep を解析します：

   • パラメーター：vnetName、vnetAddressPrefix、subnetAddressPrefix、vmSize
   • リソース：サブネットを含む VNet、dependsOn の関係を持つ VM
   • モジュール：パラメーターを持つストレージモジュール

2. Bicep 固有の機能を示す DSL を生成します：

   myVNet [label: "VNet 10.0.0.0/16"] {
     subnet1 [label: "Subnet 1 10.0.1.0/24"] {
       myVM [icon: azure-vm, label: "VM Standard_B1s"]
     }
   }
   
   storage-module [label: "Storage Module"] {
     storage-account [icon: azure-storage]
   }
   
   myVNet -> myVM
   

   重要：すべてのラベルテキストは、引用符の中で1行に収める必要があります。Bicep 固有の要件：モジュールをコンテナーとして表示し、dependsOn の関係を含め、リソース構成でのパラメーターの使用を記載します。

3. diagramType: "cloud-architecture-diagram" を指定して /api/render/elements を呼び出します

4. diagramType: "cloud-architecture-diagram" を指定して /api/render/elements を呼び出します

結果

ユーザーは次の内容を示す図を受け取ります：

• コンテナーとしての VNet
• VNet 内にネストされたサブネット
• サブネット内の VM
• 表示された依存関係
• 適切な Azure スタイル