design-doc

Design Doc

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.

Workflow

Step 1: Discovery

Antes de escrever, alinhe três coisas com o usuário (1-2 perguntas, não um questionário):

• Audiência — quem vai ler? Aprovadores (decidem se segue), implementadores (vão construir), o próprio autor (memória futura). Cada um tem necessidades diferentes; o doc deve servir aos três.
• Complexidade — atalho rápido para escolher seções. Cada seção também tem seu próprio gatilho na guidance abaixo — use os dois juntos.
  • Pequeno (< 1 semana): Cabeçalhos · Visão Geral · Solução · Compensações. Pula o resto.
  • Médio (1–4 semanas): adiciona Escopo e Contexto · Objetivos e Fora de Escopo · Diagramas · APIs e Payloads · Alternativas Consideradas · Perguntas em Aberto.
  • Grande (> 1 mês): tudo aplicável, com Preocupações Transversais detalhadas, Plano de Implantação e revisoras de múltiplas áreas.
  • Seções condicionais (independem do tamanho): Telas só se há frontend; APIs e Payloads só se há endpoint novo/alterado; Plano de Implantação só se há risco de regressão ou rollout faseado.
• Linguagem — adote a linguagem do usuário (PT/EN/ES). Cabeçalhos de seção, prosa e exemplos vão em PT-BR se o usuário escreve em português.

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.

Step 2: Compose

Trabalhe seção por seção. Para cada uma:

1. Aplique a guidance da seção (abaixo, em The 14-section canon).
2. Use apenas o que o usuário compartilhou. Não invente headers, status codes, números, MAPE, percentuais, datas, nomes de pessoas. Quando faltar dado, deixe placeholder explícito ({{a definir}}) ou pergunte.
3. Mantenha o foco em decisões e contratos, não implementação (ver seção High-level vs implementation).

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").

Step 3: Validate and self-review (não pule)

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:

• Diagramas têm texto explicativo + link pro fonte?
• Compensações da solução escolhida estão explícitas?
• Não tem código de implementação, só contratos?
• Falhas/edge cases aparecem onde fazem diferença (não só happy path)?
• O nível de detalhe é proporcional à complexidade da decisão?

Step 4: Deliver

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).

---

The 14-section canon

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.

1. Cabeçalhos — identificação
2. Visão Geral — alto nível, 1–2 parágrafos
3. Escopo e Contexto — plano de fundo
4. Objetivos e Fora de Escopo — listas mensuráveis
5. Solução — a abordagem proposta, em prosa
6. Diagramas — arquitetura (C4) e/ou sequência
7. APIs e Payloads — contratos HTTP em <details> colapsado
8. Telas — wireframes e fluxo, quando há frontend
9. Compensações — ✓ e ✗ da solução escolhida
10. Alternativas Consideradas — incluindo "não fazer nada"
11. Preocupações Transversais — impacto em outras áreas
12. Testabilidade e Observabilidade — como saberemos que funciona em prod
13. Plano de Implantação — rollout incremental
14. Perguntas em Aberto — pontos não definidos

1. Cabeçalhos

Identificam 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:

• Atualize o estado quando muda de fase. "Em revisão" há 4 meses confunde.
• Envolva revisoras de áreas afetadas (segurança, infra, plataforma, times consumidores).
• Tags ajudam busca meses depois ("como decidimos X?").

2. Visão Geral

Texto breve, 1–2 parágrafos, alto nível. O que esperar lendo o documento.

Quando incluir: sempre.

Dicas:

• Alguém sem contexto deve entender do que se trata.
• Sem detalhes técnicos profundos — vão nas próximas seções.
• Não antecipa decisões; só declara o tema.

3. Escopo e Contexto

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:

• Sucinto — só o contexto mínimo pra entender o problema.
• Não coloque objetivos nem soluções aqui.
• Encare como background; situa o leitor sem antecipar decisões.

4. Objetivos e Fora de Escopo

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:

• Mensuráveis: "reduzir ruptura em 20% até Q3" > "melhorar disponibilidade".
• Específicos: "reduzir custo via redução de tráfego" > "reduzir custos".
• Em "Fora de Escopo", aponte exclusões reais — não negue só os objetivos.

5. Solução

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:

• Fatos e dados sustentam decisões; evite justificativas vagas.
• Descreva o que a solução faz e por que essa forma — não como implementar.
• Cite gatilhos de decisão (custo, SLA, restrições) que tornam a escolha defensável.

6. Diagramas

Visualizações que complementam a prosa da Solução. Tipicamente dois tipos:

• C4 nível Containers — arquitetura de alto nível.
• Diagrama de sequência — ordem temporal de interações (chamadas API, processos batch com dependências).

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:

• Diagramas são complementares ao texto, nunca substitutos.
• Sempre tenha fonte editável linkada — imagem renderizada + link pro fonte.
• Mostre falhas relevantes, não só happy path (CSRF, consent denied, token error).

Diagrama C4

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}}**

![{{alt text}}](./diagrams/c4-containers.png)

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.

Diagrama de sequência

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.

7. APIs e Payloads

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:

• Preencha apenas as linhas que o usuário compartilhou. Não invente headers, status codes ou shapes.
• Documente payload de erro, não só sucesso.
• Não copie/cole schemas inteiros — mostre só o relevante pra decisão.

8. Telas

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}}

![{{alt text}}](./screens/{{nome}}.png)

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:

• Use a ferramenta que o time já adota (Figma, Excalidraw, Penpot, etc.). Skill não prescreve — só pede fonte editável linkada, como nos diagramas.
• Foque nas telas que sustentam a decisão. Listar 30 telas geralmente é dump de implementação.
• Mostre fluxo entre telas (setas, numeração) quando a ordem importa.

9. Compensações

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:

• Contras honestos > otimismo. Quem lê quer saber o custo da decisão.
• Não repita os objetivos; foque em consequências da escolha específica.

10. Alternativas Consideradas

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:

• Sempre inclua "não fazer nada" como alternativa documentada.
• Foco em compensações de cada opção, não em descrição da opção.
• Sucinto. Mas deixe claro por que a escolhida é a melhor dentro das restrições.

11. Preocupações Transversais

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:

• Envolva os times o mais cedo possível — surpresas tardias geram retrabalho.
• Peça revisão dos times impactados — eles enxergam problemas que o seu time não enxerga.

12. Testabilidade e Observabilidade

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:

• Testes: tipos (unit, integração, contrato, smoke) e o que cada um cobre — não só "vamos testar".
• Métricas: KPIs de sucesso mensuráveis, não vaidade.
• Observabilidade: alertas com gatilho claro + dashboards que oncall consulta primeiro.

13. Plano de Implantação

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:

• Cada fase deve entregar valor (ou viabilizar a próxima) — não fragmentação por fragmentação.
• Documente o rollback por fase: como reverter se algo der errado.
• Use feature flags quando aplicável (sem prescrever ferramenta).

14. Perguntas em Aberto

Pontos não definidos. Sinaliza honestidade e convida colaboração.

Quando incluir: sempre que houver — esconder ambiguidade força retrabalho depois.

Dicas:

• Indique quem decide / de quem se aguarda input.
• Datas/prazos quando aplicável ("resposta até {{data}}").

---

High-level vs implementation

Princípio crítico: design docs documentam decisões arquiteturais e contratos, não código.

✅ Inclua (alto nível)

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)

❌ Evite (implementação)

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

Teste rápido — "isso vai mudar?"

Antes de adicionar detalhe, pergunte:

• "Se trocar o framework, esse detalhe ainda vale?" — sim → inclua. Não → exclua.
• "Alguém pode implementar isso de outra forma e ainda atender o requisito?" — sim → foque no requisito.

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.

---

Quando NÃO escrever um design doc

Não force quando:

• 🚫 A cultura organizacional é patológica — pouco valor em documentos que dizem "é assim que vamos implementar" sem alternativas, compensações ou explicações.
• 🚫 Sobrecarga é problema — escrever doc gera custo; sem entendimento dos benefícios pela organização, pode gerar mais ruído do que valor.
• 🚫 Não há complexidade — quando a complexidade da tarefa é inferior ao esforço de escrever o doc.

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.

---

Composability

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.

---

Anti-padrões

• Problema vago. "Vamos integrar com Stripe." → ruim. "Pagamento manual gasta 2h/dia ($500/mês); não escala internacionalmente; carrinho com 45% de abandono." → bom.
• Escopo indefinido. "Construir tudo da integração de pagamento." → ruim. Liste explicitamente in-scope e out-of-scope.
• Schema/code dump. Copiar o schema inteiro do banco ou um endpoint de 80 linhas de DTO no doc. Mostre só o relevante pra decisão.
• Sem compensações. Documento que diz "vamos usar X" sem explicar por que X e não Y, e quais os trade-offs de X.
• Implementação disfarçada de design. Se o doc tem kubectl, git commit, decoradores, paths — não é design doc, é manual de implementação.
• Diagrama só com happy path. Falhas que mudam comportamento do sistema (CSRF, consent denied, token error) merecem aparecer.

---

When to load references

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.