Cheatsheet do harness do agente: componentes, arquivos, problemas comuns e checklist de execução

Os cinco subsistemas do harness

Ordem para montar do zero: feedback → instruções → estado → ambiente → ferramentas.

Arquivos do harness

Esqueleto do AGENTS.md

# Projeto: backend de pagamentos (FastAPI, PostgreSQL)

## Execução
docker compose up -d && ./scripts/init.sh

## Verificação
make check   # lint, tipos, testes unitários, arch-check
make e2e     # cenários de ponta a ponta

## Definição de pronto
- make check e make e2e terminam com código 0
- a funcionalidade é marcada como passing pelo script scripts/verify.sh
- PROGRESS.md atualizado

## MUST
- acesso ao banco apenas pelos repositórios
- segredos lidos apenas de variáveis de ambiente

## Documentos
- docs/payments.md — quando a tarefa envolver pagamentos e estornos
- docs/migrations.md — quando o esquema do banco mudar

Estados da funcionalidade

Níveis de verificação

O direito de dizer «pronto» vem só depois do nível mais alto. Testes unitários verdes não significam pronto.

Transformar regras em mecanismos

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: a camada de serviços não acessa o banco diretamente"
  echo "FIX: use o repositório de app/repositories/"
  fail=1
fi
exit $fail

Problemas comuns e soluções

Papéis em tarefas longas

Orçamento do trabalho autônomo

• O objetivo em uma frase (por exemplo: todas as funcionalidades em passing).
• WIP = 1, com limite de tempo e de tentativas por funcionalidade.
• A métrica sobe de forma monotônica; qualquer regressão leva a rollback imediato.
• Migrations, infraestrutura e dinheiro são encaminhados a uma pessoa.
• Depois de várias reprovações na revisão, a funcionalidade recomeça com contexto limpo.

Checklist para executar o agente

1. Existe AGENTS.md: stack, como subir, comando de verificação, definição de pronto.
2. O make check passa em um clone limpo.
3. O ambiente é reproduzível: arquivos de lock, Docker ou devcontainer.
4. O agente tem permissão para os comandos necessários; os perigosos são proibidos ou ficam no sandbox.
5. Existe pelo menos um E2E para o cenário principal.
6. Existe PROGRESS.md, e a regra manda lê-lo no início da sessão.
7. A lista de funcionalidades tem status, e só uma está ativa.
8. O status passing é definido pelo script.
9. As mensagens de verificação trazem WHY e FIX.
10. A tarefa tem critérios de aceite e limites de escopo claros.
11. Está definido o que exige decisão humana.
12. O verification gap foi medido antes das mudanças, para servir de comparação.

Métricas do harness

Conclusão

O harness é um circuito, não um arquivo: instruções, ferramentas, ambiente, estado e feedback. Comece pela verificação, mantenha o AGENTS.md curto, deixe a decisão de «pronto» para o script e revise o harness com regularidade. Tudo isso se reúne no curso de harness engineering, em um harness completo sobre um projeto real.