Mejores prácticas: Las pocas que realmente funcionan, más allá de la palabrería correcta

📚 Navegación de la serie: El artículo anterior (35 Hoja de referencia de comandos y configuración) expuso los comandos, las claves de configuración y los atajos en una hoja de referencia que puedes pegar en la pared. Este artículo cambia de nivel: en lugar de hablar sobre "qué funciones existen", aborda "cómo combinar estas funciones para que Codex realmente te facilite la vida". El próximo artículo (37 Preguntas frecuentes y resolución de problemas) tratará sobre "qué hacer si algo sale mal".

A decir verdad, hice algo bastante tonto cuando obtuve Codex por primera vez: leí la página oficial de best-practices de principio a fin, pensé que cada punto tenía mucho sentido y luego... cerré la página sin mejorar ni uno solo de mis hábitos.

El problema no era mío, sino de que la gran mayoría de las llamadas mejores prácticas son obviedades correctas: "escribe instrucciones claras", "recuerda hacer pruebas", "itera en pasos pequeños"; todo suena bien, pero no te dice qué tan claro, qué probar ni qué tan pequeños deben ser los pasos. Asientes con la cabeza como si entendieras todo, pero al regresar sigues usándolo exactamente igual. Este tipo de consejos genéricos, en esencia, te devuelven la responsabilidad.

Por eso, en este artículo no planeo repetir esas grandes verdades que cualquiera puede decir. He revisado a fondo la lista oficial de best-practices y he seleccionado las pocas que realmente cambiaron mi forma de trabajar y que he verificado por mí mismo, explicándote en cada una "por qué hacerlo + cómo hacerlo concretamente + qué problemas tendrás si no lo haces". Solo conservo lo que es aplicable; lo que suena elegante pero no se puede llevar a la práctica, lo descarto por completo.

A decir verdad, la mayoría de los puntos siguientes los aprendí después de equivocarme primero y sufrir las consecuencias.

Al terminar este artículo, obtendrás:

Una estrategia para configurar Codex como un "compañero de equipo" en lugar de una "herramienta de un solo uso"
Qué debe incluir exactamente el archivo AGENTS.md (manual del proyecto) y qué longitud debe tener para ser útil
Un conjunto de cuatro elementos para las instrucciones: "Objetivo + Contexto + Restricciones + Aceptación", solo tienes que rellenar los datos
Cómo clasificar los permisos en diferentes niveles según el escenario y por cuál nivel deben empezar los principiantes
Por qué debes pedirle que elabore un plan antes de ponerse a trabajar en tareas complejas
Cómo hacer que Codex pruebe y revise sus propios cambios en lugar de que tú vigiles cada paso
Cómo abordar tareas de producción: obtener primero una cadena de evidencias, registros anonimizados y luego confirmar la solución
Una tabla comparativa de "Errores comunes ❌ / Prácticas correctas ✅" para aplicar directamente

⚠️ Los comandos, las claves de configuración y el comportamiento por defecto se rigen por la documentación oficial de Codex; los nombres de los modelos y su disponibilidad varían según la versión y tu plan, por lo que siempre prevalecerá el comportamiento real de tus archivos locales codex --help, el panel /model y ~/.codex/config.toml.

01 Cambia de mentalidad: Codex es un compañero al que debes guiar, no una herramienta de un solo uso

Primero, la conclusión: la calidad de los resultados al usar Codex depende en gran medida de cómo lo consideres.

Muchas personas (incluyéndome a mí en mis inicios) lo tratan como un cuadro de búsqueda que responde a preguntas individuales: le lanzan un problema, toman la respuesta y se van, empezando desde cero la próxima vez. Si lo usas así, solo aprovecharás el 30% de su capacidad.

Analogía: Codex es como un nuevo colega muy capaz que acabas de contratar, pero que no conoce en absoluto tu proyecto. No esperarías que lo supiera todo el primer día: tienes que darle un manual de bienvenida (AGENTS.md), explicarle cómo ejecutar y probar el código, y corregirlo cuando cometa un error para que lo recuerde. Cuanto más lo guíes, más eficiente será. Por el contrario, si contratas a un trabajador temporal diferente cada vez que no te conoce, estarás repitiendo la misma explicación eternamente.

En la documentación oficial hay una frase con la que estoy muy de acuerdo: en lugar de tratar a Codex como un asistente temporal, considéralo como un compañero al que configurarás y perfeccionarás continuamente. Todas las prácticas que siguen en este artículo giran esencialmente en torno a esta idea: convertir lo temporal y repetitivo en configuraciones persistentes.

Mi punto de inflexión fue a principios de 2026. Antes de eso, cada vez que abría una nueva sesión, tenía que escribir de nuevo instrucciones como "este proyecto usa pnpm y no npm", "las pruebas se ejecutan con pnpm test" y "las confirmaciones de commit deben redactarse en chino", repitiéndolo siete u ocho veces al día. Hasta que un día me cansé y metí todo eso en AGENTS.md, y el mundo se volvió tranquilo al instante. Solo entonces me di cuenta de que estaba usando de la manera más tonta una herramienta extremadamente inteligente.

💡 Resumen en una frase: Tratar a Codex como un compañero de equipo al que guías continuamente, en lugar de una herramienta desechable, es la base de todas las mejores prácticas.

02 Escribe un buen AGENTS.md: haz que trabaje trayendo el contexto automáticamente

Por qué hacerlo. Este archivo es el remedio para el problema del apartado anterior. AGENTS.md es un manual de instrucciones ubicado en el proyecto que Codex lee automáticamente en su contexto cada vez que entra, sin necesidad de que lo menciones con @. Las cosas que deben explicarse una y otra vez en un proyecto se escriben una sola vez y tienen efecto permanente.

Analogía: AGENTS.md es el README diseñado para la IA. Un README normal se escribe para personas, explicándoles de qué trata el proyecto y cómo ejecutarlo; AGENTS.md se escribe para Codex, indicándole las reglas, las zonas de peligro y los "criterios de aceptación".

Cómo hacerlo. La documentación oficial sugiere que un buen AGENTS.md cubra las siguientes secciones, solo tienes que listarlas:

Dónde está la estructura del proyecto y los directorios importantes
Cómo poner en marcha el proyecto
Qué comandos usar para la construcción, pruebas y linting
Convenciones de ingeniería y requisitos para enviar Pull Requests (PR)
Restricciones y límites infranqueables de lo que "nunca se debe hacer"
Cuáles son los criterios de aceptación y cómo verificarlos

La forma más rápida de empezar es escribir /init en la CLI, lo que generará una estructura inicial para AGENTS.md en el directorio actual. Pero no lo uses tal cual: lo que se genera es una plantilla, debes adaptarla para que refleje la realidad de tu proyecto.

El archivo AGENTS.md también puede estructurarse en niveles: el que se coloca en ~/.codex/ es tu configuración predeterminada personal; el del directorio raíz del proyecto es la norma compartida del equipo; y los de los subdirectorios son reglas locales. Cuanto más cerca esté del directorio actual, mayor prioridad tendrá para aplicarse.

Mal ejemplo (que yo mismo cometí). Al principio cometía el error inverso: escribía un montón de instrucciones de un solo uso como "esta vez no toques la base de datos" o "esta vez solo modifica este archivo" dentro de AGENTS.md. Como resultado, el archivo crecía sin control y se llenaba de reglas obsoletas, lo que acababa confundiendo a Codex al leerlo. Después aprendí la lección:

Las peticiones temporales se escriben en las instrucciones (prompts), y solo las reglas persistentes se registran en AGENTS.md. Corto y preciso es mejor que largo y vago.

La documentación oficial menciona una práctica muy útil que vale la pena adoptar: cuando Codex cometa el mismo error por segunda vez, pídele que haga una retrospectiva y añada esa lección a AGENTS.md. De esta forma, tu manual se nutrirá de experiencias reales de fricción en lugar de suposiciones hechas desde tu escritorio.

💡 Resumen en una frase: Consolida las "reglas persistentes" en AGENTS.md. Que sea breve, preciso y real es mucho más útil que escribir un largo texto lleno de generalidades.

03 No confíes tus instrucciones a la inspiración: usa la plantilla de cuatro partes "Objetivo + Contexto + Restricciones + Aceptación"

Por qué hacerlo. En el artículo anterior sobre la hoja de referencia ya mencionamos las instrucciones, aquí solo añado una estructura que puedes copiar directamente. Codex es muy potente en la actualidad, y si le das instrucciones vagas, a menudo se las arreglará para darte un resultado; sin embargo, en proyectos grandes o tareas de alto riesgo, una instrucción confusa le obligará a adivinar, y si adivina mal, tendrás que rehacer el trabajo.

La "receta de una buena instrucción por defecto" que ofrece la documentación oficial consta de cuatro partes, que yo utilizo como un ejercicio de rellenar huecos:

Elemento	Qué pregunta responde	Qué pasa si no se incluye
Objetivo (Goal)	Qué quieres modificar o construir exactamente	No captará el punto central y hará muchas cosas que no pediste
Contexto (Context)	Qué archivos, errores o ejemplos están relacionados (puedes mencionar archivos con @)	Buscará a ciegas en lugares equivocados y dará rodeos
Restricciones (Constraints)	Qué especificaciones, arquitectura o requisitos de seguridad se deben cumplir	Seguirá sus propios hábitos y desorganizará todo el estilo
Aceptación (Done when)	Qué condiciones deben cumplirse para dar el trabajo por terminado	Considerará que su tarea terminó cuando "el código funcione", dejándote los bugs a ti

Cómo hacerlo. No es necesario redactar cada instrucción como si fuera un contrato. Siempre que se trate de una tarea mínimamente compleja o de algo en lo que no quieras volver a trabajar, repasa mentalmente (o escríbelo directamente) estas cuatro casillas antes de enviar: qué quiero que haga, dónde está el material relacionado, qué no debe tocar y cómo sabremos que ha terminado.

Analogía: Este conjunto de cuatro elementos es como las instrucciones que le das a un equipo de reformas. No les dirías simplemente "haz que la cocina se vea más bonita" y los dejarías empezar a trabajar; tendrías que especificar el estilo deseado (objetivo), dónde están los planos de distribución y de instalaciones (contexto), que no pueden tocar las paredes de carga (restricciones) y que, al momento de la entrega, las luces deben encenderse, el agua debe correr y los armarios no deben tambalearse (aceptación). Cuanto más claras sean las instrucciones, menos modificaciones posteriores habrá.

El elemento que más solía olvidar era la aceptación. Hace tiempo le pedí a Codex que modificara la validación de un formulario, indicándole solo "añade una validación para el formato de número de teléfono", pero olvidé decir "después de añadirla, la validación de correo electrónico existente no debe fallar y las pruebas asociadas deben pasar". Codex añadió rápidamente la validación telefónica, pero estropeó sin querer la lógica del correo electrónico; no me di cuenta hasta que ejecuté las pruebas antes del despliegue. Desde entonces, la sección de "Done when" es obligatoria para mí.

💡 Resumen en una frase: No confíes tus instrucciones a la inspiración; rellena las casillas de "Objetivo + Contexto + Restricciones + Aceptación", y sobre todo, nunca olvides la aceptación.

04 Para tareas complejas, elabora un plan antes de actuar

Por qué hacerlo. Cuando una tarea es compleja o vaga, si le pides que escriba código directamente, tendrá que adivinar tu intención mientras teclea, y puede que te des cuenta de que el rumbo es incorrecto demasiado tarde. Pedirle que redacte un plan primero equivale a darte una oportunidad económica de "corregir el rumbo" antes de empezar.

Analogía: Esto es como mirar los planos antes de construir una casa. Nadie permitiría que los albañiles levantaran paredes sin planos; si quedan torcidas, demolerlas es un dolor de cabeza. El plan es ese plano: apenas unas pocas líneas de texto que resultan muchísimo más baratas que reescribir todo un bloque de código.

Cómo hacerlo. La documentación oficial ofrece varias opciones, que he ordenado según su facilidad de uso:

Usa el modo Plan (el más recomendado): Emplea /plan en la CLI o pulsa Shift+Tab para alternar. Codex recopilará primero el contexto, te pedirá aclaraciones y presentará una propuesta de plan más sólida; una vez que le des el visto bueno, empezará a trabajar.
Deja que te entreviste: Si tú mismo no tienes las cosas claras, pídele "no escribas nada de código todavía, cuestiona mis ideas y hazme preguntas para convertir este concepto vago en una solución concreta".
Usa la plantilla PLANS.md: Una técnica más avanzada consiste en hacer que las tareas de múltiples pasos y largo recorrido sigan una plantilla de plan de ejecución (según la guía oficial de planes de ejecución).

Mal ejemplo. La documentación oficial clasifica explícitamente "saltarse la planificación en tareas complejas de múltiples pasos" como un error común, algo con lo que me siento muy identificado. El año pasado le pedí a Codex que me ayudara a migrar un módulo basado en callbacks a async/await. Para ahorrar tiempo, no le pedí un plan y simplemente le dije "modifícalo como creas conveniente". Hizo la migración, pero a mitad de camino decidió por su cuenta "optimizar también" mi lógica de manejo de errores global. Toda la modificación se volvió un caos; cuando revisé el diff me dolió la cabeza y decidí usar git reset para empezar de cero. Esta vez utilicé primero /plan, pidiéndole que listara "qué archivos modificar, qué cambiar en cada uno y qué no tocar bajo ningún concepto". Una vez confirmado el plan, lo dejé trabajar y todo salió a la primera.

💡 Resumen en una frase: Cuanto más compleja y confusa sea una tarea, más necesario será usar /plan para definir los pasos y confirmar la dirección antes de dejarle escribir código.

05 Niveles de permisos: estrictos por defecto, ampliándose gradualmente según el escenario

Por qué hacerlo. Codex incluye un sandbox a nivel de sistema operativo con dos controles clave: el modo de aprobación (approval mode) regula si debe preguntarte antes de ejecutar comandos, y el modo de sandbox (sandbox mode) controla si puede leer o escribir en directorios y qué archivos puede manipular. Conceder todos los permisos desde el principio es el equivalente a entregar el volante y el acelerador a un conductor novel del que aún no conoces sus capacidades.

Analogía: Esto es como configurar los accesos para un becario nuevo. El primer día solo le permites leer el código y ejecutar pruebas locales; una vez que lo conoces y confías en él, le das acceso para modificar archivos y conectarse a la base de datos de manera gradual. Nadie le entrega las llaves del entorno de producción a un recién llegado el primer día.

Cómo hacerlo. La recomendación oficial es directa:

Los principiantes deben comenzar con los permisos predeterminados, manteniendo estrictas las políticas de aprobación y de sandbox.
Una vez que domines un flujo de trabajo y necesites más fluidez, ve ampliando los permisos para repositorios de confianza o escenarios específicos, en lugar de habilitarlo todo a la vez.

Escenario	Nivel recomendado	Razón
Recién iniciado / Proyectos desconocidos	Predeterminado (preguntar antes de actuar, sandbox estricto)	Es más seguro observar qué planea hacer antes de autorizarlo
Repositorio propio de confianza / Tareas repetitivas	Flexibilizar moderadamente la aprobación	Reduce la molestia de tener que hacer clic en "Aceptar" continuamente
Scripts desconocidos / Código de terceros	Nivel más estricto	Evita que ejecute comandos que no tenías previstos

La documentación oficial menciona específicamente "darle a Codex permisos de administración completos en el ordenador antes de comprender su flujo de trabajo" como un error común. Mi propia lección no fue catastrófica, pero sí lo suficientemente memorable: en una ocasión me cansé de confirmar cada acción y abrió bastante la política de aprobación. Como resultado, durante una refactorización, ejecutó un comando de limpieza que no examiné en detalle y borró varios archivos temporales que pensaba conservar. No fue un desastre grave, pero me dio un buen susto. Ahorrarse esos pocos segundos de confirmación no merece la pena.

💡 Resumen en una frase: Mantén los permisos estrictos por defecto y revisa bien antes de autorizar; flexibiliza el acceso de forma gradual solo en escenarios de confianza y evita abrir el acceso total por comodidad.

06 Haz que se valide a sí mismo: probar, verificar y revisar, no te conformes con que solo "termine de escribir"

Por qué hacerlo. En mi opinión, este es el consejo más valioso. No permitas que Codex se detenga en cuanto termine de escribir el código: pídele que escriba las pruebas unitarias correspondientes, ejecute las verificaciones oportunas y realice una revisión de los cambios antes de entregártelos. Al automatizar este paso, te ahorrarás el constante ciclo de "él escribe, tú pruebas, sale un error y le pides que lo solucione".

Sin embargo, hay una condición: debe saber cómo es un resultado "correcto". ¿De dónde procede ese criterio? Debe estar detallado en las instrucciones (prompts) o en el archivo AGENTS.md (como ves, volvemos al apartado 02).

Cómo hacerlo. El "ciclo cerrado de autocomprobación" que sugiere la documentación oficial incluye las siguientes acciones, las cuales puedes redactar directamente en tus requisitos:

Escribir o actualizar las pruebas para esta modificación
Ejecutar la suite de pruebas correspondiente
Ejecutar herramientas de linting, formateo y comprobación de tipos
Confirmar que el comportamiento final se ajusta exactamente a lo solicitado
Revisar el diff para detectar bugs, regresiones o prácticas peligrosas

El comando de la CLI /review es de gran valor en este contexto: puede realizar una revisión al estilo de una Pull Request (PR) comparando con la rama base, revisar los cambios locales sin confirmar, evaluar un commit determinado o guiarse por tus directrices personalizadas. Si tu equipo cuenta con un archivo code_review.md referenciado en AGENTS.md, Codex aplicará exactamente esos estándares durante su revisión, lo que ayuda a unificar el criterio de revisión cuando colaboran varias personas.

Mal ejemplo. La documentación oficial clasifica como un error común "impedir que el agente observe los resultados de su propio trabajo" (es decir, no indicarle cómo ejecutar los comandos de compilación o prueba). Recuerdo un caso en el que le pedí que modificara una función de procesamiento de datos sin exigirle que ejecutara pruebas. Codex me aseguró con total confianza que el trabajo estaba "completado y con la lógica correcta", y yo le creí. Sin embargo, ese código lanzaba excepciones con datos de entrada extremos, algo que el agente no pudo detectar porque nunca le dio la oportunidad de ejecutar las pruebas. Desde entonces, he adoptado un hábito: siempre que modifique lógica de código, añado al final del prompt "cuando termines, ejecuta <comando_de_prueba> y avísame cuando todas las pruebas pasen en verde". Una sola frase me ahorra la gran mayoría de las iteraciones de corrección.

💡 Resumen en una frase: Pídele a Codex que realice las pruebas, verificaciones y revisiones antes de la entrega final, asegurándote de definir el estándar de calidad en las instrucciones o en AGENTS.md.

07 Para tareas en producción (online), obtén primero una cadena de evidencias antes de hablar de soluciones

Por qué hacerlo. El desarrollo de funciones locales puede validarse mediante pruebas unitarias. Sin embargo, los incidentes en producción exigen responder a preguntas complejas: cuál es el síntoma original que experimentó el usuario, cómo se reproduce, qué registro de log coincide con esa petición y si has verificado el cambio siguiendo la misma ruta de usuario.

En la actualidad, he incorporado esta regla a las directrices de mis proyectos: para problemas en producción, primero recopila evidencias, luego analiza y finalmente repara. Codex buscará en el código siguiendo las pistas, pero si le dices directamente "ayúdame a arreglar esto", tomará la causa más probable como la verdadera y dará por buena una prueba local exitosa. En tareas de producción, ninguno de estos dos enfoques es suficiente.

Cómo hacerlo. Pídele que no modifique nada de código al principio y que solo recopile pruebas. Puedes redactar la instrucción así:

text

No modifiques el código todavía. Investiga este problema en producción siguiendo una cadena de evidencias:

1. Reproduce la ruta del usuario, registrando el método de petición, el código de estado, un resumen de la respuesta clave y la marca de tiempo.
2. Revisa los logs de la aplicación correspondientes a esa franja horaria y extrae únicamente las líneas de error relevantes.
3. Localiza la configuración, ruta, tarea o tabla de base de datos implicada, pero evita realizar cambios en el entorno de producción.
4. Presenta conclusiones divididas en tres apartados: "Hechos confirmados / Hipótesis pendientes / Próximas comprobaciones".
5. Asegúrate de anonimizar la salida ocultando tokens, enlaces de acceso privados, correos, números de teléfono, identificadores de pedidos y direcciones internas.

Esta instrucción desvía la atención de Codex del desarrollo de soluciones rápidas y la enfoca en la comprobación basada en evidencias. El diagnóstico final que te ofrezca debe poder contrastarse con los datos: qué petición falló, qué línea del log dio error, qué configuración intervino en esa ruta y qué paso dará para descartar las hipótesis formuladas.

Suelo incluir una regla persistente en AGENTS.md específica para este tipo de tareas:

## Gestión de incidentes en producción

- Reproduce primero el problema original, registrando códigos de estado, resúmenes de respuestas clave, marcas de tiempo en los logs y la ruta de validación.
- No realices cambios sin confirmación previa en datos de producción, permisos, visibilidad, facturación, notificaciones o estados de incidencias.
- Anonimiza todo el contenido de salida; no pegues tokens, datos de usuarios, enlaces privados, claves criptográficas, direcciones IP completas ni identificadores de pedidos.
- Verifica la corrección reproduciendo la ruta original del usuario; el éxito de las pruebas en local no garantiza la resolución del problema en el entorno de producción.
- Si no es posible realizar la comprobación, explica detalladamente qué evidencia falta, por qué no está disponible y quién puede proporcionarla.

Estas directrices recuerdan a las de operaciones y son ideales para Codex. Cuando lee "verifica la corrección reproduciendo la ruta original del usuario", evitará dar por terminada la tarea solo con una prueba unitaria; si lee "no realices cambios sin confirmación previa en datos de producción", se detendrá a consultarte antes de realizar operaciones que afecten el estado del usuario.

La anonimización debe conservar la información diagnóstica. Si eliminas demasiada información, acabarás borrando las pruebas y solo te quedará una frase del estilo "falló cierta API", lo que impedirá que otros investiguen el problema. Mantén la estructura general y oculta únicamente los valores confidenciales:

Información original	Formato anonimizado de utilidad
`https://example.com/private/path?token=secret_value`	`https://example.com/private/path?token=<token>`
`user@example.com`	`<user-email>`
`order_20260201_123456`	`<order-id>`
`Authorization: Bearer ...`	`Authorization: Bearer <redacted>`
`2026-02-01 14:03:22 status=500`	Conserva el tiempo y el código de estado originales

Por lo general, las marcas de tiempo, los códigos de estado, los tipos de error y la estructura de las rutas pueden conservarse; por el contrario, los valores que identifiquen directamente a un usuario, cuenta, clave criptográfica o recurso interno deben ocultarse. De este modo, cualquier miembro del equipo podrá seguir las evidencias para diagnosticar el problema sin arrastrar información confidencial a las PR, issues o chats públicos.

Cómo evaluar la aceptación. El criterio de aceptación para tareas en producción debe reconducirse a la ruta original. Si fallaba un endpoint, vuelve a llamarlo y registra el nuevo código de estado y el resumen de la respuesta; si fallaba una vista, reproduce el comportamiento del usuario en el navegador; si fallaba un trabajo en cola o programado, evalúa el log de la siguiente ejecución y el resultado obtenido. En caso de que carezcas de permisos en el entorno correspondiente, evita redactar un vago "imposible verificar"; detalla claramente si falta acceso al entorno de producción, cuentas de prueba, callbacks externos o la confirmación directa del usuario.

💡 Resumen en una frase: No permitas que Codex adivine las causas de fallos en producción; exígele primero una cadena de evidencias. Una vez corregido, vuelve a comprobar siguiendo la ruta del usuario, anonimizando los valores sensibles pero conservando códigos de estado, marcas de tiempo y tipos de error.

08 Delega las tareas pesadas en sub-agentes, y dedica cada hilo a un único propósito

Por qué hacerlo. Una sesión no es solo un historial de conversación; constituye un hilo de ejecución donde se va acumulando el contexto. Cuanto más largo sea el hilo y más temas heterogéneos abarque, peor será la calidad del resultado. Por lo tanto, la forma de gestionar los hilos afecta de manera directa a la calidad de las soluciones.

Analogía: Esto es como organizar tu mesa de trabajo. Si tienes los papeles de tres proyectos distintos esparcidos por la mesa a la vez, tardarás más en encontrar lo que buscas y tus decisiones serán más lentas y caóticas; si tu mesa solo contiene lo necesario para la tarea actual, tu eficiencia será máxima. El hilo de conversación con Codex es su mesa de trabajo.

Cómo hacerlo (dos pautas).

Primero, dedica cada hilo a un propósito único y coherente. La idea original es que, mientras se trate del mismo problema, debes permanecer en el mismo hilo, ya que mantiene todo el hilo de razonamiento previo. Solo cuando la tarea se bifurque realmente, debes emplear /fork para iniciar una nueva rama. Dicho de otro modo, organiza tus conversaciones por tareas y no por proyectos; el antipatrón más común es utilizar un único hilo eterno para todo un proyecto, lo que saturará el contexto de información irrelevante y degradará los resultados.

Segundo, delega los trabajos secundarios acotados a sub-agentes (subagents). Mantén el hilo principal centrado en el problema principal y delega las tareas independientes con objetivos claros (como explorar el código, redactar pruebas o realizar clasificaciones de incidencias) a sub-agentes, de forma que no saturen la atención del hilo principal.

Varios comandos prácticos para gestionar hilos (según el comportamiento real de tus archivos locales):

/resume Continúa conversando desde un registro archivado
/fork Crea un nuevo hilo conservando las respuestas del registro original
/compact Comprime el contexto previo en un resumen si el hilo es demasiado largo (Codex también lo hace de forma automática)
/status Comprueba el estado de la sesión actual de un vistazo

Mi hábito actual consiste en "un hilo por tarea", archivándolo en cuanto la tarea se completa. Parece un cambio menor, pero desde que dejé de usar un "único hilo multiusos para todo el proyecto", las respuestas de Codex están mucho más enfocadas y ya no se mezclan con información antigua; antes solía recurrir a contextos de requisitos abordados tres días atrás para justificar decisiones actuales.

💡 Resumen en una frase: Dedica cada hilo a una sola tarea y delega los trabajos pesados o secundarios a sub-agentes para evitar que el contexto crezca sin control.

09 Lista de comprobación: tabla de "Errores ❌ / Prácticas correctas ✅"

La documentación oficial concluye con un resumen de los "errores más comunes" recopilados de los ocho apartados anteriores. Los he estructurado en esta tabla comparativa para que puedas autoevaluarte: si te identificas con alguna situación de la columna izquierda, corrígela aplicando la propuesta de la derecha.

❌ Errores comunes	✅ Prácticas correctas
Poner todas las reglas persistentes dentro del prompt	Mueve las persistentes a `AGENTS.md` o a una skill; reserva los prompts solo para requisitos específicos de un solo uso
No indicarle cómo ejecutar la construcción y las pruebas	Detalla los comandos en `AGENTS.md` para que el agente evalúe su propio trabajo
Escribir código directamente en tareas complejas de múltiples pasos	Usa `/plan` primero para estructurar la solución y confirmar la dirección antes de actuar
Conceder permisos de administración completos sin comprender el flujo	Empieza con políticas estrictas por defecto y flexibilízalas gradualmente según la confianza
Usar un único hilo para todo un proyecto de principio a fin	Usa un hilo diferente para cada tarea, y bifurca con `/fork` solo cuando sea necesario
Modificar los mismos archivos en varios hilos a la vez sin usar git worktree	Emplea git worktree para crear espacios de trabajo independientes en ejecuciones paralelas y evitar conflictos
Intentar automatizar tareas de las que aún no tienes un flujo estable	Ejecútalas de forma manual primero hasta estabilizarlas, y luego considera convertirlas en una skill o automatización
Observar cada paso que da en pantalla sin poder hacer otra cosa	Deja que se ejecute en paralelo mientras te dedica a otras tareas
Reparar un problema en producción sin reproducirlo primero	Registra primero los síntomas originales, estados de petición, marcas de tiempo en logs e hipótesis de validación
Declarar la incidencia resuelta solo porque pasan las pruebas locales	Comprueba de nuevo siguiendo la ruta de usuario original y registra códigos de estado, comportamiento web o logs modificados
Pegar logs, enlaces y datos de usuario sin modificar en PRs públicas	Anonimiza los valores confidenciales pero conserva marcas de tiempo, códigos de estado, tipos de error y estructura de rutas

Cómo aplicar esto. No te limites a leer esta tabla una vez. Mi consejo es: la próxima vez que sientas que trabajar con Codex te resulta frustrante o exige demasiadas correcciones, vuelve aquí y revisa la columna izquierda; lo más probable es que identifiques qué aspecto estás descuidando. Ninguno de estos errores me los contaron: los aprendí todos a base de tropezar y equivocarme.

💡 Resumen en una frase: Evalúate con esta tabla; si te identificas con la columna izquierda, aplica la solución de la derecha. Es más eficaz que recordar cualquier lema de mejores prácticas.

10 Resumen

Este artículo no te ha dado obviedades correctas, sino ocho directrices prácticas que he validado personalmente y que pueden cambiar de inmediato tu forma de usar la herramienta:

Cambio de mentalidad: Tratar a Codex como un compañero al que guías continuamente es la base de todo.
Escribir AGENTS.md: Consolida las reglas persistentes de forma breve, precisa y real.
Estructura de instrucciones: Rellena las casillas de "Objetivo + Contexto + Restricciones + Aceptación", y no olvides esta última.
Planificar antes de actuar: Usa /plan en tareas complejas; no dejes pasar esta opción económica para ajustar el rumbo.
Gestión de accesos: Restringe por defecto y revisa bien antes de autorizar.
Automatizar la validación: Pídele que pruebe, verifique y revise los cambios, indicándole previamente qué estándar de calidad debe cumplir.
Evidencias en producción: No te saltes la reproducción, logs, códigos de estado, anonimización y doble comprobación.
Organizar los hilos: Dedica cada conversación a un único tema y delega las tareas pesadas a sub-agentes.

Ahora deberías ser capaz de: Cada vez que abordes una tarea con Codex, evalúa de forma instintiva: ¿debo pedirle un plan primero?, ¿he rellenado los cuatro campos de la instrucción?, ¿son suficientes las reglas de AGENTS.md?, ¿debe probar su propio código?, ¿qué nivel de permisos conviene usar? o ¿necesito recopilar evidencias de producción antes? Convertir esto en una costumbre transformará tu colaboración con Codex de un juego de azar a un proceso estructurado y con método.

El próximo artículo (36 Mejores prácticas) es el cierre de toda la sección de Codex. La hoja de referencia resuelve el problema de "no recordar", mientras que las mejores prácticas resuelven el "cómo usarlo correctamente". Con el mismo comando codex exec, algunos logran crear un flujo de automatización perfecto, mientras que otros terminan desorganizando su repositorio de código. Una pequeña reflexión: De los comandos que tienes a mano, ¿cuáles usas a diario sin haberte planteado si existe una forma más estable de implementarlos? En el próximo capítulo desglosaremos uno a uno esos puntos que usamos diariamente pero que no hemos analizado a fondo.

Mejores prácticas: Las pocas que realmente funcionan, más allá de la palabrería correcta ​

01 Cambia de mentalidad: Codex es un compañero al que debes guiar, no una herramienta de un solo uso ​

02 Escribe un buen AGENTS.md: haz que trabaje trayendo el contexto automáticamente ​

03 No confíes tus instrucciones a la inspiración: usa la plantilla de cuatro partes "Objetivo + Contexto + Restricciones + Aceptación" ​

04 Para tareas complejas, elabora un plan antes de actuar ​

05 Niveles de permisos: estrictos por defecto, ampliándose gradualmente según el escenario ​

06 Haz que se valide a sí mismo: probar, verificar y revisar, no te conformes con que solo "termine de escribir" ​

07 Para tareas en producción (online), obtén primero una cadena de evidencias antes de hablar de soluciones ​

08 Delega las tareas pesadas en sub-agentes, y dedica cada hilo a un único propósito ​

09 Lista de comprobación: tabla de "Errores ❌ / Prácticas correctas ✅" ​

10 Resumen ​

Lecturas recomendadas ​