SPEC-Driven Development · MOFU · IT

ADRs para decisões de IA, RAG, modelos e ferramentas

Por Adriano Schneider · · 9 min de leitura

Seis meses depois do go-live, ninguém lembra por que foi escolhido RAG em vez de fine-tuning, por que LangGraph em vez de CrewAI, por que Claude em vez de GPT. Quando o modelo vai ser revisado ou a arquitetura vai mudar, a equipe recomeça a discussão do zero. ADRs resolvem esse problema — e em projetos de IA, onde as decisões são especialmente impactantes e frequentes, eles são indispensáveis.

O que é um ADR e por que surgiu

ADR (Architecture Decision Record) é um conceito da engenharia de software tradicional que ganhou novo peso em projetos de IA. A ideia original, de Michael Nygard (2011): toda decisão arquitetural significativa merece um documento curto que registra o contexto, as alternativas consideradas, a escolha feita e as consequências esperadas.

Em software convencional, as decisões mais comuns que merecem ADR são: banco de dados relacional vs. NoSQL, linguagem de programação, padrão de API (REST vs. GraphQL), estratégia de autenticação. São decisões que impactam o projeto inteiro e que seriam custosas de reverter.

Em projetos de IA, esse conjunto se expande drasticamente. Cada projeto de LLM tem pelo menos 5–8 decisões que se encaixam nessa categoria: qual modelo usar, como atualizar o conhecimento do modelo, qual framework de orquestração, como gerenciar memória de longo prazo, onde e como logar conversas.

Vou ser direto: em 2026, o maior custo de manutenção que vejo em projetos de IA não é o custo de tokens — é o custo de tempo perdido rediscutindo decisões que já foram tomadas e cujo racional foi para o Slack e nunca mais foi encontrado.

Quando escrever um ADR em projetos de IA

A regra prática: se a decisão seria custosa de reverter ou afetará como toda a equipe trabalha no projeto, ela merece um ADR. Em projetos de LLM, as categorias mais comuns:

Decisões de modelo

Decisões de conhecimento

Decisões de orquestração

Decisões de compliance e privacidade

Estrutura do ADR para projetos de IA

O ADR clássico tem 5 seções: título, status, contexto, decisão, consequências. Para projetos de IA, adiciono 3 seções específicas que resolvem questões recorrentes: alternativas consideradas (com critérios de comparação), critérios de revisão (quando rever a decisão) e referências (experimentos e benchmarks que embasaram a escolha).

Template ADR com exemplo preenchido — RAG vs Fine-tuning

Este é o artefato central deste artigo. O exemplo cobre a decisão mais comum em projetos de IA B2B: usar RAG ou fine-tuning para adaptar o modelo ao domínio da empresa.

# ADR-003 — Estratégia de adaptação de domínio: RAG vs Fine-tuning

**Status:** Aceito
**Data:** 2026-03-15
**Autor:** Adriano Schneider
**Revisores:** [Equipe Técnica]
**Deprecia:** —
**Deprecado por:** —

---

## Contexto

O assistente de suporte técnico precisa responder perguntas sobre os produtos da empresa usando informações atualizadas do catálogo, manuais técnicos e procedimentos de instalação. O modelo base (Claude 3.5 Sonnet) não tem conhecimento específico dos produtos — os dados não estão no corpus de treinamento.

Precisamos decidir como adaptar o modelo ao domínio antes do piloto (previsto para 2026-04-01). A decisão afeta custo, tempo de implementação, manutenibilidade e qualidade das respostas.

**Restrições que influenciam a decisão:**
- Dataset disponível: 847 documentos técnicos (manuais, FAQs, procedimentos) — totalizando ~1,2 M de tokens
- Orçamento para adaptação de modelo: R$ 20.000
- Prazo para piloto: 6 semanas
- Frequência de atualização de catálogo: mensal (novos produtos a cada mês)
- Tamanho da equipe técnica: 2 engenheiros part-time neste projeto

---

## Alternativas Consideradas

### Alternativa A — RAG (Retrieval-Augmented Generation)

Indexar os documentos técnicos em banco vetorial. A cada query do usuário, recuperar os trechos mais relevantes e injetá-los na context window do modelo junto com a pergunta.

**Prós:**
- Atualização imediata: novo documento indexado → disponível para consulta em minutos
- Custo de implementação dentro do orçamento (R$ 8.000–15.000 estimado)
- Viável em 4 semanas com 2 engenheiros
- Rastreabilidade: resposta inclui referência ao documento fonte
- Sem custo de treinamento de modelo

**Contras:**
- Qualidade depende da qualidade do chunking e do ranking de recuperação
- Pode falhar quando a resposta exige síntese de múltiplos documentos
- Adiciona latência de busca (50–200ms por query)
- Custo de infraestrutura de banco vetorial (R$ 300–800/mês)

### Alternativa B — Fine-tuning supervisionado

Criar dataset de pares pergunta-resposta baseados nos documentos técnicos. Treinar uma versão do modelo específica para o domínio da empresa.

**Prós:**
- Respostas mais fluentes e contextualmente alinhadas ao domínio
- Sem latência adicional de busca
- Pode ser mais barato por query em alto volume

**Contras:**
- Dataset de 847 documentos é insuficiente — fine-tuning de qualidade exige 5.000+ exemplos rotulados
- Custo de criação de dataset rotulado: R$ 25.000–50.000 (fora do orçamento)
- Prazo: 12–16 semanas (inviável para o piloto)
- Conhecimento estático: atualização de catálogo exige novo ciclo de fine-tuning
- Risco de overfitting com dataset pequeno

### Alternativa C — Few-shot sem recuperação

Incluir exemplos fixos de produtos mais consultados diretamente no system prompt.

**Prós:**
- Implementação mais simples
- Sem infraestrutura adicional

**Contras:**
- Não escala para 847 documentos — cobertura de produto muito limitada
- Atualização manual e propensa a erro
- Descartada na POC por cobertura insuficiente (42% de acerto vs. 79% do RAG)

---

## Decisão

**Escolhemos RAG (Alternativa A).**

Motivação principal: o dataset disponível é insuficiente para fine-tuning de qualidade, e o cronograma de 6 semanas torna o fine-tuning inviável. Além disso, a atualização mensal do catálogo torna o RAG estruturalmente mais adequado — um fine-tuning mensal seria operacionalmente inviável para o time atual.

Os resultados da POC confirmam viabilidade: RAG com chunking de 512 tokens e modelo de embedding text-embedding-3-small atingiu 79% de acurácia nos 120 casos de teste — acima do threshold mínimo de 75% definido pelo negócio.

**Configuração aprovada para o piloto:**
- Banco vetorial: pgvector (PostgreSQL) — aproveitando infraestrutura existente
- Modelo de embedding: text-embedding-3-small (OpenAI)
- Chunking: 512 tokens com sobreposição de 64 tokens
- Top-K: 5 trechos recuperados por query
- Reranking: sem reranker na v1 (avaliar na v2 se qualidade exigir)

---

## Consequências

**Positivas:**
- Piloto viável dentro do prazo e orçamento
- Atualização de catálogo operacionalmente simples (pipeline de reindexação automatizado)
- Rastreabilidade de fonte de cada resposta

**Negativas e riscos a monitorar:**
- Qualidade pode degradar para perguntas que exigem síntese de 10+ documentos → monitorar taxa de escalada para humano
- Custo de embedding na atualização mensal: ~R$ 50–100/mês (aceitável)
- Se volume crescer acima de 5.000 queries/dia, avaliar cache de embeddings

---

## Critérios para Revisão desta Decisão

Rever esta ADR se qualquer uma das seguintes condições ocorrer:

  • Taxa de acurácia cair abaixo de 75% por 2 semanas consecutivas em produção
  • Dataset rotulado atingir 5.000+ exemplos (reconsiderar fine-tuning)
  • Custo mensal de embedding superar R$ 500
  • Volume de queries superar 10.000/dia (avaliar modelo local para reduzir latência)
  • Novo modelo base com janela de contexto > 500k tokens (avaliar long-context sem RAG)

---

## Referências

  • Resultados da POC: `/docs/poc/relatorio-poc-2026-02-28.md`
  • Dataset de teste: `/testes/dados/casos-teste-120.jsonl`
  • Benchmark de modelos de embedding testados: `/docs/poc/benchmark-embeddings.xlsx`
  • Artigo técnico de referência: "RAG vs Fine-tuning" — Databricks Blog, 2025
  • Estimativa de custo fine-tuning: `/docs/poc/analise-custo-finetuning.md`

Onde guardar os ADRs no repositório

A convenção mais adotada: pasta /docs/adr/ na raiz do repositório, com um arquivo por ADR numerado sequencialmente:

O arquivo /docs/adr/README.md lista todos os ADRs com status e descrição de uma linha — funciona como índice. O PLAN.md do projeto referencia os ADRs relevantes na seção "Decisões Tomadas".

Ferramentas úteis: adr-tools (CLI para criar e gerenciar ADRs no formato Nygard), ou simplesmente criar arquivos .md na mão seguindo o template.

O que muda nos ADRs de projetos de IA

Algumas características específicas de IA que os ADRs precisam capturar:

Decisões com prazo de validade

O campo de LLM muda rapidamente. Uma decisão de modelo tomada em 2024 pode estar desatualizada em 2026. Por isso, a seção "Critérios para Revisão" é mais crítica em IA do que em software convencional. Datas e métricas concretas de revisão evitam que decisões obsoletas vivam para sempre no projeto.

Decisões baseadas em experimento, não em teoria

Em software convencional, muitas decisões são tomadas por raciocínio arquitetural. Em IA, a decisão certa frequentemente só é determinada empiricamente — por um benchmark, por uma POC, por um teste A/B. O ADR precisa referenciar esses experimentos explicitamente, caso contrário a justificativa parece arbitrária.

Decisões com implicações de privacidade

Enviar dados à API de um modelo proprietário pode ter implicações de LGPD. Cada decisão de modelo precisa incluir uma análise de quais dados serão processados e se o DTP (Data Processing Terms) do provedor é compatível com as obrigações da empresa. Isso precisa estar documentado.

ADRs no ecossistema SPEC-driven

Os ADRs são a camada de decisão dentro da abordagem SPEC-driven para projetos de IA. O fluxo:

  1. Experimento ou análise gera evidência (POC, benchmark, análise de custo)
  2. ADR registra a decisão com base nessa evidência
  3. PLAN.md lista as decisões tomadas e referencia os ADRs
  4. Requisitos funcionais são escritos dentro das restrições estabelecidas pelos ADRs
  5. TASKS.md decompõe os requisitos em tarefas que respeitam as decisões dos ADRs

Esse fluxo garante rastreabilidade completa: qualquer linha de código pode ser rastreada até a tarefa, que aponta para o requisito, que está dentro das restrições da ADR, que registra o raciocínio do experimento. Isso vale ouro quando um novo engenheiro entra no time, quando um cliente questiona uma decisão, ou quando a equipe precisa avaliar se ainda faz sentido continuar com o modelo escolhido.

Para uma análise aprofundada das diferenças entre fine-tuning e RAG, com critérios de decisão mais detalhados, o artigo específico cobre cada abordagem em profundidade. E para entender como o RAG funciona internamente, o artigo de fundamentos é o ponto de partida.

Erros comuns ao escrever ADRs em projetos de IA

1. ADR vazio de contexto

"Decidimos usar Claude porque é melhor." Não serve. Melhor em quê? Para qual caso de uso? Com qual dataset de teste? O contexto precisa ser específico o suficiente para que alguém de fora reconstrua o raciocínio.

2. Alternativas não consideradas

Se o ADR lista apenas uma opção, ele não é um ADR — é uma justificativa post-hoc. A seção de alternativas precisa documentar genuinamente o que foi avaliado e por que foi descartado. Isso protege a decisão de questionamentos futuros e ajuda quem precisar revisar a entender o espaço de soluções.

3. Sem critérios de revisão

Em IA, uma decisão sem critério de revisão é uma decisão que vai ficar desatualizada silenciosamente. O campo evolui rápido demais para deixar decisões arquiteturais sem uma data ou condição de reavaliação.

4. ADR sem referência a experimentos

A força de um ADR em IA está nos dados que o embasam. ADR sem referência a benchmarks, POCs ou análises de custo é uma decisão de opinião — e opiniões são mais fáceis de contestar do que evidências.

Conclusão: ADR é memória organizacional

Projetos de IA tomam mais decisões arquiteturais em menos tempo do que a maioria dos projetos de software. Modelo, embedding, banco vetorial, framework de agente, estratégia de memória, política de logging — são facilmente 8–12 decisões só no primeiro mês.

Sem registro, esse conhecimento fica na cabeça de uma ou duas pessoas. Quando essas pessoas saem do projeto ou ficam sobrecarregadas com outras demandas, o projeto fica sem memória das próprias decisões. ADRs resolvem isso de forma simples, barata e rastreável.

Comece pelo que está travando discussões hoje. Escreva o ADR para a decisão mais recente e mais difícil. Depois documente as anteriores. Em 30 dias, você terá um registro vivo que vai economizar horas de reunião e meses de retrabalho.