🧭 Fundamentos

Lock-in é quando seu projeto depende tão fundo de um agente que migrar custa semanas. Skills, agents, configs, hooks — tudo amarrado a um formato proprietário.

Se Claude Code sai do ar 8 horas (acontece), você fica parado. Se a OpenAI muda regra de uso do Codex, você fica parado. Lock-in custa downtime, não só dinheiro.

Vendor lock-in · custo de migração · downtime de fornecedor · padrão aberto vs proprietário · resiliência operacional.

Claude Code: SWE-bench 80,8%, lê código fundo, hooks programáveis, mas rate-limit constante e 4× mais tokens. Codex: lidera Terminal-Bench 2.0, 2-3× menos tokens, sandbox kernel-level, mas fraco em frontend.

Saber quando usar cada um economiza horas. Refator profundo → Claude. Script de shell rápido → Codex. Frontend → Claude. Auditoria sandboxed → Codex.

SWE-bench · Terminal-Bench · sandbox kernel vs app-layer hooks · custo por token · rate-limit · paridade de modelo.

Ter os dois rodando significa que quando Anthropic ou OpenAI tem incidente, você troca de terminal e continua. Zero parada.

Em 2026 já tivemos 4 incidentes globais que tiraram Claude Code do ar por mais de 2h. Quem tinha Codex configurado mal sentiu.

Resiliência operacional · failover de agente · status page · paralelismo de fornecedores · SLA implícito.

Claude Pro/Max + ChatGPT Plus/Pro = USD ~40 a ~400/mês. Parece muito, mas em troca: nunca para, 2× capacidade paralela, redução de tokens via Codex barato.

Quem cobra USD 80/h e perde 1h por mês por downtime já paga as duas subs. Decisão racional, não emocional.

ROI hora-poupada · custo de oportunidade · ticket médio cobrado · paralelismo real · break-even.

Cursor, Windsurf, Continue, Amp, Warp, Goose, Devin, Gemini CLI, Codex — 18+ ferramentas leem AGENTS.md. Linux Foundation steward via Agentic AI Foundation.

Se você escreve AGENTS.md hoje, qualquer agente futuro vai entender. Pra Gemini CLI agora, pra Hermes que vier amanhã.

Padrão aberto · 60.000+ repos · Linux Foundation · Agentic AI Foundation · futuro-proofing.

Trate agentes como ferramentas intercambiáveis. Seu CONHECIMENTO mora no projeto (docs, skills, AGENTS.md). Agente é o intérprete.

Quem se apaixona por uma ferramenta perde a chance de usar a melhor pra cada task. Mindset agnóstico = adaptação rápida.

Knowledge in-project · agente como commodity · separation of concerns · best-tool-for-the-job · adaptação contínua.

Padrão criado em colaboração entre Sourcegraph, OpenAI, Google, Cursor e Factory. Hoje sob a Agentic AI Foundation da Linux Foundation.

Saber que é multi-vendor te dá confiança que não vai ser descontinuado por uma empresa. É infraestrutura comum.

Multi-vendor governance · Linux Foundation · open standard · longevidade · neutralidade.

AGENTS.md: code style, comandos de build/test, estrutura do projeto, boundaries. CLAUDE.md: permission levels, @import, path-scoped rules, hooks Claude-only.

Sem essa separação você duplica conteúdo e fica com 2 fontes de verdade que divergem. Universal num lado, específico no outro.

DRY · single source of truth · separation of concerns · universal vs tool-specific.

Claude Code suporta `@AGENTS.md` dentro do CLAUDE.md. Importa as regras universais e adiciona o que é Claude-only por cima.

Atualiza AGENTS.md, Claude lê na hora. Zero duplicação. Padrão recomendado por toda a comunidade em 2026.

@import syntax · hierarchical layering · composição de contexto · DRY aplicado.

Em `~/.codex/config.toml`: `project_doc_fallback_filenames = ["CLAUDE.md", "COPILOT.md"]`. Codex passa a ler seu CLAUDE.md.

Você não precisa migrar nada pra testar o Codex. Configura fallback, abre o Codex, ele lê o que Claude já lia.

project_doc_fallback_filenames · interoperabilidade transparente · zero-cost migration trial.

Não ponha: histórico de bugs resolvidos, decisões de PRs antigos, regras temporárias. AGENTS.md é manual perene, não diário.

Arquivo inchado vira ruído. Modelo lê tudo em cada turn — desperdício de tokens e atenção.

Signal vs noise · context economy · manutenção · pruning periódico.

Mesmo prompt funciona em Claude e Codex. Agente novo no projeto produz código aderente em 1 turn. Você para de repetir as mesmas correções.

Sem métrica você não sabe se o AGENTS.md está pagando o aluguel. Esses 3 sinais dizem.

Living document · onboarding-time · correções recorrentes · aderência ao primeiro turn.

`.claude/skills/` (markdown SKILL.md), `.claude/agents/` (markdown + YAML frontmatter), `.claude/settings.local.json` (config local), `.claude/hooks/` (scripts de evento).

Saber onde tudo mora é pré-requisito pra organizar projeto e pra explicar pra outro agente onde procurar.

Convenção sobre configuração · descoberta automática · escopo local vs global.

`.codex/config.toml` (config geral + project_doc_fallback), `.codex/agents/*.toml` (um arquivo TOML por agente), skills moram em `.agents/skills/` (padrão aberto).

TOML em vez de markdown é a maior surpresa pra quem vem do Claude. Saber a sintaxe evita uma hora de "por que não funciona".

TOML syntax · campos developer_instructions, model, sandbox_mode · um agente por arquivo.

SKILL.md segue o Agent Skills standard. Mesmo arquivo funciona em Claude Code, Codex CLI, Cursor e Gemini CLI. Migração = copiar de pasta.

Você não reescreve skills. Investe uma vez, usa em qualquer agente. Maior alavancagem do curso.

Agent Skills standard · portabilidade · investimento amortizado · campos comuns (name, description, allowed-tools).

Claude: arquivo `.md` com YAML frontmatter, corpo do markdown vira system prompt. Codex: arquivo `.toml` com `developer_instructions` explícito como campo.

Converter agent Claude → Codex é trivial mas tem regra: o corpo markdown vira o campo `developer_instructions` do TOML. A IA faz isso por você se souber pedir.

Frontmatter · TOML fields · developer_instructions · isomorfismo entre formatos.

Ambos têm os 2 escopos: `~/.claude/` e `~/.codex/` (global, todos projetos) vs `./.claude/` e `./.codex/` (só este projeto). Project sobrescreve global.

Skills genéricas (revisão, formatação) ficam no global. Conhecimento do projeto fica no local. Errar isso = duplicação ou conflito.

Scope precedence · home dir vs project dir · cascading config · overrides.

CLAUDE.md ↔ AGENTS.md · .claude/skills/ ↔ .agents/skills/ · .claude/agents/*.md ↔ .codex/agents/*.toml · settings.local.json ↔ config.toml · hooks ↔ (Codex não tem hooks-equivalente direto).

Esse mapa é o que você cola na parede. Bate o olho e sabe onde mexer.

Cheat sheet · isomorfismo · pontos sem-paridade (hooks) · referência rápida.