Guias: instruções que direcionam o agente

Aula 13

AGENTS.md e CLAUDE.md: o README para agentes

O AGENTS.md é um formato aberto, hoje mantido pela Agentic AI Foundation sob a Linux Foundation, descrito como "um README para agentes": um arquivo Markdown simples, na raiz do repositório, com o que o agente precisa saber para trabalhar ali, como comandos de build e teste, convenções de estilo e cuidados específicos. Arquivos AGENTS.md aninhados em subpastas valem para aquela parte do projeto, e o mais próximo do arquivo editado prevalece. Instruções explícitas do usuário no prompt sempre têm prioridade sobre o arquivo. O Claude Code usa o mesmo conceito com o nome CLAUDE.md.

A regra mais importante para esses arquivos é ser curto. Eles são carregados inteiros em toda sessão, então cada linha custa contexto em cada tarefa. A documentação de boas práticas do Claude Code propõe um teste para cada linha: "remover esta linha faria o agente errar?". Se a resposta for não, a linha sai. A HumanLayer acrescenta outra regra: evite instruções condicionais longas ("se estiver mexendo em X, faça Y"), porque elas competem por atenção mesmo quando não se aplicam. Instruções condicionais funcionam melhor como skills, que só carregam quando são relevantes.

# AGENTS.md

## Comandos
- Instalar: yarn install
- Build completo: yarn build
- Testes: yarn test (rápido, rode após cada mudança)

## Regras
- Edite os templates em templates/**/*.eta, nunca os .html gerados.
- Todo texto visível em português do Brasil com acentuação.

## Onde está cada coisa
- Arquitetura: docs/hld.md · Decisões: docs/adr/

O exemplo acima tem o que um bom arquivo de instruções precisa: comandos exatos, poucas regras que de fato evitam erros e ponteiros para onde está o resto. O próprio repositório deste site usa um AGENTS.md assim, com regras numeradas sobre build, templates e conteúdo.

Fontes desta aula: AGENTS.md · Claude Code: Best practices · HumanLayer: Skill Issue

Aula 14

O repositório como sistema de registro

Em fevereiro de 2026, Ryan Lopopolo, da OpenAI, descreveu como um time construiu um produto em que praticamente todo o código foi escrito por agentes Codex. A primeira lição do texto é sobre onde o conhecimento mora: o repositório é o sistema de registro. Tudo o que o agente precisa saber deve estar versionado junto com o código, porque é o único lugar que ele lê de forma confiável. Uma decisão tomada numa reunião ou numa conversa de chat não existe para o agente.

A segunda lição corrige um erro comum: tentar colocar tudo num único AGENTS.md gigante. No relato da OpenAI, o AGENTS.md é curto e funciona como mapa para uma pasta docs/ estruturada, com documentos de arquitetura, planos de execução, especificações de produto e referências. O agente lê o mapa e abre apenas o documento de que precisa, que é a mesma lógica de divulgação progressiva das skills.

A OpenAI também relata que documentação não basta: as regras de arquitetura mais importantes foram transformadas em linters e testes estruturais, com mensagens de erro escritas para o agente saber como corrigir. Essa passagem de guia para sensor é o tema do módulo 6.

Fontes desta aula: OpenAI: Harness engineering (Ryan Lopopolo)

Aula 15

O ratchet: cada erro vira regra, hook ou checagem

Um ratchet é uma catraca: só gira para um lado. Addy Osmani usa a imagem para descrever o hábito que mais melhora um harness: toda vez que o agente comete um erro, o erro vira uma regra, um hook ou uma checagem, de modo que o harness nunca regride. Ele acrescenta um critério de qualidade para o AGENTS.md: cada linha deveria poder ser rastreada até uma falha real que ela evita.

Böckeler descreve o mesmo processo como um loop de direção: quando um problema se repete, melhore as guias ou os sensores para que ele fique menos provável. A escolha de onde colocar a correção segue uma escala de força:

• Instrução no AGENTS.md: rápida de criar, mas consultiva. Use para orientações gerais.
• Skill: para procedimentos que só valem em certas tarefas.
• Hook ou permissão: para regras que nunca podem falhar.
• Lint, teste ou checagem estrutural: para regras de qualidade e arquitetura, com mensagens que ensinam a corrigir.

O ratchet também funciona ao contrário: quando uma regra deixa de ser necessária, porque o modelo melhorou ou o código mudou, ela deve sair. A Anthropic observa no artigo sobre harness de aplicações longas que todo componente do harness codifica uma suposição sobre o que o modelo não consegue fazer sozinho, e essas suposições precisam ser testadas de novo a cada geração de modelos.

Fontes desta aula: Addy Osmani: Agent Harness Engineering · Böckeler: Harness engineering for coding agent users · Anthropic: Harness design for long-running apps

Aula 16

Planos, especificações e arquivos de progresso

Guias não são só regras permanentes. Para tarefas maiores, as guias mais valiosas são documentos da própria tarefa: um plano antes de começar e um registro de progresso durante a execução. A documentação do Claude Code recomenda o ciclo explorar, planejar, implementar e fazer commit, pulando o plano só quando a mudança cabe numa frase.

No artigo sobre harnesses para agentes de longa duração, a Anthropic mostra como esses documentos sustentam o trabalho entre sessões. Um agente inicializador cria um script init.sh para subir o ambiente, um arquivo claude-progress.txt e uma lista de funcionalidades em JSON, com mais de 200 itens no exemplo de um clone do claude.ai, todos marcados como falhando. A escolha do JSON foi deliberada: o modelo tende a reescrever arquivos Markdown, mas respeita mais a estrutura de um JSON com o campo passes.

No artigo seguinte sobre o mesmo tema, um agente planejador transforma um pedido de uma a quatro frases numa especificação completa, mantendo-se em alto nível, e o agente gerador e o avaliador fecham um "contrato de sprint" definindo o que significa pronto antes de escrever código. Essa ideia de documentos que antecedem o código é a base do próximo módulo, sobre Product Brief, HLD e LLD.

Fontes desta aula: Claude Code: Best practices · Anthropic: Effective harnesses for long-running agents · Anthropic: Harness design for long-running apps

Erros comuns

• AGENTS.md que cresce sem parar. Cada incidente vira um parágrafo e o arquivo passa de mil linhas. Corte o que não evita erros reais e mova procedimentos para skills.
• Regras escritas em tom de desejo. "Tente manter o código limpo" não orienta nada. Escreva comandos e restrições verificáveis.
• Conhecimento fora do repositório. Se a decisão não está versionada, o agente não sabe que ela existe.
• Confiar só em guias. Instruções são consultivas. Regras críticas precisam de sensores ou hooks.
• Nunca remover regras. Regras obsoletas consomem contexto e podem impedir soluções melhores.

Aplicação prática

1. Aplique o teste "remover esta linha faria o agente errar?" em cada linha do seu AGENTS.md ou CLAUDE.md e corte o que não passar.
2. Crie uma pasta docs/ com ao menos um documento de arquitetura e faça o AGENTS.md apontar para ela.
3. Abra um arquivo de registro de erros do agente. Para cada erro novo, decida se a correção vai para o AGENTS.md, uma skill, um hook ou um teste.
4. Na próxima tarefa grande, peça ao agente um plano antes do código e um arquivo de progresso atualizado a cada etapa.

Siglas usadas neste módulo

ADR:

Architecture Decision Record, registro de decisão de arquitetura.

HLD:

High Level Design, design de alto nível do sistema.

LLD:

Low Level Design, design de baixo nível, por componente.

JSON:

JavaScript Object Notation, formato de dados em texto.

README:

Arquivo de apresentação de um repositório.