Stats
Actions
Tags
From design-skills
Produces Structurizr DSL (.dsl) for C4 architecture diagrams (system context, container, and on explicit request component, dynamic, deployment, or system landscape views). Triggers when the user wants to draw, sketch, model, document, or visualize software architecture in the C4 tradition (Simon Brown), model microservices and queues at the right C4 level of abstraction, or work with Structurizr DSL. Output is Structurizr DSL ready to render with the user's preferred Structurizr tooling (online editor, local install, IDE plugin); default focus is system context and container levels, with component, dynamic, and deployment views only on explicit request or when complexity demands. Links ADRs via the !adrs directive when the project has them. Composes with the sequence-diagram skill (sequence diagrams are not C4 abstractions) and the design-doc skill (which has a C4 section that delegates here). Does NOT handle sequence diagrams, ER diagrams, flowcharts, class/UML diagrams, or non-architectural visualizations.
How this skill is triggered — by the user, by Claude, or both
Slash command
/design-skills:c4-diagramThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Produz diagramas de arquitetura no [C4 model](https://c4model.com/) do Simon Brown usando [Structurizr DSL](https://docs.structurizr.com/dsl/) como saída. Foco em **system context** e **container** views; outros níveis (component, dynamic, deployment) só sob pedido explícito.
Produz diagramas de arquitetura no C4 model do Simon Brown usando Structurizr DSL como saída. Foco em system context e container views; outros níveis (component, dynamic, deployment) só sob pedido explícito.
A saída é texto DSL, não imagem. A renderização fica com o usuário, na ferramenta Structurizr de preferência (editor online, instalação local, plugin de IDE). Não há script de render porque Structurizr requer JVM e a complexidade não compensa.
Validação e export via MCP, quando presente. Se a sessão tiver as ferramentas do Structurizr MCP server, a skill as usa para validar o DSL (o parser real do Structurizr) e, opcionalmente, exportar views para Mermaid/PlantUML. É detecção em runtime, não setup: a skill não prescreve como subir o servidor — isso é requisito documentado no README do repo. Sem o MCP, a entrega segue só DSL + editor online.
Antes de escrever DSL, alinhe seis coisas com o usuário (não invente nenhuma delas):
Escopo do diagrama:
systemContext + container.systemLandscape no nível superior, depois systemContext pra detalhar cada um.Se o usuário disse "modela nosso ecommerce" (ou similar) sem especificar, pergunte: "é um sistema único ou um conjunto de sistemas?" — afeta direto a escolha de view.
Nível alvo:
Software system em foco: qual é o sistema que vai estar no centro? O que está dentro do escopo do diagrama, o que é externo?
Pessoas: quem usa o sistema? Use roles/personas ("Operador", "Cliente B2B"), nunca nomes próprios.
Sistemas externos: com o que o sistema em foco se comunica? (Outros sistemas internos, SaaS, APIs externas.)
Containers (se for nível container): quais aplicações, serviços, data stores compõem o sistema? Tecnologias?
Microservices? — Se um time único é dono de tudo, modele como grupo de containers dentro de um software system. Se múltiplos times com fronteiras claras, cada serviço é um software system próprio (Conway's Law).
Monolito modular? — Se o sistema é um único deployável (uma container em deploy) com módulos internos de fronteira clara (bounded contexts, packages com ownership separado, módulos de domínio), há três representações C4 válidas — nenhuma é "a certa". A escolha depende do que você quer comunicar mais. Carregue references/modeling-patterns.md para o trade-off antes de escolher.
Queues/topics? — Modele como containers (são data stores). Ou, alternativa válida, omita e use "publishes events to {Topic} via Pub/Sub" na descrição da relação.
ADRs existentes? — Se o projeto já tem ADRs (típico se usaram a skill adr deste repo), aponte com !adrs ./decisions.
A skill explicitamente pergunta quando algo não está claro:
{{a definir}}.Não invente status codes, headers, hosts, ou tecnologias que o usuário não compartilhou. Diagrama com tecnologia inventada é diagrama errado, não diagrama incompleto.
Produza o .dsl na ordem workspace { model { ... } views { ... } }. Use a linguagem do usuário (PT/EN/ES) nos nomes e descrições; as keywords DSL são em inglês (são da linguagem).
Para começar do esqueleto, use o subset comum em DSL fundamentals abaixo. Para construções fora do comum (deployment, dynamic, archetypes complexos, scripts), carregue references/syntax.md. Para um workspace completo com archetypes, queues, ADRs e styles, carregue references/example.md.
(a) Validação autoritativa via Structurizr MCP — se disponível. Se a sessão tiver as ferramentas do Structurizr MCP server (tools cujo nome contém "Structurizr DSL" — Validate / Parse / Inspect), rode Validate Structurizr DSL contra o .dsl produzido e corrija o que ela apontar. É o parser real do Structurizr, não um check superficial. Identifique a tool pela função, não por um id fixo — o slug depende do nome que o usuário deu ao registrar o servidor.
Se as tools do MCP não estiverem presentes, não há validação mecânica nesta etapa: apoie-se no self-review (b) e lembre que o Structurizr é o source of truth no render. Como subir e registrar o servidor é decisão do usuário (ver README do repo) — a skill não prescreve setup.
(b) Self-review semantic (sempre). Os 5 itens abaixo são quick-check inline. O
full checklist (oficial do C4 + items específicos de DSL e composição com skills irmãs)
vive em references/checklist.md — sempre carregue antes de entregar. Quick-check
(pontos que nem o MCP nem o self-review mecânico pegam):
Entregue o DSL em bloco fenced (```dsl ou ```text):
Aqui está o workspace:
```dsl
<workspace>
```
Para renderizar, salve como `workspace.dsl` e abra com sua ferramenta Structurizr de preferência (editor online em https://structurizr.com/dsl, instalação local via Docker, plugin de IDE, ou exportador para outras notações).
Export embedável — se o MCP estiver disponível. Quando as tools Export view to Mermaid / Export view to PlantUML estiverem presentes, ofereça também a versão exportada de uma view-chave (system context ou container). Mermaid embeda inline em Markdown/GitHub — útil quando o .dsl vai alimentar um design-doc deste repo. O DSL continua sendo a fonte; o export é conveniência, não substituto. Sem o MCP, o mesmo export sai manualmente pelo editor online (https://structurizr.com/dsl) ou pela ferramenta Structurizr local do usuário — só não é automático na sessão.
Adapte o lead-in à linguagem do usuário. Não prescreva uma ferramenta específica de render — o usuário decide.
Audiência: todo mundo, técnico e não-técnico.
O que tem: o software system em foco no centro; pessoas (atores/roles) que interagem; sistemas externos diretamente conectados.
O que NÃO tem: containers internos, protocolos, schemas, frameworks.
Quando pular: nunca — sempre vale ter um system context para qualquer software system documentado.
Audiência: pessoas técnicas (devs, arquitetos, ops, suporte).
O que tem: containers do sistema (apps, serviços, data stores, queues), tecnologia explícita em cada um, comunicação entre containers com protocolo declarado, pessoas e sistemas externos diretamente conectados aos containers.
O que NÃO tem: componentes internos dos containers, deploy topology (clusters, load balancers), código.
Cuidado clássico: container aqui não é Docker container. É uma unidade executável ou de armazenamento (web app, mobile app, microservice, banco de dados, bucket S3). Pode até rodar dentro de um Docker container, mas a abstração é outra.
sequence-diagram deste repo pra interações temporais.Para os três, carregue references/syntax.md quando precisar.
workspace "Optional Name" "Optional description" {
!identifiers hierarchical
!adrs ./decisions
model {
u = person "Role description"
ext = softwareSystem "External System" "..." "External"
ss = softwareSystem "Our System" {
api = container "API" "Handles requests" "Spring Boot"
db = container "Database" "Stores orders" "PostgreSQL" "Database"
}
u -> ss.api "Places orders via" "HTTPS/JSON"
ss.api -> ss.db "Reads from and writes to" "JDBC/SQL"
ss -> ext "Notifies of new orders" "HTTPS/JSON"
}
views {
systemContext ss "SystemContext" {
include *
autoLayout lr
}
container ss "Containers" {
include *
autoLayout
}
styles {
element "Person" {
shape Person
background #08427b
color #ffffff
}
element "Software System" {
background #1168bd
color #ffffff
}
element "External" {
background #999999
color #ffffff
}
element "Container" {
background #438dd5
color #ffffff
}
element "Database" {
shape Cylinder
}
}
theme default
}
}
Regras de sintaxe que mais mordem:
{ na mesma linha do keyword; } em linha própria.Para o resto (archetypes, deployment, dynamic, includes, scripts), carregue references/syntax.md.
Padrões que exigem decisão de modelagem (não cabem na lista plana) vivem em
references/modeling-patterns.md — carregue-o quando o usuário mencionar qualquer um.
Resumo de escolha:
Use role ou persona, não nomes próprios. "Cliente B2B", "Analista de risco", "SRE de plantão". Pessoas sobreviven a turnover, nomes próprios não.
Toda container tem tecnologia declarada ("Spring Boot", "Cloud Run", "PostgreSQL", "S3 bucket"). Toda relação container-a-container declara protocolo ("HTTPS/JSON", "gRPC", "JDBC", "Pub/Sub"). Sem isso, o diagrama vira bonito mas inútil pra implementador.
Verbos concretos. Nunca "Uses" ou "Calls" soltos. Exemplos bons:
"publishes order events to""reads cart contents from""queries customer profile from""redirects authentication requests to"Exemplos ruins: "Uses", "Talks to", "Connects".
Default ligado. Quando você escreve u -> ss.api "Uses", o DSL cria automaticamente u -> ss "Uses" (a relação no nível de software system). Isso mantém o system context view limpo sem você ter que duplicar relações em cada nível.
Desligue (!impliedRelationships false) só se quiser controle manual — caso raro.
Ubiquitous language sobre tipos C4. Útil quando o workspace tem repetição (múltiplos serverlessApp com technology "Cloud Run" e tag "Application").
O bloco archetypes fica dentro de model (não é top-level do workspace), antes dos elementos que o usam. Aplicar um relationship archetype embute o nome na seta: --nome->.
model {
archetypes {
serverlessApp = container {
technology "Cloud Run"
tag "Application"
}
documentStore = container {
technology "Firestore"
tag "Database"
}
https = -> {
technology "HTTPS/JSON"
}
}
api = serverlessApp "Admin API"
db = documentStore "Deliveries Store"
api --https-> db "Reads delivery history from"
}
Não force pra workspace pequeno — vira overhead. Vale quando há ≥ 3 elementos do mesmo tipo.
!adrs)workspace {
!adrs ./decisions // diretório com ADRs em formato adr-tools
model { ... }
}
Default: usa AdrToolsDecisionImporter — mesmo formato que a skill adr deste repo gera (NNNN-kebab-slug.md). Então !adrs ./decisions vai puxar todos os ADRs gerados pela skill irmã sem ajuste.
Outros formatos suportados (segundo arg):
!adrs ./decisions adrtools // explicit (default)
!adrs ./decisions madr // formato MADR
!adrs ./decisions log4brains
!adrs pode aparecer no nível de workspace, software system, ou container — escolha o escopo apropriado.
design-doc skill (mesmo repo): a seção "Diagramas" do design-doc tem subseção C4 com convenção de embed (imagem + link pro fonte). O fonte é o .dsl produzido aqui. Workflow típico: gerar .dsl aqui → renderizar no Structurizr → exportar PNG → embed no design-doc com link de volta pro .dsl. Com o Structurizr MCP presente, o passo renderizar → exportar PNG vira um Export view to Mermaid direto na sessão — o Mermaid embeda inline no design-doc sem round-trip manual.adr skill (mesmo repo): !adrs puxa exatamente os ADRs que a skill adr gera (formato compatível). Não precisa converter nada.sequence-diagram skill (mesmo repo): sequência não é C4. C4 tem dynamic view, mas pra interação temporal (chamadas API, ordem de eventos), sequence-diagram produz output mais legível e embedável inline (Mermaid renderiza direto no Markdown). Não use dynamic view só pra ter algo no C4 — delegue."Uses" solto. Sempre verbo + substantivo concreto.sequence-diagram skill.| Quando | Carregue | Por quê |
|---|---|---|
| Construções fora do subset comum | references/syntax.md | DSL completo (component, deployment, dynamic, archetypes complexos, themes, scripts) |
| Usuário menciona microservices, monolito modular, event-driven ou queues/topics | references/modeling-patterns.md | Trade-off completo + DSL dos padrões que exigem decisão de modelagem |
| Usuário pediu "me mostra um exemplo" | references/example.md | Webhooks Service workspace completo (archetypes, queues, ADRs, styles) |
| Sempre antes do Step 4 | references/checklist.md | Self-review |
Os quatro são opcionais durante a composição; o checklist não é opcional antes de entregar.
npx claudepluginhub cassiobotaro/skills --plugin structurizrCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.