Pular para conteúdo

Codex Session Hygiene

Atualizado: 2026-06-11

Objetivo

Reduzir ruido nas sessoes do Codex, preservar contexto util e tornar cada execucao mais previsivel.

Este documento cobre somente Codex. Configuracoes e automacoes de outras superficies de agente ficam fora deste runbook.

Principios

  1. Menos contexto carregado por padrao: skills e plugins devem entrar quando ajudam a tarefa atual.
  2. Uma fonte de verdade por assunto: AGENTS.md define contrato de repo, docs/wiki registra decisao duravel, skill curta guia o fluxo operacional.
  3. Sessao isolada quando houver risco: se a arvore esta suja, use branch ou worktree isolado antes de editar.
  4. Verificacao antes de afirmar conclusao: relate comandos executados e limitacoes conhecidas.
  5. Push sem surpresa: force push deve ser opt-in e explicito.

Baseline Recomendada

Plugins

Manter ativos por padrao:

  • github: issues, PRs, CI e reviews.
  • browser: verificacao visual e interacao local.
  • build-web-apps: UI, design, frontend e QA visual.
  • superpowers: brainstorming, debugging, planos e verificacao.

Ativar sob demanda:

  • computer-use: somente quando for necessario operar app desktop.
  • expo: somente em tarefas mobile.
  • alpaca: somente em tarefas de mercado financeiro.
  • documents, spreadsheets, presentations: somente ao produzir esses artefatos.
  • chrome: somente quando o Browser in-app nao bastar.

Reasoning

Usar high como padrao para model_reasoning_effort e plan_mode_reasoning_effort. Subir para xhigh apenas quando houver arquitetura complexa, seguranca, migracoes, investigacao de CI dificil ou analise de risco relevante.

Git

Configurar git-always-force-push = false. Quando for preciso reescrever historico, usar --force-with-lease e declarar o motivo.

Skill de Inicio de Sessao

A skill versionada em .codex/skills/auraxis-session-start/SKILL.md deve ser a rotina curta de abertura de trabalho:

  1. ler AGENTS.md;
  2. verificar .context/active_agents.json;
  3. escolher o repo correto;
  4. isolar branch/worktree quando necessario;
  5. registrar Codex antes de editar;
  6. verificar, restaurar coordenacao, commitar, fazer push e abrir PR.

Ela nao deve duplicar regras de produto, arquitetura ou design. Quando uma decisao precisa sobreviver a sessao, ela deve ir para docs/wiki/.

Auditoria Local

Rodar o script read-only abaixo para identificar fontes de ruido:

bash scripts/codex-hygiene-audit.sh

O script reporta tamanho de caches, sessoes, worktrees, plugins instalados e flags relevantes do ~/.codex/config.toml. Ele nao remove arquivos.

Limpeza Recomendada

Executar limpezas em duas fases:

  1. Auditoria: medir tamanho e listar candidatos.
  2. Remocao explicita: apagar apenas artefatos confirmados como descartaveis.

Candidatos comuns:

  • sessoes antigas em ~/.codex/sessions;
  • worktrees antigos em ~/.codex/worktrees;
  • logs grandes que nao sao necessarios para debugging atual;
  • plugins habilitados que nao pertencem ao tipo de tarefa atual.

Nao automatizar exclusao agressiva no repo. Cada maquina pode ter historico e estado operacional diferente.

Checklist de PR do Codex

Antes de abrir PR:

  1. git diff --name-only nao deve incluir arquivos de outras superficies de agente.
  2. .context/active_agents.json deve voltar para idle, salvo quando o PR documenta intencionalmente o proprio contrato de coordenacao.
  3. O commit deve conter somente arquivos ligados ao escopo.
  4. A descricao do PR deve listar verificacoes executadas.
  5. Qualquer check nao executado deve ser declarado.