Registros de Decisão para o Desenvolvimento de Software Orientado por IA

Mantenha a intenção próxima ao 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 torna-se 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 altera a economia do desenvolvimento de software ao tornar 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 existe.

Os registros de decisão resolvem esse problema fornecendo um documento curto, com controle de versão, 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 — tornam-se uma memória de projeto durável que humanos e agentes de codificação de IA podem ler antes de fazer alterações futuras. A regra operacional prática é simples: mantenha os registros de decisão como arquivos Markdown no repositório, revise-os como código e permita que ferramentas de IA futuras os leiam antes de propor ou implementar alterações.

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, quais alternativas consideramos e quais 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 como rascunhos
DDR Decisões de design e interação Mostrar sugestões de IA em um painel lateral

Juntos, 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 fornecem aos sistemas de IA uma fonte revisada, durável e aprovada por humanos da intenção do projeto.

Registros de Decisão de Arquitetura

Os Registros de Decisão de Arquitetura capturam decisões técnicas e estruturais. Use um ADR quando uma decisão afetar a forma do sistema — seus limites, 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 o aplicativo como um monólito modular
  • Introduzir uma fila de mensagens
  • Escolher REST em vez de GraphQL
  • Usar renderização no lado do servidor para o aplicativo 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 do tempo. Um bom ADR previne a amnésia arquitetônica: sem ele, contribuidores futuros podem redescobrir as mesmas compensações, reabrir debates antigos ou acidentalmente desfazer restrições importantes.

Na programação dirigida por IA, os ADRs têm 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 um limite claro: “É assim que este sistema deve ser moldado.”

Registros de Decisão de Produto

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 os ADRs, mas muitas vezes é tão valioso — decisões de produto frequentemente se espalham por tickets, ferramentas de roteiro, threads de chat, notas de reunião e memórias das pessoas, tornando-as fáceis para os humanos esquecerem e quase impossíveis para as ferramentas de IA inferirem de forma confiável.

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

  • Mensagens geradas por IA devem permanecer como rascunhos até serem revisadas por um humano
  • Usuários do nível gratuito podem criar até três projetos
  • Espaços de trabalho excluídos são recuperáveis por 30 dias
  • Faturamento de equipe está fora do escopo para a versão 1
  • Os 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á vinculado à estratégia de preços, custo de onboarding ou carga de suporte — e que alterá-lo exige uma decisão de produto deliberada, não uma edição rápida.

Registros de Decisão de Design

Os Registros de Decisão de Design capturam decisões de experiência do usuário, interação, visuais e design de conteúdo. Use um DDR quando uma decisão afetar 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 revelaçã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 móveis

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 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 alterações.” Esse registro dá aos contribuidores futuros um princípio para preservar, não apenas um layout para copiar.

Por que os registros de decisão são mais importantes com IA

As ferramentas de codificação de IA são poderosas, mas muitas vezes são sem estado ou apenas parcialmente cientes do histórico do projeto. Elas podem inspecionar arquivos, inferir padrões e gerar alterações — 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 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 em isolamento. 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 danificar globalmente

Uma refatoração gerada pode tornar um arquivo mais limpo enquanto viola os limites do sistema. Uma mudança de UI pode reduzir a complexidade do componente enquanto enfraquece a experiência do usuário pretendida. Uma mudança de produto pode simplificar a implementação enquanto quebra suposições de preço ou conformidade. Os registros de decisão dão à IA um quadro de referência maior antes de agir 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. Às vezes, o código existente é um compromisso. Às vezes, é transitório. Às 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 uma justificativa plausível, mas errada

A IA pode redigir registros de decisão, mas também pode inventar explicações que soam confiantes e 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 de governança de arquitetura leve, documentação como código, fluxos de trabalho de gerenciamento 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 foca estreitamente no loop gerar-revisar-commit:

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

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

flowchart TB subgraph top[" "] direction LR A[Enquadrar o problema] --> B[Identificar decisões existentes] --> C[Explorar opções e compensações] --> 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

Este processo transforma o repositório em mais do que uma loja 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 documentação como código

Os registros de decisão funcionam melhor quando seguem os princípios de documentação como código, o que significa que devem ser armazenados no mesmo repositório que o código, escritos em Markdown simples, 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 notas de reunião — essas ferramentas ainda podem ser úteis para discussão, mas a decisão aceita deve sempre viver perto do código.

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 importa menos do 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 de Go, essa estrutura docs/decisions/ se encaixa naturalmente ao lado do layout cmd/, internal/ e api/ descrito em Go Project Structure: Practices & Patterns, que recomenda docs/ como o lar para decisões de arquitetura e referências de API.

Um modelo prático de registro de decisão

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

# Decisão: Título curto

Status: Proposto | Aceito | Substituído | Descontinuado
Data: AAAA-MM-DD
Tipo: Arquitetura | Produto | Design
Donos: Equipe ou nomes

## Contexto

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

## Decisão

Enuncie 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 quais riscos
ou trabalhos de acompanhamento isso cria.

## Orientação de 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:
- Substitui:
- Substituído por:

A seção “Orientação de IA” é opcional, mas para 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 colapsará em ruído. Crie um registro de decisão quando uma escolha for significativa e provavelmente importar mais tarde.

Bons candidatos são decisões que:

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

Pobres candidatos incluem pequenas escolhas de refatoração, 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 exigir 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 seu status atual. Os valores de status mais simples são suficientes.

Proposto — A decisão está sendo considerada, mas ainda não aceita. Use isso quando a equipe quiser 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.

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

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

O princípio importante é que os registros de decisão devem ser amigáveis à adição. 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 em redigir 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 que redija um registro:

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

Para trabalho de produto:

Redija um Registro de Decisão de Produto explicando por que as mensagens geradas por IA
devem permanecer como rascunhos até serem revisadas pelo usuário.
Inclua impacto no usuário, comportamento fora do escopo, compensações e orientação de IA.

O registro gerado por IA não deve ser confiado automaticamente, no entanto. A revisão humana deve verificar se o contexto é preciso, se a IA não inventou justificativa, se as alternativas listadas são reais, se as consequências são honestas e se a orientação de IA corresponde à intenção real da equipe. A IA é uma assistente de redação — 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 que implemente 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 alterar 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 substituente.
Ao 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 requests, em vez de um processo separado. Uma entrada simples na lista de verificação do 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 substituto.
- [ ] Registros de decisão existentes relevantes foram considerados.
- [ ] O 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 capturar 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 — conselhos centrais de aprovação, documentos grandes e upfront, e processos de controle 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 conselho central de arquitetura para cada mudança, nem bloqueiam equipes de aprender e se adaptar. Em vez disso, eles criam um rastro de decisões que podem ser revisadas, referenciadas e construídas 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 revisitair decisões antigas sem ter que redescobrir por que foram feitas, o que é uma forma mais saudável e honesta de governança:

  • Registros pequenos em vez de documentos gigantes
  • Revisão próxima ao código em vez de teatro de aprovação separado
  • Contexto histórico em vez de conhecimento tribal
  • Compensações explícitas em vez de suposições ocultas

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 roteiro diz o que pode acontecer. Um ticket diz o que construir em seguida. As análises dizem o que os usuários fizeram. Nenhum desses explica totalmente 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ços e embalagens, modelos de permissão, limites e cotas, fluxos de segurança e revisão de IA, escolhas de onboarding, definições de funções de usuário, regras de colaboração, políticas de retenção de dados e limites de escopo de recursos. 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 funciona assim?” Um PDR dá a resposta de uma forma que humanos e ferramentas de IA podem encontrar e usar.

Registros de decisão e sistemas de design

Os 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 a justificativa: “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 custo de recuperação alto.”

Essa justificativa importa além do componente específico. Ela 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 dirigido por especificação

O desenvolvimento dirigido por especificação explica o que o sistema deve fazer. Os registros de decisão explicam por que a equipe escolheu essa direção, e a distinção é significativa para o trabalho assistido por IA.

Uma especificação de recurso pode dizer que os 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 fortemente do que a velocidade do fluxo de trabalho. Uma especificação de arquitetura pode definir um limite de serviço, e seu ADR explica por que a equipe escolhou esse limite 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 “por quê” — o que torna a combinação tão eficaz para sistemas complexos e de longa duração.

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

Os registros de decisão estão relacionados às 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 essas restrições e compensações.” 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 rotatividade e melhorando a qualidade do trabalho assistido por IA.

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

Testes verificam o comportamento; registros de decisão explicam a intenção. Ambos são necessários e trabalham juntos. Um teste pode impor que os e-mails gerados por IA devem ser 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 substitutos para comentários de código

Comentários de código explicam detalhes de implementação local, enquanto registros de decisão explicam decisões mais amplas. Use comentários para linhas surpreendentes, casos de borda, soluções alternativas e funções que não podem ser simplificadas. Use registros de decisão para explicar 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 muito tarde

Um registro de decisão deve ser escrito quando a decisão é tomada, não meses depois, quando todos esqueceram as compensações. É aceitável redigir um durante um pull request. É ainda melhor redigir antes da implementação, enquanto a decisão ainda está sendo ativamente discutida e as alternativas estão frescas.

Tornar os registros muito longos

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

Registrar decisões sem consequências

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

Editar registros antigos como se o histórico tivesse mudado

Quando uma decisão muda, crie um novo registro e marque o antigo como substituído. 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.

Permitir que registros gerados por IA sejam 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 código gerado por IA — revise-os cuidadosamente, verifique se a justificativa é precisa e garanta que a seção de consequências reflita o que a equipe realmente aceitou.

Esconder registros fora do repositório

Se os registros de decisão vivem em um wiki separado ou sistema de documentação, eles são menos propensos a serem atualizados junto com as alterações de código e muito menos propensos a 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 faz a prática funcionar para o desenvolvimento assistido por IA.

Um modelo operacional leve

Um processo prático de equipe que adiciona sobrecarga mínima parece assim:

  1. Durante o planejamento ou implementação, identifique se uma decisão significativa está sendo tomada.
  2. Peça a um assistente de IA que redija um ADR, PDR ou DDR com base na discussão.
  3. Revise o rascunho como equipe, verificando contexto, alternativas e consequências.
  4. Commit do 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 ler os registros relevantes antes de fazer alterações futuras na área.
  7. Substitua 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 do aplicativo

Status: Aceito
Data: 2026-06-25
Tipo: Arquitetura
Donos: Equipe de plataforma

## Contexto

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

## Decisão

Usaremos PostgreSQL como banco de dados principal do aplicativo.

## Alternativas consideradas

### DynamoDB

Prós:
- Escalável operacionalmente
- Boa adequação 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 torna-se uma dependência operacional central. A equipe deve gerenciar
migrações cuidadosamente e monitorar o desempenho das consultas. Em troca, o
aplicativo obtém modelagem relacional forte, indexação madura e
suporte flexível para relatórios.

## Orientação de 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 substituto.

Exemplo de PDR

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

Status: Aceito
Data: 2026-06-25
Tipo: Produto
Donos: Equipe de produto

## Contexto

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

## Decisão

Os e-mails gerados por IA devem ser criados como rascunhos. Um usuário humano deve
revisar 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 recuperar de erros

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

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

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

## Consequências

O fluxo de trabalho é um pouco mais lento, mas mais seguro e confiável.
Automação futura pode melhorar a velocidade de revisão, mas não deve contornar
a aprovação humana sem um PDR substituto.

## Orientação de IA

Ao construir 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
Donos: Equipe de design

## Contexto

Os usuários precisam de ajuda para melhorar o conteúdo escrito, mas também precisam permanecer
no controle do texto final. Edições de IA inline podem dificultar a
distinção entre conteúdo escrito pelo usuário e 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:
- Embarca a 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, preserva o controle do usuário e torna a revisão mais clara.

## Orientação de IA

Ao adicionar recursos de assistência de escrita, preserve a separação entre
texto do usuário e sugestões de IA. Não aplique 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 alterações de código.

Redigir um novo ADR:

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

Redigir um novo PDR:

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

Redigir um novo DDR:

Redija um Registro de Decisão de Design para este padrão de interação.
Inclua problema do usuário, alternativas, compensações, consequências e orientação de 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 substituídas.

Substituir uma decisão:

Crie um novo registro de decisão que substitua o existente.
Preserve a justificativa histórica, explique o que mudou e vincule ambos os registros.

Leitura relacionada

Assinar

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