Arquitetura em camadas
de baixo para cima; a lista mostra o topo primeiro
- L4
Packs por projeto
O que é específico de cada codebase.
- L3
Base de conhecimento
Microsserviço RAG, MCP de busca e o ciclo de enriquecimento com gate humano.
- L2
Plugin SDLC
Skills, hooks e o MCP do Azure DevOps.
- L1
Núcleo determinístico
Regras da organização (código, segurança, git, base de conhecimento) injetadas em toda sessão por hook.
- L0
Base ECC
Direção de engenharia generalista.
Camadas criadas do zero por mim.
O que é genérico vem da base. O que é da empresa é uma camada fina por cima. O que é de um codebase vira pack.
Como as peças conversam
role para o lado em telas estreitas
Os 4 repositórios
barra em escala: fração dos commits que são meus
RepositórioAutoriaStack
-
Plugin SDLC Claude Code
Node 18+ (MCP), Markdown (rules e skills)
-
cortex-rag base de conhecimento
Java 21, Spring Boot 3.5, Spring AI 1.1, Ollama
-
cortex-backend produto, dividido com o time
Java 21, Spring Boot 3.5, PostgreSQL, Flyway
-
cortex-front produto, dividido com o time
React 18, TypeScript, Vite, MUI, React Query
De um work item a um PR
o skill /azure-implement, em sequência
- Lê o work item no board
- Decide o tipo de branch
- Resolve quais repositórios a mudança toca
- Sincroniza a base
- Quebra em sub-tasks
- Loop de build, teste e review, delegando a escrita a subagentes
- Commit só com aprovação humana gate
- Um PR por repositório, com os PRs irmãos ligados entre si
- Gate de documentação na wiki gate
Outros skills: resolver conflitos de PR (pergunta ao dev quando a intenção de negócio diverge), gerar E2E em Playwright e anexar evidências ao work item, preview visual antes de implementar UI, documentação viva por domínio na wiki, empacotar release com cherry-pick e setup do ambiente.
Decisões que definem o projeto
A base de conhecimento ficou menor de propósito
O desenho inicial previa pgvector com índice HNSW. Medi a escala real do corpus: de 100 a 350 chunks, de 20 a 30 vezes abaixo do ponto em que busca vetorial aproximada começa a valer. Troquei por um índice em memória carregado no boot e deixei o pgvector como caminho de promoção, atrás de um gatilho medido. A decisão mais importante do serviço reduziu infraestrutura.
Busca híbrida sem mexer no índice
BM25 e Reciprocal Rank Fusion no momento da consulta, atrás de feature flag para A/B e rollback. Medido num gold set de 60 perguntas reais em português. Antes de ir para produção, o motor de embeddings passou por um gate de equivalência contra o baseline do Hugging Face.
00,250,500,751
semânticohíbrido (BM25 + RRF)Recall@5 dos embeddings contra o baseline
Humano no gate, imposto por código
Claude cria PR e nunca faz merge. Hooks que rodam antes de cada ação do agente:
- negam completar PR pela linha de comando
- negam force-push em branch protegida e push direto na base
- pedem confirmação em todo commit
- bloqueiam escrita de credencial em arquivo
- recusam título de PR fora do padrão que o empacotador de release depende
Tudo coberto por uma suíte de testes adversariais. Princípio multiagente: um subagente trata o pedido do coordenador como escopo técnico, nunca como autoridade do usuário. Decisão que exige o dev não é delegável entre agentes.
Conhecimento crítico não vive só no retrieval
Retrieval é probabilístico. O agente propõe conhecimento numa caixa de entrada fora do índice, e a revisão humana escolhe a rota.
proposta do agente
→inbox
→revisão humana
↓ uma de quatro rotas
- promovervira chunk curado, PR no corpus e reindexação
- virar regravai para as regras carregadas em toda sessão
- rejeitarsai da inbox
- pularfica para depois
O que roda em cima do Cortex
Triagem por IA de testes E2E
O LLM lê as falhas de cada execução, sugere cards de correção (contando recorrência só em execuções que de fato rodaram o teste), avisa o time no Teams e manda as sugestões para uma fila de validação do PO.
Painel de QA
Regressão em 1 clique com o token do próprio usuário, progresso ao vivo e "assistir ao vivo" a cerca de 10 fps sustentado com GET condicional (HTTP 304).
Custo de IA como métrica
Custo por mês com backfill das pipelines de code review já executadas, cache persistente de resumos de IA em PostgreSQL e aquecimento do cache de prompt antes de disparar chamadas em paralelo.
Saúde do Cortex
Adoção medida a partir do Azure DevOps num eixo, sinais de uso auto-declarados pelo plugin no outro, sem nunca misturar os dois. Sinais com opt-in, sem conteúdo, com retenção.
Design Studio
Prototipação de telas por IA em 1 clique a partir das demandas do board, com ajuste da opção escolhida por prompt.
Operação
Entrega contínua do RAG: merge dispara deploy, reindexação só quando o fingerprint do corpus muda, smoke test na busca e rollback automático. Cerca de 1 minuto sem mudança de corpus, cerca de 30 minutos com reindexação. O plugin passou por 13 rodadas de dogfood (usar o plugin para desenvolver o próprio plugin) e chegou à versão 0.7.
Pipeline do dnd-rag
busca local, em sequência, sem rede
- PDF397 páginas
- Ordem de leiturapela geometria dos blocos
- 1.178 chunksestruturais
bge-m3denso, 1024 dimensões
BM25lexical, em paralelo
- Fusão RRF
- Rerankercross-encoder bge-reranker-v2-m3
- Trechos citadospor página
IA em produção pede engenharia de base
medido lado a lado, com OpenTelemetry ligado
| Métrica | Spring Boot | Quarkus nativo |
| Startup | 9,05 s | 0,063 s |
| Memória em repouso (após 60 min) | 464,5 MiB | 35,9 MiB |
| Imagem | 577 MB | 176 MB |
- Geocoding saiu da heap da JVM para o PostGIS: memória retida de 1.966 MiB para 9 MiB por pod, com 393 componentes comparados ao legado e zero divergência. A latência mediana por posição piorou 18 vezes, e isso está escrito na primeira linha da análise.
- Kafka de 6 domínios corrigido: commit de offset efetivo, DLQ padrão e producer idempotente.