scaffoldizr

Structurizr ワークスペース - Scaffoldizr で作成

このスキルを使用すると、Scaffoldizr CLI tool で生成された Structurizr ワークスペースをエージェントが生成し、操作できるようになります。

このスキルを使用するタイミング

• ユーザーが指定された Structurizr ワークスペース内の要素を作成または更新する必要がある場合。
• ユーザーがアーキテクチャ図を作成する必要がある場合（C4 モデルを活用）。
• ユーザーが既存の Structurizr ワークスペースを検証する必要がある場合。

一般的な手順

• ルートフォルダーで ./architecture フォルダーを探します。そのフォルダーがない場合は、Scaffoldizr を使用して作成することを提案し、次を実行します。

  scfz --dest <root_folder> \
    --workspaceName "<name>" \
    --workspaceDescription "<description>" \
    --workspaceScope "softwaresystem" \
    --systemName "<system name>" \
    --systemDescription "<system description>" \
    --authorName "<author name>" \
    --authorEmail "<author email>" \
    --shouldIncludeTheme "false"
  

  Scaffoldizr によって、関連ファイル一式を含む ./architecture フォルダーが作成されます。

注：scfz コマンドが使用できない場合、Scaffoldizr CLI tool がインストールされていません。現在の環境に適したインストールスクリプトを実行します。

• macOS / Linux — ターミナルで実行します。

  curl -s https://formulamonks.github.io/scaffoldizr/assets/install.sh | sh
  

• Windows — PowerShell で実行します。

  irm https://formulamonks.github.io/scaffoldizr/assets/install.ps1 | iex
  

詳しくは、インストール手順の全文を参照してください。

非対話型 CLI の使用方法（AI エージェントモード）

Scaffoldizr は、ジェネレーターをサブコマンドとして指定し、すべてのプロンプトへの回答を CLI フラグとして渡すことで、非対話型の実行に対応します。AI エージェントにはこの方法を推奨します — 対話型プロンプトを完全に回避できます。

サブコマンドの指定

workspace.dsl がすでに存在する場合は、ジェネレーターのサブコマンドを指定してメインメニューを回避します。

scfz <generator> [--flag "value"]

ジェネレーター名はケバブケースです：external-system、software-system など。

引数の指定

すべてのプロンプトの質問には、--parameter "value" または --parameter=value 形式の CLI フラグで回答できます。

要素ジェネレーターのリファレンス

ジェネレーター	主なフラグ
system	--systemName、--systemDescription、--archetype
container	--systemName（親）、--elementName、--containerDescription、--containerType、--containerTechnology
component	--elementName、--componentDescription、--componentTechnology
person	--elementName、--personDescription
external-system	--elementName、--extSystemDescription
view	--viewType、--viewName、--viewDescription、--dynamicScope、--systemName、--containerName、--step-N
constant	--constantName、--constantValue
archetype	--archetypeName、--archetypeBaseType、--archetypeDescription（任意）、--archetypeTechnology（任意）、--archetypeTags（任意）
theme	--themeAction "Add themes" --additionalThemes "<url1>,<url2>"

--viewType フラグには、landscape、deployment、dynamic を指定できます。その他のビュータイプ（systemContext、container、component）を使用する場合は、ビューのリファレンスの手順に従って DSL ファイルを手動で作成してください。

• 関連するドキュメントファイルはすべて ./architecture フォルダーに格納されています。
• 主なエントリーポイントは ./architecture/workspace.dsl ファイルです。
• ./architecture/workspace.json は workspace.dsl から生成されるコンパイル済み出力です。直接読み取ったり変更したりしないでください — Structurizr の次回実行時に上書きされます。再生成するには、./architecture/scripts/export.sh（Windows の場合は export.ps1）を実行します。

フォルダーの内容

architecture フォルダーには、次の構成が含まれています。

• ./architecture/archetypes：ほかの要素のベースラインまたは基盤となる要素です。再利用可能な関係パターン（例：1_https_relationship.dsl）が含まれています。
• ./architecture/containers/<system name>：ソフトウェアシステムのコンテナー定義です。各ソフトウェアシステムは個別のフォルダーに格納されています。
• ./architecture/components/<system name>/<container name>：ソフトウェアシステムのコンポーネント定義です。各ソフトウェアシステムと各コンテナーは、それぞれ個別のフォルダーに格納されています。
• ./architecture/decisions：主要なアーキテクチャ上の決定を記録したアーキテクチャ決定記録（ADR）です。
• ./architecture/docs：ワークスペース内で参照されるドキュメントファイルです。
• ./architecture/environments：デプロイメントビューの要素を含むフォルダーです。デプロイメント図の作成と表示に使用されます。
• ./architecture/relationships：システム内のさまざまな要素の関係定義です。
• ./architecture/systems：システム定義です。このフォルダーには、人物要素を参照する _people.dsl と、外部システム（実際の図のスコープ外にあるシステム）を参照する _external.dsl も含まれています。
• ./architecture/views：システムコンテキストビューを含む、図をレンダリングするビュー定義です。

図の関係

• Structurizr DSL 言語には !include ディレクティブがあり、ほかのファイルやフォルダーを参照できます。参照にファイル拡張子（例：file.dsl）が含まれている場合、そのパスにあるファイルがインクルードされます。拡張子が含まれていない場合、そのフォルダー内のすべてのファイルがインクルードされます。

ワークスペースのスコープ

• ワークスペースのスコープによって、作成できる要素が異なります。ワークスペースのスコープは softwaresystem または landscape に設定できます。

  1. どちらの場合も、archetype、constant、view、person、external system、relationship を作成できます。
  2. softwaresystem の場合、手順 1 に記載した要素に加えて、container と component のみを作成できます。
  3. landscape の場合、手順 1 に記載した要素に加えて、system のみを作成できます。

• 現在のワークスペースのスコープは、./architecture/workspace.dsl ファイルの workspace ブロックを確認してください。例：

workspace {
    ...
    configuration {
        scope softwaresystem  // <-- Here is where the scope is defined
    }
    ...
}

• 提案する操作がこのルールに抵触する場合は、必ずユーザーに知らせてください。

ワークスペース内に新しい要素を作成する

⚠️ 重要な注意 要素名はワークスペース内で一意である必要があります。新しい要素を作成する前に、同じ名前の要素がすでに存在するか必ず確認してください。存在する場合は、別の名前をユーザーに提案してください。

アーキタイプ

アーキタイプのドキュメントを参照してください。

定数

定数のドキュメントを参照してください。

ソフトウェアシステム

ソフトウェアシステムのドキュメントを参照してください。

外部システム

外部システムのドキュメントを参照してください。

コンテナー

コンテナーのドキュメントを参照してください。

コンポーネント

コンポーネントのドキュメントを参照してください。

関係

関係のドキュメントを参照してください。

ビュー

ビューを参照してください。

テーマ

theme ジェネレーターを使用して、ワークスペースのテーマを追加、削除、または一覧表示します。theme ジェネレーターは、Landscape と SoftwareSystem の両方のスコープで使用できます。

scfz theme \
  --themeAction "Add themes" \
  --additionalThemes "https://formulamonks.github.io/scaffoldizr/assets/scaffoldizr-shapes.json"

• --themeAction：「テーマを追加」｜「テーマを削除」｜「テーマを一覧表示」
• --additionalThemes：追加するテーマ URL（カンマ区切り）
• カラーテーマ（Blue、Red、Green、Yellow）は相互に排他的です。新しい色を選択すると、既存の色が置き換えられます。

Structurizr CLI コマンドを使用してワークスペースを操作する

CLI コマンドのドキュメントを参照してください。

---

ビルドプロセス

• ./architecture/workspace.dsl が唯一の信頼できる情報源です。アーキテクチャの変更はすべて .dsl ファイルに加えてください。workspace.json は変更しないでください。
• ./architecture/workspace.json はコンパイル済みの成果物です。Structurizr は実行のたびにこのファイルを上書きします。⚠️ ./architecture/workspace.json を直接読み取ったり変更したりしないでください ⚠️。手動で編集しても、何の通知もなく失われます。
• DSL ソースから workspace.json を再生成するには、エクスポートスクリプトを実行してください。
  • Linux/macOS：./architecture/scripts/export.sh
  • Windows：./architecture/scripts/export.ps1
• ./architecture/scripts/run.sh（または run.ps1）を使用して Structurizr Lite を起動し、http://localhost:8080 で図を表示してください

エラーのトラブルシューティング

ユーザーから Structurizr ワークスペースの表示中にエラーが発生したと報告があった場合は、まず Structurizr CLI で報告されたエラーを検証できるか確認してください。詳しくはこちら。先に進む前に、ツールから報告された問題をすべて解決してください。