Engenharia de Harness

A engenharia de harness transforma erros repetidos de agentes de codificação em artefatos de repositório duráveis:

Harness = Instructions + Constraints + Feedback + Memory + Evaluation + Governance

Use esta habilidade quando o usuário pedir para:

• tornar um repositório mais confiável para o GitHub Copilot ou outros agentes de codificação
• adicionar instruções de agente duráveis, regras de repositório ou guardrails
• prevenir erros repetidos de agentes de codificação por IA
• registrar caminhos de falha conhecidos e as verificações que impedem a recorrência
• adicionar verificações leves de desvio para regras de projeto
• revisar, atualizar ou modernizar um harness de agente existente

Não use esta habilidade para implementação de recursos comuns, a menos que o usuário peça para melhorar o ambiente operacional do agente do repositório.

Princípios Fundamentais

• Trate o repositório de destino como a fonte da verdade.
• Inspecione antes de editar. Preserve a pilha existente, o gerenciador de pacotes, o CI, a documentação, a nomenclatura e a arquitetura.
• Adicione o menor harness útil. Prefira atualizar arquivos existentes em vez de adicionar orientação duplicada.
• Torne as regras importantes aplicáveis, sempre que prático, por meio de testes, linters, verificações de tipo, CI, ganchos de pré-commit ou scripts de desvio.
• Use pontos de revisão manual apenas quando a automação for frágil ou enganosa.
• Registre falhas de alto risco que não devem ocorrer novamente e nomeie a verificação ou o ponto de revisão que detecta a recorrência.
• Não copie modelos genéricos cegamente. Adapte cada artefato a evidências reais no repositório de destino.

Descoberta

Antes de propor ou fazer alterações no harness, inspecione o repositório em busca de regras e evidências existentes.

Leia estes arquivos e pastas, quando existirem:

• README.md
• AGENTS.md
• .github/copilot-instructions.md
• .github/instructions/
• .github/workflows/
• CONTRIBUTING.md
• manifestos de pacotes como package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml ou build.gradle
• documentação existente em docs/
• scripts existentes em scripts/
• testes existentes e verificações de CI

Em seguida, resuma:

• pilha, gerenciador de pacotes e pontos de entrada
• comandos de desenvolvimento e verificação existentes
• instruções de agente atuais ou convenções de repositório
• falhas conhecidas, incidentes, caminhos instáveis ou comentários de revisão repetidos
• lacunas onde as regras do projeto não são aplicadas

Fluxo de Trabalho de Adoção

Siga esta sequência:

1. Escolha a superfície de harness que se adapta ao repositório de destino.
2. Escreva instruções de agente específicas para o destino.
3. Adicione verificações aplicáveis para regras de alto valor.
4. Registre a memória de falha para falhas de alto risco ou recorrentes.
5. Adicione verificações de desvio para orientações que podem ficar desatualizadas silenciosamente.
6. Relate a adoção com evidências, suposições e acompanhamento.

1. Escolha a Superfície de Harness

Escolha apenas as superfícies que se adaptam ao repositório de destino:

Se o repositório já tiver um local equivalente, atualize-o em vez de criar um sistema paralelo.

2. Escreva Instruções de Agente

As instruções do agente devem ser concretas e operacionais. Inclua:

• propósito do projeto e principais limites de propriedade
• comandos de configuração, teste, lint, build e verificação
• gerenciador de pacotes e regras de dependência
• regras de edição segura, regras de arquivo gerado e caminhos proibidos
• expectativas de teste para código alterado
• convenções de PR e commit, se o repositório as tiver
• como registrar novas falhas ou decisões

Evite orientações de personalidade amplas, melhores práticas genéricas e regras que não podem ser verificadas ou revisadas.

3. Adicione Verificações Aplicáveis

Converta regras de alto valor em verificações. Boas verificações de harness são:

• estreitas o suficiente para evitar falsos positivos
• rápidas o suficiente para serem executadas localmente e em CI
• nomeadas claramente para que os agentes possam executá-las antes de terminar
• documentadas com a regra que protegem

Exemplos:

Regra: Não edite clientes de API gerados.
Verificação: script escaneia diffs para caminhos gerados e falha com uma mensagem clara.

Regra: Cada nota de memória de falha nomeia uma verificação de regressão.
Verificação: script valida docs/failures/*.md para uma seção "Detecção".

Regra: Documentação de perfil e modelos devem permanecer alinhados.

…