1.1 Mapa mental — Claude Code vs Codex

🎯O que você ganha neste módulo

Sair daqui sabendo o que cada peça (CLAUDE.md, AGENTS.md, skills, sub-agents, MCP) significa em cada runtime. Você nunca mais vai ficar perdido lendo doc de um sem ter referência mental do outro.

Conteúdo detalhado

🤖 O que é um coding agent (e o que NÃO é)

Coding agent é um LLM que executa um loop autônomo: lê código, planeja uma ação, edita arquivos, roda comandos no terminal, observa o resultado e decide o próximo passo — tudo sem você ditar cada movimento. Não é autocompletar e não é chatbot. É um colaborador iterativo.

✓ É coding agent

✓Executa tarefa fim-a-fim (ler, planejar, agir, revisar)
✓Tem acesso a tools (shell, file edit, web, MCP)
✓Mantém contexto da sessão e itera
✓Pode delegar pra sub-agents especializados
✓Roda hooks de evento (PreToolUse, Stop, etc.)

✗ Não é coding agent

✗Autocomplete (Copilot inline) — sugere linha
✗Chatbot puro (ChatGPT padrão) — sem tools
✗Linter/formatter — regra estática
✗Snippet expander — template fixo
✗Code search — só consulta, não age

🔬O loop ReAct (Reason + Act)

É o motor de qualquer coding agent. Roda em ciclos curtos:

1. Observe — leia mensagem, ferramentas disponíveis, contexto

2. Think — qual a próxima ação que mais aproxima do objetivo?

3. Act — execute a ação (read file, run bash, edit, etc.)

4. Observe — resultado da ação. Voltar ao passo 2 ou parar.

Conceitos-chave

Loop ReAct
Reason + Act iterativo

Tool use
Bash, Edit, Read, Web, MCP

Permissões
Allow/deny/ask por ferramenta

Hooks
Eventos do harness

📘 CLAUDE.md vs AGENTS.md — o "system prompt do projeto"

Os dois agentes leem um arquivo markdown na raiz do projeto no início de toda sessão e injetam no system prompt. Mesma função, dois nomes:

Aspecto

Claude Code

Codex

Arquivo na raiz

CLAUDE.md

AGENTS.md

Versão global

~/.claude/CLAUDE.md

~/.codex/AGENTS.md

Versão por pasta

✓ Sim, concatenado

✓ Sim, similar

Injeção dinâmica (backtick-bang)

✓ Suporta

✗ Não suporta

Tamanho ideal

~2-3 KB

~1-2 KB (mais conservador)

💡Dica prática

Mantenha o CLAUDE.md/AGENTS.md focado em 3 coisas:

Comandos de build/test/lint no topo (formato literal pra copiar)
Convenções de código que sejam não-óbvias (não repetir o que linter já força)
Links pra docs internas profundas (ADRs, runbooks)

Conceitos-chave

Hierarquia
Global → projeto → subdir

Concatenação
Tudo entra no system prompt

Precedência
Específico ganha do genérico

Tamanho
Cuidado com inflação

📁 .claude/ vs .codex/ vs .agents/ — a anatomia

Pasta oculta no projeto onde mora a customização do agente. Claude usa uma única pasta. Codex usa duas pastas com responsabilidades separadas. Esta é a diferença estrutural mais importante:

Claude Code — uma pasta só

.claude/
├── CLAUDE.md            ← também pode ficar na raiz
├── settings.json        ← permissões, modelo, env, hooks
├── settings.local.json  ← override local (.gitignore)
├── agents/              ← sub-agents em Markdown
│   ├── code-reviewer.md
│   └── doc-writer.md
├── skills/              ← skills auto-invocáveis
│   └── my-skill/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
├── commands/            ← slash commands
│   └── review.md
└── hooks/               ← scripts de evento

Codex — duas pastas, responsabilidades distintas

.codex/                  ← config específica do Codex
├── config.toml          ← settings em TOML
├── agents/              ← sub-agents em TOML
│   ├── code-reviewer.toml
│   └── doc-writer.toml
└── commands/            ← slash commands específicos

.agents/                 ← spec ABERTA (compartilhada)
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── agents/openai.yaml  ← sidecar Codex
        ├── scripts/
        └── references/

AGENTS.md                ← na raiz, system prompt do projeto

⚠️Pegadinha #1 da migração

Quem vem do Claude coloca skill em .codex/skills/ achando que é o equivalente direto de .claude/skills/. Erra. Skill do Codex mora em .agents/skills/ — porque .agents/ é a convenção da spec aberta Agent Skills, e o Codex respeita.

Conceitos-chave

Pasta oculta
. no início = oculta

Convention
Nome certo, pasta certa

Separação config × ext
.codex vs .agents

Gitignore parcial
Commitar skill, ignorar local

🧩 Skills — o conceito comum, com pequenas dobras

Skill é uma "competência empacotada": pasta com SKILL.md + frontmatter YAML + corpo markdown + pastas convencionais. Os dois runtimes implementam o padrão Agent Skills (agentskills.io), então o núcleo é portável. Onde divergem:

Os 4 pilares que SEMPRE coincidem

Nome do arquivo SKILL.md — sempre

Campos do frontmatter name e description em YAML

Corpo em markdown padrão

Convenção de pastas scripts/, references/, assets/

SKILL.md mínimo

---
name: minha-skill
description: Use quando precisar processar X. Triggers comuns: "processa X", "limpa Y".
---

# Minha Skill

Instruções em markdown explicando como executar a tarefa.

Pode referenciar arquivos relativos: ver `references/exemplo.md` para mais detalhes.

🔷 Claude Code adiciona

• allowed-tools no frontmatter
• disable-model-invocation (opt-in explícito)
• Injeção dinâmica com `!comando` (backtick-bang)
• Invocação automática por descrição
• Slash: /nome-skill

🟣 Codex adiciona

• Sidecar agents/openai.yaml (branding, MCP)
• Limite oculto de ~8K chars na description
• Sem injeção dinâmica nativa (usar prosa de fallback)
• Invocação automática por descrição (também)
• Dollar: $nome-skill

🦜É exatamente aqui que polyskill entra

Você escreve UMA skill no formato portable. O polyskill emite duas versões: uma com as dobras do Claude, outra com as dobras do Codex (incluindo o sidecar e o ajuste de description). Veja a Trilha 5 pra detalhes.

Conceitos-chave

SKILL.md
Arquivo canônico

Frontmatter YAML
name + description

Semantic match
Ativação por descrição

Sidecar
Metadata específica

👥 Sub-agents — duas filosofias opostas

Sub-agent é uma "persona especializada" que o agente principal pode delegar tarefas. Aqui mora a diferença mais traiçoeira entre Claude Code e Codex — pega quase todo mundo que migra:

🔷

Claude Code — auto-invocação

Formato Markdown em .claude/agents/. O agente principal LÊ a description e decide se delega, sozinho.

Você escreve uma description rica em gatilhos ("Use proactively when..."), e o Claude principal descobre o sub-agent quando o contexto bate. Pode rodar vários em paralelo via Task tool.

🟣

Codex — invocação explícita

Formato TOML em .codex/agents/. Você TEM que chamar pelo nome no prompt.

Description ajuda você lembrar, mas não dispara automaticamente. "Usa o agent code-reviewer pra revisar X" — sem isso, ele não roda. Trade-off: mais previsível, menos ergonômico.

🚨O erro #1 de quem migra Claude → Codex

Copia o sub-agent, traduz pra TOML, espera que ele dispare sozinho como no Claude. Não dispara. Você fica horas pensando "está bugado" — não está. Codex exige invocação explícita por design.

Conceitos-chave

Auto-dispatch
Claude lê description, decide

Explicit call
Codex exige nome

Isolamento
Contexto separado

Paralelismo
Vários simultâneos

🔌 MCP — o protocolo que ambos falam

Model Context Protocol (MCP) é o denominador comum da pilha. Padrão aberto pra conectar LLMs a ferramentas externas (Slack, Gmail, GitHub, banco de dados). Server MCP roda como processo independente — Claude e Codex falam o mesmo protocolo.

A arquitetura MCP

┌──────────────┐ ┌──────────────┐

│ Claude Code │────┐ │ MCP Server │

└──────────────┘ │ │ (slack-api) │

├──→ │ │

┌──────────────┐ │ │ Expõe tools │

│ Codex CLI │────┘ │ via stdio │

└──────────────┘ └──────────────┘

Os dois clients consomem o MESMO server.

Server é independente, declarado em config do client.

🔷 Declaração no Claude Code

// .mcp.json
{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@mcp/slack"],
      "env": { "TOKEN": "$SLACK_TOKEN" }
    }
  }
}

🟣 Declaração no Codex

# config.toml
[mcp_servers.slack]
command = "npx"
args = ["-y", "@mcp/slack"]

[mcp_servers.slack.env]
TOKEN = "${SLACK_TOKEN}"

💡A boa notícia

Configurou um MCP server uma vez? Os dois runtimes podem consumir ele. Só o formato de declaração muda (JSON×TOML). Server, env, ferramentas expostas — tudo igual. É o pedaço da pilha que MAIS sobrevive entre runtimes.

Conceitos-chave

Padrão aberto
MCP é spec, não proprietário

Server independente
Processo separado

stdio vs HTTP
Dois transports

mcp__server__tool
Naming convention

🎯Resumo do módulo

✓

Coding agent = loop ReAct — não é autocomplete, não é chatbot. É colaborador iterativo.

✓

CLAUDE.md ≡ AGENTS.md — mesma função, dois nomes. Hierarquia global → projeto → subdir.

✓

.claude/ uma pasta; .codex/ + .agents/ duas — Codex separa config proprietária de spec aberta.

✓

Skills = SKILL.md + YAML + body — 4 pilares comuns; resto é específico de runtime.

✓

Sub-agents: Claude auto-invoca, Codex exige nome — erro #1 da migração.

✓

MCP é o denominador comum — server é independente, só a declaração muda.

Próximo módulo:

1.2 — Por que usar os dois juntos (complementaridade, redundância, tool-agnostic)

← Portal Próximo: 1.2 →