From design-skills
Use whenever the user wants to create or scaffold a design doc, TDD, RFC (project-level proposal), "documento de design", "documento técnico de projeto", "especificação técnica", "proposta técnica", or document a non-trivial multi-component system before implementation. Produces Markdown following a flat canon of 14 optional top-level sections (headers, overview, scope/context, goals/non-goals, solution, diagrams, APIs and payloads, screens, trade-offs, alternatives, cross-cutting concerns, testability/observability, deployment plan, open questions) — each independently optional with its own inclusion trigger. Delegates diagrams to sibling skills when available: c4-diagram (Structurizr DSL) and sequence-diagram (Mermaid). Includes collapsible payload tables for HTTP endpoints. Do NOT use for README files, API reference docs without design decisions behind them, postmortems, or single-decision ADRs like "documenta a decisão de X em vez de Y" — those are handled by the adr skill.
How this skill is triggered — by the user, by Claude, or both
Slash command
/design-skills:design-docThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Produz design docs em Markdown para projetos/sistemas de software, seguindo um cânon de 14 seções **opcionais** que o autor escolhe conforme a complexidade da decisão e gatilhos por seção. Foco em comunicar decisões e compensações, não em narrar implementação.
Produz design docs em Markdown para projetos/sistemas de software, seguindo um cânon de 14 seções opcionais que o autor escolhe conforme a complexidade da decisão e gatilhos por seção. Foco em comunicar decisões e compensações, não em narrar implementação.
Antes de escrever, alinhe três coisas com o usuário (1-2 perguntas, não um questionário):
Se o pedido for vago ("escreve um design doc"), faça uma pergunta: qual é o projeto e qual a complexidade aproximada? Não invente o escopo.
Trabalhe seção por seção. Para cada uma:
{{a definir}}) ou pergunte.Se quiser começar do esqueleto, carregue references/template.md. Se quiser ver um exemplo completo, carregue references/example.md (caso "Recomendador de reposição de estoque").
Antes de entregar, dois passos:
(a) Validação mecânica. Salve o draft do doc num arquivo temporário e rode:
python3 scripts/validate.py < draft.md
Erros (exit ≠ 0): tokens de implementação vazados (kubectl, decoradores, comandos), seções declaradas mas vazias. Avisos (exit 0, corrija antes de entregar): placeholders {{...}} não resolvidos, "Alternativas Consideradas" sem "Não fazer nada", <details> HTTP sem as 6 linhas canônicas.
(b) Self-review semantic. Carregue references/checklist.md e leia o doc com olhos críticos — como se um colega tivesse acabado de te entregar pra revisão. Pontos críticos:
Entregue como um único documento Markdown. Se a saída for longa, ofereça mover para um arquivo (docs/design/{{slug}}.md na convenção do projeto do usuário).
Ordem canônica (mas o autor decide quais usar). Cada seção é independentemente opcional — não há mais guarda-chuvas: se "APIs e Payloads" não se aplica, apague; se "Telas" não se aplica, apague. A heurística P/M/G no Step 1 é um atalho; a linha Quando incluir de cada seção é o gatilho fino.
<details> colapsadoIdentificam o documento. Use uma tabela com: ID (DD-AAAA-NNN), Estado (rascunho · em revisão · proposto · aprovado · rejeitado), Autoras, Revisoras, Criado em, Última atualização, Tags.
Quando incluir: sempre.
Dicas:
Texto breve, 1–2 parágrafos, alto nível. O que esperar lendo o documento.
Quando incluir: sempre.
Dicas:
Cenário no qual o sistema está inserido, motivadores, contexto técnico (tecnologia atual, dívidas), premissas. Plano de fundo.
Quando incluir: Médio+, ou quando o leitor precisa de background pra entender a decisão.
Dicas:
Duas listas curtas. Objetivos = requisitos a alcançar. Fora de escopo = exclusões explícitas.
Quando incluir: Médio+, ou quando há risco de o escopo ser interpretado de forma divergente.
Dicas:
A abordagem proposta em prosa: 1–2 parágrafos de visão geral, depois parágrafos de detalhe textual sobre os componentes principais e o fluxo de dados. Não embuta diagramas, payloads ou screenshots aqui — cada um tem sua própria seção.
Quando incluir: sempre.
Dicas:
Visualizações que complementam a prosa da Solução. Tipicamente dois tipos:
Quando incluir: Médio+, ou quando há mais de dois componentes interagindo, ou quando o fluxo temporal/cross-system não cabe em prosa.
Dicas:
Use C4 nível Containers para comunicar arquitetura de alto nível sem entrar em detalhes de implementação.
Quando a skill c4-diagram deste repo estiver disponível, delegue a produção do C4 a ela. Ela produz Structurizr DSL pronto pra renderizar e mantém convenções consistentes (technology em todo container, labels não-genéricos, microservices como grupo, queues como containers, link de ADRs via !adrs). Você cola o .dsl produzido como fonte e embarca a imagem renderizada.
Convenção de embed:
**Diagrama: {{título descritivo}}**

Fonte: [Structurizr DSL](./diagrams/workspace.dsl)
Se a skill c4-diagram não estiver disponível, qualquer ferramenta serve (PlantUML, Mermaid C4, draw.io). A regra opinionada é só o embed: imagem renderizada + link pro fonte editável.
Quando o doc precisar mostrar a ordem temporal de interações entre componentes (chamadas API, processos batch com dependências), delegue à skill sequence-diagram deste repo. Ela produz Mermaid sequenceDiagram, que renderiza inline direto no Markdown — e, com o Mermaid MCP na sessão, vem validado e com link de preview no mermaid.live.
Convenção de embed — aqui o fonte é o próprio bloco, sem imagem nem arquivo separado:
**Diagrama: {{título}}**
```mermaid
{{source}}
```
Se o MCP retornou link de preview, adicione Preview: {{mermaid.live URL}} logo abaixo do bloco — útil pra quem lê fora de um renderizador de Markdown.
Contratos HTTP relevantes pra decisão. Para cada endpoint, um bloco <details> colapsado com tabela de 6 linhas:
<details>
<summary><strong>METHOD /path</strong> — descrição curta</summary>
| Campo | Valor |
| --- | --- |
| Endpoint | `/path/{param}` |
| Verbo HTTP | `METHOD` |
| Headers | `Authorization: Bearer ...`<br>`Content-Type: application/json` |
| Query string | `?param=valor` |
| Payload sucesso | `200 OK`<br>`{"id":"..."}` |
| Payload erro | `4xx` `{"error":"..."}`<br>`5xx` `{"error":"..."}` |
</details>
Quando incluir: só se há endpoint novo ou alterado relevante pra decisão. Não duplique a documentação completa da API.
Dicas:
Wireframes, mockups ou screenshots que ilustram o fluxo de UI proposto. Liste também os estados relevantes de cada tela (vazio, carregando, erro, sucesso) e as transições entre telas.
Quando incluir: só se há frontend ou interface com humano no fluxo.
Convenção de embed:
**Tela: {{nome da tela}}** — {{contexto/quando aparece}}

Fonte: [Editar no {{ferramenta}}]({{link da fonte editável}})
Estados:
- **Vazio**: {{o que aparece quando não há dados}}
- **Carregando**: {{spinner, skeleton, etc.}}
- **Erro**: {{mensagem, ação possível}}
Dicas:
Lista explícita de prós (✓) e contras (✗) da solução escolhida. Isso é o que dá valor ao documento a longo prazo.
- ✓ Custo de infra ~40% menor com mesmo SLA.
- ✓ Reaproveita pipeline existente, reduz risco de regressão.
- ✗ Defasagem de até 24h nas recomendações.
- ✗ Cold start não coberto nesta versão.
Quando incluir: sempre. Sem compensações o doc vira plano de implementação disfarçado.
Dicas:
Sistemas/soluções alternativos com compensações próprias. Explica por que a escolhida ganhou.
Quando incluir: Médio+, ou sempre que houve debate real entre opções.
Dicas:
O que impacta outras áreas além do seu time: segurança, infra, compatibilidade de API/schema, fluxo em outros sistemas.
Quando incluir: Médio+, ou quando outras áreas (segurança, infra, plataforma, times consumidores) precisam revisar.
Dicas:
Como saberemos que funciona em produção: estratégia de testes, métricas de sucesso, alertas, dashboards.
Quando incluir: Médio+, ou quando o sistema gera tráfego/dado em prod que precisa ser monitorado.
Dicas:
Segmentação incremental que entrega valor de forma segura: fases, gates, rollback.
Quando incluir: Médio+, ou quando há risco de regressão, dependências entre times, ou rollout faseado por geografia/usuário.
Dicas:
Pontos não definidos. Sinaliza honestidade e convida colaboração.
Quando incluir: sempre que houver — esconder ambiguidade força retrabalho depois.
Dicas:
Princípio crítico: design docs documentam decisões arquiteturais e contratos, não código.
| Categoria | Inclua | Exemplo |
|---|---|---|
| Contratos de API | Schemas request/response | POST /subscriptions com estrutura JSON |
| Schemas de dados | Estrutura de tabela, tipos | Customer com campos id, email, stripeId |
| Arquitetura | Componentes, fluxo de dados | "Frontend → API → Service → Stripe → DB" |
| Decisões | Que tecnologia, por quê | "Stripe pelo suporte global e PCI compliance" |
| Diagramas | Sequência, arquitetura, fluxo | C4, Mermaid |
| Estratégias | A abordagem, não os comandos | "Rollback via feature flag" (não o curl) |
| Categoria | Evite | Por quê |
|---|---|---|
| Comandos CLI | kubectl rollout undo, nx db:generate | Específico demais, muda com tooling |
| Snippets de código | TypeScript/JavaScript da implementação | Vai no código, não no doc |
| Especificidades de framework | @Injectable(), extends Repository | Framework muda; a decisão é o que importa |
| Caminhos de arquivo | scripts/backfill.ts | Detalhe de implementação |
| Sintaxe de ferramenta | Decoradores NestJS, entities TypeORM | Documente o padrão, não a implementação |
Antes de adicionar detalhe, pergunte:
Goal: o design doc deve sobreviver a mudanças de implementação. Se migrar de NestJS pra Express, ou TypeORM pra Prisma, o doc deve continuar válido.
Não force quando:
Se o usuário trouxe algo que cabe nessas categorias, diga isso antes de escrever. Sugira alternativas: comentário no PR, mensagem no Slack, ADR de uma página.
Quando as skills irmãs estiverem disponíveis, delegue em vez de improvisar:
c4-diagram skill (mesmo repo): chame para o diagrama de arquitetura (system context + container) na seção Diagramas. Produz Structurizr DSL pronto. Ela já cobre microservices, queues e linkagem de ADRs via !adrs — alinhado com as outras skills deste conjunto.sequence-diagram skill (mesmo repo): chame quando o doc precisar de um diagrama de sequência (fluxos temporais, chamadas API, processos batch). Produz Mermaid sequenceDiagram que embeda inline na seção Diagramas (o bloco ```mermaid é a própria fonte), opcionalmente com link de preview no mermaid.live via MCP.adr skill (mesmo repo): se o usuário pedir registro de uma decisão pontual ("documenta a decisão de usar Postgres em vez de Mongo", "ADR pra escolha de message broker"), não acione design-doc — encaminhe pra adr. Inversamente, se o design doc gerar decisões individuais ao longo das seções Solução ou Alternativas Consideradas, ofereça extrair cada uma como ADR via adr — ambas as skills convergem no diretório ./decisions por convenção, e o C4 produzido aqui pode referenciá-las via !adrs.technical-design-doc-creator (skill do sistema, não-deste-repo): skill alternativa do Anthropic, mais opinionada (campos obrigatórios, foco em compliance, integração Confluence). Se o usuário quiser o caminho rígido com seções obrigatórias e validação automática de PCI/OWASP, encaminhe pra ela. Esta skill é a opção leve, sem mandatoriedade.kubectl, git commit, decoradores, paths — não é design doc, é manual de implementação.| Quando | Carregue | Por quê |
|---|---|---|
| Usuário pediu "me dá um esqueleto" | references/template.md | Skeleton copiável com placeholders |
| Usuário pediu "me mostra um exemplo" | references/example.md | Caso completo (Recomendador de estoque) |
| Sempre antes do Step 4 | references/checklist.md | Self-review |
Os três 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.