Pouco importa o que eu consigo fazer aqui, se você não conseguir fazer aí.

Tudo que vem a seguir é replicável no seu projeto, com a sua arquitetura, hoje. E não exige curso, framework proprietário nem ferramenta específica. Os links de referência cobrem Claude Code, Codex, Copilot, Cursor, opencode e Manus, porque o método independe de qual agente você usa.

No primeiro post da série vimos por que modelos e agentes não entregam a sua arquitetura por padrão. No segundo, vimos o que muda quando essa arquitetura é comunicada de forma explícita, em especial com suas negativas, aquilo que o projeto proíbe (ou de forma geral ou em artefatos específicos). Agora fechamos o ciclo: como criar e evoluir o harness que sustentam isso.

Antes de se assustar com o tamanho do post, entenda o que vamos fazer:

1. Criar 2 meta-skills
2. Trabalhar normalmente
3. Usar as meta-skills para criar novas skills e rules
4. Repetir a partir do item 2

Só isso.

Vamos criar as meta-skills juntos e logo em seguida você vai trabalhar normalmente, porém, no final você poderá, caso seja necessário, usar essas meta-skills para criar novas skills e rules que ajudarão o agente a nunca mais cometer os erros que você está corrigindo.

Mas afinal, o que faz parte do harness?

Harness é o conjunto de software, infraestrutura e ferramentas que envolvem um modelo de inteligência artificial para transformá-lo em um agente funcional:

• CLAUDE.md
• Skills
• Rules
• Tools
• MCPs
• SubAgents

Para o foco deste post, que é arquitetura, olhamos para um subset:

• CLAUDE.md
• Skills
• Rules

Os demais são úteis, mas não entram na conversa agora, há muito mais chance de falarmos deles quando o assunto for otimização. Hoje, nesse post o objetivo é tornar o agente funcional, e minha régua para isso é simples:

Um agente que

• não consegue seguir uma arquitetura
• erra várias vezes mais que um profissional
• distribui acoplamento e responsabilidades equivocadas
• e ainda produz essas falhas em escala industrial

não é utilizável em ambiente corporativo ou minimamente profissional.

Mas isso não quer dizer que não tenha solução, a solução é o harness.

O conjunto de instruções que ajudam o agente a comunicar ao modelo adequadamente, o que pode e o que não pode, de forma que os erros se tornem cada vez menores, até que erros deixem de ser corriqueiros e habituais, para se tornarem raros, eventuais ou até ausentes.

Encare o que vem a seguir como guia de campo de batalha, construído por aprendizado empírico, com um objetivo: torná-los competentes em seguir a sua arquitetura, com ganho real de produtividade e aderência.

Passo a Passo

Pré-requisito 1: Ter uma arquitetura

Se não há uma arquitetura para seguir, qualquer resultado é válido.

Você não precisa ter um documento formal que comunique a arquitetura, se tiver, melhor, mas é importante ter, nem que seja na sua cabeça, as principais regras ou se possível todas ou quase todas as regras de construção que fazem diferença.

• Qual é a arquitetura geral
• Quais são os componentes de deploy
• Quais são os componentes arquiteturais a serem reaproveitados.
• Quais bibliotecas não são permitidas e quais são
  • Caso tenha biblioitecas concorrentes, comunique onde se deve usar uma onde se deve usar outra.
• Quais são os estereótipos que você terá na solução
  • Também tenha em mente aqueles que não existirão.
• Qual o nível de segurança, como será feita, como validar?
• Quais tecnologias adotará, quais não, como usará? Quais são as regras a respeito do uso delas?
• Quais outras restrições existem e caso não comunicadas, poderiam gerar erros

Um dos aspectos mais importantes ao conceber uma arquitetura é saber exatamente o que, se for feito, deixará uma ferida em sua arquitetura.

Vou dar alguns exemplos:

• Microsserviços
  • Ignorar resiliência
  • Compartilhar dados via banco de dados entre microsserviços
  • Unir microsserviços diferentes no mesmo repositório
• Monolitos Modulares
  • Permitir que acoplamento entre os estereótipos
    • Http Handler conhecendo detalhes do acesso a dados
    • Acesso a dados conhecendo detalhes do protocolo http, como um HttpContext, HttpRequest ou similares.
  • Reimplementar mecanismos centrais
• Geral
  • Camadas de alto nível, acessando camadas de baixo nível de outras áreas ou segmentos.

Esses são apenas alguns tópicos que me passam pela cabeça.

Pré-requisito 2: um CLAUDE.md enxuto (ou similar)

Aqui não há muito a inventar, basta seguir o que a própria Anthropic recomenda em best practices e memory.

O ponto que importa é o limite de 200 linhas. O motivo é direto: arquivo grande consome contexto e reduz aderência. Se as instruções estão crescendo, o caminho é usar regras com escopo de caminho, carregadas apenas quando o agente toca arquivos correspondentes.

Minha dica prática: use o CLAUDE.md para aquilo que precisa de atenção a qualquer momento. Um overview da arquitetura, os termos técnicos do projeto e uma direção sobre as skills mais importantes. Todo o resto desce para skills e rules.

Se o seu projeto ainda não tem arquitetura definida, estipule alguma coisa como ponto de partida antes de seguir. Pode ser um padrão que você desenhou ou um que o próprio agente proponha. A origem importa menos do que a existência: sem referência escrita, não há como medir aderência depois, e o ciclo inteiro perde o alvo.

Por que baixar skills prontas parece atalho e não é

Existe uma tentação óbvia antes de começar:
repositórios com centenas de skills, listas curadas, pacotes prontos para clonar. Aí você pode pensar que basta baixar tudo, colocar na pasta, economizaria semanas.

A economia é real no primeiro dia. O problema aparece quando você mede o que aquilo mudou no output.

Uma skill vale exatamente a distância entre o que o Code Agent produz por padrão e o que o seu projeto exige. Skill pública foi escrita a partir de material público, que é a mesma origem da massa de treinamento do modelo. A distância que ela cobre tende a zero. Você instala trinta arquivos que ensinam o modelo a fazer o que ele já faria:

• usar injeção de dependência
• preferir async
• separar camadas
• nomear bem.

O agente concorda com tudo, produz o mesmo código de antes, e a sensação de progresso vem da pasta cheia.

Mas há um caso ainda pior, quando a skill copiada realmente carrega decisões. Aí ela carrega as decisões de outra arquitetura:

• o outbox de outro time
• a convenção de nomes de outro domínio
• o particionamento de outra realidade de carga

Aplicada ao seu repositório, ela autoriza o que você proíbe, e faz isso com a autoridade de um artefato que o agente lê como verdade do projeto. Passa a competir com as suas rules, e o agente resolve o conflito pelo critério dele.

Três efeitos colaterais que só aparecem depois:

Você perde o sinal. Código gerado a partir de skill genérica sai plausível, compila e passa no review distraído. O desvio que teria te ensinado o que escrever fica invisível, e o ciclo de aprendizado nunca começa.

Você paga contexto sem retorno. Cada skill instalada ocupa espaço na superfície de disparo. Quanto mais entradas de baixo valor competindo pela atenção do agente, menor a chance de a skill que realmente importa ser carregada na hora certa.

Você herda dívida sem origem. Skill copiada não tem vínculo com nenhum incidente do seu repositório. Quando a arquitetura mudar, ninguém saberá por que aquele arquivo existe, e ele vai continuar lá, contradizendo o código em silêncio.

Vale separar dois tipos de conhecimento:

Skill sobre ferramenta é transferível: como gerar um documento com determinada biblioteca, como operar uma CLI, como consumir uma API específica. Esse conhecimento é o mesmo em qualquer projeto e faz sentido reaproveitar.

Skill sobre arquitetura é intransferível, porque a sua arquitetura não está e nunca estará na massa de treinamento, e também não está no repositório de skills de ninguém.

Repare que os links de referência do prompt a seguir são exatamente do primeiro tipo. Eles ensinam o agente a escrever skills, que é conhecimento de formato. O conteúdo específico, aquilo que descreve o seu sistema, sai do seu próprio código.

O teste que uso antes de manter qualquer skill no repositório é uma pergunta só: o agente teria produzido isso sem ela? Se a resposta for sim, o arquivo está ocupando espaço.

Passo 1: criar as duas meta-skills

O objetivo é ter skills capazes de criar novas skills e rules. Esse trabalho não precisa ser manual, e não deve ser: padronizar formato à mão é justamente o tipo de tarefa que degrada quando o harness passa de uma dúzia de artefatos.

O prompt que uso:

Com base nos links abaixo, crie duas skills:
- Uma que seja capaz de criar, editar e otimizar Skills quando solicitada.
- Uma que seja capaz de criar, editar e otimizar Rules quando solicitada.

Elas devem ser capazes de dizer
- o que fazer
- mas também o que NÃO fazer!!!!!

isso é importante e significativo.

Documentação de Referência
- https://agentskills.io/home
- https://code.claude.com/docs/en/skills
- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- https://developers.openai.com/codex/skills/
- https://manus.im/pt-br/features/agent-skills
- https://learn.microsoft.com/en-us/agent-framework/agents/skills
- https://code.visualstudio.com/docs/copilot/customization/agent-skills
- https://opencode.ai/docs/skills/
- https://cursor.com/pt-BR/docs/skills

Os cinco pontos de exclamação em “o que NÃO fazer” são deliberados, e ligam direto ao post anterior. A negativa é a parte que o agente mais resiste a incorporar, porque a massa de treinamento é feita de código que faz coisas, não de código que se recusa a fazê-las. Meta-skill que gera apenas instruções positivas produz um harness que ensina o caminho certo e deixa todos os errados abertos.

Uma proibição isolada também não resolve. O modelo preenche o vazio com a segunda opção mais provável da distribuição, que costuma ser tão ruim quanto a primeira. Toda negativa precisa vir acompanhada da alternativa correta no mesmo bloco.

Skill ou Rule: como decidir

Essa é a primeira dúvida prática que aparece, e vale resolver antes de gerar qualquer artefato.

Rule é invariante. Vale sempre, ocupa contexto de forma permanente e por isso precisa ser curta e majoritariamente negativa. Se a frase começa com “nunca” ou “toda classe X deve”, é rule.

Skill é procedimento carregado sob demanda. Descreve como executar um estereótipo do projeto: criar um command handler, publicar um evento de domínio, montar um consumer idempotente. Custa contexto apenas quando dispara, o que permite ser longa e detalhada. Se a frase começa com “para implementar Y”, é skill.

Invariante transformada em skill nunca carrega no momento em que importa. Procedimento transformado em rule consome contexto antes da primeira linha de código. Deixe esse critério dentro das próprias meta-skills, e a decisão passa a ser tomada por quem escreve todos os artefatos seguintes.

O output desse passo são duas skills prontas. Daqui pra frente, basta trabalhar normalmente.

Passo 2: o fluxo de trabalho

Enriquecimento do contexto

Em um contexto novo, em geral peço para analisar algum fluxo de código existente que será modificado, mostrando alguns arquivos-chave e pedindo para explicar como aquilo funciona.

Isso me permite ver quais arquivos foram lidos, quais dados estão no contexto e o que ficou faltando. É o mesmo processo de pedir para um humano descrever algo que você já conhece, só para validar o entendimento.

É comum nesses casos que a resposta do Agente venha incompleta ou até errada. Ele lê certo, mas a explicação está enviesada, incompleta, ou até foi na direção oposta.

Nosso objetivo aqui é assegurar alinhamento. Significa que queremos que o agente tenha no contexto:

• O que o código faz.
• Quem são os artefatos
• Para que o código faz o que faz
• Porque faz do jeito que faz

Se alguma explicação está equivocada, ou se o entendimento estiver superficial, eu explico detalhadamente e complemento. O objetivo é que o contexto carregue intenções, objetivos, restrições e toda a explicação que o agente precisa além do código.

Não porque ele “vá entender algo”, lembra, modelos não pensam. Mas quando você elabora o contexto, você entrega tokens que enviesarão o percurso do modelo na obtenção de novos tokens. Por isso alinhamento é absolutamente importante, por isso conhecer as palavras certas, o jargões corretos, e principalmente manter o contexto sem compactação, é fundamental.

Faço isso sempre. Conforme as skills nascem, a necessidade desse reforço cai drasticamente.

Criação do plano

Hora de solicitar uma tarefa, com framework ou sem, do jeito que você preferir. É onde você diz o que precisa ser feito e, quando possível, como precisa ser feito.

Um detalhe que muda o resultado: use demanda real de roadmap. Escrever “Crie um endpoint de cadastro” produz código genérico e revela pouco. “Implemente o cancelamento de assinatura com estorno proporcional, respeitando a carência do contrato” força o agente a atravessar domínio, persistência, mensageria e cache no mesmo PR. É na travessia que as violações aparecem, e harness calibrado em CRUD desmonta na primeira feature séria.

Execução do plano

Com o plano aprovado, execute normalmente.

A jornada inteira precisa caber em um contexto, sem compactação

Este é o requisito operacional mais importante do método, e um dos mais fáceis de violar sem perceber.

Depois da compactação, o que sobrevive é o resumo do que deu certo. As tentativas erradas, as correções intermediárias e a redação exata que finalmente funcionou desaparecem. E é exatamente esse material que você precisa para escrever a skill, porque ele documenta a distância entre o que o agente produziu por padrão e o que o projeto exige.

Skill escrita a partir de contexto compactado documenta uma suposição sobre o que o agente não sabia. Skill escrita a partir do contexto íntegro documenta o que ele comprovadamente não sabia, com a formulação que comprovadamente corrigiu.

Se a demanda não couber em um contexto, quebre a demanda.
Não deixe o contexto ser compactado pelo agente.
Caso compacte, não crie skills, deixe para outro momento, outra tarefa.

Não há meio termo. Se o contexto foi compactado por acidente, já era. Não é possível gerar uma skill decente.

Validação e correção do output

Se algo saiu do lugar durante a execução, em especial se não seguir sua arquitetura, corrija com o agente ou manualmente, como faria normalmente.

O ponto de atenção aqui é o que conta como “fora do lugar”. Sem critério, você só enxerga o desvio que já estava procurando. Uso estas dimensões:

Dimensão	Pergunta
Estereótipo	Usou a abstração do projeto ou criou uma paralela?
Dependências	Alguma camada referenciou o que não deveria?
Transação	O limite transacional está onde a arquitetura define?
Observabilidade	Log estruturado, trace e métrica saíram por padrão?
Resiliência	Timeout, retry e idempotência foram tratados ou assumidos?
Configuração	Valores literais ou binding tipado?

Corrija até o código ficar no ponto em que você aprovaria em produção. Cada iteração aqui revela uma informação que faltava, e a sequência dessas correções é a matéria-prima do próximo passo.

Passo 3: criação das skills e rules específicas

Se o agente gerou algo 100% aderente à sua arquitetura, perfeito, esperamos um momento em que isso não seja verdade, pois aqui não há o que fazer.

Se seu agente gera 100% do código aderente à sua arquitetura toda vez sem harness específico, sua arquitetura tem algo de muito especial. Provavelmente está como a média do GitHub: um lixo.

Mas se encontrou algo que precisou de correção, aqui está a dica de ouro. Como você fez tudo em um único contexto, e esse contexto não foi compactado, você tem tudo que precisa para solicitar a criação da skill que reduzirá (ou eliminará) seu esforço no futuro para lidar com os mesmos problemas.

O prompt pode ser algo assim:

Analise as skills e rules existentes nesse repo, corrija para que novas
execuções não demandem essas correções e que as novas tarefas sejam
executadas sem a necessidade de intervenção. Caso seja necessário,
crie novas skills e/ou rules

Alguns prompts que já usei em sessões reais:

agora preciso corrigir as skills para que isso não ocorra novamente, 
busque as skills utilizadas nessa sessão, somente elas, e corrija, 
para que isso não ocorra novamente.

você criou as filas para esses eventos? 
e os consumidores? 
crie, está faltando. 
Documente isso novamente nas skills, não pode deixar de ocorrer

com base em tudo que conversamos, planeje novas skills, e planeje
alterações e atualização no @CLAUDE.md

aproveitando, adicione uma observação no @CLAUDE.md para que esse
processo de introspecção e aprendizado (criar e atualizar skills ou
o próprio claude.md) ocorra ao final de tarefas significativas.
se precisar, pergunte...

com base em tudo que conversamos, preciso que analise as skills
existentes, e use o /create-skill para

- criar novas skills se necessário.
- alterar skills existentes

analise o @CLAUDE.md e decida se ele precisa de updates.

Repare no penúltimo: além de criar as skills, ele instrui o agente a tornar essa introspecção parte do próprio protocolo de trabalho. O harness passa a se manter sozinho ao final de cada tarefa significativa.

Como é o artefato que sai daqui

O output de uma rule bem gerada tem esta cara:

## RULE-014: publicação de evento de domínio passa pelo outbox

**Escopo:** src/**/Domain/**, src/**/Application/**
**Proibido:** instanciar ConnectionFactory, IConnection ou IChannel
            fora de src/Infrastructure/Messaging
**Correto:** injetar IDomainEventOutbox e usar EnqueueAsync dentro
            da mesma unidade de trabalho
**Verificação:** teste de arquitetura ArchUnitNET em
            tests/Architecture/MessagingRules.cs
**Origem:** PR #482, evento perdido em rollback de transação

Dois campos merecem atenção.

Verificação é o que separa restrição de sugestão. Rule que depende de o agente lembrar de ler é comentário. Rule verificada por analyzer ou teste de arquitetura quebra o build antes do code review, e passa a valer também para os humanos do time. Rule que só pode ser verificada por leitura humana provavelmente deveria ser skill.

Origem parece burocracia e é o que impede o harness de apodrecer. Daqui a oito meses alguém vai propor remover uma regra que “não faz sentido”. O link para o incidente responde antes da discussão começar.

Passo 4: Repetir

O objetivo com as novas Rules e Skills é educar o agente de forma que na próxima tarefa, ele já tenha no contexto o necessário para fazer certo, copiando decisões da sua arquitetura sem tomar decisões que se sobreponham.

É esperado que os erros cometidos nesse contexto não sejam cometidos nos próximos. Isso não é verdade 100% do tempo, mas com poucos ciclos, se aproximar do 100% de aderência a algum assunto é muito comum.

Bonus

Na hora de mudar alguma regra, isso pode ser necessário, você pode pedir para o agente também atualizar a regra para você.

A regra continua sendo a mesma: só lidar com skills no mesmo contexto da tarefa, e que esse contexto não tenha sido compactado.

O harness cresce por sintoma, nunca por planejamento

Ninguém consegue prever quais regras o seu projeto precisa. Sentar para escrever o harness completo antes do primeiro PR produz documentação sobre problemas hipotéticos, enquanto os problemas reais continuam passando.

O harness que funciona nasce assimétrico: sete rules sobre mensageria porque foi ali que o agente errou mais, duas sobre cache, nenhuma sobre autenticação porque aquele módulo nunca foi tocado. Essa distribuição desigual é o retrato honesto de onde a sua arquitetura é difícil de inferir.

E o custo de ignorar o ciclo é silencioso: cada correção que você faz no chat e não converte em artefato é uma correção que você fará de novo na semana que vem, provavelmente no PR de outra pessoa.

Quantas vezes você já explicou a mesma decisão arquitetural para um agente, e deixou essa explicação morrer junto com a sessão?