Harness Engineering Playbook
Coletânea de skills, hooks e configurações de harness que uso e ajusto continuamente em produção - material vivo da pesquisa do Comitê de IA.
O modelo é commodity. O harness é onde mora a confiabilidade.
Trocar de modelo é trivial e fica mais barato a cada mês. O que separa um agente que faz demo bonita de um que roda confiável no dia a dia não é o modelo - é tudo que está em volta dele: o system prompt, as ferramentas disponíveis, as skills, os hooks, as permissions e a forma como o contexto e a memória são gerenciados.
Esse "tudo em volta" é o harness, e ele é sob medida. Por padrão eu reconfigurava as mesmas coisas em cada repositório, refazia os mesmos refactors à mão e torcia para o agente lembrar das regras. Repetição manual é dívida - precisava virar configuração versionada.
Tratar o harness como produto pessoal: versionado, revisado e em ajuste contínuo.
- - Tese: o modelo é commodity; o harness é onde mora a alavancagem e a confiabilidade de verdade.
- - Skills reutilizáveis em SKILL.md para tarefas recorrentes - o agente carrega só quando a descrição casa com o contexto.
- - Hooks como guardrails determinísticos: formatação no PostToolUse, bloqueio de comandos destrutivos no PreToolUse.
- - Permissions e gestão de contexto/memória ajustados a partir da pesquisa aplicada do Comitê de IA da Bamse.
Capturar o que já funciona antes de generalizar.
Toda skill ou hook nasce de uma dor concreta que apareceu mais de uma vez. Se eu refiz o mesmo refactor à mão três vezes, isso vira material do playbook.
Escrever o guardrail como código, não como pedido educado.
Formatação automática, bloqueio de comandos perigosos e checagens de lint não dependem do modelo lembrar. Ficam em hooks PreToolUse/PostToolUse que o harness executa, não o agente.
Versionar tudo e tratar como código de produção.
Skills, hooks e settings.json moram no Git, passam por review e evoluem com diff. Mudança de comportamento do agente é mudança de código - rastreável e reversível.
Levar os achados para o Comitê de IA e trazer de volta.
O que sobrevive ao uso diário no projeto da OMO vira recomendação no comitê; o que o comitê valida volta para o meu harness pessoal. Loop fechado.
O playbook não tem versão final - ele é o registro vivo do que eu realmente rodo todo dia, e muda toda vez que um caso novo aparece.
- - Skills cobrem hoje os refactors e scaffolds que eu mais repetia - menos digitação repetida, mais consistência entre PRs.
- - Hooks de PostToolUse rodam lint e format sem eu pedir; PreToolUse barra `rm -rf` e pushes em branch errada antes de acontecerem.
- - settings.json e permissions afinados reduziram a quantidade de prompts de permissão sem abrir mão dos guardrails.
- - É material vivo: nada aqui está "pronto". Cada semana de uso real expõe um caso novo que vira hook, skill ou linha no CLAUDE.md.