Decisão de Arquitetura
Transforme uma questão arquitetônica em uma decisão específica, justificada e verificável.
Esta skill é responsável pelo método de decisão, ciclo de vida do registro e entregável. engineering-philosophy é responsável pelos princípios compartilhados de design e escrita. O agente ativo e a tarefa são responsáveis pelas permissões, delegação e intenção de saída.
1. Estabelecer a Decisão
Declare a questão, o sistema afetado, o resultado necessário e as exclusões de escopo.
Uma decisão merece um ADR quando afeta materialmente contratos entre componentes, requisitos de qualidade, propriedade, confiança, operações, dependências ou custo de mudança futura.
Não exija um ADR para design local rotineiro. Retorne no-adr-needed com a resposta e uma breve justificativa, a menos que o solicitante peça explicitamente um registro formal.
Identifique decisões relacionadas. Separe escolhas independentemente reversíveis em registros separados, mas não fragmente uma decisão coerente em um ADR para cada etapa de implementação.
Para um ADR existente, estabeleça se a tarefa é esclarecimento, reavaliação ou substituição. Não converta silenciosamente uma explicação histórica em uma nova recomendação.
2. Estabelecer Contexto e Direcionadores
Leia as instruções aplicáveis, decisões aceitas relevantes e evidências de implementação suficientes para entender os limites afetados.
Estabeleça o que existe antes de descrever o que deveria existir. Para trabalho em campo verde, use os requisitos fornecidos e rotule a ausência de evidências de implementação.
Separe:
- Restrições rígidas: contratos, políticas, compatibilidade, regras de dados ou limites explícitos exigidos.
- Direcionadores de decisão: as qualidades e compensações que distinguem opções viáveis.
- Suposições: condições não verificadas das quais a recomendação depende.
Determine quais direcionadores são mais importantes. Infira uma prioridade provisória apenas quando defensável e rotule-a. Peça autoridade quando uma prioridade não resolvida alteraria materialmente o comportamento do produto, custo ou aceitação de risco.
Torne metas vagas concretas. Para requisitos de desempenho ou confiabilidade, identifique a carga de trabalho, o cenário de falha, o resultado observável e o limite quando conhecido. Rotule um limite inventado para discussão como proposto, nunca como um requisito.
Não fabrique tráfego, objetivos de nível de serviço, prazos, capacidade da equipe, custos ou requisitos futuros para justificar um design.
3. Resolver Incógnitas que Mudam a Decisão
Investigue incertezas que possam alterar viabilidade, classificação, segurança ou escopo de implementação.
Prefira evidências locais para o sistema atual. Use documentação primária para comportamento externo e verifique a versão e o ambiente relevantes.
Distinga observação direta, evidência fornecida, inferência e hipótese não testada. A capacidade de um fornecedor não estabelece que a configuração local a habilita.
Pare a pesquisa quando as evidências apoiam a decisão ou quando uma leitura adicional provavelmente não a alterará.
Quando a medição for necessária, defina um experimento delimitado: questão, carga de trabalho representativa, linha de base de comparação, resultado observável, critério de aprovação/reprovação e como o resultado altera a escolha.
Não afirme que o experimento foi executado. Retorne a solicitação de evidência específica quando a execução ou o acesso à fonte estiver fora das permissões do agente ativo.
4. Comparar Opções Credíveis
Considere manter o design atual e a menor alteração suficiente. Explique quando qualquer um falha em uma restrição rígida.
Compare apenas alternativas plausíveis. Não invente candidatos fracos para fazer um favorito vencer, exija um número fixo de opções ou pesquise todos os produtos de uma categoria.
Avalie as opções em relação aos mesmos direcionadores de decisão. Inclua esforço de migração relevante, propriedade operacional, tratamento de falhas, custo recorrente, acoplamento e reversibilidade.
Rejeite violações de restrições rígidas explicitamente. Não as dissimule com uma pontuação ponderada.
Prefira comparações qualitativas com razões concretas. Use pontuação numérica apenas quando suas entradas e pesos forem defensáveis; exponha a sensibilidade a entradas incertas.
A popularidade de uma tecnologia, um padrão de arquitetura nomeado ou escalabilidade alegada não é, por si só, um benefício específico do projeto.
5. Desafiar a Opção Preferida
Trace o caminho de sucesso importante e o caminho de falha credível mais consequente através dos limites propostos.
Considere apenas preocupações relevantes:
- Propriedade e contratos: estado autoritativo, dependências permitidas, compatibilidade, transações e propriedade do ciclo de vida.
- Falha e recuperação: conclusão parcial, entrega duplicada, ordenação, repetições, timeouts, cancelamento, sobrecarga e reparo.
- Segurança e privacidade: limites de confiança, autorização, isolamento, dados sensíveis e caminhos de abuso credíveis.
- Operação e mudança: implantação, observabilidade, limites de recursos, evidência de capacidade, migração, suporte contínuo e custo de saída.
Use a referência de Arquitetura para princípios de design em vez de reproduzir suas leis aqui.
Declare a objeção mais forte à recomendação e a evidência que poderia anulá-la. Verifique se uma opção mais simples satisfaz as mesmas restrições.
Para transições arriscadas, descreva a coexistência e a recuperação. Identifique o ponto a partir do qual o rollback é inseguro ou impossível. Use uma estratégia de roll-forward ou reparo quando a reversão perderia dados ou quebraria a compatibilidade.
Descreva os estados atual, transitório e de destino apenas quando suas diferenças forem importantes. Não produza um diagrama meramente para decorar a decisão.
6. Decidir
Recomende uma direção quando as evidências a apoiarem. Nomeie o direcionador decisivo e o custo ou limitação que a equipe aceitaria.
Proceda sob suposições divulgadas quando elas não invalidarem uma recomendação segura. Não bloqueie em incógnitas imateriais.
Quando uma suposição material permanecer não resolvida, declare a preferência provisória e a condição exata que a alteraria. Não a apresente como um compromisso incondicional.
Quando nenhuma opção satisfizer as restrições rígidas, diga isso. Identifique a menor mudança de restrição ou experimento necessário; não enfraqueça silenciosamente os requisitos.
Use um resultado de tarefa:
| Resultado | Significado |
|---|---|
recommended | Uma recomendação específica é apoiada dentro das restrições e suposições declaradas. A aprovação normal ainda pode estar pendente. |
needs-evidence | Uma lacuna de evidência nomeada impede uma seleção confiável. Inclua a preferência provisória e a verificação de resolução quando possível. |
needs-authority | Um requisito material, exceção ou decisão de risco deve ser resolvido por uma pessoa autorizada. Explique a recomendação técnica e a autoridade precisa necessária. |
no-adr-needed | A questão é design local rotineiro. Responda sem impor um processo de arquitetura formal. |
Esses resultados descrevem o resultado da tarefa, não a aprovação do ADR, conclusão da implementação ou veredictos de revisão de código.
7. Registrar a Decisão
Use a convenção de ADR do repositório quando existir. Caso contrário, leia o template de ADR e adapte-o à decisão.
Um registro deve preservar a questão, o contexto, os direcionadores decisivos, a direção escolhida, as alternativas credíveis, as desvantagens aceitas, a incerteza e as condições de validação. Mantenha-o curto o suficiente para ser mantido.
Um registro contém uma decisão arquitetônica coerente. Vincule registros relacionados em vez de copiar sua justificativa.
Se não existir uma convenção de armazenamento, sugira docs/decisions/. Inspecione a numeração existente antes de propor um identificador final. Um caminho sugerido não é um arquivo salvo.
Ciclo de Vida e Autoridade
Atribua como padrão a um novo ADR o status proposed.
Use accepted apenas quando a aceitação for evidenciada pela autoridade designada ou o projeto delegar explicitamente essa decisão ao solicitante ou agente ativo. Registre a base da aceitação. Uma solicitação para recomendar, redigir ou avaliar não é aceitação.
Uma opção técnica selecionada pode permanecer proposed aguardando aprovação normal. Não use needs-authority meramente porque essa aprovação ainda não ocorreu.
Siga os estados restantes do ciclo de vida do projeto. Sem uma convenção, use rejected, deprecated e superseded quando apropriado.
Preserve a justificativa histórica aceita. Uma decisão materialmente alterada recebe um novo registro com uma relação de substituição. O registro antigo permanece disponível; um redator autorizado atualiza seu status e link de substituição quando a nova decisão for aceita.
Uma implementação que contradiz um ADR não o substitui automaticamente. Estabeleça se a implementação, a decisão registrada ou o requisito governante precisa de correção.
A aceitação não estabelece implementação, verificação operacional ou permissão para implantar.
Evidência e Confirmação
Cite alegações consequentes ao lado do contexto ou justificativa que apoiam. Use referências duráveis de repositório e fontes externas específicas da versão quando disponíveis.
Não use identificadores de sessão inacessíveis como a única evidência em um ADR durável. Mantenha links para as fontes subjacentes ou atribua evidência fornecida claramente.
Defina verificações que confirmem tanto a conformidade arquitetônica quanto o resultado prometido. Conecte cada invariante importante a uma verificação observável.
Use comandos suportados pelo projeto apenas quando conhecidos. Caso contrário, descreva o teste ou inspeção sem inventar instruções executáveis.
Marque verificações futuras como não executadas. Identifique o proprietário pela função estabelecida quando conhecido, ou deixe a propriedade não resolvida. Não atribua trabalho a uma pessoa não envolvida.
Defina um gatilho de revisão concreto: uma validação falha, restrição alterada, limite medido ou alteração de dependência relevante. "Revisitar quando necessário" não é útil.
Entregável
Siga um formato explícito do solicitante. Caso contrário, comece com um resumo de decisão compacto:
- Recomendação: a direção selecionada e a razão decisiva, ou a escolha não resolvida.
- Resultado: um dos quatro resultados de tarefa.
- Escopo: limite afetado e exclusões importantes.
- Confiança: alta, média ou baixa, com as evidências e suposições que justificam o rótulo. Não apresente isso como uma probabilidade medida.
Para uma decisão material, retorne o ADR concluído. Quando a seleção permanecer bloqueada, mantenha-o como proposto e rotule a escolha como provisória ou não resolvida.
Adicione um handoff curto apenas quando necessário. Identifique restrições vinculantes, evidências ou autoridade não resolvidas e o próximo papel responsável. Faça referência ao ADR em vez de repetir seu conteúdo.
Não transforme o handoff em um plano de implementação em fases, relatório de revisão de código ou patch não solicitado.
Para no-adr-needed, retorne a resposta, o resultado e a justificativa sem seções de template vazias, a menos que o solicitante tenha solicitado o registro.
Verificação Final
Confirme que o resultado responde à decisão real, identifica uma opção preferida quando defensável e explica por que a alternativa mais forte não foi selecionada.
Verifique restrições rígidas, decisões existentes, consequências operacionais, alegações de verificação, autoridade de aceitação e limites de escopo.
Remova fatos inventados, pontuações decorativas, camadas desnecessárias, justificativa duplicada e alegações de que trabalho não realizado está concluído.