Instruções para agente de código: o que entra no arquivo

O arquivo de regras é onde o agente aprende o que pode decidir sozinho. Se o arquivo não diz o que é terminar, o agente para assim que o trabalho parece pronto, e você vira o revisor de tudo. As regras abaixo saem da documentação de práticas do Claude Code e da pesquisa do Nielsen Norman Group sobre trabalhar com IA.

O critério de pronto vem antes do pedido

A documentação de práticas do Claude Code (em inglês) explica o mecanismo em uma frase: o agente para quando o trabalho parece pronto. Sem uma checagem que ele mesmo consiga rodar, “parece pronto” vira o único sinal, e cada erro fica esperando você perceber.

O critério de pronto é um sinal que o agente lê sozinho. Serve a suíte de teste, o código de saída do build, o linter, ou um script que compara a saída com um arquivo de referência. A mesma página lista o que fazer com isso na prática. Peça os casos de teste junto da função, a captura de tela comparada com o desenho e a correção do erro de build na causa, em vez de silenciar o erro.

Isso muda o formato do pedido. Uma especificação que funciona nomeia os arquivos e as interfaces envolvidos, diz o que está fora de escopo e termina com uma verificação ponta a ponta. O que você escreve antes passa a valer mais do que qualquer correção no meio do caminho.

Uma checagem que passou uma vez não é avaliação. Agente de código gera de novo a cada pedido, e o Nielsen Norman Group lembra que essa geração varia de uma rodada para outra (em inglês). Rode a verificação mais de uma vez antes de tratar o resultado como sinal firme. O método completo fica em avaliação de saída de IA.

O arquivo que carrega em toda sessão precisa ser curto

O arquivo de regras é lido no começo de cada conversa, então tudo que entra nele ocupa contexto em todas as tarefas. A página de práticas recomenda um teste por linha: se remover essa linha não fizer o agente errar, corte. A própria documentação aponta o efeito colateral de um arquivo inchado: a regra se perde no meio do texto e o agente passa a ignorar instruções que estão escritas.

Quando uma regra é ignorada com frequência, o conserto não é reescrever o arquivo inteiro. A orientação é dar ênfase a essa linha sozinha, porque destaque espalhado por várias linhas não destaca nenhuma.

O que não for regra geral sai daqui. Conhecimento que só vale para um tipo de tarefa pertence a um arquivo que o agente carrega quando a tarefa aparece, e não ao arquivo que carrega sempre.

Autonomia se escreve junto com o ponto de parada

Pedir permissão a cada passo parece seguro e não é. A documentação descreve o efeito real do modo manual: depois da décima aprovação você está clicando em vez de revisando (em inglês). A pausa que ninguém planejou vira um carimbo automático.

O desenho que funciona separa três coisas. Ferramentas de leitura e comandos que você já confia entram numa lista de aprovação prévia. O que modifica o sistema pede decisão. O que não tem volta pede uma pessoa, e essa lista é curta e explícita.

Uma regra que não pode falhar não deve viver como instrução. A documentação é clara sobre a diferença: instrução em texto é conselho, hook é determinístico e garante que a ação aconteça. Lint antes do commit, teste antes do push e a varredura de segredo são hook, não frase.

Instrução nova entra em fila, e a pesquisa vai para um subagente

Uma instrução nova não deveria cancelar a execução em andamento. Ela entra na fila e o trabalho anterior termina, porque tarefa interrompida no meio deixa o repositório em estado que ninguém sabe descrever.

Pesquisa é o caso em que vale gastar contexto separado. O artigo IA no fluxo de design descreve a mesma divisão entre o que a ferramenta faz e o que fica com a pessoa. A documentação recomenda subagentes para investigação, porque eles rodam com contexto próprio e param de encher a conversa principal com arquivos que só serviam para achar um caminho. Leitura de repositório grande é o exemplo que a página dá.

Aqui a orientação mudou em relação ao que se dizia antes. O NN/g recomendava tratar a IA como estagiária (em inglês), com projeto fechado e direção passo a passo, justamente porque projeto aberto sem direção rende saída genérica. A prática atual inverte a forma do pedido sem inverter o princípio: você continua dando direção, só que escrevendo o critério de pronto e deixando o agente trabalhar até ele.

A revisão olha o diff, não a base

Revisão de código de agente se faz pelo que mudou. Um commit grande não pode ser revisado por ninguém, nem por você na semana seguinte, e é por isso que a recomendação de commit pequeno e descritivo vale em dobro aqui.

A documentação também avisa onde o registro não é confiável: os pontos de retorno acompanham só as mudanças feitas pelas ferramentas de edição do agente. O que passou por linha de comando ou por processo externo não entra. Git continua sendo o histórico, e o checkpoint não substitui.

Peça evidência em vez de afirmação. A página põe isso como economia de tempo. Ler a saída do teste, o comando executado e o que ele devolveu é mais rápido do que refazer a verificação por conta própria.

O que saiu sem fonte precisa de marca

Modelo de linguagem às vezes entrega uma resposta que soa certa, está errada e vem cheia de confiança. O NN/g descreve a alucinação exatamente assim (em inglês), como dado que parece verdadeiro e não é, apresentado de um jeito que dificulta a identificação.

O problema é que conferir dá trabalho, e é esse trabalho que decide se alguém confere ou não. A revisão do NN/g mostra que as pessoas pulam a verificação (em inglês) porque a ferramenta foi adotada justamente pela promessa de eficiência. O mesmo artigo avisa que conferir de novo é obrigatório depois de uma correção, já que a nova versão pode introduzir outro erro.

A regra que sobra para o arquivo é curta, e ela já vale em qualquer fluxo de IA, como no trabalho de síntese. Toda afirmação de fato carrega a fonte ou recebe a marca de não verificada. O que não dá para verificar não é entregue, e essa frase está na própria lista de falhas comuns da documentação de práticas.

Onde os artigos do NN/g divergem entre si

Os dois artigos discordam sobre onde a instrução deve morar. O Your AI UX Intern (em inglês) pede instrução detalhada no pedido, passo a passo, porque a ferramenta se perde em projeto aberto. O artigo The 3 Roles of Context for AI Agents (em inglês) aponta o caminho inverso. Quem usa agente todo dia monta uma biblioteca de contexto, e o que mais pesa passa a ser a curadoria dessa biblioteca.

Eles também divergem sobre o valor de uma rodada. O One AI Output Is an Example, Not an Evaluation (em inglês) trata a saída isolada como amostra que não sustenta conclusão, e pede rodadas repetidas com intervalo de confiança. O artigo da estagiária trata a primeira passada como aproveitável, desde que alguém revise depois.

O que os dois mantêm é a fronteira. O agente entrega rascunho e evidência, e a decisão de aceitar continua sendo de uma pessoa, com nome no commit.