Templates ADR para GenAI

Architecture Decision Records (ADRs) são documentos curtos que capturam decisões arquiteturais importantes junto com seu contexto e consequências. Pense como um "diário técnico" do projeto - cada decisão significativa fica registrada para consulta futura.

Por que usar ADRs em projetos GenAI?

• Decisões são complexas: Escolher entre RAG vs Fine-tuning, qual LLM usar, como implementar guardrails
• Tecnologia evolui rápido: O que era melhor há 6 meses pode não ser mais
• Equipes mudam: Novos membros precisam entender o "porquê" das escolhas
• Auditoria e compliance: Regulamentações como AI Act exigem documentação de decisões
• Evitar rediscussões: Documentar trade-offs aceitos conscientemente

Benefícios concretos:

1. Economiza reuniões - Novas pessoas leem o ADR ao invés de perguntar "por que usamos X?"
2. Evita repetição de erros - Alternativas descartadas ficam documentadas
3. Facilita mudanças - Quando contexto muda, você sabe exatamente o que reavaliar
4. Demonstra maturidade - Auditores e clientes enterprise valorizam documentação

Os 8 Templates Especializados para GenAI

Criamos 8 templates que cobrem as decisões mais comuns em projetos de IA Generativa:

1. Seleção de LLM

Quando usar: Ao escolher qual modelo de linguagem usar (GPT-4, Claude, Llama, etc.)

• Requisitos do caso de uso (latência, custo, qualidade)
• Benchmark comparativo dos modelos
• Análise de custo por token
• Considerações de vendor lock-in
• Estratégia de fallback

*Exemplo:* "Decidimos usar Claude 3.5 Sonnet como modelo principal devido ao melhor custo-benefício para nosso caso de uso de análise de documentos longos (200K context window), com GPT-4o-mini como fallback."

2. Design de RAG

Quando usar: Ao projetar o pipeline de Retrieval-Augmented Generation.

• Estratégia de chunking (tamanho, overlap)
• Modelo de embedding escolhido
• Vector store selecionado
• Estratégia de retrieval (dense, sparse, hybrid)
• Decisão sobre reranking

*Exemplo:* "Implementaremos RAG híbrido com chunks de 512 tokens, overlap de 50, usando text-embedding-3-small para embeddings, Qdrant como vector store, e Cohere Rerank v3 para reranking dos top-20 resultados."

3. Design de Agentes

Quando usar: Ao projetar sistemas de agentes autônomos com LangGraph, CrewAI, etc.

• Padrão de orquestração (ReAct, Plan-and-Execute, Supervisor)
• Tools disponíveis e suas permissões
• Estratégia de memória (curta, longa, episódica)
• Limites de iteração e timeout
• Mecanismos de human-in-the-loop

*Exemplo:* "Usaremos padrão Supervisor com 3 agentes especializados (Researcher, Analyst, Writer), limite de 15 iterações, checkpoint a cada 5 steps, e aprovação humana obrigatória para ações que modifiquem dados."

4. Guardrails e Segurança

Quando usar: Ao definir mecanismos de segurança e validação de conteúdo.

• Classificação de riscos (PII, toxicidade, alucinação)
• Guardrails de input (validação, sanitização)
• Guardrails de output (filtros, verificação)
• Estratégia de detecção de jailbreak
• Logging e auditoria de segurança

*Exemplo:* "Implementaremos guardrails em 3 camadas: (1) validação de input com regex + classificador de intent malicioso, (2) system prompt com instruções defensivas, (3) filtro de output com Presidio para PII e classificador de toxicidade."

5. Estratégia de Avaliação

Quando usar: Ao definir como medir qualidade do sistema GenAI.

• Métricas selecionadas (RAGAS, custom)
• Golden dataset e sua manutenção
• Frequência de avaliação
• Thresholds de qualidade (go/no-go)
• Processo de regression testing

*Exemplo:* "Avaliaremos com RAGAS (faithfulness > 0.85, relevancy > 0.80) semanalmente, usando golden set de 200 Q&A pairs revisados por SMEs. Deploy bloqueado se métricas caírem mais de 5%."

6. Estratégia de Dados

Quando usar: Ao definir como dados serão ingeridos, processados e armazenados.

• Fontes de dados e conectores
• Pipeline de ingestão (batch, streaming, CDC)
• Estratégia de atualização (full refresh, incremental)
• Governança e qualidade de dados
• Retenção e compliance (LGPD, GDPR)

*Exemplo:* "Ingestão incremental diária via Airflow, com CDC para documentos críticos. Dados pessoais anonimizados antes do embedding. Retenção de 2 anos com soft-delete para auditoria."

7. Estratégia de Integração

Quando usar: Ao definir como o sistema GenAI se conecta com outros sistemas.

• APIs expostas e contratos
• Integrações upstream/downstream
• Estratégia de autenticação
• Rate limiting e quotas
• Circuit breaker e fallbacks

*Exemplo:* "API REST com OpenAPI 3.0, autenticação via API Key + JWT para sessões. Rate limit de 100 req/min por tenant. Circuit breaker com fallback para cache em caso de falha do LLM provider."

8. Infraestrutura e Deploy

Quando usar: Ao definir como o sistema será deployado e operado.

• Ambiente de execução (K8s, serverless, managed)
• Estratégia de scaling (horizontal, vertical)
• CI/CD pipeline
• Disaster recovery e backup
• Custos e otimização

*Exemplo:* "Deploy em EKS com HPA baseado em CPU e queue depth. CI/CD via GitHub Actions com deploy canary (10% -> 50% -> 100%). Backup diário do vector store para S3. Budget mensal de $5K com alertas em 80%."