Enterprise LLM Architecture · Stratago

The Architect's Playbook
Padrões para produção com Claude

Guia de referência para arquitetos que constroem sistemas de IA em produção. Cada padrão documentado aqui tem uma implementação concreta nos crews do Kit Sênior — não é teoria, é o código que já roda.

📐 5 padrões arquiteturais 🧩 4 domínios de implantação 🧠 Taxonomia I2A2 de memória 📊 Reference Matrix
4 Domínios de Implantação

Cada domínio, seus próprios padrões e anti-padrões

Quatro contextos com características únicas de latência, estado, controle e acurácia. Cada um conectado a um crew do Kit Sênior.

Structured Data Extraction
High VolumeStrict SchemasBatch Pipelines

Extração em larga escala com esquemas rígidos e pipelines assíncronos. O desafio central é manter consistência matemática e tratar nulos sem alucinações.

Resilient Catch-All enums com campo other_detail para edge cases
Schema Redundancy: calculated_total != stated_total dispara revisão humana
Null Handling explícito no prompt — nunca depender de temperatura 0 isolada
Batch API para documentos com SLA > 30h (50% de economia)
Crew relacionado 🔍 Code Review — SOLIDChecker + SecurityScan
→
// Schema Output com Schema Redundancy
{ "entity": "Order", "calculated_total": 210.50, // model sum "stated_total": 260.00, // from doc "flag_review": true // mismatch! }
Anti-Pattern detectado

18% das extrações apresentam mismatch por OCR. Schema Redundancy captura automaticamente e roteia para revisão humana.

Customer Support Orchestration
StatefulHuman-in-the-LoopPolicy Constraints

Sessões com estado, política de conformidade zero-tolerância e escalation inteligente. O modelo não deve ter discrição em operações financeiras críticas.

Application-Layer Intercept bloqueia server-side — não via prompt
Context Pruning filtra tool_results obsoletos ao retomar sessões
Escalation Handoff: structured summary com Customer ID, Root Cause, Amount
Crew relacionado 🏗️ Architecture Review — CAPTheoremAdvisor
→
// Orchestration Flow
ORCHESTRATOR
↓
AI AGENT
↓
POLICY VIOLATION
HUMAN REVIEW
APPROVED ✓
Regra arquitetural: "NEVER process >$500" em prompt ainda resulta em 3% de falha. Interceptação na camada de aplicação remove completamente a discrição do modelo.
Developer Productivity
Dynamic TasksIterative ContextMCP Tools

Tarefas dinâmicas com exploração iterativa de codebase. O desafio central é evitar context bloat ao ler arquivos sequencialmente.

Directed Exploration: analyze imports → trace implementations → generate subtasks
Scratchpad Pattern: agente mantém scratchpad.md para sessões longas
MCP Tool Specificity: dividir analyze_deps em list_imports + resolve_transitive
Relacionado a 🎓 CCA-F D3 — Claude Code & Workflows
→
// MCP Tool Granularity
// Anti-Pattern: tool monolítica ignorada analyze_dependencies("src/") // Pattern: granular e descritiva list_imports("src/main.py") resolve_transitive(["fastapi","pydantic"]) detect_circular("src/")
O Kit Sênior implementa este padrão: 7 tools MCP granulares (kit_solid_check, kit_security_scan, kit_rag_config...) em vez de uma única ferramenta genérica.
Multi-Agent Systems
Parallel SubagentsShared Vector StoreStructured Intermediates

Síntese de múltiplas fontes com risco de inconsistência entre agentes. O desafio é garantir que os outputs parciais sejam comparáveis antes da síntese final.

Structured Intermediates: Format Conversion Layer antes do Synthesis Agent
tool_choice enforcement garante ordem de execução — não prompt begging
Citation Rule: require claim-source mappings através do pipeline
Implementado em 🏗️ Architecture Review — 4 agentes sequenciais
→
// SYNTHESIS_EXCHANGE
AGENT_A
AGENT_B
⬡ SHARED VECTOR STORE
WRITE · SEMANTIC_SEARCH · READ
O Kit Sênior usa Process.sequential com output de cada agente como contexto do próximo — padrão de Structured Intermediates em ação.
Padrões vs Anti-Padrões

Designing for Production Resilience

5 armadilhas comuns e as soluções arquiteturais. Cada padrão tem implementação concreta no Kit Sênior.

Pattern 01 Enums Frágeis vs Resilient Catch-Alls SOLIDChecker
✗ Anti-Pattern: Fragile Expansion

Expandir enums continuamente. "studio" e "converted warehouse" quebram validação em produção.

// Fails em produção: "property_type": "studio"
✓ Pattern: Resilient Catch-All

Adicionar "other" + campo property_type_detail captura qualquer valor novo sem quebrar schema.

// Robusto: "property_type": "other", "property_type_detail": "studio"
Pattern 02 Alucinações em Nulos vs Null Handling Explícito HAL-006
✗ Anti-Pattern: Plausible Hallucination

Campos anuláveis sem instrução explícita — modelo inventa dados plausíveis.

// Inventado: "count": "500" // hallucination
✓ Pattern: Explicit Null Instruction

Prompt explícito: "If not mentioned, return null." Não confiar só em temperature 0.

// Correto: "count": null // ✓ honest
Pattern 03 Inconsistência Matemática vs Schema Redundancy SecurityScan
✗ Anti-Pattern: Single Extraction Trust

18% das invoices têm totais divergentes por OCR. Confiar em extração única é risco sistêmico.

// Risco: subtotal ≠ total // sem validação cruzada
✓ Pattern: Schema Redundancy

Flag humano apenas quando calculated_total != stated_total.

"calculated": 210.025, "stated": 260.00, "flag_review": true // ✓
Pattern 04 Tool Monolítica vs Granular MCP Tools MCP Server
✗ Anti-Pattern: Monolithic Tool

Tool analyze_dependencies ignorada — agente prefere Grep nativo por familiaridade.

✓ Pattern: Granular Tools

Dividir em list_imports + resolve_transitive + detect_circular com descrições explícitas.

Pattern 05 Retry Ilimitado vs Fail Fast Strategy Celery Tasks
✗ Anti-Pattern: Blind Retry Loop

Retry eficaz para erros de formatação, mas ineficaz para informação ausente no documento.

✓ Pattern: Typed Error + Fail Fast

Retornar isError: true, errorCategory: "missing_info", isRetryable: false.

Taxonomia I2A2 · Memória em Agentes

O Substrato Cognitivo da Arquitetura

Um LLM sem memória é uma função sem estado. Tratar tudo como "um banco vetorial" é o erro mais comum — cada tipo tem formato, estratégia de recuperação e momento de escrita diferentes.

⚡
Curto Prazo
Working Memory
Histórico recente, rascunhos de raciocínio, resultados de ferramentas recentes. Vive dentro do contexto — volátil, some ao fim da sessão.
Técnicas: janela deslizante · sumarização progressiva
📚
Semântica
"O que eu sei"
Fatos estáveis, preferências do usuário, políticas, definições de domínio. Alimenta RAG e torna o agente personalizado.
Armazenamento: embeddings · banco vetorial · grafo
🎞
Episódica
"O que aconteceu"
Registros de experiências com metadados (tempo, resultado, contexto). Base do aprendizado — evitar repetir erros, reaproveitar acertos.
Recuperação: similaridade + recência (hybrid retrieval)
⚙️
Procedural
"Como eu ajo"
System prompt, instruções refinadas ao longo do tempo, workflows e ferramentas. Frameworks modernos permitem ao agente atualizar suas próprias instruções.
Formato: instruções versionadas · regras por feedback
// Hierarquia de Memória — Analogia do Sistema Operacional ↑ mais rápido · ↓ mais persistente
Contexto
(Prompt)
≈ RAM · Working Memory ativa, raciocínio do momento, tool results recentes. Tudo que cabe na janela de tokens.
Alto custo/token Volátil
Recall
(Recente)
Histórico de sessão acessível, memórias de curto prazo externalizadas. Pode ser retomado sem re-processar tudo.
Custo médio Semi-persistente
Arquivo
(Longo Prazo)
≈ Disco · Semântica, Episódica e Procedural. Vetores, grafos, chave-valor. Persiste entre sessões.
Baixo custo Persistente
Regra de ouro: não comece pela ferramenta. Comece pela pergunta do tipo de memória, desenhe o ciclo READ → raciocínio → ação → WRITE, e só então escolha o framework. Janela de contexto não é memória — contexto guarda; memória gerencia.
Reference Matrix

Constraint × Domínio × Padrão Mitigador

Mapa consolidado de cada dimensão de falha ao padrão arquitetural mitigador por domínio de implantação.

Constraint Extração de Dados Suporte ao Cliente Dev Productivity Multi-Agent
Token BloatFilter StaleScratchpadVector Store
LatênciaBatch RoutingParallelization
ComplianceApp-Layertool_choice
AcuráciaSchema Redund.Granular MCPStruct. Interm.
MemóriaSemântica/RAGEpisódicaProceduralShared Vector
Nulos/Halluc.Null InstructionCatch-All Enum
🔒
Architect's Reference Matrix — versão completa
A Reference Matrix completa inclui padrões expandidos, casos de uso por indústria e métricas reais de impacto dos anti-padrões em produção. Acesso exclusivo para usuários Kit Sênior — disponível a partir do plano Starter.
Criar conta e acessar → Ver planos