🧱 Fundamentos

Coding agent é um LLM que executa um loop autônomo: lê código, planeja, edita arquivos, roda comandos e revisa o próprio resultado — diferente do autocompletar, que só sugere a próxima linha.

Sem esse modelo mental, você usa Claude Code/Codex como se fosse Copilot e perde 90% do valor. O agente faz tarefa fim-a-fim, não trecho de código.

Loop ReAct (raciocínio + ação), tool use, permissões, contexto persistente da sessão, hooks de evento.

Arquivo markdown na raiz do projeto que o agente lê automaticamente no início de toda sessão. Claude Code procura por CLAUDE.md; Codex procura por AGENTS.md. Mesma função, nome diferente.

É o "manual do projeto" que o agente sempre tem em mente. Bem escrito, evita você ter que repetir contexto toda sessão. Mal escrito, vira ruído ignorado.

Hierarquia global (~/.claude/CLAUDE.md) vs projeto, instruções diretas, convenções de código, comandos de build/test, links para docs internas.

Pasta oculta no projeto onde mora tudo que é específico do agente: settings, skills, sub-agents, hooks. Claude usa .claude/; Codex usa .codex/ para config e .agents/ para skills.

É onde você customiza o comportamento do agente por projeto. Sem entender essa pasta, você vive só com defaults — e os defaults nunca são o ideal pro seu fluxo.

Global vs projeto (tilde-dot vs dot), pastas semânticas (skills/, agents/, commands/), settings.json e config.toml, gitignore parcial (commitar skills, ignorar credenciais).

Skill é uma "competência empacotada": um arquivo SKILL.md com frontmatter YAML (nome, descrição) + corpo em markdown explicando como executar uma tarefa, ativada automaticamente quando o gatilho aparece no contexto.

Skills são o jeito moderno de ensinar comportamento ao agente sem inflar o CLAUDE.md/AGENTS.md. Os dois runtimes implementam o padrão Agent Skills (agentskills.io) — só algumas dobras diferentes.

Frontmatter YAML, ativação por descrição (semantic match), diretórios scripts//references//assets/, slash invocation (/skill) vs dollar invocation ($skill).

Sub-agent é uma "persona especializada" que o agente principal pode delegar tarefas. Claude Code descobre e invoca sub-agents automaticamente; Codex exige que você chame por nome.

Esse é o maior choque entre os dois. Quem migra esquece e fica frustrado pensando que o Codex "não tem sub-agents". Tem — só não chama sozinho.

Formato Markdown (Claude) vs TOML (Codex), descrição como gatilho de auto-seleção, isolamento de contexto, parallel agent dispatch, custo de tokens.

Model Context Protocol é um padrão aberto pra conectar LLMs a ferramentas externas (Slack, Gmail, banco de dados, etc.). Claude Code e Codex consomem MCP servers da mesma forma.

MCP é o pedaço da pilha que NÃO muda entre runtimes. Configurou um MCP server, vale pros dois. Só o jeito de declarar a dependência muda.

Servidor stdio vs HTTP, declaração em .mcp.json, ferramenta exposta como mcp__server__tool, permissions/allowlist por server.

Cada agente tem perfis distintos: Claude tende a ser mais detalhista em refactor longo e debug profundo; Codex costuma ser mais rápido em tasks pequenas e seguir hard prompts à risca.

Saber qual ferramenta puxar pra cada tarefa economiza horas. Não é "qual é melhor" — é "qual é melhor pra isso aqui agora".

Estilo de raciocínio (planner-heavy vs doer-heavy), tolerância a ambiguidade, comportamento em edição de arquivo grande, custo por token.

Padrão observado por quem usa os dois: quando um agente entra em loop, repete o mesmo erro ou perde o fio, passar o contexto pro outro frequentemente resolve em segundos.

É a justificativa #1 pra ter os dois instalados. Não precisa esperar suporte ou ficar lutando — abre o segundo agente, cola o resumo, segue em frente.

Session handoff (cf. T6.1), context dump em markdown, "fresh eyes effect", custo de troca quase zero quando o projeto está bem documentado.

Provedores caem. Limites são atingidos. Se sua produtividade depende 100% de Anthropic OU OpenAI, qualquer instabilidade te tira do ar. Ter os dois é seguro de continuidade.

Se você cobra por hora ou tem deadline, o custo de ficar parado é maior que o custo das duas assinaturas. Faz a conta.

Status pages (status.anthropic.com, status.openai.com), rate limit por janela, fallback manual, "tool-agnostic" como princípio.

Tudo que NÃO é configuração do agente (código-fonte, docs, scripts, READMEs, wikis) é lido igualmente pelos dois. Você não duplica nada disso.

Esse é o ponto que destrava a coexistência: 95% do projeto é compartilhado. Só os 5% de configuração precisam de tradução — e o polyskill resolve essa tradução pra skills.

Source code, documentação, ADRs, scripts shell, dados de exemplo — tudo compartilhado. Só skills, sub-agents e settings se duplicam.

Atitude de não casar com uma ferramenta. O ecossistema de coding agents muda rápido — Gemini CLI, Cursor, Copilot, JetBrains, e o próximo. Sua skill deve sobreviver à troca de ferramenta.

Quem fica preso em um runtime sofre toda vez que aparece algo melhor. Quem escreve portable migra em horas. O polyskill é a manifestação técnica desse mindset.

Spec aberta (agentskills.io), formato canônico vs formato de runtime, adapters plugáveis, drift policy, "rewrite-once, deploy-many".

Sim, são dois planos a pagar. Mas quanto vale uma hora sua bloqueada por um agente travado? Quanto vale aprender o ecossistema dominante quando a maré virar?

Pra defender a escolha pra você mesmo (e pro time/cliente) com números, não com vibe. Tem cenários onde uma só basta — e tem cenários onde duas é o mínimo.

Plano por uso vs assinatura, custo de oportunidade, depreciação de conhecimento, valor da redundância em fluxos críticos.