mcpField
C
c4-structurizr

c4-structurizr

github.com/mercatorproj開発059 回インストール4 週間前に更新
リポジトリ

c4-structurizr について

c4-structurizr は、プロジェクトのコードやドキュメントを根拠に C4 アーキテクチャモデルを作成するスキルです。開発者向けに、スタイル付き PlantUML の 7 つのビュー、SVG の生成と検証を案内します。

主な機能

  1. 01アーキテクチャの根拠を調査
  2. 02必要に応じて AI ワークフローを分析
  3. 037 種類のアーキテクチャビューを選定
  4. 04スタイル付き C4-PlantUML ファイルを生成
  5. 05SVG 図を生成して検証

活用シーン

  1. 01プロジェクトのシステム構成を文書化
  2. 02図の内容をコードや設定まで追跡
  3. 03根拠に基づく AI ワークフロー経路を整理

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/mercatorproj/c4-structurizr --skill c4-structurizr

インストール後、Claude Code で/c4-structurizrを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

.gitignore
README.md
LICENSE
agents/
openai.yaml
assets/
c4-style.puml
assets/c4-plantuml/
C4_Container.puml
C4_Component.puml
C4_Deployment.puml
C4_Context.puml
C4.puml
C4_Dynamic.puml
C4_Sequence.puml
references/
ai-workflow-analysis.md
view-catalog.md
model-analysis.md
scripts/
render_c4.py

詳細

C4 Structurizr

対象となる1つのシステムについて、根拠に基づくC4アーキテクチャモデルを生成します。C4-PlantUMLファイルを7つ作成し、SVGにレンダリングして、レンダリングされたすべての図が空白ではなく、コードベースを根拠としていることを検証します。デフォルトのC4-PlantUMLスタイルは使用しないでください。

ワークフロー

  1. 対象プロジェクトを特定します。指定されたプロジェクトパスがあればそれを使用し、なければ現在のリポジトリから推定します。プロジェクトまたは対象システムが曖昧な場合は、作業を中止して簡潔な質問を1つ尋ねてください。

  2. references/model-analysis.mdを読みます。コード、設定、マニフェスト、インフラストラクチャファイル、テスト、既存のドキュメントから、人、ソフトウェアシステム、コンテナー、コンポーネント、外部システム、ストア、キュー、プロセス、デプロイメント、関係性を洗い出します。

  3. モデル、設定、依存関係、プロンプト、エージェント、ワークフロー、ランタイム実行エンジン、モデルアダプター、コンテキストストア、トレースストアにAIワークフローを示すものがあれば、references/ai-workflow-analysis.mdも読み、図を作成する前にAI関連の項目をすべて洗い出します。そのような証拠がなければ、AIに関する意味付けを追加しないでください。

  4. references/view-catalog.mdを読みます。ドメイン固有の動的フローとクリティカルパスを含む7つのビューを選びます。あるビューを裏付ける証拠がない場合は、捏造せずに作業を中止し、不足している証拠を報告してください。

  5. 図の作業ディレクトリを作成します。ユーザーが別の場所を指定しない限り、対象プロジェクトのdocs/architecture/structurizr/plantumlを使用します。assets/c4-style.pumlをそのディレクトリにコピーし、assets/c4-plantuml/を兄弟ディレクトリのdocs/architecture/tools/c4-plantumlにコピーします。対象のディレクトリ構成が異なる場合は、インクルードパスが有効になるようにし、アセットを配置した場所をユーザーに伝えてください。

  6. 簡潔で根拠に基づく名前を付けた.pumlファイルを7つ生成します。次の標準名を優先してください：system-landscape.puml、system-context.puml、container.puml、component.puml、dynamic-flow.puml、deployment.puml、critical-path.puml。明確さが向上する場合はドメイン固有のサフィックスを使用できます。AI駆動型システムでは、モデルを利用する経路にai-critical-path.pumlを使用できます。

  7. 次のコマンドでレンダリングします：

    python "<skill-directory>/scripts/render_c4.py" --source "<diagram-directory>"

    レイアウトを目視確認するためにPNGプレビューが必要な場合は、--previewを追加します。レンダラーがplantuml.jarを見つけられない場合は、--plantuml-jar "<path>"を追加します。

  8. 7つのSVGファイルがすべて存在し、空白ではなく、想定どおりの白い背景とアクセントカラーを使用し、テキストが判読できることを確認します。レイアウトが複雑な場合はプレビューを確認します。関係性、要素の種類、境界、クリティカルパスの順序を分析結果の一覧と照合します。AIシステムの場合、PlantUMLソースを読まなくても、ランタイム境界、エージェントとワークフローの区別、実行エンジン、モデルゲートウェイ、コンテキスト、トレース経路を視覚的に識別できることを確認します。

  9. 図のディレクトリ、7つの図の名前、レンダリング状況、主要なアーキテクチャ上の主張を裏付けるコードパスを報告します。未解決の証拠不足があれば明示的に報告します。

図のソースに関するルール

  • 各ファイルの先頭を @startuml <DiagramId> とし、末尾を @enduml にしてください。
  • C4-PlantUML のエントリーポイントを最初に1つ含め、その後に !include c4-style.puml を記述してください。
  • デフォルトのワークスペースでは、!include ../../tools/c4-plantuml/C4_Context.puml のようなインクルードパスを使用してください。
  • PlantUML は SVG および PNG のファイル名に @startuml の ID を使用するため、@startuml の ID を出力ファイル名に合わせてください。
  • すべてのビューで SHOW_PERSON_OUTLINE() と HIDE_STEREOTYPE() を使用してください。
  • 図のタイトルには left footer <b>... を使用してください。PlantUML の title は使用しないでください。
  • C4 の粒度に応じて、Person、System、System_Ext、Container、ContainerDb、Container_Ext、ContainerDb_Ext、Component、Deployment_Node を使用してください。
  • すべての Rel および RelIndex のリレーションシップに $tags="OfficialRelationship" を追加してください。
  • 人物は緑、内部要素は青、一般的な外部システムはグレー、境界は青の実線、リレーションシップは太い破線、背景は白にしてください。プロジェクト固有の意味を示すアクセントタグを追加してもかまいませんが、基本スタイルの値を弱めないでください。
  • 共有 AI タグは、根拠がある要素にのみ使用してください。対象となるタグは AIWorkflow、AIAgent、AIExecutor、AIContext、AITrace、AIBoundary、AIFlow、ModelCall、AIContextFlow、AITraceFlow です。各ビューで AI ワークフローの意味を一貫させ、図が色だけで意味を伝える状態にならないよう、要素名または説明に役割を記載してください。
  • 対象プロジェクトのドメイン用語と技術用語を使用してください。別のプロジェクト用に生成した図に、6S 固有のエンティティを含めないでください。

生成されたファイルを、その場限りの PlantUML スタイルに置き換えないでください。C4-PlantUML のマクロやスタイルの動作が想定と異なる場合は、ステージング済みの C4-PlantUML アセットを確認し、7つすべてを再生成する前に図を1つテストしてください。

コメント

Markdown 対応