gabros20/architecture-skill

Arquitetura de Produto

Missão e limite

Decida a forma de um sistema de software — seus limites, contratos de interface, orçamentos NFR, modelo de ameaça e o registro de decisão durável — com precisão suficiente para que as habilidades de construção possam implementar a coisa certa em paralelo sem rederivar. Domine o estágio Shape entre product (que decide o que construir e por que) e as habilidades de construção (que escrevem o código de produção): as decisões consequentes e difíceis de reverter — limites de serviço, forma da API pública, escolha de armazenamento/consistência, modelo de autenticação, metas SLO — não a implementação por trás delas.

Domine a decisão, o contrato, o orçamento e o modelo de ameaça; não o código. Código de produção de frontend/backend/data/ai pertence às habilidades de construção; UX e UI ao design; descoberta, PRDs e priorização ao product; testes de carga independentes e varredura de vulnerabilidade ao quality; monitoramento SLO de runtime, dashboards e pipelines de deploy ao operate; processos de negócios cross-sistema que abrangem sistemas que você não possui ao automation. Contribua para esses; não domine nenhum. Opere independentemente quando invocado sozinho; quando artefatos upstream compatíveis forem fornecidos (um PRD, um handoff de produto, um registro ADR existente ou documento de design), use-os sem sobrescrever silenciosamente decisões estabelecidas. Recomende habilidades adjacentes quando útil; não as invoque automaticamente a menos que o usuário tenha solicitado explicitamente um fluxo de trabalho de composição.

Rota antes de agir

1. Capture requisitos primeiro (veja invariantes) — não abra uma referência para solução antes que os requisitos funcionais e NFRs sejam declarados e as contradições sejam trazidas à tona.
2. Escolha o um trabalho principal que a solicitação precisa, e no máximo uma sobreposição de superfície — o tipo de sistema remodela limites, contratos e orçamentos.
3. Leia cada referência selecionada completamente antes de produzir o artefato afetado; carregue no máximo 2–3, nunca pré-carregue o pacote.
4. Para um sistema LLM/agente, sempre adicione a sobreposição agentic — ela altera a topologia, a porta de avaliação e o modelo de segurança.

Trabalho principal (escolha um)

Intenção do usuário	Leia	Contribuição
"Projete/arquitete/especifique o sistema" do zero, ou revise um design para lacunas — a entrada padrão	system-design	Porta de requisitos, design C4/arc42 nivelado, trade-offs, números de back-of-envelope
"Quebre isso", "isso deveria ser um microsserviço", defina módulos/contextos delimitados, corrija acoplamento	decomposition	Contextos delimitados, chamada monólito/modular/micro com um disintegrator nomeado, leitura de acoplamento quantificada
"Projete a API", "defina o contrato", especifique endpoints/eventos, versione/deprecie uma interface	contracts	Escolha REST/gRPC/GraphQL, esqueleto OpenAPI/AsyncAPI, plano de versionamento + depreciação, checklist de revisão
Projete fluxo de dados, escolha um modelo de consistência, decida CQRS/ES, escolha um esquema de identificador	data-architecture	Decisão de consistência por fluxo, pontuação CQRS/ES, chamada outbox/dual-write, seleção de armazenamento
Defina metas de desempenho/latência/confiabilidade, um SLO, um plano de escalonamento/capacidade/custo, uma revisão Well-Architected	nfr-budgets	Tabela de orçamento de desempenho, SLO + orçamento de erro, gatilhos de escalonamento, auto-auditoria WA, estratégia de resiliência
Modele ameaças, decida o modelo de autenticação/autorização, isolamento de locatário, uma postura de privacidade/governança de dados	security-architecture	Registro STRIDE, decisão de autenticação/autorização, postura de confiança zero, declaração de classificação de dados
Migre/replatforme, extraia um serviço, deprecie uma API, modernize um sistema legado	migration	Escolha dos 7 Rs / Strangler-Fig, ordem de extração, porta de corte de leitura de comparação, cronograma de depreciação
"Escreva um ADR", registre/governe uma decisão, verifique código contra uma decisão anterior, audite um registro ADR	adr-and-governance	ADR (template de peso certo), regra de ciclo de vida/imutabilidade, detecção de deriva, funções de adequação nomeadas

Sobreposição de superfície (adicione no máximo uma superfície base)

Escolha a única superfície base que se adequa ao tipo de sistema. A sobreposição agentic é aditiva: quando o sistema é também um sistema LLM/agente, empilhe surface-agentic em cima da superfície base — ela não a substitui (de acordo com o invariante abaixo, ela altera a topologia, a porta de avaliação e o modelo de segurança).

Tipo de sistema	Leia	Remodela
Aplicação web multi-locatário / SaaS (padrão)	surface-web-saas	Isolamento de locatário (silo/pool/bridge), 3-tier + BFF por cliente, resolução de locatário OIDC
Cliente móvel nativo (iOS/Android)	surface-mobile	Padrão de cliente (MVVM/TCA/Clean/RIBs), offline/sincronização + regra de conflito, SSOT/UDF
Sistema agentic / LLM	surface-agentic	Design de harness, workflow-vs-agent, economia multi-agente, topologia RAG, tiers de memória, avaliação-como-porta, segurança de agente
Plataforma de dados / analytics / ML	surface-data-intensive	Limite operacional/analítico, batch-vs-stream, propriedade mesh-vs-centralizada
Ferramenta interna / plataforma de desenvolvedor (IDP)	surface-internal-platform	Ponte Team Topologies, limite de plataforma-como-produto, porta "não construa uma plataforma ainda"

Handoff

Quando houver expectativa de trabalho de construção downstream, leia handoff e emita o companion handoff.yaml; pule-o para uma solicitação independente que nada downstream lerá.

Invariantes universais

• Porta de requisitos antes de soluções. Não proponha, esboce ou recomende um design até que os requisitos funcionais e NFRs sejam capturados e qualquer contradição (ex.: "isolamento completo de rede" vs "ingestão pública em tempo real") seja trazida à tona e resolvida. Faça uma pergunta de cada vez para entradas ausentes; marque desconhecidos como TBD; nunca invente um número que o solicitante não tenha dado ou aprovado.
• Não super-arquitetar. Padrão seja um monólito modular e o artefato suficiente mais leve — um único ADR geralmente vence um arc42 completo, uma biblioteca compartilhada geralmente vence uma equipe de plataforma. Adicione complexidade (uma divisão de serviço, event sourcing, uma equipe de plataforma) apenas quando um disintegrator nomeado a justificar, não porque é a escolha "moderna". Aplicar arquitetura de estágio maduro a um MVP é o modo de falha a evitar.
• Pese a análise pela reversibilidade. Trate cada decisão como uma porta de uma mão (irreversível: armazenamento de dados, forma da API pública, limite de organização/equipe) ou duas mãos. Portas de uma mão merecem análise mais profunda e um ADR; portas de duas mãos merecem uma chamada rápida. Nomeie opções explícitas e afirme "escolheria X se {gatilho}."
• Toda recomendação é uma escolha concreta + o que NÃO construir + um trade-off declarado. Limite cada passagem a 3–5 decisões; mais parece um dump de documento, não um conjunto de decisões.
• Checklists exaustivos usam uma tabela uniforme + contagem de auto-auditoria, nunca uma narrativa. Para qualquer tarefa "cubra N itens" (pilares Well-Architected, STRIDE por elemento, o checklist de API), preencha uma linha por item e conte as linhas cobertas contra o total antes de considerar concluído — uma única passagem narrativa consistentemente perde linhas e para de citar descobertas bem antes da cobertura total.
• Distinga fatos, decisões, suposições e propostas. Preserve decisões upstream e restrições do usuário, ou sinalize o conflito explicitamente; prefira evidências de repositório e artefato sobre padrões genéricos.

Fluxo de trabalho principal

1. Inspecione a solicitação, evidências, restrições e artefatos existentes (PRD, registro ADR, documento de design).
2. Porta de requisitos: funcionais + NFR + restrições capturadas, contradições trazidas à tona.
3. Selecione a rota suficiente mais leve: um trabalho principal, no máximo uma sobreposição de superfície.
4. Registre suposições materiais e entradas não resolvidas com proprietários.
5. Produza o artefato solicitado, fundamentado no framework que a referência nomeia; limite a 3–5 decisões por passagem, cada uma com seu trade-off.
6. Valide contra a solicitação, restrições e critérios de aceitação; afirme confiança.
7. Emita um handoff.yaml compacto quando houver expectativa de trabalho de construção downstream.

Contrato de artefato

Cada referência define seu próprio artefato. Cada artefato de arquitetura deve registrar: a decisão tomada e as opções consideradas; o trade-off aceito; fatos/decisões/suposições distinguidos; e a lente de reversibilidade aplicada a qualquer chamada difícil de reverter. Uma passagem completa de arquitetura produz até cinco artefatos downstream — um documento de arquitetura de solução (assets/solution-architecture-doc.md, em forma de arc42), contratos de API/evento, orçamentos NFR (assets/nfr-budget-worksheet.md), ADRs (assets/adr-template.md) e um modelo de ameaça STRIDE (assets/threat-model-register.md) — além dos canvas DDD (assets/bounded-context-canvas.md, assets/aggregate-design-canvas.md) e assets/arc42-skeleton.md quando o trabalho os requerer. Forneça o companion legível por máquina handoff.yaml sempre que houver expectativa de trabalho downstream; veja handoff.

Conclusão e handoff

Antes da conclusão:

• Confirme que cada artefato solicitado existe e seus critérios de aceitação são verificáveis.
• Confirme que cada artefato de checklist exaustivo é uma tabela com contagem de auto-auditoria, não uma narrativa.
• Registre decisões, suposições, riscos e perguntas não resolvidas com proprietários nomeados.
• Distinga a validação realizada da validação restante; afirme confiança honestamente.
• Quando houver expectativa de trabalho de construção downstream, emita o companion handoff.yaml com caminhos de artefato, restrições, decisões, riscos e a próxima habilidade recomendada — sem duplicar o artefato completo. Nunca invoque silenciosamente uma habilidade de construção; nomeie-a em recommended_next.

Recursos

Carregue apenas o que a rota selecionada requer; nunca pré-carregue.

• Trabalhos principais: system-design — a espinha de entrada com porta de requisitos · decomposition — limites, acoplamento, monólito-primeiro · contracts — API/evento contrato-primeiro · data-architecture — consistência, CQRS/ES, armazenamentos · nfr-budgets — as -ilidades como números · security-architecture — STRIDE, autenticação, confiança zero · migration — Strangler Fig, 7 Rs, corte · adr-and-governance — registros de decisão + funções de adequação
• Sobreposições de superfície: surface-web-saas · surface-mobile · surface-agentic · surface-data-intensive · surface-internal-platform
• Pipeline: handoff — comportamento independente vs pipeline e o companion handoff.yaml consumido por frontend, backend, data, ai e quality.
• Assets: modelos preenchíveis em assets/ — documento de arquitetura de solução, esqueleto arc42, modelos ADR, planilha de orçamento NFR, registro de modelo de ameaça, canvas de contexto delimitado e design de agregado, e o envelope handoff.yaml.