Caso 07 Instruções · Skills · Verificação
Harness pessoal: IA com instruções, contexto e verificação
Uso IA ativamente no meu fluxo de desenvolvimento. Para que a velocidade não vire débito técnico, construí um harness pessoal: instruções, skills, contexto da tarefa, escolha de modelo e verificações que envolvem cada uso de agentes.
Contexto
Por harness, entendo o conjunto que envolve o uso de agentes de IA no meu trabalho: as instruções que eles seguem, as skills que executam, o contexto que recebem, o modelo e o nível de raciocínio escolhidos para cada tarefa e as verificações que o resultado precisa passar.
Ele é pessoal e evolui com a prática. Parte das skills está publicada em um repositório público, com versões para Claude Code, Codex CLI e OpenCode.
Problema
Assistentes de IA produzem código mais rápido do que uma equipe consegue entender, revisar e manter. Sem regras e verificação, a velocidade vira débito técnico: estilos inconsistentes, testes que apenas repetem a implementação, problemas de segurança e desempenho que passam despercebidos.
A pergunta não é se usar IA, mas como usá-la sem abrir mão de julgamento humano e de código compreensível.
Minha responsabilidade
Construí o harness e mantenho as instruções e skills que o compõem. Defino regras para os agentes com objetivos explícitos de qualidade e escolho, para cada tarefa, o modelo e o nível de raciocínio adequados, com apoio de Jev, da TypeSafe AI, uma ferramenta que utilizo nesse processo.
Continuo responsável por revisar o resultado e confrontá-lo com os requisitos.
Decisão
As regras que defino para os agentes miram atributos concretos: manutenibilidade, com Clean Code e responsabilidades claras; desempenho, com diretrizes explícitas e validação; segurança, com revisão e instruções orientadas a riscos; resiliência, com testes significativos e prevenção de regressões; legibilidade dos testes, com BDD; e consistência, com as convenções de cada projeto.
A IA acelera a escrita. O entendimento do problema, as decisões e a verificação continuam sendo trabalho de engenharia.
Alternativas e trade-offs
Análise atual, escrita para este site. Não é um registro das alternativas avaliadas na época.
- Instruções e skills custam manutenção: ficam desatualizadas se o projeto muda e não são lidas. Por isso trato instruções como código: revisadas e ajustadas sempre que um problema aparece.
- Nenhum harness garante software sem defeitos, seguro ou escalável. Ele aumenta a chance de acertar e torna os erros mais fáceis de encontrar; a verificação continua necessária.
Implementação
As peças do harness e o papel de cada uma:
Instruções por projeto
Arquivos de orientação com arquitetura, convenções, comandos reais e restrições do projeto, para que o agente comece pelo contexto certo.
Skills reutilizáveis
Fluxos como planejamento em etapas com aprovação, revisão de código, refatoração de testes com BDD e investigação de bugs com hipóteses ranqueadas.
Jev, modelo e raciocínio
Uso Jev, da TypeSafe AI, para apoiar a escolha de harness, modelo e nível de raciocínio conforme a tarefa. A decisão e a verificação continuam sob minha responsabilidade.
Verificação
Checagem de tipos, testes, build e revisão humana antes de considerar uma tarefa concluída.
Resultado
O objetivo é entregar mais rápido sem abrir mão de julgamento humano, código compreensível e verificação.
Instruções claras e testes apoiam a qualidade; não garantem, sozinhos, software sem defeitos. A responsabilidade pelo que vai para produção continua sendo minha.