Documentación automática
En esta página
Documentar sin interrumpir el desarrollo
Todo el mundo coincide en que la documentación es necesaria, pero casi nadie la escribe. ¿Por qué? Porque la redacción se produce en el peor momento posible: la funcionalidad está terminada y la atención ya ha pasado a otra cosa. Codex traslada este coste. Analiza el código tal como existe y genera documentación completa y actualizada que se ajusta a la implementación real. Esta fidelidad es el factor decisivo: una documentación inventada causa más daño que una página en blanco porque inspira una falsa confianza.
Documentación integrada: JSDoc y comentarios
La documentación más consultada aparece directamente en la información emergente del editor, justo donde surge la duda.
"Añade documentación JSDoc a todas las funciones
y tipos exportados en src/lib/. Incluye una descripción,
parámetros, tipo de retorno y un ejemplo de uso
para cada función."
Esto es lo que produce Codex para una función de cálculo de precios:
/**
* Calcula el precio total tras aplicar el descuento.
*
* @param basePrice - Precio unitario en céntimos
* @param quantity - Número de unidades (mínimo 1)
* @param discountPercent - Porcentaje de descuento (0-100)
* @returns El precio total en céntimos, redondeado a un entero
*
* @example
* calculateTotal(1000, 3, 10) // 2700 (30€ - 10% = 27€)
*
* @throws {ValidationError} Si el precio o la cantidad son negativos
*/
export function calculateTotal(
basePrice: number,
quantity: number,
discountPercent: number = 0
): number {
// ...
}
Dos datos aquí valen más que todo lo demás: la unidad (céntimos, no euros) y la excepción que se lanza para valores negativos. Estas son precisamente las dos cosas que un desarrollador suele descubrir en producción, después de haber facturado a los clientes diez veces menos de lo previsto. Codex las ha extraído de la implementación, no de una plantilla de comentarios genérica.
Generar un README
Para un proyecto nuevo, o para un README que se ha vuelto ficticio debido a la deriva del código, enumera lo que el lector debe ser capaz de hacer una vez termine la lectura.
"Genera un README.md completo para este proyecto. Incluye:
- Descripción y propósito del proyecto
- Prerrequisitos (Node.js, PostgreSQL, etc.)
- Instrucciones de instalación paso a paso
- Variables de entorno requeridas (sin valores)
- Comandos disponibles (dev, test, build, lint)
- Estructura del proyecto
- Cómo contribuir"
Codex se basa en package.json, los archivos de configuración y el árbol de directorios real para producir un documento que refleje el estado actual del proyecto. La instrucción «sin valores» no es un capricho: sin ella, un agente que acaba de leer un .env.example bien poblado podría copiar alegremente valores que no quieres que aparezcan en un archivo versionado.
Documentación de la API
Para una API REST, la documentación más rentable es aquella que otras herramientas pueden consumir sin intervención humana.
"Analiza todas las rutas en src/api/routes/ y genera
un archivo openapi.yaml. Incluye esquemas de solicitud
y respuesta basados en los tipos de TypeScript existentes
y las validaciones de Zod."
Todo se extrae del código: rutas, métodos HTTP, esquemas de validación y tipos de respuesta. La especificación resultante es, por tanto, fiel a la implementación, lo que permite a tus consumidores derivar un cliente tipado o una colección de pruebas sin hacerte ni una sola pregunta.
Documentación de la arquitectura
Las decisiones de arquitectura rara vez se ponen por escrito. Cuando se hace, describen la intención inicial en lugar de la realidad tres años después. Pide a Codex que formalice lo que realmente existe en el código.
"Analiza la arquitectura del proyecto y crea un
archivo docs/architecture.md documentando:
- Capas (API, servicios, repositorios, modelos)
- Flujo de datos para una solicitud típica
- Patrones utilizados (patrón repositorio, inyección de dependencias)
- Dependencias entre módulos"
Este documento tiene un beneficio secundario inesperado: al describir las dependencias de los módulos tal como son realmente, expone acoplamientos que nadie había reconocido, como el servicio de facturación importando una utilidad desde el módulo de autenticación.
Actualizar documentación existente
La documentación obsoleta es peor que la ausencia de documentación porque hace perder tiempo con autoridad.
"Compara README.md con el estado actual del proyecto.
Identifica secciones obsoletas (comandos que ya no existen,
dependencias eliminadas, instrucciones incorrectas).
Actualiza el README en consecuencia."
Codex confronta cada afirmación del README con el código real y corrige las inconsistencias. Programa esta tarea periódicamente, por ejemplo antes de cada versión, en lugar de descubrir su necesidad el día que un nuevo empleado comprueba que ninguno de los comandos de instalación funciona.
Automatizar mediante AGENTS.md
Para dejar de tratar la documentación como una tarea separada, conviértela en una restricción permanente del proyecto.
## Documentación
- Toda nueva función exportada DEBE tener JSDoc completo
- Los cambios en la API DEBEN actualizar openapi.yaml
- Formato de comentarios: francés para la lógica de negocio, inglés para detalles técnicos
Con estas tres reglas, cada tarea de desarrollo lleva consigo su propia actualización de documentación. La brecha entre el código y la descripción deja de ampliarse en silencio, que es la única forma sostenible de ganar esta batalla.
Puntos clave
- Codex genera documentación fiel al código real, no inventada
- La documentación integrada (JSDoc) es la más útil para el trabajo diario
- Codex puede producir READMEs, especificaciones OpenAPI y documentación de arquitectura
- Usa Codex para detectar y corregir documentación obsoleta
- Añade reglas de documentación a AGENTS.md para automatizar el proceso