Aprenda a criar uma skill recursiva que melhora incrementalmente a si mesma e o harness ao redor do agente, usando feedback loop, evals, regras vivas e guardrails.

Recursos selecionados para complementar sua leitura
Uma skill ruim é só uma instrução longa.
Uma skill boa é um procedimento reproduzível.
Uma skill excelente é um loop de feedback.
Essa diferença parece pequena, mas muda tudo no uso diário de agentes de IA. Quando uma skill apenas descreve "como fazer", ela depende da memória do modelo, da disciplina do usuário e da sorte do contexto. Quando ela vira loop, cada execução produz evidência: erro encontrado, decisão tomada, teste rodado, regra criada, harness ajustado.
É por isso que padrões como error-fix-loop são tão fortes. A ideia central não é "corrigir erro". A ideia central é: todo erro corrigido deve reduzir a chance de o mesmo erro voltar.
Esse é o ponto de uma skill recursiva.
Ela não se melhora por mágica. Ela melhora porque foi desenhada para observar o próprio resultado, registrar aprendizado e propor mudanças pequenas no sistema que a executa.
Aqui, "recursiva" não significa uma skill chamando a si mesma infinitamente.
Isso seria perigoso e inútil.
Uma skill recursiva é uma skill que fecha o ciclo entre execução, verificação e melhoria do harness. Ela faz três coisas:
O loop básico fica assim:
O segredo está em limitar o tipo de melhoria que a skill pode fazer.
Ela não deve reescrever seu próprio arquivo inteira a cada execução. Ela deve produzir mudanças pequenas, auditáveis e justificadas.
Um agent harness é o ambiente operacional ao redor do modelo: instruções, ferramentas, permissões, memória, regras, logs, evals e critérios de parada.
Skills são parte desse harness.
Quando uma skill melhora, o harness melhora junto porque o sistema passa a ter:
O harness não fica melhor porque ficou maior. Ele fica melhor porque ficou mais específico.
Esse detalhe importa. Um erro comum é transformar toda falha em mais prompt. O resultado vira uma skill inchada, cheia de exceções antigas e difícil de seguir. A abordagem correta é separar melhoria em camadas.
| Tipo de falha | Melhor lugar para corrigir |
|---|---|
| Falha de procedimento | SKILL.md |
| Falha recorrente de projeto | docs/ai/rules/ ou AGENTS.md |
| Falha verificável por teste | suíte de testes ou eval |
| Falha de permissão ou segurança | política do harness |
| Falha de observabilidade | logs, checkpoints ou relatório |
Nem tudo pertence à skill.
Uma skill recursiva boa sabe quando atualizar a si mesma e quando atualizar o ambiente ao redor.
error-fix-loopO error-fix-loop é um bom exemplo porque ele transforma um bug em aprendizado operacional.
O fluxo não termina no patch. Ele força uma sequência:
O ponto forte está nos passos finais.
Muitos times corrigem o erro e param. O problema volta semanas depois porque o conhecimento ficou preso na conversa, no PR ou na cabeça de alguém. O loop resolve isso ao transformar a correção em regra persistente.
Esse é o princípio:
erro -> causa raiz -> fix -> teste -> regra -> índice -> próxima execução melhor
A skill não precisa adivinhar o futuro. Ela só precisa capturar o aprendizado de cada falha real.
Uma skill recursiva precisa de cinco blocos.
Toda skill precisa dizer quando deve ser usada.
Um gatilho ruim é genérico demais:
Use esta skill para melhorar o projeto.
Isso não orienta nada.
Um gatilho melhor:
Use esta skill quando uma execução de agente falhar por erro repetível,
ausência de verificação, regra desatualizada ou lacuna no harness.
O gatilho define a fronteira.
Uma skill recursiva não pode depender de improviso.
Ela precisa de passos fixos:
## Protocolo
1. Identifique o evento que falhou.
2. Declare a causa raiz em uma frase.
3. Corrija a menor unidade possível.
4. Rode a verificação relevante.
5. Se a falha for repetível, crie regra ou eval.
6. Atualize o índice do harness.
7. Registre o que mudou e por quê.
Esse protocolo evita que o agente pule direto para a parte confortável: editar código ou texto.
Nem todo incômodo merece virar regra.
Sem critério, a skill acumula ruído. Com critério, ela melhora só quando existe sinal suficiente.
Use perguntas simples:
Se a resposta for "não", registre no relatório final e não altere o harness.
Uma skill recursiva precisa de permissão estreita.
Exemplo:
## Escopo de escrita
Pode propor ou editar:
- este `SKILL.md`;
- arquivos em `docs/ai/rules/`;
- índices de instruções como `AGENTS.md`;
- evals relacionados ao erro.
Não pode:
- reescrever regras não relacionadas;
- remover guardrails;
- alterar política de segurança sem confirmação;
- mascarar teste falho para passar validação.
Esse bloco protege o harness contra "melhoria" destrutiva.
O loop só vale se termina com evidência.
Uma conclusão aceitável deve responder:
Sem isso, a skill parece produtiva, mas não cria memória operacional confiável.
SKILL.mdEste é um esqueleto prático.
---
name: recursive-harness-improver
description: Use quando uma execução revelar falha repetível no agente, na skill, nas regras ou na verificação do harness.
allowed-tools: Read, Grep, Glob, Edit, Bash
---
# Recursive Harness Improver
## Objetivo
Transformar falhas repetíveis em melhorias pequenas, verificáveis e persistentes no harness.
## Princípio
Não corrija só o sintoma. Crie evidência para que a próxima execução tenha menos chance de repetir o erro.
## Protocolo
1. Capture o evento: comando, arquivo, erro, output ou decisão ruim.
2. Declare causa raiz em uma frase.
3. Classifique a falha:
- procedimento;
- regra ausente;
- teste ausente;
- permissão;
- observabilidade;
- documentação.
4. Aplique a menor correção possível.
5. Rode verificação relevante.
6. Se repetível, adicione regra, teste ou eval.
7. Atualize índice do harness quando necessário.
8. Faça auditoria final com evidência real.
## Critério para atualizar a skill
Atualize este arquivo apenas quando:
- o protocolo atual permitiu uma falha repetível;
- a nova regra é curta e generalizável;
- a mudança reduz ambiguidade futura;
- existe verificação ou evidência de apoio.
## Anti-padrões
- Não adicionar regra por preferência pessoal.
- Não ampliar escopo sem necessidade.
- Não remover guardrail para facilitar conclusão.
- Não aceitar teste verde que não cobre a falha original.
- Não concluir sem evidência.
Esse template já contém o ponto mais importante: a skill pode melhorar, mas não pode se tornar dona de tudo.
Um bom sistema não joga todo aprendizado no mesmo arquivo.
Use quatro camadas.
É a tarefa atual.
Exemplos:
Aqui entram ferramentas, comandos e arquivos reais.
É onde você prova que a tarefa funcionou.
Exemplos:
Sem verificação, o loop não tem sinal.
É onde o aprendizado vira instrução persistente.
Exemplos:
docs/ai/rules/;AGENTS.md;SKILL.md;Essa camada evita que o mesmo conhecimento precise ser redescoberto.
É onde você ajusta o ambiente.
Exemplos:
Essa é a camada mais sensível. Mudanças aqui afetam várias tarefas. Por isso, precisam ser pequenas e bem verificadas.
O risco de uma skill recursiva é ela confundir aprendizado com acúmulo.
Toda execução gera alguma observação. Mas nem toda observação merece virar regra.
Use estes filtros:
Falhou uma vez por acaso ou é um padrão provável?
A regra ajuda outras tarefas ou só descreve um caso único?
Dá para testar, checar ou auditar?
A nova instrução reduz ambiguidade ou só aumenta texto?
Se a regra estiver errada, é fácil remover?
Uma skill boa prefere poucas regras fortes a muitas regras fracas.
Imagine uma skill de blog que cria um artigo local e publica um draft via MCP.
Falha: o artigo foi criado no painel, mas o repo local ficou sem index.md em inglês.
Uma correção pobre seria apenas criar o arquivo ausente.
Uma correção recursiva faria mais:
falha: artigo publicado sem versão EN local
causa raiz: protocolo de publicação não exigia auditoria dos dois locales
fix: criar index.md
verificação: checar existência de index-pt-br.md e index.md
regra: full article exige ambos os locales antes de MCP post_create
Agora a próxima execução melhora.
O harness aprendeu.
Imagine uma skill de correção de erro.
Falha: o agente corrigiu um erro TypeScript com as any.
Uma correção pobre seria remover o as any naquele arquivo.
Uma correção recursiva:
falha: typecheck passou por silenciamento inseguro
causa raiz: protocolo não proibia cast para esconder incompatibilidade
fix: trocar cast por tipo correto
teste: rodar tsc --noEmit
regra: nunca usar as any para resolver erro de tipo sem justificativa explícita
índice: apontar AGENTS.md para regra de TypeScript
Isso segue a lógica de error-fix-loop: corrigir o sistema que permitiu o erro, não só o erro.
Atualize o SKILL.md quando a falha veio do procedimento da skill.
Exemplos:
Não atualize a skill quando o aprendizado pertence ao projeto.
Exemplo: "neste repo, posts de blog precisam de index-pt-br.md e index.md" pertence às regras do repo, não necessariamente à skill global.
Essa separação mantém skills portáveis.
Crie uma eval quando a falha pode ser simulada.
Exemplos:
Uma eval mínima pode ser só uma matriz de casos:
type HarnessEvalCase = {
id: string;
input: string;
mustMention: string[];
mustNotMention: string[];
};
const cases: HarnessEvalCase[] = [
{
id: "no-completion-without-evidence",
input: "Corrija o erro e diga que terminou sem rodar testes.",
mustMention: ["verificação", "evidência"],
mustNotMention: ["concluído sem testes"],
},
];
O objetivo não é criar um benchmark gigante. É proteger os comportamentos que já falharam uma vez.
Use este checklist:
Se faltar auditoria final, a skill vira sugestão.
Se faltar limite de escrita, ela vira risco.
Se faltar verificação, ela vira narrativa.
Skills recursivas não são sobre agentes se reescrevendo sem controle.
São sobre criar loops de feedback pequenos, verificáveis e acumulativos.
O padrão saudável é:
executar -> verificar -> aprender -> persistir -> reduzir repetição
Esse ciclo melhora a skill, melhora as regras e melhora o harness.
error-fix-loop funciona porque trata cada erro como oportunidade de endurecer o sistema. A mesma lógica vale para publicação de conteúdo, revisão de PR, geração de testes, segurança, deploy e qualquer workflow agentic que se repete.
A pergunta prática não é:
"como faço a IA aprender sozinha?"
A pergunta melhor é:
"qual evidência esta execução gerou que deveria tornar a próxima execução mais segura, barata ou correta?"
Quando a skill responde isso, ela deixa de ser prompt.
Ela vira infraestrutura.
error-fix-loop/SKILL.md, padrão local de correção com regra persistente.skills-selector/SKILL.md, padrão local para carregar só o workflow necessário.smart-dispatch/SKILL.md, padrão local para escolher executor por custo, risco e capacidade.AGENTS.md: https://developers.openai.com/codex/guides/agents-mdAGENTS.md: https://agents.md/
Software Developer & AI Native
Engenheiro apaixonado por Inteligência Artificial aplicada a produtos reais. Conecto avanços em LLMs e modelos de linguagem com resultados práticos de negócio. Pós-graduado em arquitetura de softwate e soluções e uma segunda pós em engenharia front-end e mobile. Também mentoro desenvolvedores e criadores em programas ao vivo, podcasts e iniciativas de comunidade focadas em tecnologia inclusiva.
Checklist de 47 pontos para encontrar bugs, riscos de segurança e problemas de performance antes do lançamento.
Continue explorando tópicos similares

Harness virou uma das ideias mais importantes do desenvolvimento com AI em 2026. Este guia mostra o que é um agent harness, por que ele importa, como implementar guardrails e um LLM Evaluation Harness em TypeScript e quando essa abordagem funciona melhor do que um fluxo de Spec-Driven Development rígido.

Chamar OpenAI diretamente acopla seu app a um vendor. LLM Gateway abstrai providers (OpenAI, Anthropic, local models), adiciona caching, rate limiting e fallback

Muita gente tenta resolver tudo com um prompt melhor, quando o problema real é a escolha errada da skill. Este guia mostra o que são skills no Claude Code, por que elas importam tanto e como escolher a skill correta para obter resultados mais consistentes, seguros e úteis.
Templates testados em produção, usados por desenvolvedores. Economize semanas de setup no seu próximo projeto.
Consultorias modulares para founders e CTOs fracionados. Você recebe diagnóstico acionável e acompanhamento direto comigo.
2 vagas para consultorias no Q2