📜 AGENTS.md: as regras da casa

O nome assusta, mas o arquivo é simples. AGENTS.md é um arquivo de texto comum, que você abre no Bloco de Notas. A terminação .md só avisa que ele usa um jeito leve de marcar títulos e listas.

Esse jeito se chama Markdown. Você escreve normalmente e usa três ou quatro símbolos para dar forma ao texto. As IAs leem Markdown muito bem, e por isso ele virou o formato padrão de instruções.

Como ler o desenho: à esquerda está o texto cru, do jeito que você digita. À direita, o mesmo texto com as marcas aplicadas. O Codex entende os dois lados: as marcas só ajudam a separar assuntos.

Toda vez que você abre uma conversa nova num projeto, o Codex lê o AGENTS.md antes da sua primeira mensagem. Você não precisa pedir nem anexar nada.

Na prática, o que está escrito ali ele sabe sempre. É como o crachá e o manual que um funcionário novo recebe na porta: antes de atender o primeiro cliente, ele já sabe as regras da casa.

Como ler o desenho: o passo 2 acontece sozinho e antes do passo 3. Por isso a resposta do passo 4 já sai no tom e nas regras que você definiu, mesmo que a sua mensagem seja curta.

A primeira parte do AGENTS.md responde duas perguntas: quem é você e qual é o papel do agente. Parece óbvio, mas muda tudo. Sem isso, ele escreve para "qualquer pessoa".

A Paula escreveu: "Você é o assistente do escritório da Paula, consultora de RH que trabalha sozinha. Seu trabalho é poupar o tempo dela com a operação, para ela focar nos clientes". Em seguida vêm as regras de trabalho e as de segurança.

Como ler o desenho: leia de baixo para cima. A identidade sustenta tudo; sem ela, as regras ficam soltas. O bloco azul do topo é o mapa de rotas, que vem a seguir.

Leia os arquivos desta pasta e escreva um rascunho de AGENTS.md na raiz. Use quatro seções: "Quem sou eu" (sou <seu nome>, <sua profissão>), "Seu papel", "Regras de trabalho" e "Segurança". Em Segurança, inclua: pedir confirmação antes de apagar, mover ou enviar qualquer coisa. Me mostre o texto antes de salvar.

Com o tempo, a pasta cresce. Projetos grandes chegam a milhares de arquivos. Sem um guia, o Codex abre um por um até achar o certo, e isso custa tempo e cota.

O mapa de rotas é uma lista curta no AGENTS.md: "precisa disto, vá ali". Funciona como as placas de uma estrada. Ele lê a placa e segue direto para a saída certa.

Como ler o desenho: o ponto azul é o Codex procurando algo. Em vez de entrar em todas as ruas, ele lê a placa e pega a saída certa. Cada placa é uma linha do seu mapa de rotas.

Cada projeto tem o seu AGENTS.md, com as regras daquele trabalho. O da Paula fala de clientes e propostas. O do Rui fala de estoque, preço e promoção.

Se o Rui copiasse o arquivo da Paula, o Codex escreveria promoção de cimento com tom de consultoria de RH. Regras certas, projeto errado, resultado estranho.

Como ler o desenho: cada pasta carrega o próprio arquivo de regras. Quando o Rui abre loja-rui, o Codex lê só o AGENTS.md da loja. As regras da Paula ficam do outro lado da linha vermelha.

O que olhar na tabela: as quatro partes são as mesmas nos dois arquivos. O que muda é o conteúdo. Use essa estrutura como molde em todo projeto novo.

O AGENTS.md nunca fica pronto de primeira. Ele melhora com o uso. A regra prática é simples: corrigiu o agente duas vezes pela mesma coisa, vira linha no AGENTS.md.

O Rui pediu duas vezes "não use ponto de exclamação nas promoções". Na terceira, mandou o Codex anotar. Desde então, nenhuma promoção saiu gritando.

Como ler o desenho: siga as setas no sentido horário. Cada volta acontece quando um erro se repete, e termina com uma linha nova no arquivo do centro. Com algumas semanas de uso, as correções ficam raras.