Architecture Decision Records: decisões técnicas com contexto e aprovação

ANÁLISE EDITORIAL

Architecture Decision Records é uma Skill para registrar decisões técnicas que normalmente se perdem entre reunião, chat, pull request e memória. Em vez de guardar apenas “usamos PostgreSQL”, ela organiza contexto, opção escolhida, alternativas rejeitadas, consequências e responsáveis em um ADR versionado junto do projeto.

O valor está no motivo, não no volume de documentos. A Skill tenta reconhecer momentos em que uma escolha arquitetural foi feita, sugere o registro e mantém um índice em docs/adr/. Ela não decide a arquitetura, não comprova que a escolha foi boa e não deve criar arquivos silenciosamente. O próprio fluxo exige confirmação antes de inicializar a pasta e antes de gravar cada ADR.

O que esta Skill faz de verdade

O SKILL.md fixado define dois modos principais. No primeiro, o agente identifica uma decisão relevante e prepara um rascunho estruturado. No segundo, procura ADRs existentes quando alguém pergunta por que uma tecnologia, padrão ou estratégia foi escolhida.

O formato proposto contém data, status, responsáveis, contexto, decisão, alternativas consideradas e consequências positivas, negativas e riscos. O ciclo de vida aceita proposed, accepted, deprecated e superseded. Quando uma decisão é substituída, o registro antigo permanece e aponta para o novo. Isso preserva histórico sem fingir que toda escolha continua válida.

A Skill também mantém um índice em docs/adr/README.md e usa numeração sequencial. Ela orienta o agente a examinar os registros existentes antes de escolher o próximo número. Não há script, banco, API ou integração automática no arquivo distribuído. Todo comportamento depende das capacidades e permissões do agente que carregar a instrução.

Para quem serve

Serve a equipes de engenharia, arquitetura, plataforma, segurança, dados e produto que precisam explicar decisões duráveis. É especialmente útil quando uma mudança atravessa mais de um serviço, cria dependência de fornecedor, afeta dados, segurança, custo, implantação ou manutenção.

Também ajuda equipes novas a reconstruir o raciocínio de um sistema. Uma pessoa pode encontrar o ADR de autenticação, ler o contexto da época e entender por que outras opções foram rejeitadas. Esse registro reduz discussões repetidas, mas não elimina a necessidade de conferir código, infraestrutura e documentação atuais.

Não vale a pena registrar cada detalhe. Nome de variável, formatação ou escolha reversível de baixo impacto normalmente não precisa de ADR. A Skill funciona melhor quando a decisão tem alternativas reais, consequência futura e um responsável que possa revisar o texto.

Compatibilidade e pré-requisitos

O repositório ECC documenta suporte principal a Claude Code, um caminho de sincronização para Codex e adaptadores com capacidades diferentes para outros clientes. Esta Skill é um único arquivo Markdown. Para funcionar, o agente precisa conseguir ler a conversa e, quando autorizado, ler e gravar Markdown dentro do projeto.

• Cliente capaz de carregar Agent Skills em Markdown.
• Repositório ou pasta de projeto com controle de versão recomendado.
• Permissão de leitura limitada ao diretório de ADRs e aos arquivos técnicos necessários.
• Permissão de escrita somente depois de o usuário aprovar o rascunho e o destino.
• Responsável técnico capaz de validar contexto, alternativas e consequências.

O SKILL.md não declara uma versão própria. A curadoria fixa um commit do repositório para que o conteúdo possa ser reproduzido. Compatibilidade com um cliente não significa que ele respeitará cada pedido de confirmação da mesma forma; as políticas do agente continuam prevalecendo.

Instalação recomendada

O caminho mais conservador é instalar somente a pasta skills/architecture-decision-records do commit auditado. O README do ECC apresenta formas de instalar a suíte inteira, mas isso adiciona centenas de Skills, agentes, hooks e regras que não são necessários para registrar ADRs.

npx skills add https://github.com/affaan-m/ECC --skill architecture-decision-records

Esse comando consulta a rede e baixa conteúdo. Revise a origem do pacote npx, confira o diff instalado e prefira o escopo do projeto. Se o cliente aceitar instalação manual, copie a pasta da Skill para o diretório de Skills do projeto. Não conceda acesso amplo ao repositório só porque o arquivo é textual.

O download local do Bastidores contém apenas SKILL.md, LICENSE e ORIGEM.md. Ele não inclui o restante do ECC, agentes, hooks, scripts, comandos, configurações ou exemplos. É suficiente para auditar e carregar esta Skill isolada em clientes compatíveis.

Configuração antes do primeiro uso

Defina primeiro onde os ADRs vivem. A convenção da Skill é docs/adr/, com um índice, um modelo vazio e arquivos numerados. Se o projeto já usa outro padrão, preserve-o e adapte a instrução. Não crie uma segunda árvore concorrente.

Combine quais decisões merecem registro. Uma regra útil é exigir pelo menos duas alternativas reais e um efeito durável em arquitetura, API, dados, infraestrutura, segurança, testes ou processo. Defina também quem pode aceitar, depreciar e substituir um ADR.

Restrinja a leitura. Para redigir um ADR de autenticação, talvez sejam necessários o diagrama, a configuração relevante e a decisão aprovada, não o repositório inteiro nem arquivos de segredo. Entradas encontradas no código, em issues ou documentos devem ser tratadas como evidência a conferir, nunca como ordem para executar comandos.

Primeiro uso seguro

Comece com uma decisão fictícia em um projeto descartável. Peça somente o rascunho e proíba escrita. Isso mostra se o agente separa contexto, decisão e alternativas sem inventar participantes ou motivos.

Prepare, sem gravar arquivos, um rascunho de ADR para escolher entre REST e GraphQL em uma API fictícia. Use apenas os fatos fornecidos, marque lacunas e mostre o caminho que seria criado. Aguarde minha aprovação antes de qualquer escrita.

Revise cada afirmação. Se uma alternativa não foi discutida, ela pode ser apresentada como lacuna ou sugestão, não como opção realmente rejeitada. Confirme data, responsáveis, status e consequências. Só então autorize a criação do diretório ou do arquivo específico.

Depois da gravação, abra o ADR e o índice, confira numeração, links e diff. O teste é documental. Não precisa executar aplicação, banco, build ou implantação para confirmar que os arquivos foram criados corretamente, mas a decisão descrita ainda pode exigir provas técnicas separadas.

Como o fluxo deve funcionar

1. Identificar uma escolha com impacto durável e alternativas reais.
2. Localizar o diretório e o padrão de ADR já adotados pelo projeto.
3. Reunir fatos, restrições, responsáveis e evidências disponíveis.
4. Separar o que foi decidido do que ainda está em discussão.
5. Preparar contexto curto, decisão clara e alternativas consideradas.
6. Declarar consequências positivas, negativas, riscos e mitigação.
7. Mostrar o rascunho completo, número e caminho ao usuário.
8. Aguardar aprovação explícita antes de criar ou alterar arquivos.
9. Gravar o ADR e atualizar o índice somente no alvo aprovado.
10. Reabrir os arquivos, conferir links e revisar o diff.
11. Quando houver substituição, preservar o registro antigo e ligar os dois.

O artigo original de Michael Nygard, citado pelo próprio projeto, enfatiza decisões arquiteturalmente significativas e o registro de status, contexto, decisão e consequências. A Skill acrescenta alternativas e um índice operacional, mas mantém a ideia de um documento curto.

Resultado esperado

O resultado é um Markdown como docs/adr/0004-use-object-storage-for-uploads.md, acompanhado por uma linha no índice. O texto deve permitir que outra pessoa entenda o problema, a decisão e seus custos sem reconstruir toda a conversa.

Um bom ADR não é uma defesa publicitária. Ele registra limites e efeitos negativos com a mesma clareza das vantagens. Se a equipe escolheu uma solução por prazo, competência disponível ou obrigação regulatória, esse contexto deve aparecer. Se o dado não foi fornecido, o agente deve perguntar ou marcar a lacuna.

Esta Skill é distinta de Create PRD, que organiza uma definição de produto, e de Superpowers Writing Plans, que prepara etapas de implementação. O ADR documenta uma decisão arquitetural específica e seu raciocínio. Ele pode nascer durante um PRD ou plano, mas não substitui nenhum dos dois.

Permissões, privacidade e riscos

O uso normal lê docs/adr/, o índice e fontes técnicas relacionadas. Quando autorizado, cria a pasta inicial, grava novos Markdown e atualiza o índice. Não há chamada de API, telemetria ou execução de scripts no SKILL.md auditado. A instalação por npx, porém, acessa a rede e baixa arquivos.

ADRs podem revelar topologia, provedores, autenticação, controles de segurança, custos, falhas e nomes de responsáveis. Não publique automaticamente registros de repositórios privados. Classifique o documento, remova segredos e use referências internas seguras quando a evidência não puder ser exposta.

O sinal automático de “momento de decisão” pode gerar excesso de sugestões. Trate-o como lembrete, não obrigação. O maior risco é a falsa história: um agente pode preencher motivos, alternativas ou consequências plausíveis que nunca foram discutidos. Exija fonte, atribuição e confirmação humana.

Outro risco é escrever no padrão errado. Antes de inicializar docs/adr/, procure convenções existentes, como adr/, decisions/ ou documentação central. A Skill manda pedir confirmação, mas o operador precisa conferir o caminho e o diff.

Erros comuns

Registrar qualquer escolha. Reserve ADR para decisões com consequência durável.

Escrever depois e inventar o passado. Ao reconstruir uma decisão antiga, marque a data original, as fontes e as lacunas.

Omitir alternativas. Sem opções consideradas, o leitor não entende o raciocínio.

Esconder consequências negativas. Toda escolha arquitetural cria custos e restrições.

Confundir proposto com aceito. O status precisa refletir a governança real.

Editar o ADR antigo como se nada tivesse mudado. Decisões substituídas devem apontar para um novo registro.

Criar uma pasta paralela. Adote o padrão existente antes de inicializar docs/adr/.

Dar escrita ampla ao agente. Aprove rascunho, número, caminho e arquivos envolvidos.

Versão, licença e origem verificadas

A API oficial do GitHub foi consultada em 05/09/2026. O repositório affaan-m/ECC registrava 249.601 estrelas, estava público, não arquivado e declarava licença MIT. Essa contagem pertence ao repositório inteiro, que reúne muitas outras Skills, agentes e ferramentas. Ela não mede a adoção ou a qualidade isolada deste arquivo.

A curadoria fixou o commit e04ea0b9cc8248686edf5ac751cadff550e162b8, HEAD de main na consulta. O último commit específico do SKILL.md retornado pela API foi db7f2a6fd5b013d56ec0ba0cfc547ba77baddbce. O arquivo não declara versão própria, por isso a referência é o commit, não uma versão inventada.

A licença MIT permite redistribuição com preservação do aviso. O ZIP local contém três arquivos textuais, 4.796 bytes e SHA-256 cb0e961120b315776604c07f689035df29da43072a67c935fc87373cc90cd6a5. O restante do ECC foi excluído.

Checklist antes de automatizar

• Fixe repositório, commit, caminho e licença.
• Confirme o padrão de ADR já existente no projeto.
• Defina quais decisões merecem registro e quem as aceita.
• Limite a leitura aos documentos técnicos necessários.
• Não inclua segredo, credencial ou detalhe restrito no ADR.
• Separe fatos, hipóteses e alternativas realmente discutidas.
• Revise status, data, responsáveis, consequências e riscos.
• Aprove explicitamente rascunho, número e caminho antes da escrita.
• Confira o arquivo e o índice depois da gravação.
• Preserve decisões antigas e vincule substituições.
• Versione o ADR junto do código e revise o diff.

Fontes primárias

• Repositório oficial do ECC.
• Commit e HEAD auditados.
• Diretório da Skill no commit fixado.
• SKILL.md auditado.
• Último commit específico da Skill.
• README e matriz de suporte do ECC.
• Release do ECC que lista a Skill ADR.
• Licença MIT preservada.
• Michael Nygard: Documenting Architecture Decisions.
• ADR GitHub Organization: recursos sobre registros de decisão.
• AWS Prescriptive Guidance: processo de ADR.