harness-engineering

Quando um agente de IA entra em um repositório que nunca viu, ele precisa descobrir quais comandos funcionam, onde estão as regras e como uma mudança deve ser validada. Sem esse contexto, uma sugestão tecnicamente razoável pode contrariar o projeto em que será aplicada.

O harness-engineering verifica esse ambiente e transforma as lacunas encontradas em propostas que respeitam o próprio repositório.

O que acontece quando ele analisa um projeto

A análise começa pelo que já existe: documentação, scripts, configuração de testes, convenções e instruções para agentes. O resultado é um relatório dividido em oito eixos, com evidências para cada aprovação ou reprovação.

Quando encontra uma lacuna, o sistema não instala uma solução pronta. Ele descreve o problema, procura uma técnica compatível com as ferramentas disponíveis e produz uma proposta para revisão.

O fluxo principal é:

inventário do repositório
  → avaliação em oito eixos
  → relatório com evidências
  → proposta para cada lacuna
  → alteração somente após autorização
  → verificação pelo próprio projeto

As skills separam diagnóstico de alteração

A separação é intencional. Encontrar um problema não concede autorização para alterar o repositório. O diagnóstico termina numa proposta; a implementação começa apenas quando essa proposta é aceita.

O formato nasceu de testes em repositórios reais

A primeira versão validou uma cadeia completa: detectar um problema, produzir uma proposta e descrever como corrigi-lo. As fases seguintes foram executadas contra projetos existentes, incluindo o DocAuto.

Esse processo mostrou que uma biblioteca fixa de soluções introduziria suposições demais. A mesma lacuna pode exigir abordagens diferentes em um projeto com npm, em outro com Python ou em um repositório que já possui ferramentas equivalentes.

Por isso, o sistema usa receitas: instruções para investigar o repositório e construir a solução com o que estiver disponível. Uma receita dedicada só deve se tornar padrão depois de a mesma técnica funcionar em mais de um projeto real. Nos demais casos, o fluxo usa uma investigação específica para aquele código.

Três decisões limitam o que o agente pode fazer

1. O inventário vem antes da geração: uma ferramenta existente deve ser reutilizada ou estendida.
2. Nenhuma dependência é instalada sem autorização.
3. Toda alteração precisa ser validada pelos comandos do próprio projeto e demonstrada no git status.

Essas regras reduzem o risco de substituir convenções locais por uma preferência genérica do agente.

O que ainda precisa ser validado

Parte do sistema foi exercitada principalmente nos meus próprios repositórios. A adoção completa foi validada uma vez no DocAuto, e ainda falta executá-la em outro projeto com uma stack diferente.

Algumas receitas também antecedem o critério atual de validação em dois projetos. Elas permanecem disponíveis, mas ainda não têm a mesma evidência das receitas que já passaram pelo processo completo.

Estado atual

O projeto já produz diagnósticos, propostas e alterações autorizadas. O trabalho seguinte é ampliar os testes externos e observar onde as premissas precisam mudar em repositórios mantidos por outras pessoas.

Até essa validação acontecer, o resultado demonstrado é a capacidade de adaptar o processo aos projetos usados nos testes. O apelo e a utilidade fora desse conjunto ainda não foram medidos.