Harness Engineer: como um knowledge base (RAG) centralizado pode impactar positivamente sua empresa

Imagine um novo engenheiro chegando à sua equipe hoje. A barreira número um de produtividade nunca é a sintaxe da linguagem. A verdadeira barreira é o ramp-up de regras de negócio.

O desenvolvedor recém-chegado abre o repositório, lê um Confluence desatualizado de dois anos atrás, cria a branch e pede para um assistente de IA gerar o código da feature. A IA gera um código sintaticamente perfeito, com Clean Code e testes unitários passando. O Pull Request é aberto e parece impecável.

Mas quando a alteração vai para produção... o sistema quebra.

Por que isso acontece? Porque a regra que aquele código quebrou não estava escrita no arquivo que ele alterou. Ela nasceu de um incidente gravíssimo de dois anos atrás, num serviço vizinho que ninguém documentou na wiki: uma cobrança duplicada no checkout, um cálculo de juros que exige dias úteis ou um vazamento de dados de outro vendedor.

Neste artigo, vamos entender como a engenharia de harness resolve esse problema na raiz: usando uma base de conhecimento versionada no Git (Knowledge Base / RAG cirúrgico) ancorada nos arquivos do projeto, garantindo que o code review e os agentes de IA nunca repitam os erros que a sua empresa já pagou caro para aprender.

O Problema: O Diff Está Certo, mas a Empresa Paga a Conta

Code reviews tradicionais e linters automatizados são ótimos para encontrar bugs locais: ponteiros nulos, sintaxe errada ou consultas SQL ineficientes.

O que escapa silenciosamente são as fronteiras de negócio:

[ Desenvolvedor / Agente ] ──> Altera `checkout/payment_step.go`
                                        │
                                        ▼
                               [ Testes Unitários: OK ]
                               [ Linter / Build: OK ]
                                        │
                                        ▼
                                 [ PULL REQUEST ]
                                        │
                         (Mas quebrou a regra invisível:)
             "Cobranças de cartão exigem idempotency_key de 32 chars"
                                        │
                                        ▼
                       [ PRODUÇÃO: Cobrança Duplicada! ]

Seis Classes de Erros que a Memória do Time Costuma Esquecer

1. Cobrança Duplicada: Um novo gateway de pagamento entra sem a chave de idempotência obrigatória que um incidente passado já exigia.
2. Juros em Calendário Errado: O código faz diferença simples de dias (data_fim - data_inicio) onde o meio financeiro exige dias úteis bancários.
3. Assinatura com Ciclo a Menos: Um operador < onde o contrato de recorrência exigia <=, encurtando o acesso do cliente.
4. IDOR / Acesso Indevido: Um endpoint de detalhes de pedido que recebe o order_id sem validar o tenant_id da sessão logada.
5. Painel de Outro Vendedor: Suporte acessando dados de sellers sem token de uso único e sem trilha de auditoria.
6. Saque Acima do Teto: Lógica de transferência que valida saldo, mas ignora o limite regulatório da conta física.

A dor não é falta de observabilidade ou falta de testes. É falta de memória institucional no momento do review.

A Arquitetura: Knowledge Base Ancorado em Arquivos (File-Path RAG)

Muitas empresas tentam resolver isso jogando todo o Confluence e wikis num banco vetorial com bilhões de embeddings. O resultado? O agente alucina, confunde regras de times diferentes e gera custos astronômicos de infraestrutura.

A abordagem moderna de Harness Engineering é mais simples e muito mais eficiente: recuperação por caminho de arquivo (Path-Anchored RAG):

                  ┌─────────────────────────────────────────┐
                  │      Pull Request Aberto com Diff       │
                  │ Arquivos tocados: src/payments/charge.ts│
                  └────────────────────┬────────────────────┘
                                       │
                                       ▼
                  ┌─────────────────────────────────────────┐
                  │   Recorte Automático no Knowledge Base   │
                  │   Busca fichas vinculadas a este path   │
                  └────────────────────┬────────────────────┘
                                       │
                                       ▼
                  ┌─────────────────────────────────────────┐
                  │     Ficha de Regra Injetada no Review   │
                  │ "Regra #114: Todo charge.ts exige chave  │
                  │  de idempotência SHA-256 no header"     │
                  └────────────────────┬────────────────────┘
                                       │
                                       ▼
                  ┌─────────────────────────────────────────┐
                  │  Revisor / Agente Valida o Contrato      │
                  │  Bloqueia merge ANTES de ir para prod   │
                  └─────────────────────────────────────────┘

Em vez de obrigar o modelo a decorar 200 regras abstratas, o harness injeta apenas a ficha exata do arquivo que o desenvolvedor alterou.

A Anatomia de uma Ficha de Conhecimento (Regra de Negócio)

Para que uma regra de negócio funcione como um sensor confiável e não como um conselho vago, ela precisa ser estruturada como código:

id: RULE-PAY-042
titulo: Idempotência Obrigatória em Criação de Cobranças
status: vigente # vigente | a-confirmar | gap
severidade: critica # critica | alta | media
arquivos_fonte:
  - "services/billing/charge_processor.go"
como_checar: |
  Verificar se a chamada à API do gateway propaga o header 'X-Idempotency-Key'.
  Se a requisição for reenviada em caso de timeout, a mesma chave deve ser reutilizada.
incidente_origem: "INC-2024-883 (Duplicidade em Black Friday)"

Os Três Estados de uma Regra

• Vigente: A regra é lei comprovada. Se o Pull Request violar o campo como_checar, o revisor ou o agente pode bloquear o merge.
• A-Confirmar: Hipótese técnica. O revisor aponta como dúvida construtiva no PR, mas não bloqueia o fluxo de entrega.
• Gap: Identificamos que o sistema atual não garante um comportamento esperado, servindo de alerta de risco para o time.

Por Que Manter a Base no Git e Não em uma Wiki Corporativa?

Quando a base de regras vive no Git, os desenvolvedores tratam a governança de negócio com o mesmo cuidado com que tratam o código de produção.

O Papel do Harness Engineer

O engenheiro de software tradicional foca em entregar a funcionalidade. O Harness Engineer projeta o ambiente e os sensores para que a entrega aconteça com segurança contínua:

1. Outer Harness: Constrói os scripts e automações de pré-commit e CI que extraem os arquivos alterados e injetam as regras no prompt do revisor.
2. Curadoria Contínua: Transforma post-mortems de incidentes reais em novas fichas de regras no repositório.
3. Roteamento de Modelos: Para triagens simples de regras, utiliza modelos locais ou classificadores eficientes como o Downshift (harness-downshift) em Go, escalando para modelos de ponta via OpenRouter apenas quando o diff envolve fluxos financeiros críticos.

Referências Didáticas e Vídeos Recomendados

Para aprofundar na construção de Knowledge Bases e engenharia de contexto para times:

• 📺 Vídeo (YouTube em Português): RAG Descomplicado: O Que é Retrieval-Augmented Generation e Como Usar - Introdução didática sobre recuperação de contexto para modelos de IA.
• 📺 Vídeo (YouTube em Português): Como Documentar Arquitetura com Markdown e Git (Architecture Decision Records) - Boas práticas para manter documentação viva e versionada no Git.
• 📖 Artigo de Referência: Harness Engineering for Coding Agent Users (Martin Fowler) - Como guias feedforward e sensores feedback criam guard-rails para equipes de software.

Como Começar na Sua Squad Nesta Semana

Você não precisa catalogar 200 regras no primeiro dia. Comece pequeno com este plano de 3 passos:

1. Pegue o último incidente da sua equipe: Em vez de deixar o post-mortem esquecido em um PDF, crie uma pasta rules/ no repositório.
2. Escreva sua primeira ficha: Crie um arquivo RULE-001.md descrevendo o arquivo afetado e a instrução exata de como_checar.
3. Adicione ao checklist do PR: Coloque no template de Pull Request a pergunta: "Este PR altera algum arquivo com regra cadastrada em rules/?".

O maior valor de uma empresa de tecnologia não é o código que ela escreveu hoje, mas a capacidade de não repetir os erros que já custaram caro no passado.