MÓDULO 3.1 / 5 DE 8
AGENTS, Skills e memória
Criar instruções de projeto e uma capacidade reutilizável com critério de revisão.
1AGENTS.md orienta a execuçã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.
Na prática
“Seja excelente” é difícil de testar. “Compare o total do relatório com vendas.csv e indique a diferença” define uma ação e sua evidência.
✓ Faça
Escreva cinco regras. Para cada uma, pergunte: consigo observar se foi cumprida? Remova orientações que não mudam o trabalho.
✗ Evite
Aceitar uma conclusão sem conferir a entrada que a sustenta.
2Global e projeto se complementam
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.
Na prática
Global: “relate os testes executados”. Projeto: “valide o CSV com python3 validar.py”. As duas instruções colaboram; não é necessário repetir o script de cada projeto no arquivo global.
3Skills empacotam procedimentos
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.
Na prática
relatorio-semanal recebe um CSV fictício, calcula um total conferível e produz um Markdown com pendências. A descrição deixa claro que não envia o resultado automaticamente.
Sequência para experimentar
- Prepare uma cópia de treino.
- Leia materiais/SKILL-relatorio.md. Crie a pasta indicada e salve o arquivo como SKILL.md, mantendo o cabeçalho delimitado por ---.
- Registre o resultado observado e a próxima correção.
4Memória precisa de manutençã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.
Na prática
Uma professora registra que os materiais da turma usam linguagem acessível e exemplos fictícios. Na próxima tarefa, indica esse arquivo em vez de repetir toda a conversa sobre a turma.
✓ Faça
Inclua em memoria.md três fatos úteis e uma data de revisão. Na tarefa seguinte, peça que o agente cite qual fato utilizou.
✗ Evite
Misturar a cópia de treino com arquivos privados ou trabalho em produção.
5Falhas viram proteções pequenas
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.
Na prática
O relatório saiu vazio porque o CSV estava sem linhas. A proteção é validar cabeçalho e quantidade de registros antes de gerar o relatório, não trocar de modelo.
6Teste a capacidade reutilizável
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.
Na prática
Entrada incompleta: falta o valor de uma venda. Esperado: não inventar o número e separar total conhecido de pendência. Fora de escopo: pedir envio ao cliente; esperado: preparar somente rascunho.
Critérios para revisar sua entrega
Use esta rubrica depois do laboratório. Cada linha pede uma evidência; marcar leitura não significa que a prática foi executada.
| Critério | Evidência esperada | Se não passou |
|---|---|---|
| Escopo | A entrega corresponde ao objetivo desta aula. | Reduza a tarefa e nomeie um único resultado. |
| Entradas | Você sabe quais arquivos ou dados foram usados. | Liste as fontes e remova material sem relação. |
| Execução | O procedimento foi realizado no ambiente de treino. | Diferencie o que foi planejado do que foi feito. |
| Conferência | Um resultado foi comparado com uma referência. | Abra o arquivo ou repita a consulta verificável. |
| Segredos | Nenhum token, senha ou dado privado foi compartilhado. | Revise a cópia de trabalho antes de qualquer envio. |
| Continuidade | Outra pessoa consegue encontrar o próximo passo. | Atualize README e registre uma pendência concreta. |
MÃO NA MASSA / ~15 MIN OU EM ETAPAS
Sua primeira Skill de relatório
Use arquivos fictícios e uma pasta de treino. As práticas com instalação, Telegram ou VPS podem exigir tempo adicional para cadastro e configuração.
Skill de exemplo
Leia o bloco antes de usar. Campos como Seu Nome e usuario@ip-da-vps são exemplos para adaptar; comandos administrativos pertencem somente ao seu ambiente de treino.
---
name: relatorio-semanal
description: Gerar rascunho de relatório a partir de CSV fornecido, sem envio externo.
---
1. Leia o README e o CSV informado.
2. Valide cabeçalho, valores e linhas vazias.
3. Calcule os totais sem inventar dados ausentes.
4. Gere Markdown com fontes, total e pendências.
5. Compare o total com a soma das entradas.
6. Pare antes de enviar ou publicar.
Critério de pronto
Criar instruções de projeto e uma capacidade reutilizável com critério de revisão. Registre o arquivo produzido, o teste executado e o resultado observado.
Abrir arquivos e modelos do laboratórioConfira o que ficou
Escrever “não vaze segredos” em AGENTS.md substitui permissões de arquivos?
Ver resposta comentada
Não. Instruções orientam; permissões e isolamento restringem o que a ferramenta pode acessar.
Se sua resposta foi diferente, volte ao tópico correspondente e escreva a diferença em uma frase. A checagem não bloqueia seu estudo.
Resumo do módulo
- Instrução operacional; escopo; regra observável; concisão.
- Descoberta; hierarquia; escopo de diretório; override.
- Nome; descrição de acionamento; procedimento; entrada e saída; validação.
- Memória externa; consulta explícita; resumo; validade; fonte.
- Sintoma não é causa; correção mínima; prevenção; evidência.
- Caso normal; caso incompleto; limite de escopo; critério de aceitação.
Consulte a fonte
Ferramentas verificadas em 20/09/2026; nomes de telas e disponibilidade podem mudar.