perhapsspy/codex-token-discipline

Disciplina de Tokens para o Codex

Propósito

Reduzir o custo total da raiz e dos filhos sem enfraquecer o sucesso da tarefa, a evidência necessária ou a entrega solicitada.

Manter leituras, saídas de ferramentas, novas tentativas e delegações limitadas. Preservar evidências reutilizáveis e escalar apenas a parte não resolvida.

Quadro Operacional

Use apenas o que muda o comportamento:

1. Nomeie a fase atual: explore, planeje, implemente, verifique, publique ou passe adiante.
2. Defina a próxima evidência necessária antes de ler amplamente.
3. Antes de uma chamada de ferramenta potencialmente ruidosa, defina o menor formato de retorno útil e o orçamento de saída.
4. Delegue trabalho secundário ruidoso apenas quando ele puder retornar descobertas destiladas com evidência.
5. Nos limites das fases, salve um estado de retomada compacto e entregue as decisões de continuação da sessão ao diretor proprietário, quando houver um.

Pule o ritual para pequenas edições, respostas diretas e comandos simples.

Contrato Antecipado de Saída

Impedir o excesso de saída antes que ele entre no contexto principal; não confie em resumi-lo depois.

• Para qualquer comando imprevisível ou em lote, nomeie o formato de retorno necessário primeiro: status, contagem, caminhos, campos selecionados ou primeira falha acionável.
• Defina um orçamento de retorno finito para a chamada de ferramenta. Para chamadas da família exec, defina como padrão um orçamento explícito em ou abaixo de 2.000 tokens, a menos que a evidência nomeada exija mais; não espere por um único limite de saída grande.
• Filtre, agregue ou selecione na fonte. Para testes e builds, retorne o status de saída, a primeira falha acionável e o comando antes de solicitar mais detalhes.
• Quando a saída completa for útil para inspeção posterior, escreva-a em um artefato local à tarefa ou temporário e retorne apenas seu caminho, tamanho, resumo compacto e primeira falha acionável. Inspecione fatias limitadas do artefato conforme necessário.
• Não crie um artefato para saída descartável que possa ser reduzida na fonte.

Leituras com Resumo Primeiro

Comece estreito; amplie apenas quando isso mudar a próxima decisão.

• Pesquise com rg ou listas de arquivos antes de abrir arquivos.
• Prefira git diff --stat, git diff --name-only, git diff --<path> focado e intervalos sed -n direcionados antes de diffs completos.
• Para logs e saída de comandos, use tail, head, jq, contagens, filtros ou pesquisas de erro antes de transcrições completas.
• Trate cada resultado de ferramenta retornado como custo de entrada futuro. Prefira contagens, caminhos, resumos ou evidências selecionadas antes da saída completa.
• Após uma falha, amplie a partir do artefato salvo ou execute novamente apenas o menor escopo com falha; evite transcrições completas repetidas no thread principal.

Se uma leitura ampla for necessária, declare o motivo e limite-a ao menor escopo útil.

Trabalho de Longa Duração

Trate as mudanças de fase como pontos de verificação de contexto.

• Antes de implementação ou alternância entre repositórios/tarefas, preserve a conclusão, a próxima decisão, o próximo passo mais próximo e o menor limite útil.
• Em repositórios que usam project-context, prefira BRIEF.md para estado atual compacto e logs para evidência.
• Quando um diretor coordena trabalho de longa duração, relate o ponto de verificação e deixe o diretor decidir se continua, transfere ou rotaciona a sessão. Não prescreva ou inicie incondicionalmente uma nova sessão.
• Sem um diretor, comece do zero apenas quando a superfície salva for suficiente para continuar e o usuário ou fluxo de trabalho proprietário solicitar.

Não armazene transcrições, matrizes de validação ou inventários de arquivos para compensar uma conversa grande.

Subagentes

Delegação não é inerentemente mais barata. Use o agente nomeado mais restrito para trabalho limitado que possa retornar evidência ou saída compacta e independentemente útil.

Comece com um agente. Paralelize apenas escopos independentes e não sobrepostos. Não duplique a mesma investigação, mantenha agentes vivos após a integração ou repita validação ainda válida.

Instrua com escopo, limite de escrita, condição de conclusão, validação e saída compacta esperada. Filhos não devem delegar.

Loops de Navegador e Interface

Antes de verificação visual ou de navegador repetida, anote os estados a verificar.

• Prefira uma captura de tela ou passagem de navegador por estado nomeado.
• Se uma verificação falhar, inspecione o menor proprietário: erro de console, estado do DOM, dados de rota ou componente focado.
• Mantenha imagens, capturas de tela em base64, texto completo do corpo e despejos de DOM fora do thread principal, a menos que esse artefato em si afete a próxima decisão.
• Pare assim que os estados nomeados forem verificados ou um bloqueador concreto for isolado.

Superfícies de Leitura Constante

Cada linha em instruções globais ou de repositório tem custo recorrente.

• Coloque regras de comportamento duráveis e limites de segurança em arquivos do tipo AGENTS.
• Coloque fluxos de trabalho repetíveis em skills.
• Coloque o estado atual da tarefa em documentos de tarefa do repositório.
• Coloque fatos de domínio reutilizáveis atuais em documentos de referência.
• Remova perfis desatualizados, instruções duplicadas e explicações históricas em vez de documentar ao redor deles.

Ao editar um arquivo de leitura constante, prefira uma regra de roteamento curta em vez de texto de procedimento.

Auditoria de Uso

Quando perguntado para onde os tokens foram, resolva scripts/summarize_codex_usage.py relativo ao diretório desta skill instalada, execute-o com --help e então audite com um --cwd-prefix explícito.

O script agrupa logs de implantação do Codex por thread raiz e relata totais de tokens, taxa de cache de entrada, participação de tokens de sessão filha, volume de saída de ferramentas, eventos de saída grande e sinais de ferramenta com maior saída, sem payloads brutos.

Trate os totais de tokens como sinais, não como qualidade. Evite pesquisas de texto em toda a casa; aponte o script para $CODEX_HOME/sessions ou outra raiz explícita de sessões.

Verificação Final

• O thread principal recebeu apenas a evidência necessária para a decisão atual?
• O trabalho ruidoso de ferramentas teve um formato de retorno e orçamento antes da execução, com detalhes completos mantidos em um artefato apenas quando útil?
• Leituras grandes, loops de navegador e subagentes foram limitados por perguntas explícitas?
• O estado retomável está na superfície correta, e o diretor proprietário reteve a decisão de continuar/transferir/rotacionar?
• A orientação de leitura constante permaneceu curta e encaminhou detalhes para outro lugar?