📜 A Linguagem dos Agentes

Arquivo de markdown na raiz do projeto que Codex, Cursor e Claude leem automaticamente antes de qualquer sessão. Contém objetivo, stack, comandos, regras e preferências.

Sem AGENTS.md você re-explica o projeto toda vez — perde tempo e o agente erra padrões básicos. Com AGENTS.md, qualquer agente já chega calibrado.

Contexto durável, system prompt do projeto, memória compartilhada, fonte de verdade.

Cinco seções obrigatórias: Objetivo (uma frase), Stack (versões e libs), Comandos (dev, test, lint, deploy), Regras de código (TS strict, conventional commits) e Critério de pronto.

É o mínimo para o agente operar bem. Mais que isso vira ruído; menos que isso vira improviso. Padronizar essas 5 seções evita 80% dos erros.

Template, seções obrigatórias vs opcionais, comandos canônicos, tone of voice de regras.

AGENTS.md na raiz vale para todo o projeto. AGENTS.md em subpasta (ex: /backend) override regras só naquela área. O agente combina os dois automaticamente.

Em monorepo ou app cheio de áreas (frontend, backend, infra), regras únicas globais não cobrem tudo. Hierarquia evita poluir o arquivo raiz.

Override, herança, escopo de regra, monorepo, separação por área.

Análise linha a linha do AGENTS.md real do projeto InboxAI: cada decisão justificada, com explicação de por que essa regra está ali e o que ela evita.

Ver um AGENTS.md de produção real ensina mais que qualquer template abstrato. Você copia o padrão e adapta para seus projetos.

Estudo de caso, justificativa por linha, cópia consciente, adaptação ao contexto.

Os 3 vícios mais comuns: regras vagas tipo "seja útil"; informação desatualizada (versões antigas, comandos quebrados); prolixidade que faz o agente perder o foco.

Cada erro corrói a utilidade do AGENTS.md silenciosamente. Reconhecer os padrões evita que seu arquivo vire ruído ignorado.

Genericidade, drift documental, tamanho ótimo, sinal vs ruído.

AGENTS.md não é setup once and forget. Ao notar padrões repetidos, vira regra. Ao virar ruído, sai. A cada sprint, revisar e podar mantém o sinal alto.

Documentos vivos refletem o projeto real. Documentos congelados viram folclore que ninguém respeita — e o agente também ignora.

Cadência de revisão, poda, evolução, gatilhos de update, AGENTS.md changelog.

Uma skill é um pacote de instrução durável + recursos (scripts, references, templates). Diferente de prompt (efêmero, vive na sessão) e de tool (interface técnica para uma API).

Skills transformam capacidade pontual em capacidade reusável. Sem skills, você re-prompta a mesma rotina toda semana. Com skills, vira um comando.

Skill vs prompt vs tool, durabilidade, reuso, invocação por nome.

Toda skill tem SKILL.md (frontmatter com name, description, when_to_use + corpo de instruções), pasta references/ (docs longas, exemplos) e pasta scripts/ (executáveis auxiliares).

Estrutura padronizada permite que qualquer agente carregue a skill. Frontmatter bem escrito é o que faz o agente decidir invocar a skill no momento certo.

Frontmatter, when_to_use, references, scripts, layout convencional.

O agente vê apenas nome+descrição inicialmente. Carrega SKILL.md ao decidir usar. Carrega references/ só quando o SKILL.md aponta para um arquivo específico. Tudo lazy.

Carregar tudo de uma vez explode a janela de contexto. Progressive disclosure permite ter 50 skills disponíveis sem queimar tokens.

Lazy loading, janela de contexto, decision-time loading, references on-demand.

A loja oficial da OpenAI tem skills prontas: browser-use (navegar sites), computer-use (controlar tela), remotion (animações em vídeo). Instalação em 1 clique.

Antes de criar skill própria, sempre cheque a loja. Skills oficiais são otimizadas e mantidas. Reinventar dá retrabalho.

Loja oficial, instalação, manutenção, skills oficiais vs comunidade.

O agente pode puxar a skill sozinho quando reconhece o gatilho do when_to_use. Você também pode forçar com @skill-name. Cada modo serve a um cenário diferente.

Invocação automática é fluida mas pode falhar se o gatilho está mal escrito. Manual garante mas exige você lembrar do nome. Saber quando usar cada uma evita frustração.

Auto-invocação, invocação explícita, gatilhos, controle vs fluidez.

Cinco skills proprietárias entregues no curso: landing-page (gera site em 1h), pr-review (auditoria), qa-visual (screenshots), micro-saas-launch (kit completo), weekly-report (relatório semanal).

Skills do Master Codex foram desenhadas para tirar você do zero a entregar projeto vendável. São o atalho que justifica os R$ 5k do curso.

Skill proprietária, atalho prático, kit de produtividade, ROI do curso.

Antes de pedir X, pergunte: "O que você precisa saber pra fazer X bem feito?". O agente lista lacunas. Você preenche. Aí pede X.

Inverte o trabalho de descobrir o que falta. Em vez de você adivinhar, o agente declara. Cobertura de contexto fica muito mais alta na primeira tentativa.

Reverse prompting, gap analysis, contexto declarado, briefing reverso.

Modo onde o agente propõe um plano em 3–7 etapas antes de tocar em qualquer arquivo. Você lê, ajusta, aprova. Só então ele executa.

Discutir abordagem em 30s evita refatorar 200 linhas depois. É a economia mais barata do fluxo agentic.

Plan mode, ciclo plan-approve-execute, validação prévia, decomposição.

Critério objetivo de "pronto": build passa sem warning, lint clean, testes verdes, smoke test no browser, diff revisado por humano. Tudo declarado no AGENTS.md.

Sem DoD explícita, "pronto" é subjetivo. Agente para cedo demais ou tarde demais. Com DoD, o critério é claro pra todo mundo.

Definition of Done, checklist objetiva, gate de aceite, contrato verificável.

DoD específica para frontend: bun run build sem erro, lint clean, smoke test no Chrome em viewport desktop+mobile, screenshots antes/depois anexados ao PR.

Frontend tem armadilhas próprias (responsividade, hidratação, dark mode). DoD genérica deixa passar bug visual. Específica filtra.

Smoke visual, viewport breakpoints, screenshots como prova, hidratação.

DoD backend: testes unitários + integração passam, migrations rodadas em staging sem erro, deploy de staging OK, rollback testado, log em ordem.

Backend quebra silenciosamente em produção. Pegar tudo em staging com DoD apertada custa pouco e evita incidente caro.

Migrations idempotentes, rollback, staging, observabilidade, smoke test de API.

Frase única que combina Reverse + Plan + DoD. Você cola no início de qualquer sessão e o agente já entra calibrado nos três eixos. Bônus do curso.

Reduz a 1 cola o que normalmente exige 3 hábitos manuais. Isso por si só justifica investir tempo no método.

Template autoral, frase mestre, atalho mental, padrão repetível.

A janela de contexto é o que o agente lembra na sessão atual. GPT 5.5 Codex tem 1M tokens, mas Codex compacta automaticamente quando enche. Saber ler os sinais é importante.

Quando a janela trava, o agente esquece. Reconhecer e abrir nova sessão antes de degradar evita ter que refazer trabalho.

Janela de contexto, compactação, prompt cache, degradação progressiva.

Memória que sobrevive entre sessões. Você salva fatos sobre você, preferências, atalhos. Agente recupera no próximo chat. Você gerencia: ver, editar, limpar.

Sem memória, você reapresenta as mesmas preferências toda hora. Com memória bem cuidada, o agente vai te conhecendo. Mas memória inchada vira ruído.

Memory store, escopo de memória, audit, poda, memória global vs projeto.

Três níveis de permissão: read-only (só lê), edit (edita arquivos), full-access (roda comandos shell, instala). Você escolhe por contexto.

Full-access em projeto novo é seguro. Em código de cliente, é arriscado — o agente pode rodar comando destrutivo. Calibrar é segurança operacional.

Sandbox, escalada de permissão, blast radius, permissão contextual.

git worktree add cria uma nova pasta com uma branch checada. Cada agente trabalha numa worktree própria. Sem stash, sem trocar branch, sem conflito.

É a base técnica do multiagente. Sem worktrees, dois agentes editando arquivos simultaneamente geram conflitos e perda de trabalho.

git worktree add, branches paralelas, isolamento físico, cleanup.

Sub-agente é um agente filho que recebe uma tarefa fechada e devolve o resultado. Útil para paralelismo e isolamento de contexto. Tem overhead.

Delegar bem multiplica throughput. Delegar mal duplica trabalho. Saber a hora certa é a diferença entre 4x mais rápido e 2x mais lento.

Sub-agent, paralelismo, overhead, contexto isolado, fan-out.

Os 3 acidentes clássicos: dois agentes na mesma branch (conflito), dois agentes no mesmo arquivo (overwrite), agente em sandbox full deletando .env. Como prevenir.

Cada erro pode custar horas de retrabalho ou pior — perda de dados de cliente. Reconhecer o padrão antes de cometer é proteção barata.

Race condition, branch hygiene, blast radius, secrets safety, prevenção.