vlaskos/brief-to-architecture

Análise de ASR

Um briefing não é uma especificação. É uma pilha de desejos, suposições e restrições mal declaradas, e enterrado ali estão os poucos requisitos que realmente decidirão a forma — e o custo — do sistema. Esta skill encontra esses requisitos, os torna precisos e os verifica uns contra os outros antes que alguém se comprometa com uma estimativa ou um design.

Um requisito arquitetonicamente significativo (ASR) é um requisito com efeito mensurável na arquitetura: atendê-lo força uma escolha estrutural, restringe uma tecnologia, define uma barra de qualidade difícil de atingir ou interage com outros requisitos de forma a limitar suas opções. A maioria dos requisitos em um briefing não é arquitetonicamente significativa. O trabalho é separar os poucos vitais dos muitos e explicar por que cada um importa.

O lado dos atributos de qualidade deste trabalho é ancorado na ISO/IEC 25010, o modelo internacional de qualidade de produto. Usar um conjunto padrão de características de qualidade mantém a análise completa (você verifica as mesmas dimensões todas as vezes) e dá a todos um vocabulário compartilhado. Veja references/quality-model.md.

O pipeline

Execute um briefing em seis etapas. Cada uma produz um artefato que a próxima utiliza.

1. Extraia, não transcreva. Leia a entrada bruta e extraia os requisitos reais, incluindo aqueles declarados como funcionalidades, reclamações ou comentários paralelos. Uma frase como "nosso tráfego da Black Friday é 40× o normal" não é um pedido de funcionalidade; é um requisito de desempenho e escalabilidade disfarçado. Interprete. Veja references/asr-framework.md para saber como reconhecer o que é arquitetonicamente significativo.

2. Classifique. Classifique cada requisito extraído em uma de três categorias:

   • Funcional — o que o sistema deve fazer.
   • Atributo de qualidade — quão bem ele deve fazer (desempenho, confiabilidade, segurança, manutenibilidade, …). Use as características ISO/IEC 25010 para cobrir o mesmo terreno toda vez — references/quality-model.md.
   • Restrição — um limite fixo e inegociável (uma tecnologia obrigatória, uma regulamentação, um prazo, um sistema existente). Restrições não estão abertas a design; elas moldam todo o resto.

3. Refine. Reescreva cada requisito significativo para que seja inequívoco e testável, e declare sua implicação arquitetônica — a consequência estrutural de levá-lo a sério. Remova soluções que o autor introduziu sorrateiramente ("usar Kafka" é um mecanismo proposto, não um requisito; o requisito é a taxa de transferência ou o desacoplamento por trás disso). Um requisito que você não pode testar, você não pode estimar.

4. Priorize em dois eixos. Nem todo ASR merece atenção igual. Classifique cada um em:

   • Valor de negócio — o quanto o resultado importa para o cliente.
   • Impacto arquitetônico — o quanto ele restringe o design e quão caro é reverter. (Alto impacto é sobre irreversibilidade e raio de explosão, não esforço.) Os requisitos que são altos em ambos são onde a arquitetura é realmente decidida. Gaste sua análise neles. Veja references/scenarios-and-priorities.md.

5. Verifique a viabilidade. Antes de projetar qualquer coisa, verifique se os requisitos de alta prioridade podem coexistir. Os briefings mais perigosos são internamente contraditórios: um alvo de latência, um alvo de consistência e um teto de custo que não podem ser todos verdadeiros ao mesmo tempo. Veja references/feasibility-check.md para um método concreto, incluindo a aritmética para requisitos numéricos.

6. Especifique cenários e escolha estratégias. Para os atributos de qualidade de alta prioridade, escreva cenários de qualidade mensuráveis (um gatilho, as condições e uma resposta que você pode medir), então escolha as estratégias de design que satisfariam cada um, com seu custo. Veja references/scenarios-and-priorities.md e references/design-strategies.md.

Disciplina que torna a análise confiável

• Identifique os cheiros. Briefings têm padrões recorrentes de falha: superlativos vagos, suposições ocultas, números sem unidade ou fonte, requisitos que contradizem. references/brief-smells.md é um catálogo deles e o que perguntar quando você vir um.
• Marque cada suposição. Quando o briefing é silencioso e você preenche uma lacuna, rotule-a: é uma lacuna preenchida (informação faltando, você forneceu um padrão), uma interpretação (ambíguo, você escolheu uma leitura) ou um estreitamento de escopo (você deliberadamente excluiu algo)? Uma estimativa construída sobre suposições não rotuladas é um palpite vestindo terno.
• Termine com as perguntas que mudam a forma. A saída de uma boa análise inclui as duas ou três perguntas cujas respostas mais mudariam a arquitetura. Essas são o que a próxima conversa com o cliente deve abordar.
• Uma estimativa é tão defensável quanto a análise por trás dela. É por isso que a análise vem primeiro: é o que torna o número que você dá ao cliente algo que você pode defender.

Como usar esta skill

• Analisar um briefing do início ao fim → execute o pipeline de seis etapas acima.
• Decidir o que é arquitetonicamente significativo → references/asr-framework.md.
• Escolher e cobrir atributos de qualidade → references/quality-model.md (ISO/IEC 25010).
• Escrever cenários de qualidade testáveis e priorizá-los → references/scenarios-and-priorities.md.
• Escolher abordagens de design por atributo de qualidade → references/design-strategies.md.
• Capturar contradições e combinações impossíveis → references/feasibility-check.md.
• Ler um briefing criticamente → references/brief-smells.md.
• Modelar o entregável escrito → references/output-template.md.