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

Imagina um novo colaborador quando chega na empresa. A barreira mais comum entre todas é o ramp-up de negócio. Regras, fronteiras, o que o código cobra e não está no diff. Quem chegou agora não carrega isso na cabeça. A regra só aparece quando alguém lembra, ou quando o erro volta.

Do dia 1 em diante, o onboarding que ele abre já está desatualizado. Confluence, wiki, runbook velho: a página existe, o fluxo mudou, e ninguém reescreveu. O PR está aberto. O agente lê o diff. O código local parece certo. Ele confia bastante na IA e no que consegue ler e ver no arquivo. Aprova no code review.

A regra que esse PR quebra não está nesse onboarding. Está num incidente antigo, noutro serviço, num ticket que ninguém colocou na wiki. Cobrança que saiu duas vezes. Juros no calendário errado. Assinatura que fechou um ciclo a menos. Compra de outra pessoa. Painel de outro seller. Saque acima do teto.

Pedir para ele "saber a empresa" é pedir para ele decorar um onboarding que já nasceu velho. O que funcionou foi o contrário: antes de opinar, o recorte pega o arquivo que o PR tocou e traz só as fichas daquele caminho. A ficha entra no code review sem ele ter vivido o incidente. É assim que a base encurta o ramp-up de negócio.

No repositório que eu mantenho, isso não é metáfora. São 217 fichas, 21 domínios, 16 repositórios citados. 194 já podem entrar no code review. 116 são dinheiro, acesso ou dado de outra pessoa. Em 26 de setembro eu rodei o recorte contra seis incidentes que já tinham custado isso. A ficha certa voltou nos seis, pelo caminho do arquivo. Não é o agente decorando 217 regras. É o recorte trazendo a ficha do arquivo que o PR tocou. As pessoas chamam isso de RAG. Aqui é Git, e o índice é o caminho do arquivo. Para quem chegou, o ganho é o ramp-up de negócio: a fronteira daquele arquivo entra no code review antes de virar memória pessoal.

Esse é o case. Montei a base e o harness em volta dela. Skills, recorte, gate, CI, conjunto de prova, desenho do Guardian. O code review consulta antes de comentar o PR. Começou no meu code review. Quando o mesmo tipo de erro apareceu fora da minha squad, o repositório foi para o Git interno e a skill entrou no kit do time.

Neste artigo

1. O code review via o arquivo. A empresa pagava a fronteira
2. A dor, classe por classe
3. O que a base resolve
4. Como o agente consulta, sem decorar 217 regras
5. A busca no código vê o arquivo. A base vê o que não pode voltar
6. O harness: skills, hooks, o que copiar
7. Os modelos que populam a base
8. Premissas e como montar o seu
9. Clone este AGENTS.md para a raiz do seu repositório
10. O Guardian e o que mais vive no repositório
11. A ficha, ancorada no código
12. Por que Git, e não a wiki
13. O que esse case mostra sobre Harness Engineering

1. O code review via o arquivo. A empresa pagava a fronteira

Quem chegou agora leu o onboarding desatualizado e o que o PR mostrou. A barreira é o ramp-up de negócio: a regra estava num incidente antigo, num arquivo que esse PR não abriu. Sem a ficha no code review, o ramp-up espera quem lembra.

Code review tradicional pega bug técnico dentro do domínio: null, SQL, lógica local. O que escapa é regra de negócio que atravessa fronteira. O diff está certo. A empresa paga.

Essa regra vivia em ticket antigo, em reunião, na cabeça de quem implementou o fluxo. O PR seguinte no mesmo arquivo não abria nada disso. A plataforma pagava de novo na mesma classe de erro.

O mapa de dependências existe para esse buraco. Ele não julga o diff. Ele mostra o vizinho: o arquivo que o PR tocou chama um serviço que outra squad consome. Quem chegou e só leu o onboarding desatualizado, confiando na IA e no código do PR, não vê esse vizinho. Quem abre o mapa antes do comentário vê a fronteira que o código cobra fora do arquivo.

2. A dor, classe por classe

Seis incidentes que já tinham acontecido. Em todos, a mudança era válida no arquivo e falsa no contrato do lado. Essa é a cara do ramp-up de negócio. O código compila. A empresa paga a fronteira.

1. Venda duplicada. Checkout lento, ingresso novo de pagamento, sem a chave que o incidente anterior já exigia. O cliente é cobrado duas vezes. O time refaz a venda.
2. Juros no calendário errado. O código usava diferença simples de data onde o meio de pagamento pede dia útil. Quem paga recebe cobrança a mais.
3. Um ciclo a menos. Condição com < onde o contrato do período pede <=. Um dia de diferença, em assinatura, reduz a receita recorrente.
4. Compra de outra pessoa. O endpoint aceitava o identificador na query. Um comprador via o pedido de outro.
5. Painel de outro seller. O fluxo de suporte aceitava o id direto, sem um ticket de uso único. Acesso de uma conta na sessão de outra.
6. Saque acima do teto. A lógica não olhava o tipo de conta antes do limite. Pessoa física saía do teto da própria conta. Risco financeiro e regulatório.

A dor não era "falta de observabilidade" nem "falta de teste". Era memória. A fronteira entre checkout e pagamento, entre assinatura e calendário, entre suporte e identidade, não estava no onboarding nem no diff na hora do PR.

Tem buraco que a ficha não cobre, e a resposta certa é dizer isso. Workflow de automação que só vive na instância, fora do git. Valor que muda no banco, no cache ou numa flag, sem commit. Domínio varrido pela metade: o manifesto existe, a cobertura não. Nesses três, quem chegou declara lacuna. "Não tenho ficha para este fluxo" é uma resposta que o code review consegue usar. Completar o silêncio com uma regra sem fonte é o jeito de parecer seguro e errar.

3. O que a base resolve

A base não desfaz esses seis. Eles já tinham sido corrigidos no código. O que ela resolve é a repetição, que é o ramp-up de quem entra depois.

Antes, a correção ficava no commit e na cabeça de quem fez o hotfix. O próximo PR no mesmo arquivo nascia sem essa memória. O code review olhava o diff. A empresa corria o mesmo risco: segunda cobrança, juros indevido, ciclo que não fecha, dado de outro comprador, painel de outro seller, saque acima do teto.

Depois, a regra da correção mora numa ficha apontando para o arquivo. O code review desse arquivo abre a ficha antes do comentário. Quem não viveu o incidente ainda vê a fronteira.

O valor de negócio é esse. A empresa deixa de depender de quem lembra. A mesma classe de erro, a que já custou dinheiro, acesso ou dado de outra pessoa, passa a ter dono no fluxo do PR. São 116 regras nesse nível de severidade, de 217 no catálogo. 194 já podem ser citadas. 16 estão a confirmar. 7 são gap. 194 + 16 + 7 = 217. O resto não entra como se fosse lei.

O que a pessoa nova pode fazer com cada status cabe numa frase, e muda o comentário.

Ficha vigente pode ser citada como evidência no code review. Vira bloqueio só quando três coisas estão juntas: severidade alta, o corpo do diff quebra o como-checar, e o hash ainda descreve o arquivo que foi lido. Faltar uma das três: o comentário fica dúvida, não veto.

Ficha a-confirmar é hipótese. Quem chegou pode escrever a dúvida no PR. Não promove a vigente. Não bloqueia merge sozinha. O campo existe para você não inventar certeza onde a leitura linha a linha ainda não aconteceu.

Ficha gap diz que o código lido não garante o comportamento. É risco aberto. Entra como alerta. Não vira lei, e não serve para completar cobertura no chute.

4. Como o agente consulta, sem decorar 217 regras

A barreira continua sendo o ramp-up de negócio. Quem chegou não decora o onboarding. O recorte traz as fichas do arquivo que o PR tocou. A ficha daquele caminho entra no code review antes de virar memória pessoal.

O recorte faz isto:

1. Recebe o diff.
2. Lista os arquivos tocados.
3. Busca no knowledge base as fichas cuja fonte menciona esses arquivos.
4. Coloca só essas fichas no contexto do code review, antes do comentário.

É recuperação por caminho. Sem vector database, sem embedding. O agente não decora 217 regras. Ele lê a regra que aquele PR pode quebrar de novo.

Handbook inteiro no system prompt estoura contexto e ainda cita regra velha. Recorte por arquivo cita a dor daquele diff.

Se nenhuma ficha casa, o code review segue e registra o silêncio. Silêncio repetido num fluxo de dinheiro ou de acesso é gap de cobertura. Não é sinal de que está tudo bem.

Tem dois jeitos de consultar, e os dois são válidos. A escolha é o momento, não o gosto.

Consulta humana. Use quando você vai implementar ou entender um domínio, e ainda não existe diff para recortar. Ou quando você quer ler o domínio inteiro antes de desenhar. Clone, abra a página daquele domínio, leia. Se a mudança atravessa serviço, abra o mapa de dependências. Skill e índice vetorial ficam fora desse modo. Para ler, o clone basta.

Code review assistido. Use quando o PR já tem diff e o comentário precisa da ficha daquele arquivo, não dos 21 manifestos. No repositório de produto, rode o recorte. Leia só o que o comando imprimir. Compare o como-checar com o que o PR faz. Cite o arquivo e o hash. Quem compara o corpo do diff é o revisor. O comando lista. O revisor decide.

O como-checar é o contrato do próximo PR naquele arquivo. Não é slogan e não é resumo da dor. É a frase que diz o que o diff precisa respeitar para a fronteira continuar de pé. Sem esse campo, a ficha não entra no gate. Com ele, quem chegou sabe o que olhar, mesmo sem ter vivido o incidente.

Se alguém insistir em vector store, o chunk é um bloco de slug, com domínio e repositório como filtro. Arquivo inteiro dilui a regra: a busca devolve o manifesto inteiro, e a fronteira some no meio do texto. A preferência deste case é hub-first. O diff escolhe o domínio. O agente lê aquela página. Similaridade no vault inteiro custa mais e erra o domínio, porque a ficha vizinha parece a certa.

5. A busca no código vê o arquivo. A base vê o que não pode voltar

Muita gente me pergunta isso no meio do code review. Pra que uma base centralizada se a IA já busca a regra no código?

A pessoa nova abre o arquivo do PR. O modelo lê aquelas linhas, e às vezes a função vizinha no mesmo repositório. Ele completa bem a próxima linha. Parece que achou a regra, porque a regra local está na tela: o if, o nome, o teste do lado. O que a empresa já pagou para aprender está em outro lugar. O chamado de dois anos. O calendário que pede dia útil onde o código fez conta de dia corrido. O filtro que impede um comprador de ver a compra de outra pessoa, escrito noutro serviço. O teto de saque de pessoa física. O mapa de quem consome essa API. Nada disso entra sozinho porque o diff abriu esta função.

Busca no código do PR melhora a previsão local. O modelo vê o invariante que está escrito agora, naquele recorte de arquivos. Ele não atravessa, por conta própria, o incidente antigo noutro repositório, nem o contrato entre times, nem a ficha que nunca virou comentário no arquivo.

A base faz o caminho inverso. Cada ficha fica presa ao arquivo@sha: o caminho e o hash do conteúdo que foi lido. O recorte não abre os 21 manifestos. Recebe os arquivos do diff e devolve só as fichas cujo fonte é aquele caminho. Uma página por domínio, para a mesma fronteira não morar em dois manifestos. Quando o PR atravessa serviço, o mapa de dependências mostra quem consome o que essa mudança mexe. O que entra no contexto é a fronteira da qual aquele arquivo participa. As linhas da tela continuam lá. A ficha chega junto.

Prever o próximo token depende do que está na frente do modelo. Contexto local produz previsão local: o que essa função tende a fazer. Contexto de regra de negócio produz outra previsão: o que não pode acontecer de novo, mesmo com o diff certo na função. Global, neste case, não é um adjetivo de marketing. É as seis classes que já custaram, e que moram fora da função aberta. Cobrança que sai duas vezes. Juros no calendário errado. Assinatura com um ciclo a menos. Compra de outra pessoa. Painel de outro seller. Saque acima do teto. Sem a ficha, o modelo completa o PR com o que o arquivo sugere. Com a ficha, a previsão fica ancorada no que o code review precisa impedir. A base não deixa o modelo mais inteligente. Ela põe a fronteira no code review.

Tem uma honestidade que eu não pulo. Busca no código sempre vê o arquivo de agora. A ficha é retrato, lido na data da extração. Pode descrever um comportamento que o arquivo já não tem. Por isso o hash e o staleness: hash diferente, a ficha deixa de valer como lei até alguém reler o fonte. O código do repositório de produto continua sendo a fonte da verdade. A base não é uma segunda fonte. O valor é o trio que a busca no arquivo não entrega pronta: o invariante curado, o como-checar do próximo PR, e o status. Vigente pode ser citada. A-confirmar é dúvida. Gap é risco aberto, não lei.

O que a busca no código faz mal, quando a gente pede para ela substituir a base, cabe em quatro cenas. Despejar 16 repositórios e 21 manifestos de uma vez estoura o contexto e ainda devolve o domínio parecido, não o certo. Citar uma regra sem hash é palpite com formato de evidência. O modelo que só leu o diff não separa, sozinho, vigente de a-confirmar e de gap, e o code review precisa dessa separação para saber o que pode bloquear. E tem regra que viveu num chamado, numa reunião, na cabeça de quem fez o hotfix, e nunca apareceu como comentário no arquivo. Busca no código não acha o que o código não guarda.

O Guardian, que um dia compararia o corpo do diff com o como-checar e comentaria no PR, continua proposta. Ele não vota. Eu não afirmo precision nem recall: o veredito no corpo do diff ainda não tem baseline. Hoje o revisor lê a ficha que o recorte colocou no code review e decide. A busca no arquivo continua obrigatória, porque o retrato mente quando o fonte andou. As duas juntas fecham o code review. Uma vê o código do PR. A outra lembra o que a empresa já pagou para não repetir.

6. O harness: skills, hooks, o que copiar

Um modelo genérico não vira code review de produto sozinho. Falta a identidade no time, o procedimento do PR e a base que ele consulta. Isso é o harness do usuário: guia (identidade, skill, o texto de todo turno, a ficha) e sensor (o validate no CI). O harness do fornecedor é o IDE, com system prompt, ferramentas e orquestração. O modelo fica no centro.

Este repositório é a base e o procedimento da regra. O roster de quem decide e quem executa no IDE fica noutro kit. Aqui não duplica o time. Liga a skill, sem copiar as 217 fichas.

Três perguntas no code review. O Guardian é a terceira. Não substitui as duas primeiras. Não são as três camadas do harness (usuário, fornecedor, modelo).

A primeira pergunta olha se o código está são: mudança mínima, um achado por vez, impacto em quem paga ou em quem acessa. A segunda olha a mecânica do comentário no PR: onde escrever, o que aprovar, o que devolver. A terceira olha a ficha. Misturar as três num prompt só faz o modelo julgar estilo e chamar isso de regra de negócio.

O recorte é o jeito de achar a ficha. Não é uma quarta camada. A skill do Guardian, copiada em agent/skills/, manda rodar o recorte, abrir o mapa se o PR cruza serviço, e comparar o como-checar. Ela não publica comentário e não vota. Isso é da mecânica. Quem compara a ficha com o corpo do diff, hoje, é o revisor. O bot no PR ainda é proposta. O script é o kb-rag. O sensor é o validate, que recusa ficha sem hash. Skill que só descreve o passo continua sendo guia. Um exemplo de skill que executa de verdade está no mesmo kit: a database-migration-checker barra DROP, TRUNCATE, coluna NOT NULL sem default e índice sem CONCURRENTLY, com saída 1 bloqueando o PR.

A instalação é um symlink, de propósito. Duas cópias da mesma skill divergem, e o code review passa a citar a versão velha com segurança.

./agent/install.sh            # dry-run: mostra o symlink, não copia as regras
./agent/install.sh --apply    # liga a skill no IDE
./agent/install.sh --check    # o link ainda aponta para a fonte?

Sem flag, o script só mostra o link que criaria. --apply cria o symlink da skill para a pasta do IDE. --check confere se esse link existe e aponta para a mesma fonte. Se já existir um diretório no lugar do link, ele para. As regras continuam em rules/. Nada é copiado. Um espelho, se o time tiver, também é symlink, não uma segunda árvore.

No repositório de produto:

kb-rag --diff origin/main

Go 1.22 ou mais novo. Sem token. Sem serviço extra. A saída lista a ficha. Quem decide se o diff quebrou é o revisor.

Cada comando da base existe por um motivo. O nome sozinho não ensina.

rules lista as fichas cujo fonte é um arquivo do diff. Existe para você não abrir os 21 manifestos. A lista não prova que o corpo quebrou a regra.

validate confere campo obrigatório, hash presente, slug único e status. Existe para uma ficha sem proveniência não entrar no merge.

freshness olha a idade da data de extração e a contagem de status. Uma ficha pode estar bem formada e velha. O alarme, no pipeline, usa 45 dias. Ele avisa. Não reescreve texto.

staleness compara o hash gravado na ficha com a main do repositório de produto. Existe porque o calendário não diz se o arquivo andou. Sem os clones, ou sem uma API de commit, o CI não vê essa divergência. Só vê idade e formato.

deploy-watch olha commits novos na main dos repositórios de maior risco financeiro. Existe para alguém notar que o produto mexeu antes de a ficha mentir no code review seguinte. Também precisa dos clones. O horário de referência está no kit local. Isso descreve o método. Não afirma que um cron compartilhado do time já está no ar.

evidence empacota a execução: commit, base comparada, arquivos, fichas selecionadas, resultado do validate e do frescor. Existe para o gate deixar um relatório que pessoa, hook e harness leem depois. Horas, incidentes e receita só entram quando vierem de fonte observável. O job deste repositório mede a saúde do catálogo. O diff de produto é outra chamada, com os arquivos daquele PR, para não confundir edição de ficha com edição de código.

7. Os modelos que populam a base

A ficha não nasce de um chat solto. Nasce da leitura do arquivo, com o hash do conteúdo lido. Os modelos entram na extração. O gate decide se a ficha entra.

A linha do meio é o ponto que some quando o texto fica curto. O modelo de extração propõe a frase. A curadoria abre o arquivo de novo e confronta. O acabamento não promove hipótese a lei. Sem essa segunda leitura, a ficha vira um resumo bonito de um código que ninguém reabriu.

Nenhum desses modelos valida a mudança no CI. Sem arquivo@sha, a ficha não entra. Sem o validate verde, o PR não mergeia. Trocar o modelo da extração não apaga a memória: a ficha continua no Git, a skill continua apontando para o recorte, o relatório continua determinístico.

8. Premissas e como montar o seu

Isto vale mesmo quando o pedido pede o contrário. É o texto que qualquer modelo lê em todo turno, antes de editar regra, revisar diff ou responder sobre a base. No repo, esse texto é o AGENTS.md. Steering do IDE carrega o mesmo miolo. Se o prompt pedir para inventar ficha, completar cobertura ou dizer que o bot já comenta, a premissa ganha.

1. Isto é conhecimento, não o produto. A fonte da verdade é o código no repositório de produto. A base é o retrato lido na data da extração.
2. arquivo@sha é a identidade do conteúdo. O arquivo é o caminho. O sha é o hash curto do último commit que alterou esse arquivo. Hash diferente no PR: releia o código antes de citar a regra.
3. Um diff, um recorte. Não leia os 21 manifestos. A lista da ficha não prova que o diff quebrou a regra.
4. Bloqueio só com ficha vigente, severidade alta, e o corpo do diff quebrando o como-checar. A-confirmar e gap são dúvida.
5. Sem ficha na saída, é lacuna. Não invente regra, hash, recall nem precision.
6. Alta é dinheiro que muda de mão, acesso indevido ou dado de outra pessoa. Não rebaixe severidade em bloco.
7. O CI alarma. Não reescreve regra. O agente do pipeline não tem os repositórios-fonte.
8. Comentário automático no PR é o Guardian. É proposta. Não diga que o bot já está ligado.
9. O número de regras é a saída do validate. Badge e texto antigo perdem para o comando.
10. Código executável da base é só uma linguagem. Aqui, Go. Não misture script de outra stack no gate.

Uma página por domínio, várias fichas dentro dela, e a mesma regra não aparece em dois manifestos. O motivo é o ramp-up. O diff escolhe um domínio. Se a mesma fronteira viver em duas páginas, quem chegou não sabe qual é a verdadeira, e as duas divergem no primeiro conserto. Domínio novo ganha arquivo próprio. Duplicar para "facilitar a busca" é o jeito de criar duas memórias.

Os dois modos do começo valem aqui também. Consulta humana sem diff. Code review assistido quando o PR já escolheu os arquivos. Skill e recorte entram só no segundo.

Passo a passo para montar o semelhante:

1. Um repo só de conhecimento. Não misture com o deploy do produto.
2. Uma página por domínio. Template único. Campos obrigatórios: domínio, repositório, fonte, invariante, severidade, como-checar, status.
3. Extraia lendo o arquivo. Grave o hash. Não escreva de memória. Hipótese fica a-confirmar.
4. Um comando de validate no PR. Sem hash, não mergeia.
5. Um comando de recorte: arquivos do diff → fichas cuja fonte cita esses caminhos.
6. Uma skill que manda o agente rodar o recorte antes de abrir manifesto. Symlink. Não copie as fichas para a pasta do IDE.
7. CI que alarma frescor. Conserto é PR com o arquivo-fonte aberto. O pipeline não reescreve ficha, porque não tem os 16 clones.
8. Um conjunto de prova: casos que devem bloquear e casos que devem ficar em silêncio. Meça recuperação por caminho. Só então desenhe o bot no PR.

Quando algo sai errado:

A tabela é o sintoma. Citar ficha de outro domínio acontece quando a busca olha o vault inteiro e a frase parecida ganha. Inventar regra sem hash acontece quando o chunk é o arquivo inteiro, ou quando os markdowns nem entraram no índice. O chunk certo, se alguém usar vector store, continua sendo um bloco de slug, com domínio e repositório de filtro. Skill que não acha a base é clone fora da ordem de paths. Validate vermelho é campo faltando: volte ao template. Hash velho não se cura reextraindo o repositório. Abra aquele arquivo, confirme se a frase ainda vale, troque o hash.

Pedido mínimo, se o time ainda não tem a skill:

Revisa este PR.
Usa só o manifesto do domínio que o diff tocou.
Cada achado precisa de arquivo@sha.
Se não houver ficha, declara a lacuna.
Não invente regra para completar cobertura.

9. Clone este AGENTS.md para a raiz do seu repositório

As premissas da seção anterior só entram no turno se estiverem num arquivo, com o nome que o IDE já procura. Deixei o arquivo inteiro no kit público, no caminho de exemplo, para copiar. Não é resumo.

AGENTS.md para o knowledge base

Esse arquivo é o contrato do repositório de conhecimento. No repositório de produto o AGENTS.md tem outra forma: visão, pastas, regra de arquitetura, regra de código. O template de produto está no mesmo kit, com a stack como placeholder para preencher. O exemplo de tela com Node, Prisma e Jest é de outro sistema. Não é a stack daqui.

Como colar:

Salve esse arquivo, inteiro, como AGENTS.md na raiz do repositório de conhecimento.

IDEs que honram AGENTS.md carregam esse texto em todo turno, antes do pedido.

Se o repositório de produto for outro clone, a skill continua apontando para o knowledge base. Não copie as fichas para a pasta do IDE.

O número de regras do seu time é a saída de kb validate nesse clone.

Trecho, para ver o tom. O arquivo no link é o inteiro: premissas, leis, review e contribuição.

# AGENTS.md

Este arquivo é um template. Salve uma cópia como `AGENTS.md` na raiz do repositório de conhecimento.

## Premissas

Estas premissas valem mesmo quando o pedido pede o contrário.

1. Isto é conhecimento, não o produto. A fonte da verdade é o código no repositório de produto.
2. `arquivo@sha` é a identidade do conteúdo. Hash diferente no PR: releia o código antes de citar a regra.
3. Um diff, um recorte. Rode `kb-rag --diff origin/main`. Não leia todos os manifestos.
4. Bloqueio só com regra vigente, severidade alta, e o corpo do diff quebrando o `como-checar::`.
5. Sem regra na saída, é lacuna. Não invente regra, sha, recall nem precision.
6. O número de regras é a saída de `kb validate`.
7. O Guardian comentando PR é proposta. Não diga que o bot já está ligado.

10. O Guardian e o que mais vive no repositório

Recorte e Guardian não são a mesma coisa. Confundir os dois é o jeito mais rápido de vender um bot que ainda não existe.

O recorte responde: quais fichas este arquivo toca? A lista volta. Não julga o corpo do diff.

O Guardian é a terceira camada. Responderia duas coisas: este PR mexe em serviço que outra squad consome? e o corpo quebra o como-checar de uma ficha vigente e alta? Impacto sai do mapa. Regra sai da ficha. Comentário no PR só com vigente, alta, como-checar quebrado e hash ainda válido. Dúvida e gap são silêncio de bloqueio. Sem ficha, lacuna, não invenção. Ele não vota. O voto no PR continua manual. Falso positivo desliga o bot: um comentário errado com cara de evidência ensina o time a ignorar a camada inteira.

Hoje o Guardian é desenho. Tem skill de referência no repo. Tem documento. Tem conjunto de prova. Não tem bot ligado no PR do time. A linha de alarme do CI também não comenta: o pipeline só vê a base, não clona os 16 repositórios de produto.

O conjunto de prova não é manifesto. Não entra na conta das 217. São casos rotulados, com causa conhecida e veredito esperado: 6 que devem bloquear, 2 que devem ficar em silêncio. Em 26 de setembro a recuperação por caminho achou a ficha correspondente nos 8. Isso mostra que o conjunto de prova está no repo. A baseline que falta é outra: rodar o code review contra o diff de cada caso e preencher o resultado com acerto, falso negativo ou falso positivo. Esse número, no corpo do diff, ainda não foi preenchido. Sem ele, ligar comentário automático é chute que o time vai ler como evidência. Eu não afirmo precision nem recall.

Quando a baseline existir, a ordem é comentário no PR. O voto continua manual. Fora desta fase, de propósito: baseline de produção para comparar o PR com o que está no ar, voto automático, extração em massa por modelo, agente especialista por domínio.

O restante do repositório, o que o harness realmente tem:

A tabela lista o lugar. O que quem chega erra é achar que o pipeline conserta a ficha. São duas camadas, e a segunda não roda no agente hospedado.

O alarme existe porque ficha sem campo, sem hash ou velha demais não pode passar calada. O conserto existe porque reescrever a frase sem o arquivo aberto é exatamente o modo que a base proíbe. O pipeline YAML faz o sanity, o teste do gate, o validate e o frescor. Publica o bundle de evidência. Não faz deploy. Não reescreve ficha. Não faz checkout dos repositórios de produto.

A manutenção já registra um risco de pessoa única no CODEOWNERS. O code review das fichas para se essa pessoa não estiver. Não é teoria de plantão. É gap escrito ao lado do alarme.

O que este repo não é, de propósito:

• Não é serviço de produção.
• Não é o roster do IDE. O time de agentes mora noutro kit.
• Não é o Guardian ligado. O desenho existe. O bot no PR, não.
• Não inventa precision, recall, nem reais poupados. O número oficial é a saída do validate.

Quem for copiar: recorte e conjunto de prova primeiro. Guardian no PR só depois que o veredito no corpo do diff tiver número. Até lá, o revisor humano lê a ficha que o recorte colocou no code review.

11. A ficha, ancorada no código

Uma ficha, uma regra, um arquivo. O template do repo é este. Copie o bloco. O gate lê campo com ::. Slug no título do bloco. Sem os obrigatórios, o PR da ficha não mergeia.

## idempotencia-da-cobranca
status: vigente
severidade: alta
invariante: cobrança repetida com a mesma chave de negócio devolve a primeira resposta
fonte: caminho/do/middleware.php@<sha-do-arquivo-lido>
como-checar: diff que abre outro ingresso de pagamento precisa da mesma chave

O como-checar merece o parágrafo porque é o campo que o ramp-up usa. A invariante conta a dor. A fonte prova de onde a frase saiu. O como-checar diz o gesto no diff: se este PR abre outro ingresso, a mesma chave precisa estar aqui. Quem chegou compara essa frase com o corpo. Se a frase for vaga ("cuidado com pagamento"), a ficha não orienta ninguém, e o gate deveria ter recusado um campo vazio, não um campo frouxo. Frouxo ainda passa. O revisor é quem devolve.

Cinco leis do PR de ficha:

1. Sem hash, não entra.
2. Não edite de memória. Abra o arquivo, leia, grave o hash do último commit daquele arquivo.
3. Uma página por domínio. Não duplique a mesma regra em dois manifestos.
4. Hipótese fica como a-confirmar. Não promova a vigente.
5. PR para a main. Validate verde. Sem commit direto.

12. Por que Git, e não a wiki

A wiki continua útil para o humano ler o produto. A dor do code review era outra: a regra não chegava no PR. Página que ninguém abre na hora do diff não encurta ramp-up de negócio. Ficha no mesmo fluxo do commit, sim.

1. O hash avisa quando o código andou e a ficha ficou para trás.
2. O agente clona o repositório e lê markdown. Não depende de busca numa página que ninguém abre na hora do diff.
3. Mudar regra é PR. O time discute a frase da dor. O histórico fica no commit.

Ticket antigo e página de wiki servem para escrever a ficha. Não servem para o code review citar. Foi exatamente aí que a regra se perdeu da primeira vez: a correção ficou no chamado, o próximo diff não abriu o chamado, e a fronteira voltou.

13. O que esse case mostra sobre Harness Engineering

O problema não era de uma squad. Eram 16 repositórios, 21 domínios, e a regra de dinheiro na cabeça de pessoas em times diferentes. Pedir um modelo melhor não tirava essa regra da cabeça e punha no PR. O ramp-up de negócio continuava igual: quem chegava lia o onboarding desatualizado, confiava na IA e no código do PR, e aprovava.

Harness Engineering, aqui, é a infraestrutura que faz o code review enxergar a dor:

• Onde a regra fica: Git, uma ficha por fronteira que já custou.
• Como o agente recupera: skill de recorte pelo arquivo do diff.
• Como ela expira: hash, staleness, alarme de 45 dias no CI.
• Como você sabe que a ficha é ficha: validate no PR. Premissas no AGENTS.md, em todo turno. O arquivo para clonar está na seção 9.
• Como a base nasceu: Qwen local extraiu, Grok e Opus curaram, o gate ficou determinístico.
• O que ainda não liga: Guardian no PR. Conjunto de prova 8/8 na ficha correspondente. Veredito no corpo, sem baseline.
• O que isso resolve: a segunda cobrança, o juros indevido, o ciclo a menos, o dado de outro comprador, o painel de outro seller, o saque acima do teto.

Isto é o harness do usuário, não o modelo. A ficha e o AGENTS.md são guia: entram antes do agente gerar. O validate no CI é sensor: volta depois e recusa regra sem hash. Teste, log e o texto o HTTP 200 esconde catch vazio são o outro sensor, o da aplicação, e não moram neste repositório. Model routing e effort só alocam o modelo que esse harness vai usar. Sem guia e sem sensor, trocar o modelo não cria o harness. No Harness engineering for coding agent users, este case regula sobretudo o harness de maintainability (regras internas, catálogo, review). O behaviour funcional do produto (spec + suite verde + teste manual) é outro eixo: o Guardian proposto e o validate não substituem spec nem sensor de runtime.

O modelo fica tão bom quanto a dor que você coloca na frente dele. Sem a regra do dia útil, o melhor code review aprova o juros errado. Sem a venda duplicada, o melhor agente não sabe por que a chave do pagamento existe. Sem premissa, sem recorte e sem gate, a ficha vira wiki de novo. Sem baseline, o Guardian vira bot que comenta no escuro.

No code review de vocês, a regra chega no PR por skill, recorte e premissa, ou ainda mora na cabeça de quem lembra do incidente?