Estrategia IT · base v1 · 13/07/2026

Manual de boas práticas ChatGPT Codex

Uma wiki inicial para padronizar como profissionais iniciantes, intermediários e avançados usam Codex com clareza, segurança, rastreabilidade e foco em entrega real.

Começar pelo fluxo Ver templates Atalhos e comandos
Contexto Arquivos, regras, dependências e critérios de aceite.
Execução Planejar, editar, testar, revisar e registrar decisões.
CODEX
Governança Sandbox, aprovações, revisões e limites de acesso.
Escala Skills, MCP, hooks, worktrees e automações futuras.

Visão Geral

Codex deve ser tratado como um agente de desenvolvimento: ele lê contexto, altera arquivos, executa comandos e precisa de limites claros para trabalhar bem.

Defina o contrato

Explique objetivo, escopo, arquivos relevantes, restrições, comandos de verificação e o formato esperado da resposta.

Preserve o repositório

Não misture refatorações, formatação massiva ou mudanças de arquitetura quando a tarefa pede uma correção pequena.

Valide sempre

Peça evidência: testes, lint, build, prints, logs ou uma explicação objetiva do que não foi possível executar.

Registre padrões

Use AGENTS.md, .codex/config.toml, skills e hooks para transformar bons hábitos em rotina reutilizável.

Regra de ouro para a empresa Codex acelera trabalho quando o time sabe dizer o que quer, como medir pronto e onde o agente pode agir. Quanto mais explícitos forem os padrões do repositório, menos energia será gasta corrigindo direção.

Trilhas Por Nível

Use as trilhas como orientação de onboarding. A evolução natural é sair de pedidos pontuais, passar por tarefas verificáveis e chegar a fluxos automatizados.

Objetivo

Aprender a pedir mudanças pequenas, entender o diff e validar a entrega sem perder controle.

Prompt claro Arquivos citados Teste simples

Pratique

  • Peça explicação antes de pedir alteração quando não conhecer a área.
  • Solicite uma mudança por vez em arquivos pequenos.
  • Leia o resumo final e confira se os testes foram executados.

Evite

  • Pedidos genéricos como "melhore tudo".
  • Aprovar comandos que instalam dependências sem entender por quê.
  • Ignorar avisos de teste não executado.

Fluxo De Trabalho

Este fluxo é o padrão recomendado para tarefas de desenvolvimento, documentação, análise e revisão dentro da empresa.

Contextualizar

Explique objetivo, área do sistema, restrições, arquivos importantes e o que não deve ser alterado.

Planejar quando houver risco

Para mudanças pequenas, Codex pode agir direto. Para mudanças amplas, peça um plano curto com riscos, dependências e verificação.

Executar com escopo fechado

O agente deve tocar apenas nos módulos necessários, respeitar padrões existentes e pedir aprovação para ações fora do limite do sandbox.

Verificar

Rode testes, lint, build, inspeção visual ou comandos equivalentes. Se algo não rodar, registre o motivo e o risco residual.

Revisar e consolidar

Leia o resumo final, confira arquivos alterados, compare com critérios de aceite e só então faça commit ou abra pull request.

Principais Arquivos

Estes arquivos formam a base de uma operação Codex organizada. Nem todo projeto precisa de todos no primeiro dia.

Arquivo Uso recomendado Boas práticas
AGENTS.md Instruções persistentes do repositório: setup, comandos, padrões de código, testes, revisão e restrições. Curto, acionável, sem duplicar README inteiro. Use seções por tecnologia ou módulo.
AGENTS.override.md Override temporário ou específico em uma pasta, carregado com maior prioridade que AGENTS.md. Use com cuidado, explique validade e remova quando não for mais necessário.
.codex/config.toml Configuração local do projeto, como defaults, MCP, features e limites aplicáveis quando o projeto é confiável. Prefira configurações mínimas e revisáveis. Não inclua segredos.
~/.codex/config.toml Preferências pessoais do usuário: modelo, perfil, sandbox, providers, features e servidores MCP pessoais. Não trate como padrão corporativo. Para time, documente no projeto ou em política administrada.
.codex/hooks.json Hooks do projeto para validações determinísticas durante eventos do ciclo Codex. Use para checks objetivos: segredo em prompt, lint obrigatório, validação de mensagens ou logging autorizado.
SKILL.md Define uma skill reutilizável com instruções, workflow e referências para tarefas recorrentes. Descreva quando usar, entradas esperadas, passos e critérios de qualidade.
.codex-plugin/plugin.json Manifesto de plugin para empacotar skills, conectores, MCP, hooks e assets distribuíveis. Use quando a skill precisa ser instalada por outras pessoas ou equipes.
docs/ Documentação humana: decisões, runbooks, playbooks, ADRs e guias do produto. Mantenha links entre AGENTS.md e documentos longos para não inflar o contexto inicial.

Estrutura De Pastas

Esta estrutura é uma sugestão para projetos internos que querem crescer com documentação, automação e governança desde cedo. 

repositorio/
  AGENTS.md
  README.md
  .codex/
    config.toml
    hooks.json
    skills/
      review-pr/
        SKILL.md
        references/
      gerar-documentacao/
        SKILL.md
    local-environment/
      README.md
  docs/
    index.md
    arquitetura/
      adr-0001-template.md
    operacao/
      runbook-deploy.md
      checklist-release.md
    codex/
      prompts-padrao.md
      politicas-de-uso.md
  scripts/
    validate-docs.ps1
    check-secrets.ps1
  tests/
  src/
  package.json

Raiz do projeto

Guarde instruções essenciais, setup e comandos oficiais. Codex deve conseguir começar pela raiz sem adivinhar.

.codex/

Centralize configuração do agente, hooks, skills locais e notas de ambiente. Só use dados que possam ser versionados.

docs/codex/

Guarde padrões de prompt, políticas internas e exemplos validados. Esta pasta vira a base da wiki corporativa.

Comandos

Separe comandos de produto, slash commands, atalhos e comandos de projeto. Isso reduz ambiguidade e deixa o onboarding mais rápido.

Slash Commands Úteis

Comando Quando usar
/init Gerar um scaffold de AGENTS.md para o projeto atual.
/status Ver ID da tarefa, uso de contexto e limites disponíveis.
/plan Alternar para planejamento em tarefas com múltiplas etapas.
/goal Definir um objetivo persistente para trabalho mais longo.
/review Iniciar modo de revisão de código em mudanças locais ou contra uma branch base.
/worktree Executar a tarefa em um Git worktree isolado.
/mcp Ver servidores MCP conectados e seu estado.
/compact Compactar o contexto quando a tarefa fica longa.

Atalhos E Ações

Ação Atalho ou comando
Menu de comandos Ctrl/Cmd + Shift + P ou Ctrl/Cmd + K
Configurações Ctrl/Cmd + ,
Nova tarefa Ctrl/Cmd + N
Buscar tarefas Ctrl/Cmd + G
Buscar na tarefa Ctrl/Cmd + F
Terminal integrado Ctrl + `
Confirmar instruções carregadas codex --ask-for-approval never "Summarize the current instructions."
Rodar em subpasta codex --cd services/api "Explique o setup deste módulo."
Padrão interno para comandos de projeto Todo AGENTS.md deve listar os comandos oficiais de instalação, lint, teste, build, execução local e geração de documentação. Codex não deve adivinhar o comando certo quando a equipe já conhece a resposta.

Prompts

Bons prompts reduzem ida e volta. O segredo é combinar intenção, contexto, limites e evidência de pronto.

Prompt de implementação

Use quando espera alteração de código.

Objetivo: corrigir [problema].
Escopo: alterar apenas [arquivos/módulo].
Contexto: [regra de negócio, erro, link interno].
Validação: rode [comando] e reporte resultado.
Critério de aceite: [comportamento esperado].

Prompt de investigação

Use antes de mexer em área desconhecida.

Analise o fluxo de [feature].
Não altere arquivos ainda.
Liste: arquivos principais, riscos,
dependências, perguntas abertas
e proposta de menor mudança segura.

Prompt de revisão

Use para encontrar bugs e regressões.

Faça review das mudanças atuais.
Priorize bugs, regressões,
riscos de segurança e testes ausentes.
Responda com achados por severidade
e referências de arquivo/linha.

Checklist de um bom pedido

  • O objetivo está em uma frase.
  • O escopo diz o que pode e o que não pode mudar.
  • Os arquivos ou módulos relevantes foram citados.
  • Os comandos de validação foram informados.
  • O formato da resposta final está claro.

Sinais de prompt fraco

  • Pede "melhorar" sem métrica.
  • Mistura bug, refatoração e feature sem prioridade.
  • Não informa como validar.
  • Não diferencia hipótese de fato.
  • Não limita acesso a arquivos sensíveis.

Segurança E Governança

O modelo operacional deve ser simples: dar autonomia dentro de limites técnicos e exigir aprovação quando a tarefa cruza esses limites.

Sandbox

Define quais arquivos e comandos o agente pode acessar sozinho. Comandos executados pelo agente herdam essas restrições.

Aprovações

Use aprovações para rede, instalação de dependências, escrita fora do workspace, comandos destrutivos e acesso a dados sensíveis.

Worktrees

Use worktrees para tarefas paralelas sem interferir no checkout local. Eles exigem repositório Git.

Quando usar MCP

MCP conecta Codex a ferramentas e contexto externo autorizado. Use para documentação privada, navegador, Figma, GitHub, Slack, Jira ou bases internas quando houver conector aprovado.

  • Prefira MCP a copiar dados sensíveis no prompt.
  • Configure por usuário ou projeto em config.toml.
  • Revise permissões e autenticação antes de habilitar para o time.

Quando usar hooks

Hooks são scripts determinísticos no ciclo do Codex. Eles servem para checks repetíveis que não dependem de julgamento criativo.

  • Bloquear colagem acidental de segredo.
  • Rodar validações ao final de uma tarefa.
  • Registrar auditoria aprovada pela empresa.

Templates

Copie a estrutura conceitual destes exemplos para iniciar a padronização. Ajuste comandos e políticas ao projeto real.

AGENTS.md inicial

# AGENTS.md

## Objetivo do repositório
Descreva em 3 a 5 linhas o sistema, público e domínio.

## Setup
- Instalar dependências: `npm install`
- Rodar localmente: `npm run dev`
- Variáveis: copie `.env.example` para `.env.local`

## Comandos oficiais
- Lint: `npm run lint`
- Testes: `npm test`
- Build: `npm run build`

## Convenções
- Siga os padrões existentes antes de criar abstrações.
- Não adicione dependências sem justificar.
- Atualize `docs/` quando mudar comportamento público.

## Verificação antes de concluir
- Rode os comandos afetados.
- Informe qualquer comando que não pôde ser executado.
- Liste arquivos alterados e risco residual.

.codex/config.toml inicial

# .codex/config.toml
# Use apenas configurações que devem acompanhar este projeto.

project_doc_max_bytes = 65536
project_doc_fallback_filenames = [
  "TEAM_GUIDE.md",
  ".agents.md"
]

[features]
# Habilite somente recursos aprovados para o time.

[mcp_servers]
# Configure servidores MCP do projeto quando necessário.
# Nunca versionar tokens ou segredos.

Checklist de PR com Codex

  • A tarefa tem critério de aceite explícito.
  • O diff não contém mudanças fora do escopo.
  • Testes relevantes foram executados.
  • Arquivos sensíveis e segredos não foram expostos.
  • Documentação foi atualizada quando necessário.
  • Resumo final explica o que mudou e como validar.

Modelo de tarefa

Título: [verbo + objeto + resultado]

Contexto:
[o que está acontecendo e por que importa]

Escopo:
Inclui: [arquivos, módulos, tela, endpoint]
Não inclui: [fora de escopo]

Critérios de aceite:
- [resultado observável]
- [teste ou evidência]

Validação:
Rode: [comandos]
Reporte: [logs, prints, resumo]

Roadmap Da Wiki

Próximos incrementos para transformar este HTML em uma base corporativa viva e hospedável.

Fase 1 · Base

  • Publicar esta página como index.html.
  • Revisar com líderes técnicos.
  • Adicionar exemplos reais de projetos internos.

Fase 2 · Modularização

  • Separar em páginas: prompts, segurança, comandos, templates.
  • Criar busca global.
  • Adicionar changelog e dono por página.

Fase 3 · Operação

  • Publicar em portal interno.
  • Criar processo de contribuição.
  • Conectar com treinamentos, onboarding e políticas de TI.

Fontes Oficiais

Conteúdo baseado em documentação oficial consultada em 13/07/2026. O helper do manual Codex não validou o cabeçalho de integridade nesta rede, então a página usa fontes oficiais web como apoio.