Codex na prática: AGENTS.md, Skills, Subagents, Hooks, MCP e outros recursos

Quando alguém começa a usar o Codex, é comum tratar a ferramenta como um chat de programação.

A pessoa abre a conversa, explica o que quer, cola um prompt enorme e espera que a IA resolva tudo.

E quase sempre realmente funciona.

Ela cria uma tela, corrige um erro, monta uma função, ajusta um arquivo.

O problema é que esse jeito de trabalhar começa a falhar quando o projeto cresce.

Com o tempo, aparecem situações bem conhecidas:

• você precisa repetir as mesmas instruções várias vezes;
• o Codex esquece decisões importantes do projeto;
• cada resposta segue um padrão diferente;
• o código começa a ficar inconsistente;
• tarefas simples exigem explicações longas;
• o prompt vira uma mistura de regra, contexto, pedido, exceção e lembrete.

Aí surge aquela sensação incômoda:

Talvez IA ainda não funcione bem em projetos grandes.

Mas essa conclusão nem sempre é justa.

Muitas vezes, o problema não está na IA. Está na forma como o contexto foi entregue para ela.

Pense em uma equipe nova entrando em um projeto.

Se ninguém explica a estrutura, os padrões, as regras de negócio e o jeito certo de trabalhar, cada pessoa vai tomar decisões diferentes.

Com IA acontece algo parecido.

Se o Codex recebe apenas comandos soltos, ele trabalha no improviso.

Mas quando você organiza o ambiente, a história muda.

O Codex deixa de depender de prompts gigantes e passa a encontrar orientações no lugar certo: arquivos de instrução, documentação do projeto, configurações, skills, agentes especializados, automações e integrações.

É aqui que muita gente conhece apenas o AGENTS.md. E ele é importante.

Mas o ecossistema do Codex vai além disso.

Você pode organizar documentação, separar regras, criar processos reutilizáveis, configurar permissões, usar subagents para tarefas específicas, automatizar verificações com hooks e conectar o Codex a ferramentas externas por meio de MCP e plugins.

Na prática, isso muda o jeito de desenvolver.

O projeto deixa de depender de memória improvisada dentro de uma conversa e passa a ter:

• contexto organizado;
• padrões claros;
• documentação estruturada;
• memória entre sessões;
• processos reutilizáveis;
• especialistas para tarefas específicas;
• automações que não dependem de lembrete manual;
• integrações com ferramentas que você já usa.

Neste artigo, vamos entender de forma prática e sem complicação:

• o que é o Codex;
• como instalar e usar;
• o que é AGENTS.md;
• como funciona o config.toml;
• o que são Memories;
• para que serve a pasta docs/;
• o que são regras de execução;
• como funcionam slash commands e skills;
• o que são subagents;
• o que são hooks;
• o que é MCP;
• o que são plugins;
• o que vale ou não levar para o Git;
• quando usar cada recurso.

Uma observação importante

Este artigo foi escrito com base na documentação atual do Codex. Como a ferramenta evolui rápido, nomes de comandos, telas e disponibilidade de recursos podem mudar com o tempo.

Mais importante do que decorar nomes de arquivos é entender a lógica por trás do Codex.

A grande mudança não está apenas em usar uma ferramenta nova.

Está em organizar o conhecimento, o contexto e os processos do projeto para que a IA consiga trabalhar melhor.

É isso que separa:

Vibe Coding

de:

desenvolvimento assistido por IA

O que é o Codex?

O Codex é o agente de desenvolvimento de software da OpenAI.

Na prática, ele funciona como uma IA capaz de trabalhar dentro do seu projeto. Ele pode ler arquivos, entender a estrutura do sistema, sugerir mudanças, editar código, rodar comandos, revisar alterações e ajudar em tarefas de desenvolvimento.

Um cuidado importante

Quando você ouvir falar em “Codex da OpenAI“, pode ser que a pessoa esteja se referindo a duas coisas diferentes.

Existe um modelo antigo chamado Codex, lançado em 2021, que era voltado para completar código via API. E existe o Codex atual, que é um agente de desenvolvimento bem mais completo.

Este artigo fala do Codex atual.

A diferença para um chat comum é simples: em vez de você apenas conversar com a IA, o Codex pode trabalhar com o projeto real.

Ele pode:

• ler arquivos;
• criar arquivos;
• editar código;
• entender a estrutura de pastas;
• seguir padrões do projeto;
• executar comandos;
• revisar diferenças;
• ajudar com testes, refatorações e correções.

A lógica é:

Você organiza o contexto e o Codex trabalha seguindo esse contexto.

Isso evita repetir instruções como:

Use PHP 8.3.
Use MySQL.
Use Bootstrap.
Siga MVC.
Não misture SQL na view.

Você escreve isso uma vez no lugar certo, como no AGENTS.md, e o Codex passa a considerar essas orientações durante o desenvolvimento.

Outro detalhe importante: partes importantes do Codex são open source. A documentação oficial cita como componentes abertos o Codex CLI, o Codex SDK, o App Server e o repositório de skills. Já a extensão de IDE e a versão web não são abertas.

Ou seja: é melhor dizer que o Codex possui componentes open source, não que tudo no produto é aberto.

Como instalar o Codex

Hoje existem quatro formas principais de usar o Codex:

1. Pelo aplicativo desktop.
2. Pela extensão do VS Code ou editores compatíveis, como Cursor e Windsurf, e pela integração para IDEs JetBrains.
3. Pela CLI, que é a versão de terminal.
4. Pelo navegador, em chatgpt.com/codex.

Se você está começando e prefere uma interface visual, o aplicativo desktop costuma ser o caminho mais confortável.

Se você já trabalha no editor de código, a extensão pode fazer mais sentido.

Se você gosta de terminal, a CLI é direta e poderosa.

Se você quer delegar tarefas na nuvem e acompanhar depois, a versão web é uma boa opção.

Aplicativo desktop

O aplicativo desktop está disponível para Windows e macOS.

Ele é uma boa opção porque oferece uma interface visual para acompanhar conversas, revisar alterações, trabalhar em várias tarefas e usar recursos como worktrees, automações e integrações.

Você pode baixar o aplicativo pela página oficial do Codex, sempre conferindo se está usando o instalador mais recente para o seu sistema operacional.

Extensão do editor

Se você usa VS Code, Cursor, Windsurf ou uma IDE JetBrains, pode instalar a integração do Codex no próprio editor.

A vantagem é que o Codex consegue usar melhor o contexto do que você está vendo no editor:

• arquivos abertos;
• trechos selecionados;
• mudanças em andamento;
• e estrutura do projeto.

CLI: Codex no terminal

A CLI é a versão de linha de comando.

Para instalar via npm:

npm install -g @openai/codex

O nome correto do pacote é @openai/codex.

Não confunda com pacotes antigos ou não oficiais chamados apenas codex.

Também é possível instalar com Homebrew:

brew install codex

Depois, execute:

codex

Na primeira execução, o Codex vai pedir autenticação.

Você pode entrar com sua conta do ChatGPT ou usar uma chave de API da OpenAI. Algumas funcionalidades de nuvem podem não estar disponíveis quando você usa apenas chave de API, então vale conferir o que faz sentido para o seu caso.

Codex no navegador

Também é possível usar o Codex pela web em:

👉 chatgpt.com/codex

Essa versão é útil quando você quer iniciar uma tarefa na nuvem, acompanhar logs, revisar alterações e criar pull requests sem depender do computador local rodando a sessão.

Planos e acesso

Segundo a documentação atual de Quickstart, todo plano ChatGPT inclui Codex.

Também é possível usar Codex com créditos de API ao entrar com uma chave de API.

Na prática, recursos, limites, clientes disponíveis e funcionalidades específicas podem variar conforme plano, região, forma de login e ambiente usado.

Antes de começar: comandos, interfaces e mudanças rápidas

O Codex muda rápido, alguns recursos aparecem primeiro no app desktop. Outros aparecem primeiro na CLI. Alguns comandos funcionam no terminal, mas não necessariamente da mesma forma na versão web. Certas funções dependem do sistema operacional.

Por exemplo:

• slash commands são muito fortes na CLI;
• o aplicativo desktop tem recursos visuais como revisão de diffs, worktrees e automações;
• Computer Use, na documentação atual, é um recurso ligado ao app no macOS;
• subagents aparecem no app e na CLI, mas a visibilidade na extensão de IDE ainda está evoluindo;
• plugins podem ser gerenciados pelo app ou pela CLI.

Então, se você não encontrar exatamente o mesmo botão ou comando no ambiente que está usando, não significa que você fez algo errado.

Às vezes a interface simplesmente é diferente.

Uma boa regra é: se não encontrar um recurso, pergunte ao próprio Codex como usar aquilo no ambiente atual.

Se você não encontrar algum recurso na interface que está usando, a forma mais rápida de resolver é perguntar diretamente no chat (ChatGPT ou Codex).

A IA te orienta para o caminho certo no ambiente em que você está.

Arquivos locais e globais do Codex

Antes de falar de AGENTS.md, skills ou subagents, existe uma diferença importante:

• arquivos globais;
• arquivos locais do projeto.

O que são arquivos globais?

Arquivos globais ficam na sua máquina e podem valer para vários projetos.

Por exemplo:

~/.codex/config.toml
~/.codex/AGENTS.md

O símbolo ~ representa a pasta do usuário.

No Windows, por exemplo, isso normalmente equivale a:

C:\Users\SeuUsuario

Então:

~/.codex/

significa algo como:

C:\Users\SeuUsuario\.codex\

No macOS:

/Users/seu-usuario/.codex/

No Linux:

/home/seu-usuario/.codex/

Esses arquivos são bons para preferências pessoais, como:

• estilo de resposta que você prefere;
• configurações padrão;
• servidores MCP que usa em vários projetos;
• ajustes de modelo;
• permissões globais.

O que são arquivos locais?

Arquivos locais ficam dentro do projeto atual.

Exemplo:

meu-sistema/
├── AGENTS.md
├── docs/
├── .codex/
│   ├── config.toml
│   ├── hooks.json
│   ├── rules/
│   └── agents/
└── .agents/
    └── skills/

Esses arquivos fazem sentido quando o conteúdo pertence ao projeto.

Por exemplo:

• arquitetura do sistema;
• comandos de teste daquele projeto;
• padrões da equipe;
• regras específicas do módulo financeiro;
• skills criadas para aquele repositório.

A pergunta simples é:

Isso pertence ao projeto ou pertence à minha máquina?

Se pertence ao projeto, provavelmente fica no repositório.

Se pertence às suas preferências pessoais, provavelmente fica na sua pasta de usuário.

Você não precisa escrever tudo sozinho

Depois de conhecer recursos como:

AGENTS.md
config.toml
skills
subagents
hooks
MCP
plugins

é normal pensar:

Isso parece complicado demais para criar manualmente.

Mas existe um detalhe importante:

Você pode usar o próprio Codex para criar e melhorar esses arquivos.

Você não precisa sentar e escrever um AGENTS.md perfeito do zero.

Também não precisa decorar toda a estrutura de skills, hooks ou subagents.

Você pode começar com pedidos simples:

Crie um AGENTS.md inicial para este projeto.

ou:

Transforme este prompt repetitivo em uma skill reutilizável.

ou:

Configure um MCP para acessar a documentação oficial da OpenAI.

O mais importante é não tentar acertar tudo na primeira versão.

O fluxo natural é:

1. Criar algo simples.
2. Usar no projeto.
3. Perceber problemas.
4. Ajustar aos poucos.

Com o tempo, a estrutura fica melhor.

O que é o AGENTS.md?

O AGENTS.md é o principal arquivo de instruções do Codex dentro de um projeto.

Pense nele como um manual de entrada.

Ele explica ao Codex:

• o que é o projeto;
• quais tecnologias usa;
• como o código está organizado;
• quais padrões devem ser seguidos;
• quais comandos rodam testes;
• quais cuidados são importantes.

Na prática, ele evita que você tenha que repetir as mesmas instruções toda vez.

Em vez de escrever sempre:

Use PHP 8.3.
Use MySQL.
Siga MVC.
Nunca misture SQL na view.

você coloca isso no AGENTS.md.

Onde fica o AGENTS.md?

Normalmente, o arquivo fica na raiz do projeto:

meu-sistema/
├── AGENTS.md
├── app/
├── public/
├── database/
└── docs/

Mas ele também pode existir em subpastas.

Exemplo:

meu-sistema/
├── AGENTS.md
├── app/
│   └── financeiro/
│       └── AGENTS.md
└── tests/
    └── AGENTS.md

O Codex lê as instruções da raiz até a pasta onde está trabalhando. Arquivos mais próximos da pasta atual têm mais peso, porque são mais específicos.

AGENTS.override.md

Além do AGENTS.md, existe o AGENTS.override.md.

Esse arquivo tem prioridade sobre o AGENTS.md no mesmo diretório.

Ele é útil quando você precisa de uma instrução temporária ou uma regra mais forte para uma área específica.

Exemplo:

services/payments/
├── AGENTS.md
└── AGENTS.override.md

Nesse caso, o Codex usa o AGENTS.override.md daquela pasta no lugar do AGENTS.md da mesma pasta.

Para iniciantes, não é obrigatório usar AGENTS.override.md. Mas é bom saber que ele existe.

AGENTS.md global

Também pode existir um arquivo global:

~/.codex/AGENTS.md

Esse arquivo guarda preferências pessoais que você quer aplicar em vários projetos.

Por exemplo:

• prefira respostas curtas;
• explique decisões importantes;
• sempre avise antes de instalar dependências;
• use um estilo específico de revisão de código.

Esse arquivo é pessoal e normalmente não vai para o Git.

Exemplo simples de AGENTS.md

# Sistema Financeiro

Este projeto é um sistema de contas a pagar e receber.

## Tecnologias

- PHP 8.3
- MySQL 8
- Bootstrap 5

## Arquitetura

- MVC
- Repository Pattern
- Service Layer

## Padrões de código

- Nunca misturar SQL nas views.
- Sempre usar prepared statements.
- Controllers devem ser leves.
- Validar uploads de arquivos.
- Seguir PSR-12.

## Comandos importantes

- Rodar o projeto: `php -S localhost:8000 -t public/`
- Rodar testes: `./vendor/bin/phpunit`
- Verificar estilo: `./vendor/bin/phpcs`

O maior erro com AGENTS.md

O erro mais comum é transformar o AGENTS.md em um prompt gigante.

Misturar tudo no mesmo arquivo parece prático no começo, mas vira bagunça.

Não coloque ali:

• documentação completa de API;
• regras de negócio enormes;
• checklists longas;
• processos de release;
• prompts repetitivos;
• instruções específicas demais para uma tarefa isolada.

O AGENTS.md funciona melhor como:

visão geral
+
padrões principais
+
comandos importantes
+
orientações de navegação

Se uma informação é detalhada demais, talvez pertença à pasta docs/.

Se é um processo repetitivo, talvez vire uma skill.

Se é uma investigação especializada, talvez use um subagent.

Limite de tamanho

A documentação do Codex cita um limite padrão de tamanho para instruções de projeto: project_doc_max_bytes, que por padrão é 32 KiB.

Em português simples: isso dá algo em torno de 32 mil caracteres, ou aproximadamente 4 a 6 mil palavras, dependendo do idioma, da formatação e da quantidade de código no arquivo.

Ou seja, existe um limite de quanto texto o Codex carrega desses arquivos de instruções.

Isso reforça a ideia principal:

O AGENTS.md deve ser útil, não enorme.

A pasta docs/

A pasta docs/ é onde você guarda documentação do projeto.

Pense nela como a biblioteca do sistema.

Ela serve para explicar como o projeto funciona.

Mas existe uma ressalva importante: o Codex não carrega automaticamente toda a pasta docs/ como instrução permanente.

Quem pode entrar automaticamente na cadeia de instruções são arquivos como AGENTS.md, AGENTS.override.md e nomes alternativos configurados no config.toml, respeitando a hierarquia de pastas e o limite de tamanho.

Então, uma boa prática é usar o AGENTS.md para apontar quais documentos em docs/ devem ser consultados em cada situação.

Exemplo:

## Documentação importante

- Para regras de negócio, consulte `docs/regras-negocio.md`.
- Para decisões de arquitetura, consulte `docs/arquitetura.md`.

Exemplos:

• regras de negócio;
• arquitetura;
• fluxos do sistema;
• integrações;
• documentação de API;
• decisões importantes;
• processo de deploy.

Exemplo:

meu-sistema/
├── AGENTS.md
├── docs/
│   ├── arquitetura.md
│   ├── regras-negocio.md
│   ├── api.md
│   └── deploy.md

Observação importante

A pasta docs/ serve como a “biblioteca central” do seu sistema. É o lugar perfeito para você criar arquivos de texto simples (no formato Markdown, com a extensão .md) para explicar as regras de negócio do projeto, como funcionam as telas, as integrações de APIs ou os fluxos que o usuário faz no seu site.

Mas aqui vai uma “observação técnica importante” que pouca gente percebe: a pasta docs/ não é um recurso de fábrica ou uma ferramenta nativa da IA. Diferente das pastas de skills ou de subagentes (que precisam ter nomes exatos e específicos para a IA encontrar), a pasta docs/ é apenas uma convenção de organização. Os desenvolvedores, costumam usar esse padrão no mercado para deixar manuais e papéis arrumados dentro de qualquer projeto.

A IA não tem nenhuma linha de código secreta que diz “procure uma pasta chamada docs”. O que ela faz, na verdade, é ter a capacidade de ler e indexar os arquivos de texto do seu projeto para usá-los como base de conhecimento (contexto).

Ao criar uma pasta docs/ e colocar seus manuais ali dentro, você não está ativando um botão oculto da IA; você está apenas aplicando uma boa prática de mercado que facilita a vida da IA na hora de encontrar e ler os seus arquivos de documentação.

docs/ não é a mesma coisa que AGENTS.md

Essa diferença é importante.

docs/ explica o sistema.

AGENTS.md explica como o Codex deve trabalhar no sistema.

Exemplo de docs/:

Cobranças vencidas geram multa após 5 dias.

Exemplo de AGENTS.md:

Nunca misture SQL nas views.

Uma regra simples:

Se explica o funcionamento do produto, coloque em docs/.
Se orienta como o Codex deve trabalhar, coloque em AGENTS.md.

O arquivo config.toml

O config.toml é o arquivo de configuração do Codex.

Se o AGENTS.md explica o projeto, o config.toml ajusta o comportamento da ferramenta.

Ele pode configurar, por exemplo:

• modelo padrão;
• esforço de raciocínio;
• permissões;
• sandbox;
• servidores MCP;
• hooks;
• Memories;
• perfis de configuração.

O arquivo global fica em:

~/.codex/config.toml

Também pode existir uma configuração local do projeto:

.codex/config.toml

Mas há um detalhe de segurança: o Codex só carrega configurações locais de .codex/ quando o projeto é confiável.

Isso evita que um repositório baixado da internet configure permissões perigosas sem você perceber.

Mesmo em projetos confiáveis, nem tudo pode ser configurado pelo arquivo local.

Algumas chaves sensíveis, como provedor do modelo, URLs base, autenticação, perfil, telemetria e comandos locais de notificação, devem ficar no ~/.codex/config.toml do usuário. Se aparecerem em .codex/config.toml, o Codex ignora e avisa no início.

Isso evita que um projeto altere configurações críticas da sua máquina.

Exemplo simples

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
memories = true

TOML é apenas um formato de configuração legível. Você escreve chaves e valores.

Não precisa decorar. Na prática, você pode pedir:

Configure o Codex para usar Memories e um modo seguro de aprovação.

E o próprio Codex pode ajudar a criar ou ajustar o arquivo.

Sandbox e aprovações

Esse é um dos assuntos mais importantes para usar Codex com segurança.

O sandbox é uma área controlada onde o Codex pode trabalhar.

Em linguagem simples:

O sandbox define o que o Codex pode acessar no seu computador.

Já a política de aprovação define quando o Codex precisa pedir sua confirmação.

Por exemplo, você pode configurar o Codex para:

• ler arquivos do projeto;
• editar arquivos dentro da pasta atual;
• pedir aprovação antes de rodar certos comandos;
• bloquear acesso à rede;
• impedir alterações fora do diretório permitido.

Isso é importante porque o Codex pode executar comandos e editar arquivos. Quanto mais acesso você libera, mais cuidado precisa ter.

Para quem está começando, a regra é simples:

Use configurações conservadoras e aprove manualmente ações importantes.

Com o tempo, quando você confiar nos fluxos do projeto, pode liberar mais coisas aos poucos.

Memories: quando o Codex aprende com o tempo

Memories é o sistema que permite ao Codex carregar informações úteis de sessões anteriores.

Por padrão, Memories ficam desligadas.

Para ativar no config.toml:

[features]
memories = true

Depois disso, o Codex pode guardar contexto útil, como:

• preferências estáveis;
• padrões recorrentes do projeto;
• comandos que aparecem com frequência;
• armadilhas conhecidas;
• fluxos de trabalho repetidos.

Mas existe uma regra importante:

Memories ajudam, mas não substituem AGENTS.md nem documentação versionada.

Se uma regra precisa valer para toda a equipe, coloque no AGENTS.md ou em docs/.

Memories são uma camada útil de lembrança local. Não devem ser a única fonte de regras obrigatórias.

Dependendo da região, Memories podem não estar disponíveis. Quando ativadas, elas geram arquivos locais dentro do diretório do Codex, como:

~/.codex/memories/

Outro cuidado: não coloque segredos em Memories. O Codex pode tentar ocultar ou evitar registrar informações sensíveis, mas você ainda deve tratar memórias como dados que precisam de cuidado.

Chronicle

Chronicle é um recurso ligado ao sistema de Memories.

Ele usa contexto recente da tela para ajudar o Codex a entender no que você estava trabalhando, sem você precisar explicar tudo do zero.

Mas, na documentação atual, ele tem limitações importantes:

• está em research preview;
• é opt-in, ou seja, precisa ser ativado;
• está disponível no app Codex para macOS;
• exige permissões de gravação de tela e acessibilidade;
• não está disponível em algumas regiões no lançamento;
• pode consumir limites de uso rapidamente;
• pode aumentar riscos de privacidade e prompt injection;
• pode armazenar memórias localmente sem criptografia no dispositivo.

Então, para a maioria dos iniciantes, Chronicle não é o primeiro recurso a estudar.

O ideal é começar com:

AGENTS.md
docs/
config.toml
skills simples

E só depois explorar Chronicle.

Regras de execução em .codex/rules/

No Codex, as regras de execução servem para controlar quais comandos podem rodar fora do sandbox.

Em português simples: elas ajudam a definir o que o Codex pode ou não pode executar no seu ambiente.

Isso é diferente de uma regra de estilo de código.

Essa distinção é importante:

• AGENTS.md orienta como o Codex deve trabalhar no projeto.
• .codex/rules/ controla comandos que o Codex pode executar.

Por exemplo: imagine que o Codex queira consultar informações de um pull request usando o GitHub CLI.

Um comando desse tipo poderia ser:

gh pr view

Esse comando normalmente apenas consulta informações. Mesmo assim, como ele roda fora do sandbox, você pode querer que o Codex peça confirmação antes de executá-lo.

É para isso que servem as Rules.

As regras ficam em arquivos com extensão .rules, dentro de uma pasta chamada rules/.

Exemplo de regra global, válida para sua máquina:

~/.codex/rules/default.rules

Exemplo de regra local, válida apenas para um projeto:

.codex/rules/default.rules

Regras locais só são carregadas quando o projeto é confiável.

Dentro do arquivo .rules, você pode criar uma regra usando prefix_rule().

Exemplo simplificado:

# Pede confirmação antes de rodar comandos que começam com `gh pr view`
# fora do sandbox.
prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "Ver pull requests é permitido, mas deve pedir confirmação antes.",
)

Em português simples, essa regra diz:

Quando o Codex quiser executar um comando que começa com gh pr view fora do sandbox, ele deve pedir confirmação antes.

A decisão da regra pode variar conforme o caso. Por exemplo:

• prompt: pede confirmação antes de executar;
• allow: permite executar sem pedir confirmação;
• forbidden: bloqueia a execução do comando.

Para iniciantes, o mais seguro é começar com prompt.

Use allow com muito cuidado, porque ele libera a execução sem confirmação. E use forbidden quando quiser bloquear comandos que não devem rodar de jeito nenhum.

Na documentação atual, Rules aparecem como recurso experimental. Isso significa que a forma de configurar ou usar pode mudar com o tempo.

Por isso, para quem está começando, esse recurso pode esperar.

Ele faz mais sentido quando você já está cansado de aprovar manualmente os mesmos comandos seguros, ou quando quer bloquear comandos específicos no ambiente do projeto.

Mesmo assim, evite tratar Rules como sua única camada de segurança. Elas ajudam, mas não substituem boas práticas como revisar comandos, usar sandbox, manter permissões conservadoras e evitar liberar acesso demais para a IA.

Slash commands

Slash commands são comandos rápidos que começam com /.

Eles servem para controlar a sessão sem escrever um prompt longo.

Exemplos:

/clear
/compact
/diff
/model
/permissions
/mcp
/skills
/hooks
/review

Eles são especialmente úteis na CLI.

Alguns exemplos práticos:

• /diff mostra as alterações feitas;
• /compact resume a conversa para economizar contexto;
• /permissions ajusta permissões da sessão;
• /mcp mostra servidores MCP ativos;
• /skills lista e usa skills;
• /hooks mostra hooks configurados;
• /review abre fluxos de revisão de código, quando disponível;
• /model troca o modelo;
• /agent permite navegar entre threads de subagents;
• /init ajuda a criar um AGENTS.md inicial.

A lista muda com o tempo e pode variar entre CLI, app, extensão, permissões e recursos habilitados. Não trate listas de slash commands como definitivas.

Por isso, no ambiente que você estiver usando, digite:

/

e veja os comandos disponíveis.

Se você encontrar referências antigas a “custom prompts” como comandos personalizados, atenção: na documentação atual eles aparecem como recurso depreciado. Para instruções reutilizáveis, prefira skills.

Skills: processos reutilizáveis

Skills são instruções reutilizáveis para tarefas específicas.

Pense em uma skill como um manual de procedimento.

Ela diz ao Codex:

• quando usar;
• o que fazer;
• em qual ordem;
• quais cuidados tomar;
• que resultado entregar.

Exemplo:

Em vez de escrever toda vez:

Revise todos os arquivos alterados, procure riscos, confira testes,
verifique migrations e gere uma checklist antes da publicação.

você pode criar uma skill chamada:

revisar-release

Depois, basta chamar a skill ou pedir algo que combine com ela.

Onde as skills ficam?

A documentação atual do Codex usa estes caminhos:

Skills do projeto:

.agents/skills/

Skills do usuário:

$HOME/.agents/skills/

No Windows, $HOME normalmente aponta para algo como:

C:\Users\SeuUsuario

Então uma skill pessoal poderia ficar em:

C:\Users\SeuUsuario\.agents\skills\

Existe uma pequena confusão aqui porque algumas ferramentas internas e instaladores ainda podem mencionar $CODEX_HOME/skills ou ~/.codex/skills.

A forma mais segura de explicar é esta:

A documentação atual lista .agents/skills/ para skills do projeto e $HOME/.agents/skills/ para skills pessoais. Se o seu ambiente ou instalador mostrar outro caminho, confira a tela de /skills e a documentação atual daquele cliente.

Estrutura de uma skill

Uma skill fica dentro de uma pasta própria e precisa ter um arquivo chamado SKILL.md.

Exemplo:

.agents/
└── skills/
    └── revisar-release/
        └── SKILL.md

Conteúdo:

---
name: revisar-release
description: Use quando o usuário pedir para revisar uma release antes da publicação.
---

# Revisar release

1. Verifique arquivos alterados.
2. Procure riscos.
3. Confira se há migrations.
4. Veja se existem testes relacionados.
5. Gere um resumo claro.
6. Monte uma checklist final.

Não publique nada automaticamente.
Sempre peça confirmação antes de ações irreversíveis.

Arquivos extras dentro de skills

Uma skill pode ter mais do que o SKILL.md.

Ela pode incluir:

scripts/
references/
assets/
agents/

Exemplo:

.agents/skills/revisar-release/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
│   └── verificar.sh
└── references/
    └── checklist.md

Isso permite criar skills mais poderosas sem colocar tudo dentro do arquivo principal.

O arquivo agents/openai.yaml é opcional e serve para metadados de interface, política de invocação e dependências, como MCP. Para a maioria das skills simples, você não precisa pensar nele no começo.

Você também não precisa criar skills do zero manualmente. O Codex inclui recursos como:

$skill-creator
$skill-installer

O primeiro ajuda a criar uma skill. O segundo ajuda a instalar skills prontas ou curadas, quando disponível no seu ambiente.

Em algumas interfaces, além de abrir /skills, você também pode chamar uma skill diretamente com $nome-da-skill.

Quando usar skills?

Use skills quando a tarefa:

• tem várias etapas;
• se repete com frequência;
• precisa de consistência;
• é grande demais para virar só um comando curto.

Bons exemplos:

• revisar release;
• gerar changelog;
• preparar descrição de pull request;
• auditar segurança;
• criar plano de testes;
• revisar performance;
• gerar documentação.

Uma boa pista:

Se o prompt ficou grande e você usa sempre, talvez ele deva virar uma skill.

Quando não usar skills?

Não use skill para tudo.

Se a tarefa é simples, um pedido direto resolve.

Exemplo:

Gere uma mensagem de commit.

Também não use skill para regra permanente do projeto.

Exemplo:

Nunca misture SQL na view.

Isso pertence ao AGENTS.md.

Subagents: especialistas separados

Subagents são agentes separados que o Codex pode criar para trabalhar em tarefas específicas.

Na prática, eles funcionam como especialistas.

Exemplos:

• especialista em segurança;
• especialista em testes;
• especialista em performance;
• especialista em arquitetura;
• especialista em investigação de bugs.

Mas o maior benefício dos subagents não é apenas a especialização.

O maior benefício é separar contexto.

Imagine que você está implementando uma funcionalidade e quer analisar ao mesmo tempo:

• segurança;
• performance;
• testes;
• arquitetura;
• bugs possíveis.

Se tudo isso fica na mesma conversa, o contexto cresce rápido. A sessão mistura logs, arquivos, hipóteses, decisões e trechos de código.

Com subagents, você pode pedir:

Crie um subagent para revisar segurança e outro para revisar testes.
Depois junte os resultados em um resumo.

Cada subagent trabalha separado e devolve apenas o que importa.

Ponto importante: subagents precisam ser pedidos

A documentação atual é clara: o Codex só cria subagents quando você pede explicitamente.

Ou seja, não conte com subagents sendo acionados sozinhos.

Se quiser usar, peça.

Exemplo:

Crie um subagent para revisar segurança e outro para procurar bugs.
Depois espere os dois terminarem e resuma os achados.

Custom agents

Além dos subagents criados durante a conversa, você pode definir agentes personalizados.

Eles ficam em arquivos TOML separados:

Projeto:

.codex/agents/

Global:

~/.codex/agents/

Cada arquivo representa um agente personalizado.

A documentação atual exige campos como:

• name;
• description;
• developer_instructions.

Exemplo simplificado:

name = "security-reviewer"
description = "Especialista em revisar riscos de segurança sem alterar arquivos."
developer_instructions = """
Revise o código procurando riscos de segurança.
Explique os achados com clareza.
Não modifique arquivos.
"""
sandbox_mode = "read-only"

Para quem está começando, não precisa criar custom agents logo de cara.

Use subagents quando a tarefa for grande o suficiente para justificar especialistas separados.

Skill e subagent não são a mesma coisa

Essa confusão é comum.

Uma skill é um processo.

Um subagent é um especialista.

Exemplo de skill:

Procedimento para revisar uma release.

Exemplo de subagent:

Especialista em segurança.

Inclusive, uma skill pode pedir ajuda a subagents durante o processo.

Hooks: automações determinísticas

Hooks são scripts que rodam automaticamente em momentos específicos da vida do Codex.

Em linguagem simples:

Hook é uma ação automática disparada por um evento.

Por exemplo, você pode configurar o Codex para fazer algo:

• quando uma sessão começa;
• quando o usuário envia uma mensagem;
• antes de o Codex usar uma ferramenta;
• depois de uma ferramenta rodar;
• quando uma tarefa termina.

Isso é útil porque algumas ações não devem depender de a IA lembrar.

Imagine este cenário:

Você quer que, sempre que o Codex terminar uma tarefa, ele rode uma verificação simples no projeto.

Sem hook, você precisa lembrar de pedir:

Agora rode a verificação final.

Com hook, essa verificação pode rodar automaticamente quando a tarefa termina.

Onde ficam os hooks?

Hooks podem ser configurados em arquivos como:

~/.codex/hooks.json
~/.codex/config.toml
.codex/hooks.json
.codex/config.toml

Para um hook global, válido para sua máquina, você poderia usar:

~/.codex/hooks.json

Para um hook local, válido apenas para um projeto, você poderia usar:

.codex/hooks.json

Hooks locais do projeto só são carregados quando o projeto é confiável.

Também é possível que plugins tragam hooks próprios, dependendo da configuração.

Exemplo simples de hook

Imagine que dentro do seu projeto exista um script chamado:

.codex/hooks/verificacao-final.sh

Esse script poderia fazer uma checagem simples quando o Codex termina uma tarefa.

Exemplo de conteúdo do arquivo .codex/hooks/verificacao-final.sh:

#!/usr/bin/env bash

echo "Verificação final executada pelo hook do Codex."

Depois, no arquivo:

.codex/hooks.json

você poderia registrar o hook assim:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$(git rev-parse --show-toplevel)/.codex/hooks/verificacao-final.sh\"",
            "timeout": 30,
            "statusMessage": "Executando verificação final"
          }
        ]
      }
    ]
  }
}

Em português simples, esse arquivo diz ao Codex:

Quando a tarefa terminar, execute o script .codex/hooks/verificacao-final.sh.

O evento usado nesse exemplo é Stop, que acontece quando o turno ou tarefa do Codex termina.

Por que usar $(git rev-parse --show-toplevel)?

Esse trecho:

$(git rev-parse --show-toplevel)

serve para descobrir a pasta raiz do repositório Git.

Isso torna o caminho do script mais confiável, porque o Codex pode ser iniciado a partir de uma subpasta do projeto.

Então, em vez de depender de um caminho relativo frágil como:

.codex/hooks/verificacao-final.sh

o hook encontra a raiz do projeto e chama o script no lugar certo.

Exemplos de uso

Hooks podem servir para:

• registrar logs;
• bloquear prompts com segredos;
• rodar validações;
• carregar contexto adicional;
• notificar quando uma tarefa termina;
• aplicar verificações de qualidade.

Um exemplo mais realista seria trocar o conteúdo de verificacao-final.sh por comandos do seu projeto, como:

#!/usr/bin/env bash

npm test

ou:

#!/usr/bin/env bash

./vendor/bin/phpunit

Mas cuidado: hooks rodam automaticamente. Então, antes de colocar comandos pesados, demorados ou sensíveis, pense bem se eles realmente devem executar toda vez.

Hooks precisam ser revisados

Hooks podem executar comandos na sua máquina. Por isso, o Codex pode pedir que você revise e confie em um hook antes de executá-lo.

Se você alterar o conteúdo do hook, ele pode precisar ser revisado novamente.

Na CLI, você pode usar:

/hooks

para ver hooks configurados, revisar hooks novos ou alterados e desativar hooks não gerenciados.

Hooks são avançados

Para a maioria das pessoas, hooks não são o primeiro recurso a usar.

Comece com:

AGENTS.md
docs/
skills
config.toml

Depois, quando sentir que precisa de garantias automáticas, estude hooks.

Na prática, hooks fazem mais sentido quando você quer que certas ações aconteçam sempre, sem depender de o Codex lembrar.

Mesmo assim, use com cuidado.

Um hook mal configurado pode rodar comandos desnecessários, deixar o fluxo lento ou executar algo que você não pretendia. Por isso, prefira começar com hooks simples, visíveis e fáceis de revisar.

MCP: conectando o Codex a outras ferramentas

MCP significa Model Context Protocol.

O nome parece complicado, mas a ideia é simples:

MCP é um padrão para conectar o Codex a ferramentas e fontes de contexto externas.

Por exemplo:

• documentação;
• GitHub;
• Slack;
• Linear;
• Google Drive;
• Figma;
• navegador;
• bancos de dados;
• ferramentas internas da empresa.

Sem MCP, um fluxo comum é:

1. Abrir uma ferramenta.
2. Copiar informação.
3. Colar no Codex.
4. Esperar o Codex trabalhar.
5. Voltar na ferramenta para atualizar algo.

Com MCP, o Codex pode acessar a ferramenta diretamente, dentro dos limites de permissão que você configurou.

Como configurar MCP

A configuração fica no config.toml.

A documentação atual usa tabelas nomeadas assim:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Para servidores HTTP:

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Você também pode usar a CLI:

codex mcp add context7 -- npx -y @upstash/context7-mcp

E dentro do Codex pode usar:

/mcp

para ver os servidores ativos.

Quando usar MCP?

MCP faz sentido quando o Codex precisa acessar algo fora do projeto.

Exemplos:

• ler um ticket no Linear;
• consultar uma documentação externa;
• acessar dados de uma planilha;
• buscar informações no Slack;
• usar Figma;
• consultar uma API interna.

Plugins

Plugins são pacotes instaláveis que aumentam o que o Codex consegue fazer.

Eles podem incluir:

• skills;
• integrações com apps;
• servidores MCP;
• fluxos prontos.

Exemplos:

• plugin do Google Drive;
• plugin do Slack;
• plugin do Gmail;
• plugin do GitHub;
• plugin de Figma;
• plugin com skills internas de uma equipe.

Você pode instalar plugins pelo diretório de plugins no aplicativo Codex ou pela CLI usando:

/plugins

Depois de instalar, você pode pedir naturalmente:

Resuma os documentos recentes do Google Drive.

Ou escolher um plugin específico usando @, dependendo da interface.

Plugin não é a mesma coisa que skill

• Uma skill é um procedimento.
• Um plugin é um pacote de distribuição.
• Um plugin pode conter várias skills, integrações e configurações.

Pense assim:

• skill: a receita;
• plugin: a caixa que instala várias receitas e ferramentas juntas.

O que vai para o Git e o que não vai?

Git é o histórico compartilhado do projeto.

Tudo que vai para o Git pode parar na máquina de outras pessoas.

Por isso, é importante separar:

• contexto compartilhado;
• preferências pessoais;
• dados sensíveis;
• arquivos temporários.

Normalmente vai para o Git

Vai para o Git o que faz parte do projeto e ajuda a equipe:

AGENTS.md
docs/
.agents/skills/
app/
database/
public/

Também podem ir:

• skills locais úteis para a equipe;
• documentação;
• exemplos de configuração sem segredos;
• scripts do projeto.

Normalmente não vai para o Git

Não devem ir arquivos pessoais, temporários ou sensíveis:

.env
logs/
tmp/
node_modules/
vendor/
~/.codex/config.toml
~/.codex/AGENTS.md

Cuidado especial com:

• senhas;
• tokens;
• chaves de API;
• credenciais de banco;
• arquivos com caminhos pessoais;
• memórias locais;
• configurações privadas.

E .codex/config.toml?

Depende.

• Se o arquivo contém configuração segura e útil para toda a equipe, pode fazer sentido versionar.
• Se contém preferências pessoais, caminhos locais, servidores privados ou segredos, não deve ir para o Git.

Na dúvida, use .gitignore e crie um arquivo de exemplo, como:

.codex/config.example.toml

Regra simples

Pergunte:

Isso precisa existir igual na máquina de toda a equipe?

• Se sim, talvez vá para o Git.
• Se é pessoal, temporário ou sensível, não deve ir.

Qual recurso usar em cada situação?

Depois de conhecer todos esses recursos, a dúvida natural é:

Quando eu uso cada um?

Aqui vai um resumo prático.

Recurso	O que é	Quando usar
AGENTS.md	Instruções principais do projeto	Padrões, arquitetura, comandos importantes
AGENTS.override.md	Instrução com prioridade na mesma pasta	Regras específicas ou temporárias
docs/	Documentação do sistema	Regras de negócio, API, fluxos, arquitetura
config.toml	Configuração do Codex	Modelo, permissões, MCP, Memories
Memories	Lembranças locais entre sessões	Preferências e padrões recorrentes
.codex/rules/	Regras de execução	Controlar comandos fora do sandbox
Slash commands	Comandos rápidos	Controlar a sessão sem prompt longo
Skills	Processos reutilizáveis	Revisões, checklists, releases, testes
Subagents	Especialistas separados	Investigações paralelas ou complexas
Hooks	Scripts automáticos	Garantias e validações automáticas
MCP	Conexões externas	Acessar ferramentas e dados fora do repo
Plugins	Pacotes instaláveis	Instalar skills e integrações prontas

Para projetos pequenos

Comece com:

AGENTS.md
docs/ simples
config.toml básico

Para projetos médios

Adicione:

skills
Memories
MCP para ferramentas essenciais

Para projetos grandes

Considere:

AGENTS.md em subpastas
subagents
hooks
rules
plugins internos
automations
worktrees

O objetivo não é usar tudo.

O objetivo é organizar melhor.

Não tente resolver falta de organização com prompts maiores.

Outros recursos que valem explorar depois

O Codex tem mais recursos do que caberia aprofundar em um único artigo.

Se você está começando, não precisa dominar tudo agora.

Mas vale conhecer os nomes.

Automations

Permitem agendar tarefas recorrentes no app Codex.

Exemplo:

• revisar pendências toda segunda;
• checar bugs diariamente;
• gerar relatório semanal;
• rodar uma análise recorrente.

Worktrees

Worktrees permitem que o Codex trabalhe em cópias separadas do mesmo repositório.

Isso é útil quando você quer rodar tarefas em paralelo sem bagunçar sua pasta principal.

Review mode

O modo de revisão permite pedir ao Codex para analisar alterações antes de você publicar ou abrir um pull request.

Na CLI, isso pode aparecer como /review. Ele revisa diffs, mudanças não commitadas ou commits específicos e devolve achados priorizados, sem mexer automaticamente nos seus arquivos.

Modo não interativo

Para scripts e automações, existe o modo não interativo com codex exec.

Exemplo:

codex exec "revise as mudanças e gere um resumo"

Isso é útil em CI, scripts internos ou tarefas repetitivas que não precisam de uma conversa aberta.

Computer Use

Permite que o Codex veja e opere interfaces gráficas no macOS, com permissões específicas.

É útil para tarefas que exigem clicar, navegar, testar uma tela ou usar um aplicativo sem API.

Remote Connections

Permitem controlar um host Codex a partir de outro dispositivo, como celular, ou conectar o app a projetos em máquinas remotas.

GitHub Action

Permite rodar Codex dentro do GitHub Actions, por exemplo para revisar pull requests ou executar tarefas automáticas no CI.

Team Config e requirements.toml

Em empresas, pode fazer sentido padronizar configurações para a equipe.

Team Config e requirements.toml ajudam administradores a compartilhar defaults, skills e regras, além de impor limites como políticas de aprovação e sandbox.

Codex SDK e App Server

São recursos mais técnicos para criar automações, integrações ou interfaces em cima do Codex.

Codex Security

É uma área voltada para análise de segurança, threat modeling e busca de vulnerabilidades.

Para projetos sérios, especialmente em empresas, vale pesquisar.

Modelos

O artigo usa gpt-5.5 como exemplo porque é o modelo recomendado na documentação consultada.

Mas modelos disponíveis mudam com o tempo e podem depender do plano, do cliente e da forma de autenticação. Antes de fixar um modelo em material interno, confira /model ou a documentação atual.

Como começar sem se perder

Se você está lendo tudo isso e pensando que é muita coisa, comece pequeno.

Não tente montar a estrutura perfeita no primeiro dia.

Um bom caminho é:

1. Criar um AGENTS.md simples.
2. Colocar documentação básica em docs/.
3. Configurar o config.toml com permissões seguras.
4. Criar um checkpoint no Git antes de mudanças maiores.
5. Usar o Codex no projeto real.
6. Quando repetir um prompt grande, transformar em skill.
7. Quando uma investigação ficar pesada, usar subagents.
8. Quando precisar conectar ferramentas externas, explorar MCP.
9. Quando precisar de garantia automática, estudar hooks.

Esse processo cresce junto com o projeto.

Não é sobre montar uma arquitetura de contexto perfeita.

É sobre melhorar o ambiente aos poucos.

Conclusão

Muita gente ainda usa IA para programar como se estivesse apenas conversando com um chatbot.

Mas o Codex permite outro tipo de fluxo.

Em vez de depender apenas da conversa atual, você constrói um ambiente organizado para a IA trabalhar.

O projeto passa a ter:

• contexto estruturado;
• documentação;
• padrões permanentes;
• memória;
• workflows reutilizáveis;
• especialistas separados;
• automações;
• integrações com ferramentas externas.

E isso muda a qualidade do desenvolvimento.

• O Codex deixa de trabalhar no improviso.
• Ele passa a trabalhar seguindo uma estrutura.

Essa talvez seja a principal ideia do artigo:

Desenvolvimento assistido por IA não é sobre criar prompts gigantes. É sobre organizar contexto.

Quando você organiza tudo corretamente, o projeto fica mais previsível, mais consistente e mais sustentável.

Principalmente em projetos longos e em equipes.

E isso vale não apenas para o Codex.

Essa forma de pensar tende a ficar cada vez mais importante em qualquer ambiente de desenvolvimento com IA.

Porque no futuro, a diferença não será apenas sobre quem usa IA. A diferença será sobre quem sabe estruturar contexto para IA.

• No primeiro caso, você apenas conversa com a ferramenta. Isso é Vibe Coding.
• No segundo, você constrói um ambiente real de desenvolvimento com contexto, padrões, processos, memória e organização. Isso é desenvolvimento assistido por IA.