3.1 AGENTS.md, .codex/ e agents TOML

🎯O que você ganha aqui

Mapeamento direto Claude → Codex pra cada peça de configuração. Sair sabendo onde cada arquivo mora, qual sintaxe usar (TOML vs JSON) e o motivo da separação .codex/ × .agents/.

Conteúdo detalhado

📜 AGENTS.md — o irmão do CLAUDE.md

Arquivo markdown na raiz do projeto que o Codex lê no início da sessão e injeta no system prompt. Função idêntica ao CLAUDE.md. Quem migra copia o CLAUDE.md, renomeia pra AGENTS.md, funciona em 90% dos casos.

Mapeamento direto

Claude Code

Codex

~/.claude/CLAUDE.md

~/.codex/AGENTS.md

./CLAUDE.md

./AGENTS.md

./src/api/CLAUDE.md

./src/api/AGENTS.md

⚠️Os 10% que NÃO portam

• Backtick-bang dentro do AGENTS.md → não interpreta, vira texto literal
• Descrições muito longas podem ser truncadas (limite oculto ~8K chars)
• Referências a tools exclusivas do Claude (Task, plan mode) → ignoradas
• Hooks/permissões inline não funcionam — pertencem ao config.toml

Conceitos-chave

Mesma função
System prompt do projeto

Mesma hierarquia
Global → projeto → subdir

Sem bang nativo
Vira texto

Tamanho conserv.
~1-2KB

📂 Por que DUAS pastas — .codex/ e .agents/

Codex faz uma separação intencional: o que é proprietário (config do Codex, agents em TOML) fica em .codex/; o que é spec aberta (Agent Skills) fica em .agents/. Compatibilidade com outras tools que adotam a spec.

🔧 .codex/ — proprietário

.codex/
├── config.toml         ← settings (TOML)
├── agents/             ← sub-agents (TOML)
│   ├── reviewer.toml
│   └── doc-writer.toml
└── commands/           ← slash commands
    └── review.md

Coisas específicas do Codex. Nenhuma outra tool entende isto.

🌐 .agents/ — spec aberta

.agents/
└── skills/             ← Agent Skills spec
    └── my-skill/
        ├── SKILL.md
        ├── agents/openai.yaml  ← sidecar
        ├── scripts/
        └── references/

Compartilhável. Outras tools (Cursor, etc.) que respeitem a spec também leem.

🚨O erro de path mais frequente

Você lê "skill do Codex" e por reflexo coloca em .codex/skills/. Errado. Skill mora em .agents/skills/ — sempre. .codex/ é só config proprietária e sub-agents em TOML.

📊 Comparação completa

Item

Claude — onde

Codex — onde

System prompt

./CLAUDE.md

./AGENTS.md

Settings

.claude/settings.json

.codex/config.toml

Sub-agents

.claude/agents/*.md

.codex/agents/*.toml

Skills

.claude/skills/<n>/

.agents/skills/<n>/

Slash commands

.claude/commands/*.md

.codex/commands/*.md

MCP servers

.mcp.json

[mcp_servers] no toml

Conceitos-chave

Sep. config/ext
.codex × .agents

Spec aberta
.agents = portable

TOML vs JSON
Sintaxe diferente

Mirror global
~/.codex e ~/.agents

⚙️ config.toml — settings em TOML

Equivalente do settings.json do Claude, mas em TOML. Não é mais difícil — é DIFERENTE. Sintaxe de seções com colchetes, arrays com colchetes duplos, multiline com aspas triplas.

config.toml comentado

# modelo padrão
model = "gpt-5-codex"
approval_policy = "on-failure"   # quando pedir aprovação
sandbox_mode = "workspace-write" # nível de sandbox

# profiles — perfis nomeados
[profiles.safe]
sandbox_mode = "read-only"
approval_policy = "always"

[profiles.danger]
sandbox_mode = "danger-full-access"
approval_policy = "never"

# MCP servers
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[mcp_servers.github.env]
GITHUB_TOKEN = "${GITHUB_TOKEN}"

# model providers
[model_providers.openai]
base_url = "https://api.openai.com/v1"
api_key_env_var = "OPENAI_API_KEY"

Sintaxe TOML em 30 segundos

# comentário
chave = "string"
numero = 42
booleano = true
array = ["a", "b", "c"]

[secao]               # seção (= objeto)
chave = "valor"

[secao.sub]           # sub-seção
outra = "outra"

[[lista_de_secoes]]   # array de seções
nome = "item1"

[[lista_de_secoes]]
nome = "item2"

multiline = """
texto
em várias
linhas
"""

Conceitos-chave

[section]
Equivalente a objeto

[[arrays]]
Array de seções

"""multi"""
String multiline

${ENV}
Interpolação env

👤 Sub-agents em TOML — não é Markdown

Sub-agents no Codex são arquivos .toml em .codex/agents/. Estrutura, não prosa. Você preenche campos de uma struct: name, description, model, tools, e instructions (string multiline com o system prompt).

Exemplo — .codex/agents/code-reviewer.toml

name = "code-reviewer"
description = "Reviews code for correctness bugs. Call explicitly with 'use code-reviewer to ...'"
model = "gpt-5-codex"
tools = ["read", "grep", "glob", "bash"]

instructions = """
You are a senior code reviewer focused on correctness.

## Your role
- Read the diff carefully
- Flag correctness bugs (NOT style — linter handles that)
- Check edge cases (null, empty, off-by-one, race conditions)
- Note security risks (SQLi, XSS, path traversal, auth bypass)

## Output format
A numbered list of findings:
1. **[severity]** file:line — what's wrong, why, suggested fix

Be terse. No fluff.
"""

🔷 Claude Code agent

---
name: code-reviewer
description: Use proactively...
tools: Read, Grep, Bash
---

You are a senior code reviewer.
...

Markdown com frontmatter. Prosa flui natural.

🟣 Codex agent

name = "code-reviewer"
description = "Call with 'use code...'"
tools = ["read", "grep", "bash"]
instructions = """
You are a senior code reviewer.
...
"""

TOML estruturado. Prompt dentro de string.

💡Conversão prática

Pra portar um sub-agent Claude pro Codex: pega o frontmatter, vira chaves TOML. Pega o body do markdown, joga em instructions = """...""". Ajusta a description pra mencionar "call explicitly".

Conceitos-chave

TOML struct
Não Markdown

instructions
String multiline

tools array
["read", "bash"]

model override
Por agent

🚦 Invocação explícita — a pegadinha do Claude → Codex

No Codex, sub-agents NÃO são auto-disparados pela description. Você precisa chamar pelo nome no prompt. É a diferença que mais quebra a cabeça de quem vem do Claude.

🔷 Claude — auto

User: "revisa essa PR"

→ Claude lê descriptions
→ Match: code-reviewer
→ Dispara sub-agent
→ Devolve findings

Você não precisa saber que existe o agent.

🟣 Codex — explícito

User: "revisa essa PR"

→ Codex faz revisão genérica
→ Sub-agent code-reviewer NÃO roda

User: "use code-reviewer para
        revisar a PR #123"

→ AGORA dispara o sub-agent.

Você precisa lembrar do agent e chamar.

🚨Sintoma do erro

"Por que meu agent não está sendo chamado? Está exatamente como no Claude!"

→ Porque você não chamou. No Codex, description é só pra você LEMBRAR que o agent existe, não pra disparar. Chama pelo nome.

Trade-off de design

Vantagem (Codex):

Previsibilidade. Você sempre sabe o que vai rodar. Sem surpresa de "Claude resolveu chamar X que eu não esperava".

Desvantagem (Codex):

Menos ergonômico. Você TEM que lembrar dos agents. Se esquece, agent vira "código morto".

Conceitos-chave

Invocação por nome
"use agent X..."

Sem auto-dispatch
Por design

Previsibilidade
Trade-off

Description = lembrete
Pra você, não pro LLM

🏖️ Sandbox e approval modes

Codex tem sandbox configurável via config.toml. Três níveis crescentes de poder + approval policies que controlam quando pedir confirmação. Mais granular e explícito que o equivalente do Claude.

🔒

read-only

Só leitura. Bash funciona pra ls, cat, grep. Sem escrita, sem rede. Modo ideal pra análise sem risco.

📝

workspace-write (padrão)

Escreve no projeto. Não escreve fora. Rede limitada. Modo do dia a dia.

⚠️

danger-full-access

Sem restrições. Escreve em qualquer lugar, rede aberta, comandos quaisquer. Só em sandbox real (container/VM).

Approval policies

"always" — pede confirmação em TODO comando

"on-failure" — só pede se a primeira tentativa falhou (padrão razoável)

"on-request" — pede só se o modelo achar que precisa

"never" — nunca pede (combina com sandbox restritivo)

Conceitos-chave

3 sandbox levels
read / write / full

Approval policy
When to ask

Profiles
Pré-combinados

Network gating
Por sandbox

🔄 Slash commands no Codex

Codex suporta slash commands customizados em .codex/commands/ (arquivos .md). Conceito idêntico ao do Claude — algumas diferenças em sintaxe de argumentos e ausência de backtick-bang.

Exemplo — .codex/commands/review.md

---
description: Revisa o diff atual procurando bugs
---

Revise o diff atual da branch (rode git diff).

Procure:
- Bugs de correção
- Casos não tratados
- Vulnerabilidades comuns

Se passar argumento, foque nesse arquivo.

Retorne lista numerada de findings + severity.

Uso: /review ou /review src/api/auth.ts

⚠️Sem backtick-bang

No Claude, você poderia escrever Branch atual: `!git branch --show-current` dentro do command e o resultado entrava no prompt. No Codex, vira texto literal. Solução: peça que o agente RODE o comando (prosa de fallback) ou chame um script.

Conceitos-chave

.codex/commands/
Mesma convenção

Frontmatter
description mínima

Sem bang
Prosa de fallback

Script delegado
Alt à injeção

🎯Resumo do módulo

✓

AGENTS.md ≡ CLAUDE.md — mesma função, mesma hierarquia, só sem backtick-bang.

✓

Duas pastas: .codex/ proprietário, .agents/ spec aberta — skills SEMPRE em .agents/.

✓

config.toml em TOML — [section], [[arrays]], """multiline""", ${ENV}.

✓

Sub-agents = TOML struct — instructions string multiline, não markdown body.

✓

Invocação EXPLÍCITA de agent — "use agent X..." ou nada acontece.

✓

Sandbox em 3 níveis + 4 approval policies — granularidade explícita.

✓

Slash commands sem backtick-bang — usar prosa de fallback ou script.

Próximo módulo:

3.2 — Skills no Codex e o sidecar openai.yaml (a peculiaridade que mais confunde)

← Voltar para Trilha 3 Próximo: 3.2 →