Registros de Decisões para Desenvolvimento de Software Orientado por IA

Mantenha a intenção próxima do código.

Conteúdo da página

Registros de decisão são a camada de memória ausente no desenvolvimento de software assistido por IA. Eles capturam não apenas o que foi construído, mas o porquê — e essa distinção se torna crítica quando ferramentas de IA estão escrevendo seu código.

Registros de decisão — ADR, PDR, DDR — conectando intenção ao código

Registros de decisão são a camada de memória ausente

A programação dirigida por IA muda a economia do desenvolvimento de software, tornando o código mais barato de gerar, mais fácil de refatorar e mais rápido de descartar. Isso é útil. Também é perigoso, porque quando o código se torna mais fácil de produzir, o recurso escasso não é mais a digitação — o recurso escasso é o julgamento.

Por que a equipe escolheu PostgreSQL em vez de DynamoDB? Por que o produto exige revisão humana antes de enviar e-mails gerados por IA? Por que a interface mostra sugestões em um painel lateral em vez de aplicá-las diretamente? Por que uma abordagem mais simples foi rejeitada há seis meses? O código pode mostrar o que existe, mas raramente explica por que ele existe.

Os registros de decisão resolvem esse problema ao fornecer um documento curto, controlado por versões, que captura uma escolha importante, o contexto por trás dela, as alternativas consideradas e as consequências que a equipe aceitou. Em uma base de código assistida por IA, esses registros se tornam mais do que documentação — eles se tornam uma memória de projeto durável que tanto humanos quanto agentes de codificação de IA podem ler antes de fazer mudanças futuras. A regra prática de operação é simples: mantenha os registros de decisão como arquivos Markdown no repositório, revise-os como código e deixe as ferramentas de IA futuras lê-los antes de propor ou implementar mudanças.

O que são registros de decisão?

Um registro de decisão é um registro escrito de uma decisão significativa, estruturado para responder a quatro perguntas básicas: o que decidimos, por que decidimos isso, que alternativas consideramos e que consequências aceitamos? A forma mais comum é o Registro de Decisão de Arquitetura, abreviado para ADR. Os ADRs são amplamente utilizados para documentar decisões técnicas, e o mesmo padrão pode ser estendido além da arquitetura para trabalho de produto e design.

Para a programação dirigida por IA, três tipos são especialmente úteis:

Tipo de registro Captura Exemplo
ADR Decisões de arquitetura e técnicas Usar PostgreSQL como banco de dados principal
PDR Decisões de comportamento e escopo do produto E-mails gerados por IA devem permanecer rascunhos
DDR Decisões de design e interação Mostrar sugestões de IA em um painel lateral

Juntos, os ADRs, PDRs e DDRs descrevem não apenas a estrutura do sistema, mas também a intenção do produto e o raciocínio por trás da experiência do usuário. Essa combinação é importante porque os agentes de IA podem ler código, mas o código sozinho não contém contexto suficiente para tomar boas decisões. Os registros de decisão oferecem aos sistemas de IA uma fonte durável, revisada e aprovada por humanos da intenção do projeto.

Registros de Decisão de Arquitetura (Architecture Decision Records)

Os Registros de Decisão de Arquitetura capturam decisões técnicas e estruturais. Use um ADR quando uma decisão afete a forma do sistema — suas fronteiras, dependências, modelo operacional ou manutenibilidade a longo prazo.

Exemplos de decisões que valem a pena registrar como ADRs incluem:

  • Escolher PostgreSQL como banco de dados principal
  • Usar uma arquitetura orientada a eventos para processamento em segundo plano
  • Manter a aplicação como um monólito modular
  • Introduzir uma fila de mensagens
  • Escolher REST em vez de GraphQL
  • Usar renderização no lado do servidor para a aplicação web
  • Exigir que todos os trabalhos em segundo plano sejam idempotentes
  • Adotar um modelo específico de autenticação e autorização

Um ADR não é um documento completo de arquitetura — é intencionalmente pequeno, registrando uma decisão importante em um momento específico no tempo. Um bom ADR previne a amnésia arquitetural: sem ele, contribuidores futuros podem redescobrir os mesmos trade-offs, reabrir debates antigos ou acidentalmente desfazer restrições importantes.

Na programação dirigida por IA, os ADRs carregam ainda mais peso. As ferramentas de IA são frequentemente habilidosas em otimização local e podem propor uma mudança tecnicamente plausível que viola uma restrição arquitetural maior. Um ADR dá à IA uma fronteira clara: “É assim que este sistema deve estar estruturado.”

Registros de Decisão de Produto (Product Decision Records)

Os Registros de Decisão de Produto capturam comportamento do produto, escopo e intenção voltada para o usuário. Isso é menos comum do que ADRs, mas muitas vezes é tão valioso — decisões de produto são frequentemente espalhadas por tickets, ferramentas de roadmap, threads de chat, anotações de reuniões e memórias das pessoas, tornando-as fáceis de esquecer para os humanos e quase impossíveis de inferir de forma confiável para as ferramentas de IA.

Use um PDR quando uma decisão afete o que o produto faz, quem ele atende, o que está intencionalmente fora do escopo ou como um recurso voltado para o usuário deve se comportar. Exemplos incluem:

  • Mensagens geradas por IA devem permanecer rascunhos até serem revisadas por um humano
  • Usuários do plano gratuito podem criar até três projetos
  • Workspaces excluídos são recuperáveis por 30 dias
  • Cobrança em equipe está fora do escopo para a versão 1
  • Usuários podem exportar seus dados sem contatar o suporte
  • Resumos de IA com baixa confiança mostram um aviso em vez de serem ocultos

Um PDR é especialmente útil quando uma escolha de produto parece arbitrária a partir do código. O código pode conter um limite de três projetos para usuários gratuitos e, sem um PDR, uma ferramenta de IA pode tratar esse número como uma constante mágica e sugerir alterá-lo. Com um PDR, a IA pode ver que o limite está ligado à estratégia de preços, ao custo de onboarding ou à carga de suporte — e que alterá-lo requer uma decisão de produto deliberada, não uma edição rápida.

Registros de Decisão de Design (Design Decision Records)

Os Registros de Decisão de Design capturam decisões de experiência do usuário, interação, visual e de design de conteúdo. Use um DDR quando uma decisão afete como os usuários interagem com o produto, como a informação é apresentada ou como um princípio de design deve ser aplicado em trabalhos futuros.

Exemplos de decisões de design que valem a pena registrar incluem:

  • Usar validação inline em vez de validação apenas no envio
  • Colocar sugestões de IA em um painel lateral em vez de diretamente no editor
  • Usar divulgação progressiva para configurações avançadas
  • Exigir confirmação antes de ações destrutivas
  • Usar “Rascunho” e “Publicado” em vez de “Inativo” e “Ativo”
  • Manter ações primárias visíveis em telas de celular

A intenção de design é fácil de perder durante a implementação. Um desenvolvedor pode simplificar um fluxo, ou um agente de IA pode gerar um componente que funciona tecnicamente, mas que quebra o modelo de interação pretendido. Por exemplo, um DDR pode registrar: “Mostramos sugestões de escrita de IA ao lado do documento, não dentro dele, porque os usuários precisam comparar o texto gerado com seu próprio rascunho antes de aceitar as mudanças.” Esse registro dá aos contribuidores futuros um princípio para preservar, não apenas um layout para copiar.

Por que registros de decisão importam mais com IA

As ferramentas de codificação com IA são poderosas, mas muitas vezes são desprovidas de estado (stateless) ou têm apenas uma percepção parcial do histórico do projeto. Elas podem inspecionar arquivos, inferir padrões e gerar mudanças — mas não sabem automaticamente quais decisões são intencionais, quais são acidentais e quais já foram debatidas e resolvidas. Isso cria vários riscos distintos.

A IA pode reabrir debates já resolvidos

Se a equipe já decidiu usar um monólito modular, um agente de IA ainda pode propor extrair um serviço, porque isso parece limpo isoladamente. Sem um ADR, a IA não tem uma maneira durável de saber que a equipe já considerou e rejeitou esse caminho, e o resultado é esforço desperdiçado ou uma regressão sutil na coerência do sistema.

A IA pode otimizar localmente e causar dano globalmente

Uma refatoração gerada pode tornar um arquivo mais limpo, mas violar as fronteiras do sistema. Uma mudança de interface pode reduzir a complexidade do componente, mas enfraquecer a experiência do usuário pretendida. Uma mudança de produto pode simplificar a implementação, mas quebrar pressupostos de preço ou conformidade. Os registros de decisão dão à IA um quadro de referência maior antes que ela aja com base em sinais de escopo restrito.

A IA pode preservar o código, mas perder a intenção

Um modelo pode seguir padrões existentes na base de código, mas padrões não são a mesma coisa que princípios. À vezes, o código existente é um compromisso. À vezes, é transitório. À vezes, ele existe devido a uma restrição externa que não é visível no arquivo. Os registros de decisão explicam a diferença entre “é assim que funciona” e “é por isso que foi construído desta maneira”.

A IA pode gerar um raciocínio plausível, mas incorreto

A IA pode rascunhar registros de decisão, mas também pode inventar explicações que soam confiantes, mas que não correspondem à decisão real. É por isso que a revisão humana é inegociável: a IA pode gerar o primeiro rascunho de um registro, mas um humano deve verificar se ele descreve com precisão a decisão real, as alternativas e as consequências antes que o registro seja mesclado.

Registros de decisão como parte de uma metodologia mais ampla

Os registros de decisão não são apenas documentação — eles são parte de uma maneira mais ampla de trabalhar que está na interseção da governança de arquitetura leve, docs as code, fluxos de trabalho de gestão de conhecimento aumentados por IA, descoberta de produto, racional de design, governança de IA e revisão de código. Uma maneira útil de descrever o processo maior é o Desenvolvimento Orientado a Decisões.

A maioria dos fluxos de trabalho de programação dirigida por IA se concentra estreitamente no ciclo gerar-revisar-comitar:

flowchart LR A[Prompt] --> B[Gerar código] B --> C[Testar] C --> D[Commit]

Esse ciclo é fino demais para trabalho sério de sistemas. Um fluxo de trabalho mais forte trata o repositório como um depósito de código e intenção — os diagramas aqui usam Mermaid, um formato leve que funciona bem dentro de registros de decisão em Markdown também:

flowchart TB subgraph top[" "] direction LR A[Enquadrar o problema] --> B[Identificar decisões existentes] --> C[Explorar opções e trade-offs] --> D[Registrar a decisão selecionada] end subgraph bottom[" "] direction LR E[Gerar ou modificar código] --> F[Revisar código vs decisões] --> G[Mesclar implementação e memória] --> H[Usar registro para guiar trabalho futuro] end D --> E

Esse processo transforma o repositório em algo mais do que um depósito de código. Ele se torna a fonte de verdade para implementação, intenção e raciocínio — um artefato durável que acumula valor a cada decisão tomada.

Registros de decisão e docs as code

Os registros de decisão funcionam melhor quando seguem os princípios de docs-as-code, o que significa que devem ser armazenados no mesmo repositório que o código, escritos em Markdown puro, revisados em pull requests, versionados com Git, vinculados a problemas e pull requests relacionados, e pesquisáveis tanto por humanos quanto por ferramentas de IA. Isso é muito mais confiável do que armazenar decisões importantes em chats, páginas de wiki, apresentações ou anotações de reuniões — essas ferramentas podem ainda ser úteis para discussão, mas a decisão aceita deve sempre viver próxima do código. Mantendo Especificações, Testes e Código em Sincronia no Desenvolvimento com IA estende esse mesmo hábito de “vincular de volta ao registro” para um modelo de rastreabilidade completo que liga IDs de requisito e decisão de design a testes e pull requests.

Uma estrutura de repositório bem organizada para registros de decisão pode parecer assim:

docs/
  decisions/
    architecture/
      0001-use-postgresql-for-primary-storage.md
      0002-keep-billing-inside-the-core-app.md
    product/
      0001-ai-generated-email-requires-human-review.md
      0002-free-tier-project-limit.md
    design/
      0001-use-inline-validation.md
      0002-place-ai-suggestions-in-side-panel.md

Para projetos menores, uma estrutura mais plana funciona igualmente bem. A organização exata das pastas é menos importante que a consistência — os registros devem ser fáceis de encontrar, fáceis de revisar e fáceis para as ferramentas de IA carregarem como contexto antes de agir na base de código. Para equipes Go, essa estrutura docs/decisions/ se encaixa naturalmente ao lado do layout cmd/, internal/ e api/ descrito em Estrutura de Projeto Go: Práticas e Padrões, que recomenda docs/ como lar para decisões de arquitetura e referências de API.

Um modelo prático de registro de decisão

Um modelo útil de registro de decisão deve ser curto o suficiente para que as pessoas realmente o usem. Aqui está um modelo prático em Markdown que inclui uma seção opcional, mas valiosa, de orientação para IA:

# Decisão: Título curto

Status: Proposto | Aceito | Suplantado | Obsoleto
Data: AAAA-MM-DD
Tipo: Arquitetura | Produto | Design
Responsáveis: Equipe ou nomes

## Contexto

Descreva o problema, restrições, metas, necessidades do usuário, fatos técnicos
e fatores de negócios que levaram a esta decisão.

## Decisão

Afirme a decisão claramente.

## Alternativas consideradas

### Opção 1

Prós:
- ...

Contras:
- ...

## Consequências

Descreva o que se torna mais fácil, o que se torna mais difícil e que riscos
ou trabalhos de follow-up isso cria.

## Orientação para IA

Quando um assistente de IA trabalhar nesta área, ele deve:
- Preservar ...
- Evitar ...
- Preferir ...
- Pedir revisão quando ...

## Links

- Problemas relacionados:
- Pull requests relacionados:
- Arquivos relacionados:
- Suplanta:
- Suplantado por:

A seção “Orientação para IA” é opcional, mas para a programação dirigida por IA é extremamente valiosa — ela transforma o registro de decisão em uma instrução durável para agentes futuros trabalhando na mesma área da base de código.

O que pertence a um registro de decisão?

Nem toda escolha merece um registro, e se cada pequeno detalhe de implementação se tornar um registro de decisão, o processo colapsa em ruído. Crie um registro de decisão quando uma escolha for significativa e provavelmente importará mais tarde.

Boas candidatas são decisões que:

  • Afetam várias partes do sistema
  • Codificam uma promessa de produto
  • Resolvem um debate real
  • Introduzem um trade-off a longo prazo
  • Dependem de restrições de negócios, conformidade ou operacionais
  • Seriam caras de redescobrir mais tarde
  • Ferramentas de IA futuras podem plausivelmente errar
  • Contribuidores futuros podem ser tentados a reverter casualmente

Ruínas candidatas incluem escolhas de pequenas refatorações, correções de bugs óbvias, experimentos temporários, decisões de nomenclatura local e detalhes de implementação sem consequência duradoura. Uma boa regra prática é direta: se reverter a decisão exigisse discussão, registre a decisão.

Valores de status e ciclo de vida

Os registros de decisão devem ter um ciclo de vida para sinalizar sua situação atual. Os valores de status mais simples são suficientes.

Proposto — A decisão está sendo considerada, mas ainda não foi aceita. Use isso quando a equipe deseja discutir uma decisão em um pull request antes de se comprometer com ela.

Aceito — A decisão está ativa e deve guiar o trabalho futuro. A maioria dos registros de decisão úteis passará a maior parte de sua vida neste estado.

Suplantado — A decisão foi substituída por um registro mais novo. Não apague registros antigos; mantenha-os para o histórico e vincule à decisão mais nova para que a evolução do pensamento permaneça visível.

Obsoleto — A decisão não é mais recomendada, mas ainda pode descrever partes existentes do sistema. Isso é particularmente útil durante migrações, quando padrões antigos existem na base de código ao lado de abordagens mais novas.

O princípio importante é que os registros de decisão devem ser amigáveis para acréscimos (append-friendly). Quando a equipe muda de direção, crie um novo registro e vincule o antigo, em vez de reescrever o histórico para fazer o passado parecer mais limpo.

Como a IA deve gerar registros de decisão

A IA pode ajudar a criar registros de decisão, e este é um dos melhores usos da IA no desenvolvimento de software — ela é rápida para rascunhar documentos estruturados a partir do contexto. Após uma discussão, revisão de arquitetura ou pull request, você pode pedir a um assistente de IA para rascunhar um registro:

Rascunhe um Registro de Decisão de Arquitetura para a decisão neste pull request.
Inclua contexto, alternativas, consequências e orientação para IA.
Salve como Markdown sob docs/decisions/architecture.

Para trabalho de produto:

Rascunhe um Registro de Decisão de Produto explicando por que as mensagens
geradas por IA devem permanecer rascunhos até serem revisadas pelo usuário.
Inclua impacto no usuário, comportamento fora do escopo, trade-offs e orientação para IA.

O registro gerado pela IA não deve ser confiável automaticamente, no entanto. A revisão humana deve verificar se o contexto é preciso, se a IA não inventou racional, se as alternativas listadas são reais, se as consequências são honestas e se a orientação para IA corresponde à intenção real da equipe. A IA é uma assistente de rascunho — ela não é a dona da decisão.

Como a IA deve ler registros de decisão

A outra metade da prática é instruir a IA a ler os registros antes de agir. Antes de pedir a um assistente de IA para implementar uma mudança, inclua uma instrução como esta:

Antes de modificar este recurso, leia docs/decisions.
Identifique quaisquer Registros de Decisão de Arquitetura, Produto ou Design que se apliquem.
Siga as decisões aceitas. Se sua mudança proposta conflitar com um
registro de decisão, explique o conflito antes de mudar o código.

Para tarefas maiores, reforce o papel dos registros como memória do projeto:

Use os registros de decisão como memória do projeto.
Não reverta decisões aceitas sem propor uma nova decisão suplante.
Quando gerar código, explique quais registros de decisão influenciaram a implementação.

Isso muda o papel da IA de “prever código plausível” para “operar dentro de um sistema documentado de restrições” — uma melhoria significativa na confiabilidade para projetos complexos ou de longa duração.

Registros de decisão em pull requests

Os registros de decisão devem fazer parte da revisão normal de pull request, em vez de um processo separado. Uma entrada simples na lista de verificação de PR torna o hábito visível:

## Lista de verificação de registro de decisão

- [ ] Este PR não introduz uma decisão significativa de arquitetura, produto ou design.
- [ ] Este PR introduz uma decisão significativa e inclui um novo registro de decisão.
- [ ] Este PR altera uma decisão anterior e inclui um registro suplante.
- [ ] Registros de decisão existentes relevantes foram considerados.
- [ ] Código gerado por IA segue os registros de decisão aceitos.
- [ ] Registros de decisão gerados por IA foram revisados por um humano.

Esta lista de verificação é simples, mas muda o comportamento ao lembrar à equipe que o código não é o único artefato que importa em um pull request. Também torna natural detectar quando uma mudança gerada por IA viola silenciosamente uma decisão anterior.

Registros de decisão e governança de arquitetura

A governança de arquitetura tradicional frequentemente falha porque é muito pesada, muito lenta ou muito desconectada da implementação — comitês centrais de aprovação, grandes documentos iniciais e processos de gatekeeping que bloqueiam em vez de guiar. Os registros de decisão oferecem uma alternativa mais leve que se integra diretamente ao fluxo de trabalho de desenvolvimento.

Eles não exigem um comitê central de arquitetura para cada mudança, nem bloqueiam as equipes de aprender e se adaptar. Em vez disso, criam um rastro de decisões que pode ser revisado, referenciado e construído ao longo do tempo. Isso suporta a arquitetura evolutiva: a arquitetura pode mudar, mas muda com memória, não apesar dela. A equipe pode visitar decisões antigas sem ter que redescobrir por que foram feitas, o que é uma forma mais saudável e honesta de governança:

  • Pequenos registros em vez de documentos gigantes
  • Revisão próxima do código em vez de teatro de aprovação separado
  • Contexto histórico em vez de conhecimento tribal
  • Trade-offs explícitos em vez de pressupostos ocultos

Registros de decisão e gerenciamento de produto

O trabalho de produto também precisa de memória de decisão, e esta é uma área onde o valor dos registros de decisão é frequentemente subestimado. Um roadmap diz o que pode acontecer. Um ticket diz o que construir a seguir. As analíticas dizem o que os usuários fizeram. Nenhum desses explica completamente por que um comportamento de produto existe.

Os Registros de Decisão de Produto preenchem essa lacuna e são especialmente úteis para decisões de preço e embalagem, modelos de permissão, limites e quotas, segurança e fluxos de revisão de IA, escolhas de onboarding, definições de papel do usuário, regras de colaboração, políticas de retenção de dados e fronteiras de escopo de funcionalidades. Uma vez implementadas, as decisões de produto se tornam invisíveis no código — mais tarde, alguém vê apenas o código e pergunta: “Por que isso funciona assim?” Um PDR dá a resposta em uma forma que tanto humanos quanto ferramentas de IA podem encontrar e usar.

Registros de decisão e sistemas de design

Sistemas de design frequentemente documentam componentes, tokens e regras de uso, mas raramente documentam por que o sistema funciona dessa maneira. Os Registros de Decisão de Design preenchem essa lacuna. Uma biblioteca de componentes pode dizer “use o diálogo de confirmação para ações destrutivas”, enquanto um DDR explica o racional: “Exigimos confirmação para ações destrutivas porque os usuários frequentemente trabalham com dados de equipe compartilhados, e a exclusão acidental tem um alto custo de recuperação.”

Esse racional importa além do componente específico. Ele ajuda designers, desenvolvedores e ferramentas de IA futuros a aplicar o princípio corretamente em novas situações. Sem o DDR, um agente de IA pode gerar uma interação mais rápida que pula a confirmação porque parece mais eficiente. Com o DDR, o agente pode reconhecer que preservar a propriedade de segurança é intencional e inegociável.

Como os registros de decisão suportam o desenvolvimento orientado a especificação

O desenvolvimento orientado a especificação explica o que o sistema deve fazer. Os registros de decisão explicam por que a equipe escolheu aquela direção, e a distinção importa significativamente para o trabalho assistido por IA.

Uma especificação de funcionalidade pode dizer que e-mails gerados por IA devem ser salvos como rascunhos. Um Registro de Decisão de Produto explica por que o envio automático foi rejeitado, quais riscos foram considerados e quais mudanças futuras exigiriam uma nova decisão. Uma especificação de design pode descrever uma interação de painel lateral, enquanto o DDR correspondente explica por que as edições de IA inline foram explicitamente rejeitadas e por que preservar o controle do usuário foi ponderado mais pesadamente do que a velocidade do fluxo de trabalho. Uma especificação de arquitetura pode definir uma fronteira de serviço, e seu ADR explica por que a equipe escolheu aquela fronteira em vez de uma alternativa mais simples ou mais distribuída.

A especificação guia a implementação. O registro de decisão preserva o julgamento. Juntos, eles dão aos agentes de codificação de IA tanto instruções quanto contexto – o “o quê” e o “porquê” – o que torna a combinação tão eficaz para sistemas complexos e de longa duração. Quando você adota uma cadeia de ferramentas orientada a especificação, compare como cada opção traz esse contexto à tona; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows detalha portabilidade, portões de revisão e ancoragem no repositório entre os principais setups. Para o processo neutro de cinco fases que essas ferramentas implementam, veja Fluxo de Trabalho de Desenvolvimento Orientado a Especificação Da Exigência ao Código. A maioria das ferramentas de SDD só lida com a metade “entregue” desse loop de forma limpa; Propostas Rejeitadas do OpenSpec: Uma Convenção de Memória de Decisão cobre a outra metade – registrar uma decisão rejeitada de forma durável o suficiente para que um agente a verifique antes de repropor a mesma ideia.

Registros de decisão não são especificações

Os registros de decisão estão relacionados a especificações, mas servem a um propósito diferente. Uma especificação diz “o sistema deve fazer X”, enquanto um registro de decisão diz “escolhemos X em vez de Y devido a estas restrições e trade-offs.” Esse “em vez de Y” é a parte valiosa. As ferramentas de IA frequentemente geram soluções encontrando um caminho plausível para o resultado solicitado, mas os registros de decisão lhes dizem quais caminhos plausíveis já foram explorados, avaliados e rejeitados — reduzindo a instabilidade e melhorando a qualidade do trabalho assistido por IA.

Registros de decisão não são substituto para testes

Testes verificam comportamento; registros de decisão explicam intenção. Ambos são necessários e funcionam juntos. Um teste pode exigir que e-mails gerados por IA sejam salvos como rascunhos, enquanto um Registro de Decisão de Produto explica que isso é necessário porque os usuários devem revisar a comunicação gerada por IA antes que ela saia do sistema. O teste protege o comportamento. O registro de decisão protege o significado. Juntos, tornam as mudanças futuras mais seguras e previsíveis.

Registros de decisão não são substituto para comentários de código

Comentários de código explicam detalhes locais de implementação, enquanto registros de decisão explicam decisões mais amplas. Use comentários para linhas surpreendentes, casos extremos, soluções de contorno (workarounds) e funções que não podem ser simplificadas. Use registros de decisão para por que uma arquitetura existe, por que um comportamento de produto existe, por que um padrão de interação existe e por que a equipe escolheu uma direção em vez de outra. Se a explicação afeta apenas algumas linhas, um comentário é a ferramenta certa. Se afeta a direção do sistema, um registro de decisão é a ferramenta certa.

Erros comuns

Escrever registros tarde demais

Um registro de decisão deve ser escrito quando a decisão é tomada, não meses depois, quando todos esqueceram os trade-offs. Está bem rascunhar um durante um pull request. É ainda melhor rascunhá-lo antes da implementação, enquanto a decisão ainda está sendo ativamente discutida e as alternativas estão frescas.

Tornar registros longos demais

Um registro de decisão não é um ensaio. Ele deve ser detalhado o suficiente para preservar o julgamento, mas curto o suficiente para que as pessoas realmente o leiam. Prefira clareza a completude — um registro conciso que é lido é muito mais valioso do que um abrangente que é ignorado.

Registrando decisões sem consequências

A seção de consequências é o coração do registro. Uma decisão sem consequências declaradas é muitas vezes apenas uma preferência em vez de uma decisão real. Bons registros admitem trade-offs honestamente, incluindo o que se torna mais difícil ou arriscado como resultado da escolha.

Editando registros antigos como se o histórico tivesse mudado

Quando uma decisão muda, crie um novo registro e marque o antigo como suplantado. Reescrever silenciosamente uma decisão antiga para corresponder ao estado atual destrói o contexto histórico que torna os registros de decisão valiosos. O histórico é útil precisamente porque mostra como o pensamento evoluiu. Bases de conhecimento compiladas enfrentam o problema idêntico sob um nome diferente — Manutenção de Wiki LLM: Deriva, Contradições e Revisão chama isso de deriva de decisão e aplica a mesma regra de suplantar em vez de sobrescrever às páginas de wiki.

Deixando registros gerados por IA serem mesclados sem revisão

A IA pode produzir um registro polido e bem estruturado que está sutilmente errado. Trate os registros de decisão gerados por IA exatamente como o código gerado por IA — revise-os cuidadosamente, verifique se o racional é preciso e garanta que a seção de consequências reflita o que a equipe realmente aceitou.

Escondendo registros fora do repositório

Se os registros de decisão viverem em uma wiki ou sistema de documentação separado, eles têm menos probabilidade de serem atualizados junto com mudanças de código e muito menos probabilidade de serem lidos por ferramentas de codificação de IA carregando contexto para uma tarefa. Mantê-los no repositório não é apenas uma conveniência — é o que torna a prática funcionar para o desenvolvimento assistido por IA.

Um modelo operacional leve

Um processo de equipe prático que adiciona overhead mínimo é este:

  1. Durante o planejamento ou implementação, identifique se uma decisão significativa está sendo tomada.
  2. Peça a um assistente de IA para rascunhar um ADR, PDR ou DDR com base na discussão.
  3. Revise o rascunho como equipe, verificando contexto, alternativas e consequências.
  4. Comita o registro como Markdown no repositório.
  5. Vincule-o do problema ou pull request relacionado.
  6. Instrua as ferramentas de codificação de IA a lerem os registros relevantes antes de fazer mudanças futuras na área.
  7. Suplante os registros quando as decisões mudarem, preservando o registro antigo para o histórico.

Isso não requer uma nova burocracia ou um papel dedicado de documentação. Requer um pequeno hábito: preservar o julgamento importante no momento em que é criado, próximo ao código onde será necessário.

Exemplo de ADR

# Decisão: Usar PostgreSQL para armazenamento principal da aplicação

Status: Aceito
Data: 2026-06-25
Tipo: Arquitetura
Responsáveis: Equipe de Plataforma

## Contexto

A aplicação precisa de armazenamento relacional durável para contas, projetos,
permissões e eventos de auditoria. A equipe espera consultas de relatório
frequentes e requisitos de consistência forte para verificações de permissão.

## Decisão

Usaremos o PostgreSQL como o banco de dados principal da aplicação.

## Alternativas consideradas

### DynamoDB

Prós:
- Escalável operacionalmente
- Bom encaixe para padrões de acesso chave-valor previsíveis

Contras:
- Mais complexo para consultas relacionais
- Mais difícil para relatórios ad hoc
- Menos familiar para a equipe atual

### MySQL

Prós:
- Banco de dados relacional maduro
- Modelo operacional familiar

Contras:
- PostgreSQL atende melhor às necessidades da equipe para suporte a JSON,
  opções de indexação e experiência existente

## Consequências

O PostgreSQL se torna uma dependência operacional central. A equipe deve
gerenciar migrações cuidadosamente e monitorar o desempenho das consultas.
Em troca, a aplicação obtém modelagem relacional forte, indexação madura
e suporte flexível a relatórios.

## Orientação para IA

Ao modificar o código de persistência, prefira modelagem relacional no PostgreSQL.
Não introduza um segundo banco de dados principal sem um ADR suplante.

Exemplo de PDR

# Decisão: E-mails gerados por IA devem permanecer rascunhos

Status: Aceito
Data: 2026-06-25
Tipo: Produto
Responsáveis: Equipe de Produto

## Contexto

O produto pode gerar respostas de e-mail usando IA. O envio de e-mail é uma
ação de alta confiança porque erros podem alcançar clientes, parceiros
ou equipes internas.

## Decisão

E-mails gerados por IA devem ser criados como rascunhos. Um usuário humano
deve revisá-los e enviá-los.

## Alternativas consideradas

### Enviar automaticamente

Prós:
- Fluxo de trabalho mais rápido
- Menos esforço do usuário

Contras:
- Maior risco de mensagens incorretas ou inadequadas
- Menor confiança do usuário
- Mais difícil de se recuperar de erros

### Pedir confirmação apenas após a geração

Prós:
- Mantém o fluxo de trabalho simples
- Fornece algum controle do usuário

Contras:
- Ainda encoraja revisão superficial
- Não se encaixa no comportamento do cliente de e-mail existente tão bem quanto rascunhos

## Consequências

O fluxo de trabalho é ligeiramente mais lento, mas mais seguro e confiável.
A automação futura pode melhorar a velocidade de revisão, mas não deve
burlar a aprovação humana sem um PDR suplante aceito.

## Orientação para IA

Ao criar recursos de geração de e-mail, crie rascunhos por padrão.
Não adicione envio automático, a menos que um novo PDR aceito o permita explicitamente.

Exemplo de DDR

# Decisão: Mostrar sugestões de escrita de IA em um painel lateral

Status: Aceito
Data: 2026-06-25
Tipo: Design
Responsáveis: Equipe de Design

## Contexto

Os usuários precisam de ajuda para melhorar o conteúdo escrito, mas também
precisam manter o controle do texto final. Edições de IA inline podem
tornar difícil distinguir o conteúdo escrito pelo usuário das sugestões geradas.

## Decisão

As sugestões de escrita de IA aparecerão em um painel lateral. Os usuários podem
aceitar, rejeitar ou copiar sugestões para o editor principal.

## Alternativas consideradas

### Aplicar sugestões inline

Prós:
- Rápido
- Parece integrado

Contras:
- Borda autoria
- Torna a revisão mais difícil
- Pode surpreender os usuários

### Mostrar sugestões em um modal

Prós:
- Experiência focada
- Fácil de implementar

Contras:
- Interrompe o fluxo de escrita
- Mais difícil comparar sugestão e texto original

## Consequências

O painel lateral ocupa mais espaço na tela, especialmente em telas pequenas.
No entanto, ele preserva o controle do usuário e torna a revisão mais clara.

## Orientação para IA

Ao adicionar recursos de assistência de escrita, preserve a separação entre
o texto do usuário e as sugestões de IA. Não aplique o texto gerado
diretamente no documento sem ação explícita do usuário.

Biblioteca de prompts sugerida

Use estes prompts para tornar os registros de decisão parte do desenvolvimento diário assistido por IA.

Encontrar registros relevantes antes de trabalhar em um recurso:

Leia docs/decisions e identifique quaisquer registros de decisão aceitos que
se apliquem a esta tarefa. Resuma as restrições antes de propor mudanças de código.

Rascunhar um novo ADR:

Rascunhe um Registro de Decisão de Arquitetura para esta decisão técnica.
Inclua contexto, decisão, alternativas, consequências e orientação para IA.
Mantenha-o conciso e específico.

Rascunhar um novo PDR:

Rascunhe um Registro de Decisão de Produto para este comportamento de produto.
Inclua impacto no usuário, escopo, alternativas, consequências e orientação para IA.

Rascunhar um novo DDR:

Rascunhe um Registro de Decisão de Design para este padrão de interação.
Inclua problema do usuário, alternativas, trade-offs, consequências e orientação para IA.

Revisar um pull request contra decisões existentes:

Revise este pull request contra os registros de decisão aceitos em docs/decisions.
Identifique quaisquer conflitos, registros de decisão ausentes ou decisões que
devem ser suplantadas.

Suplantar uma decisão:

Crie um novo registro de decisão que suplante o existente.
Preserve o racional histórico, explique o que mudou e vincule ambos os registros.

Leitura relacionada

Subscrever

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.