MÓDULO 3.1
AGENTS, Skills e memória
Criar instruções de projeto e uma capacidade reutilizável com critério de revisão.
O que é
AGENTS.md é o arquivo de instruções que Codex descobre no escopo aplicável. Ele descreve como trabalhar: arquivos iniciais, comandos de verificação, limites e formato de entrega. Não precisa explicar toda a história da organização; prefira regras curtas que alterem uma decisão real.
Por que aprender
Instruções objetivas evitam repetir os mesmos detalhes em cada conversa. O arquivo deve ajudar o agente a escolher uma ação concreta, como verificar o relatório antes de considerá-lo finalizado.
Conceitos-chave
Instrução operacional; escopo; regra observável; concisão.
O que é
Por padrão, ~/.codex/AGENTS.md guarda instruções globais. No projeto, AGENTS.md acrescenta regras específicas; arquivos em pastas mais próximas podem prevalecer no escopo correspondente. AGENTS.override.md tem prioridade sobre AGENTS.md no mesmo nível. Isso não supera instruções de sistema, permissões ou a solicitação explícita da sessão.
Por que aprender
O caminho importa. Uma regra local pode não ser aplicada a outra pasta, e um arquivo override esquecido pode explicar um comportamento inesperado. Mantenha o global pequeno e deixe detalhes locais no projeto.
Conceitos-chave
Descoberta; hierarquia; escopo de diretório; override.
O que é
Uma Skill reúne instruções de uma atividade recorrente, com nome e descrição no início de SKILL.md. Pode incluir recursos e programas de apoio. Skills pessoais ficam em ~/.agents/skills; as do projeto podem ficar em .agents/skills dentro do repositório. A pasta ~/.codex continua sendo configuração do Codex.
Por que aprender
Uma regra diz o que respeitar; uma Skill ensina um procedimento que pode ser acionado quando necessário. Separar esses papéis evita carregar todo manual em todas as tarefas.
Conceitos-chave
Nome; descrição de acionamento; procedimento; entrada e saída; validação.
O que é
A memória operacional do curso é um conjunto de arquivos consultáveis, não uma mudança nos pesos do modelo. Ela funciona quando o agente lê as informações relevantes e quando alguém mantém essas informações atualizadas. Guarde fatos estáveis, decisões e causas de falhas; não preserve cada frase de cada conversa.
Por que aprender
Copiar todo o histórico aumenta volume e pode reintroduzir instruções antigas. Uma memória pequena, datada e revisada ajuda mais que um arquivo imenso que ninguém consegue validar.
Conceitos-chave
Memória externa; consulta explícita; resumo; validade; fonte.
O que é
Registre o sintoma, a causa observada, a menor correção e como verificar. Diferencie falha de pedido, como objetivo ambíguo, de falha de infraestrutura, como processo encerrado. O registro só gera aprendizado operacional quando altera o procedimento seguinte.
Por que aprender
Refazer todo o projeto pode mascarar um problema simples. Uma proteção pequena, como verificar a existência de um arquivo antes de ler, costuma ser mais fácil de testar e manter.
Conceitos-chave
Sintoma não é causa; correção mínima; prevenção; evidência.
O que é
Teste a Skill com uma entrada normal, outra incompleta e uma fora de escopo. Observe se o resultado preserva dados, sinaliza incerteza e para quando deveria. O teste deve medir comportamento, não apenas procurar o nome da Skill na resposta.
Por que aprender
Um procedimento que funciona uma vez pode estar dependendo de contexto acidental. Variar entradas ajuda a descobrir o que precisa ficar explícito nas instruções.
Conceitos-chave
Caso normal; caso incompleto; limite de escopo; critério de aceitação.