跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

setup-architecture-as-code

Establish architecture-as-code practice using C4 modeling and Structurizr DSL. Use after bootstrap-project, when establishing architecture documentation, or when migrating from diagram-based to code-based architecture.

jrjsmrtn · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add jrjsmrtn/project-orchestration-skills --skill setup-architecture-as-code

技能说明


name: setup-architecture-as-code description: Establish architecture-as-code practice using C4 modeling and Structurizr DSL. Use after bootstrap-project, when establishing architecture documentation, or when migrating from diagram-based to code-based architecture. metadata: author: "Georges Martin jrjsmrtn@gmail.com" version: "0.1.34" license: MIT

Setup Architecture-as-Code

Establish architecture-as-code practice using C4 modeling and Structurizr DSL.

When to Use

  • After running bootstrap-project skill
  • When establishing architecture documentation for a project
  • When migrating from diagram-based to code-based architecture documentation
  • When you need version-controlled, validated architecture models

What is Architecture-as-Code?

Architecture-as-Code treats architecture documentation like source code:

Traditional DiagramsArchitecture-as-Code
Draw in GUI toolsDefine in text/DSL
Manual updatesAutomated validation
Binary files (PNG, VSDX)Text files (version control friendly)
Diagrams diverge from realitySingle source of truth
Hard to review changesPR-reviewable changes
No validationSyntax + semantic validation

Implementation Stack:

  • Modeling Approach: C4 Model (Context, Container, Component, Code)
  • Definition Language: Structurizr DSL
  • Validation & Inspection: structurizr/structurizr (consolidated image, replaces deprecated structurizr/cli and structurizr/lite)
  • Visualization: structurizr/structurizr local subcommand or Structurizr Cloud

Required Inputs

  1. Project/System name
  2. System description (1-2 sentences)
  3. Key users/personas (who interacts with the system)
  4. External systems (what the system integrates with)
  5. Main containers (applications, databases, services)
  6. Technology stack (languages, frameworks, databases)

C4 Model Overview

The C4 model provides four levels of abstraction (zoom levels):

LevelNamePurposeAudience
1System ContextSystem in its environmentEveryone
2ContainerDeployable unitsTechnical staff
3ComponentInternal structureDevelopers
4CodeClass/module levelDevelopers (often generated)

Key Principle: Start with Level 1-2, add Level 3 only when needed. Level 4 is usually generated from code.

Workflow

Step 1: Create Directory Structure

mkdir -p architecture/shared
mkdir -p docs/architecture    # Structurizr-specific docs (h2-first, numbered files)
# Symlink so !adrs and !docs directives can reach docs/ from architecture/
ln -s ../docs architecture/docs

The symlink is required because Structurizr restricts !adrs and !docs paths to the same directory or subdirectories of the DSL file — it cannot traverse parent directories.

Why docs/architecture/ and not docs/explanation/? Structurizr silently strips h1 headings (it auto-generates h1 from the element name). Diátaxis docs use h1 as their title, so pointing !docs at a Diátaxis directory would lose those titles. Keep Structurizr docs in a dedicated directory with h2-first files.

Step 2: Create Workspace File

Create architecture/workspace.dsl:

workspace "[Project Name]" "[Brief description]" {

    !identifiers hierarchical
    !adrs docs/adr
    !docs docs/architecture

    model {
        # ===== USERS/ACTORS =====
        user = person "User" "Primary user of the system" "User"

        # Add other personas as needed:
        # admin = person "Administrator" "System administrator" "Admin"
        # developer = person "Developer" "API consumer" "Developer"

        # ===== EXTERNAL SYSTEMS =====
        # externalSystem = softwareSystem "External System" "Description" "External"

        # ===== THE SYSTEM =====
        system = softwareSystem "[System Name]" "[System description]" {

            # ----- CONTAINERS -----

            # Web Application (if applicable)
            webApp = container "Web Application" "Provides user interface" "[Framework]" "Web"

            # API Service (if applicable)
            api = container "API Service" "Provides REST/GraphQL API" "[Framework]" "API"

            # Database
            database = container "Database" "Stores application data" "[Database Technology]" "Database"

            # Background Workers (if applicable)
            # worker = container "Background Worker" "Processes async tasks" "[Technology]" "Worker"

            # ----- COMPONENTS (for main container) -----
            # Uncomment and customize for your architecture:

            # api {
            #     authComponent = component "Authentication" "Handles user auth" "[Module]"
            #     businessComponent = component "Business Logic" "Core domain logic" "[Module]"
            #     dataComponent = component "Data Access" "Database operations" "[Module]"
            # }
        }

        # ===== RELATIONSHIPS =====

        # User interactions
        user -> system "Uses"
        user -> system.webApp "Interacts with" "HTTPS"

        # Internal relationships
        system.webApp -> system.api "Makes API calls to" "HTTP/JSON"
        system.api -> system.database "Reads from and writes to" "SQL"

        # External system relationships (if any)
        # system.api -> externalSystem "Integrates with" "HTTPS"
    }

    views {
        # ===== SYSTEM CONTEXT VIEW =====
        systemContext system "SystemContext" {
            include *
            autoLayout
            description "System Context diagram showing [System Name] and its environment"
        }

        # ===== CONTAINER VIEW =====
        container system "Containers" {
            include *
            autoLayout
            description "Container diagram showing the main deployable units"
        }

        # ===== COMPONENT VIEW (optional) =====
        # Uncomment when you have c
阅读完整来源 ↗