Como fazer o Codex entender você melhor: Domine estas técnicas de memória para aumentar a eficiência em 90%

Depois de usar o Codex App por um tempo, você pode ter encontrado frustrações semelhantes: ter que repetir preferências básicas toda vez que inicia uma nova conversa, ou ele executar acidentalmente comandos do sistema além do esperado.

A essência desses pontos de dor de alta frequência é que seu Codex não possui uma memória estável de longo prazo. Para resolver completamente essas comunicações repetitivas e ineficazes, você precisa construir um sistema de memória completo para ele.

Este artigo vai apresentar como configurar o AGENTS.md e o recurso de Memórias para dar ao Codex uma memória persistente, fazendo com que ele realmente entenda suas intenções e gere ganhos de eficiência.

1. AGENTS.md

1. O que é?

O AGENTS.md é um conjunto de instruções de regras pré-escritas que o Codex lê automaticamente toda vez que é iniciado.

Sem o AGENTS.md, o Codex começa do zero a cada vez — ele não conhece seus hábitos de trabalho, o contexto do projeto ou os limites para executar operações.

Depois que as regras relevantes são configuradas, esses contextos se tornam permanentemente eficazes, e você nunca mais precisará explicar o mesmo problema repetidamente.

2. Como configurar e usar

1️⃣ Camada Global: Armazenada no diretório ~/.codex/AGENTS.md no seu computador local, aplicando-se a todos os seus projetos. Adequada para escrever preferências pessoais globais e regras gerais.

No Codex App, isso corresponde à seção "Instruções Personalizadas" na página de configurações de Personalização.

Aqui está um modelo básico recomendado que você pode copiar e colar diretamente no local mostrado acima e, em seguida, ajustar continuamente de acordo com suas necessidades:

1# AGENTS.md
2
3## Comportamento Básico
4
5- Responder em português por padrão, a menos que o usuário solicite explicitamente outro idioma.
6- As respostas devem ser concisas e diretas, evitando preenchimento desnecessário e repetição.
7- Se a descrição da tarefa não estiver clara, peça confirmação antes de iniciar a execução.
8- Não especule ativamente sobre necessidades além da intenção do usuário; faça apenas o que for solicitado.
9
10## Limites de Segurança
11
12- Padrão somente leitura; não modifique ou exclua ativamente nenhum arquivo, a menos que instruído explicitamente pelo usuário.
13- Antes de envolver operações irreversíveis (como excluir, sobrescrever ou chamar APIs externas para escrever), a confirmação deve ser obtida primeiro.
14- Não imprima chaves, tokens ou credenciais confidenciais na saída.
15
16## Padrões de Engenharia
17
18- Evite engenharia excessiva; faça apenas as alterações explicitamente necessárias ou obviamente necessárias para a tarefa, mantendo a solução simples.
19- Não adicione recursos, refatore código ou execute otimizações extras, a menos que solicitado.
20- Não adicione comentários, anotações de tipo ou docstrings a código não alterado.
21- Adicione comentários apenas quando a lógica não for autoexplicativa.
22- Não adicione tratamento de erros ou lógica de fallback para cenários improváveis de ocorrer.
23- Não crie funções utilitárias ou camadas de abstração que sejam usadas apenas uma vez.
24- Exclua diretamente o código confirmado como inútil; não deixe explicações em comentários.

2️⃣ Camada do Projeto: Armazenada no diretório do projeto, usada principalmente para personalizar regras com base no tema e nas características do projeto.

Um bom AGENTS.md de nível de projeto geralmente deve cobrir os seguintes aspectos:

• Contexto e estrutura do projeto: O que é o projeto e onde estão localizados os diretórios importantes.
• Métodos de execução: Como iniciar, executar ou operar o projeto.
• Padrões e restrições: Padrões que precisam ser seguidos e coisas que explicitamente não podem ser feitas.
• Critérios de conclusão: Como determinar se uma tarefa está finalizada.

3. Melhores Práticas do AGENTS.md

Configurar um AGENTS.md básico é apenas o primeiro passo. Os seguintes princípios práticos determinam o limite superior do seu sistema de memória:

1️⃣ Hierarquia de Regras, Responsabilidades Claras

No Codex, o AGENTS.md segue o princípio da proximidade: Subdiretório > Diretório Raiz > Global. Ou seja, as regras no diretório onde o trabalho atual está localizado têm a maior prioridade.

Isso significa que as regras de nível de projeto substituirão diretamente as configurações globais do mesmo tipo. Se todas as regras forem misturadas, as regras locais de alta prioridade podem facilmente poluir ou destruir acidentalmente a lógica global subjacente.

Portanto, um sistema de memória de regras razoável deve seguir o princípio da "separação de preocupações": a camada global contém apenas regras gerais, como preferências de idioma, limites de segurança e hábitos básicos de comportamento; a camada do projeto contém especificações específicas para aquele projeto, como comandos de build, convenções de código e descrições de módulos.

As duas desempenham suas respectivas funções sem interferir uma na outra, e nenhum conflito surgirá quando forem mescladas.

2️⃣ Comece pelo Básico, Itere Conforme Necessário

O AGENTS.md não precisa ser escrito de uma só vez. Comece com as regras mais essenciais. Quando o Codex repetir o mesmo erro, peça diretamente a ele para revisar e atualizar as regras, por exemplo:

"Você acabou de cometer o mesmo erro da última vez. Por favor, resuma o motivo e adicione a experiência relevante ao AGENTS.md."

Dessa forma, as regras sempre vêm do atrito real do uso, e o AGENTS.md evoluirá continuamente com o uso.

3️⃣ Mantenha Enxuto, Separe Conteúdo Complexo Separadamente

À medida que o uso se aprofunda, o conteúdo do AGENTS.md pode aumentar. Nesse ponto, não há necessidade de colocar tudo em um único arquivo. Em vez disso, escreva o conteúdo para tópicos específicos em arquivos independentes e depois faça referência a eles no arquivo principal.

Por exemplo, escreva a descrição da arquitetura do projeto separadamente como ARCHITECTURE.md e inclua apenas uma referência de uma linha no AGENTS.md:

"Para a arquitetura principal e as especificações de diretório deste projeto, consulte o arquivo ARCHITECTURE.md no diretório atual."

2. Recurso de Memórias

Além de configurar ativamente as regras relevantes, o Codex também suporta um recurso de memória ativa, que precisa ser ativado em Configurações - Personalização - Memória, conforme mostrado abaixo:

Depois de ativar o botão, o Codex irá resumir ativamente informações úteis e preferências importantes da conversa na memória. Se você quiser ver quais memórias seu Codex adicionou, pode abrir o arquivo Memory.md em ~/.codex/memory para visualizar o conteúdo da memória adicionado pelo seu Codex. Abaixo está o meu:

Finalmente

Construir um sistema de memória é um processo que evolui com o tempo. Acredite em mim, enquanto você persistir em melhorar e atualizar as regras de ação e acumular memórias continuamente, o Codex rapidamente se tornará a ferramenta de produtividade mais poderosa que melhor te entende e é a mais conveniente de usar.