perhapsspy/codex-token-discipline

Codex Token Discipline

Propósito

Reducir el costo total de raíz y ramas sin debilitar el éxito de la tarea, la evidencia requerida o el entregable solicitado.

Mantener acotados las lecturas, la salida de herramientas, los reintentos y la delegación. Preservar la evidencia reutilizable y escalar únicamente la parte no resuelta.

Marco Operativo

Usar solo lo que cambia el comportamiento:

1. Nombrar la fase actual: explorar, planificar, implementar, verificar, publicar o transferir.
2. Definir la siguiente evidencia necesaria antes de leer de forma amplia.
3. Antes de una llamada a herramienta potencialmente ruidosa, definir la forma de retorno útil más pequeña y el presupuesto de salida.
4. Delegar trabajo secundario ruidoso solo cuando pueda devolver hallazgos destilados con evidencia.
5. En los límites de fase, guardar un estado de reanudación compacto y delegar las decisiones de continuación de sesión al director propietario cuando exista.

Omitir el ritual para ediciones pequeñas, respuestas directas y comandos simples.

Contrato de Salida Prevuelo

Prevenir el exceso de salida antes de que entre al contexto principal; no confiar en resumirlo después.

• Para cualquier comando impredecible o por lotes, nombrar primero la forma de retorno requerida: estado, recuento, rutas, campos seleccionados o el primer fallo accionable.
• Establecer un presupuesto de retorno finito en la llamada a la herramienta. Para llamadas de tipo exec, por defecto usar un presupuesto explícito de 2,000 tokens o menos, a menos que la evidencia nombrada requiera más; no esperar un umbral único de salida grande.
• Filtrar, agregar o seleccionar en la fuente. Para pruebas y compilaciones, devolver el estado de salida, el primer fallo accionable y el comando antes de solicitar más detalle.
• Cuando la salida completa sea útil para una inspección posterior, escribirla en un artefacto local a la tarea o temporal y devolver solo su ruta, tamaño, resumen compacto y primer fallo accionable. Inspeccionar fragmentos acotados del artefacto según sea necesario.
• No crear un artefacto para salida desechable que pueda reducirse en la fuente.

Lecturas con Resumen Primero

Comenzar estrecho; ampliar solo cuando cambie la siguiente decisión.

• Buscar con rg o listas de archivos antes de abrir archivos.
• Preferir git diff --stat, git diff --name-only, git diff --<ruta> enfocado y rangos de sed -n dirigidos antes que diferencias completas.
• Para registros y salida de comandos, usar tail, head, jq, recuentos, filtros o búsquedas de errores antes que transcripciones completas.
• Tratar cada resultado de herramienta devuelto como costo de entrada futuro. Preferir recuentos, rutas, resúmenes o evidencia seleccionada antes que la salida completa.
• Después de un fallo, ampliar desde el artefacto guardado o volver a ejecutar solo el ámbito de fallo más pequeño; evitar transcripciones completas repetidas en el hilo principal.

Si es necesaria una lectura amplia, indicar por qué y limitarla al ámbito útil más pequeño.

Trabajo de Larga Duración

Tratar los cambios de fase como puntos de control de contexto.

• Antes de la implementación o cambios de repositorio/tarea, preservar la conclusión, la siguiente decisión, el siguiente paso más cercano y el límite útil más pequeño.
• En repositorios que usen project-context, preferir BRIEF.md para el estado actual compacto y registros para evidencia.
• Cuando un director coordine trabajo de larga duración, informar el punto de control y dejar que el director decida si continuar, transferir o rotar la sesión. No prescribir ni iniciar incondicionalmente una sesión nueva.
• Sin un director, comenzar de nuevo solo cuando la superficie guardada sea suficiente para continuar y el usuario o el flujo de trabajo propietario lo requieran.

No almacenar transcripciones, matrices de validación o inventarios de archivos para compensar una conversación grande.

Subagentes

La delegación no es inherentemente más barata. Usar el agente nombrado más estrecho para trabajo acotado que pueda devolver evidencia o salida compacta e independientemente útil.

Comenzar con un agente. Paralelizar solo ámbitos independientes y no superpuestos. No duplicar la misma investigación, mantener agentes vivos después de la integración ni repetir validación aún válida.

Indicar con ámbito, límite de escritura, condición de finalización, validación y salida compacta esperada. Los hijos no deben delegar.

Bucles de Navegador y UI

Antes de verificación visual o de navegador repetida, anotar los estados a verificar.

• Preferir una captura de pantalla o pase de navegador por estado nombrado.
• Si una verificación falla, inspeccionar el propietario más pequeño: error de consola, estado del DOM, datos de ruta o componente enfocado.
• Mantener imágenes, capturas de pantalla en base64, texto completo del cuerpo y volcados del DOM fuera del hilo principal, a menos que ese artefacto en sí mismo afecte la siguiente decisión.
• Detenerse una vez que los estados nombrados estén verificados o se haya aislado un bloqueador concreto.

Superficies de Lectura Permanente

Cada línea en las instrucciones globales o del repositorio tiene un costo recurrente.

• Colocar reglas de comportamiento duraderas y límites de seguridad en archivos tipo AGENTS.
• Colocar flujos de trabajo repetibles en skills.
• Colocar el estado actual de la tarea en documentos de tarea del repositorio.
• Colocar hechos de dominio reutilizables actuales en documentos de referencia.
• Eliminar perfiles obsoletos, instrucciones duplicadas y explicaciones históricas en lugar de documentar alrededor de ellos.

Al editar un archivo de lectura permanente, preferir una regla de enrutamiento corta sobre texto de procedimiento.

Auditoría de Uso

Cuando se pregunte adónde fueron los tokens, resolver scripts/summarize_codex_usage.py relativo al directorio de este skill instalado, ejecutarlo con --help, luego auditar con un --cwd-prefix explícito.

El script agrupa los registros de despliegue de Codex por hilo raíz e informa totales de tokens, tasa de entrada en caché, participación de tokens de sesiones hijas, volumen de salida de herramientas, eventos de salida grande y señales de herramientas de mayor salida sin cargas útiles sin procesar.

Tratar los totales de tokens como señales, no como calidad. Evitar búsquedas de texto en toda la casa; apuntar el script a $CODEX_HOME/sessions u otra raíz de sesiones explícita.

Verificación Final

• ¿Recibió el hilo principal solo la evidencia necesaria para la decisión actual?
• ¿Tuvo el trabajo ruidoso de herramientas una forma de retorno y presupuesto antes de la ejecución, con el detalle completo mantenido en un artefacto solo cuando fue útil?
• ¿Estuvieron las lecturas grandes, los bucles de navegador y los subagentes acotados por preguntas explícitas?
• ¿Está el estado reanudable en la superficie correcta, y retuvo el director propietario la decisión de continuar/transferir/rotar?
• ¿Se mantuvo breve la guía de lectura permanente y se enrutaron los detalles a otro lugar?