Pide, revisa, publica
Publicación reproducible de datos con Quarto y agentes de programación con IA
Quarto, publicación reproducible, agentes de programación, Markdown, Python, EPUB, análisis de datos, k-means
Prefacio: cómo usar este libro
Cambia un número en un conjunto de datos: ¿cuántos documentos quedan mal? Si ese número se copió a mano en un informe, una diapositiva, un correo y una página web, nadie lo sabe sin ponerse a buscar. Este libro enseña una forma de publicar en la que no hay nada que buscar: escribes una sola vez, en texto plano, y una página web, un documento de Word, un PDF, diapositivas, un libro electrónico, un sitio web, un blog y un dashboard se reconstruyen todos desde esa única fuente con un solo comando. El programa que los reconstruye es Quarto.
Este libro trata de producir documentos con calidad de publicación, reproducibles a partir de sus datos y su código, a una velocidad que los agentes de programación hicieron posible hace muy poco. Reproducible significa que cada número, tabla y figura lo calcula un código a partir de los datos, guardado junto a la prosa, así que un solo comando los reconstruye todos y cualquiera puede comprobar cómo se hicieron. Calidad de publicación significa que cada salida sirve al lector que la va a usar: compuesta, con leyendas, con citas y revisada. La velocidad la pone el agente. Los comandos crípticos y la configuración frágil que antes se interponían entre un análisis y su forma publicada e interactiva ya no son el cuello de botella: tú describes el paso, el agente escribe el código y ejecuta los comandos, y tú revisas el resultado.
Quarto es una de tres piezas. Junto con git, que registra cada versión de la fuente, y un servicio de alojamiento como GitHub Pages, que pone el resultado en la web, le permite a una sola persona producir trabajo reproducible y con calidad de publicación para muchos contextos y formatos: una página que se lee en el teléfono, un informe impreso para una reunión, diapositivas en un proyector, un libro electrónico, un dashboard interactivo. Un agente de programación hace el tecleo de las tres, y este libro te enseña a dirigirlo y a revisar su trabajo.
Pide, revisa, publica
El título nombra el método, un ciclo que recorres en cada paso de cada proyecto. Le pides algo a un agente de programación, un programa que escribe archivos y ejecuta comandos cuando se lo pides, y le describes una pequeña tarea, con sus archivos y columnas por su nombre. Es un agente, no un chat, porque actúa: donde un chat web te responde con código para que lo copies y lo ejecutes, un agente edita tus archivos y ejecuta los comandos él mismo, y luego te informa. Revisas lo que hizo: lees lo que cambió, miras el resultado y lo comparas con los datos. Un agente puede ser elocuente, rápido y estar equivocado, así que este paso nunca se salta, y siempre te toca a ti. Luego Quarto publica: reconstruye cada salida desde la fuente revisada, siempre de la misma manera. El Capítulo 1 explica por qué puedes confiar en el último paso, y el Capítulo 2, cómo hacer confiables los dos primeros.
Cada paso práctico a partir de la Parte II da una vuelta al ciclo de la Figura 1.
Para quién es este libro
Escribí este libro para analistas, personas investigadoras, especialistas en ciencia de datos, especialistas en ingeniería de aprendizaje automático, personas fundadoras con perfil técnico, docentes y estudiantes: cualquiera que trabaje con datos y código y necesite compartir los resultados. Sobre todo, es para quienes publican números que cambian: quien hace análisis y copia a mano su informe mensual en Word y PowerPoint, quien investiga y necesita que sus figuras sobrevivan a una nueva ronda de revisión, quien hace ingeniería y redacta cada evaluación tres veces, para un informe, una presentación y una página, y quien funda una empresa y les manda a sus inversionistas una cifra del mes equivocado. Muestra cómo publicarlo todo desde una sola fuente de texto plano, prosa y código juntos, con Quarto. Quarto es software libre y de código abierto, y es software tradicional, no IA, así que la misma fuente siempre construye el mismo informe, presentación o página web: reproducible, interactivo y con calidad de publicación. Con un agente de programación, un trabajo que antes llevaba días ahora lleva minutos. En el camino, explico los conceptos, los argumentos y las decisiones detrás de cada paso.
La reproducibilidad es la razón por la que escribí este libro. Un trabajo que otras personas pueden reconstruir se gana su confianza, justifica las decisiones que se toman con él y les da algo sobre lo cual construir, que es como avanzan la ciencia, la tecnología y el entendimiento. Más automatización significa menos errores y una mejor experiencia, para quienes hacen el trabajo y para quienes lo leen.
Publicar es la mitad del trabajo; la otra mitad es que te lean. El contenido funciona solo si le llega a la gente para la que es, así que el libro trata cada salida como algo que usará un lector concreto, y la revisa como la revisaría ese lector. Espero que mejore las interacciones, y los resultados, de todas las personas que trabajan con datos, software y aplicaciones de IA y tienen que comunicarlos.
Las startups sacan de él un tipo particular de valor, y conviene que conozcan sus límites. El método rinde donde cambian los números de una empresa joven: el informe mensual para inversionistas, el documento técnico (white paper) de un benchmark o de una evaluación, el informe por cliente, el sitio de documentación. Un equipo pequeño que ya vive en un repositorio con un agente lo obtiene casi gratis, y el hábito de revisar evita que un número equivocado llegue a manos de quien invierte. Rinde menos donde dominan el diseño o la coedición: la presentación para inversionistas diseñada a mano, el sitio de marketing y el plan que el equipo fundador comenta en un documento compartido pueden quedarse donde están (Cuándo Quarto no es la herramienta adecuada).
Puede que Quarto, los agentes de programación o ambos sean nuevos para ti. No se da por sentado que sepas programar: explico el Python que escribe el agente, pero no tienes que escribirlo tú. Si la terminal es nueva para ti, el 4 Preparar tu computadora te enseña lo poco que necesitas, un paso revisado a la vez, y el 5 Un primer informe, a mano te la hace usar a mano en un informe real antes de que le encargues a un agente su primera edición. El Apéndice B — Teclas, símbolos y hábitos de la terminal reúne las teclas, las rutas y los mensajes de error que vale la pena conocer. El código del libro es Python; Quarto ejecuta R igual de bien, a través de knitr, pero este libro no lo enseña.
Necesitarás una computadora en la que puedas instalar software (Windows, Mac o Linux), una cuenta gratuita de GitHub y una cuenta con un agente de programación (la Antes de empezar enumera lo que necesita cada uno). Si no puedes instalar software, te sirve un entorno ya preparado en tu navegador (Sin instalar nada: un codespace), y la Antes de empezar da una ruta de bajo costo para conseguir un agente.
Software libre y de código abierto, casi de punta a punta
Casi todo lo que usa este libro es software libre y de código abierto: puedes usarlo, leer su código fuente, cambiarlo y compartirlo, sin costo, en la computadora que quieras. Ubuntu, el Linux que instalan quienes usan Windows y que corre en muchos servidores; la terminal y su shell; Git; Python y los paquetes que usan los proyectos, pandas, matplotlib y scikit-learn; uv; el kernel de Jupyter; y la propia cadena de publicación, Quarto (licencia MIT), Pandoc (GNU GPL) y Typst (licencia Apache 2.0). Los sitios son archivos estáticos simples que cualquier servidor web puede alojar.
Eso importa por algo más que el precio. Un informe construido con herramientas abiertas lo puede reconstruir cualquiera, en cualquier lugar, dentro de muchos años, sin una licencia, una cuenta ni el permiso de la empresa que hizo las herramientas: la reproducibilidad de la que trata este libro depende de eso. Los formatos y las herramientas abiertos también significan que no quedas atado a nadie: la fuente de cada documento es texto plano que te pertenece, y llevarla a otra herramienta, o a otro servicio de alojamiento, es una copia.
La excepción es el agente de programación. El programa que tienes en tu computadora puede ser de código abierto (Codex CLI, de OpenAI, se publica con la licencia Apache 2.0, como se publicó Gemini CLI, de Google; Claude Code, de Anthropic, no lo es), pero los modelos que hacen el razonamiento son propietarios y corren en los servidores de sus proveedores, y usarlos suele costar dinero; la Antes de empezar da el nivel gratuito y las rutas de bajo costo. Así están las cosas mientras se escribe este libro (licencias consultadas el 2026-11-18), y no es una ley de la naturaleza. Los modelos abiertos, y los agentes gratuitos que los ejecutan, podrían cambiarlo, y no tendría que cambiar nada más del método: el agente es la única pieza que podrías reemplazar sin tocar un solo archivo fuente.
Encuentra tu ruta
No hace falta que leas el libro en orden. Busca tu perfil en la Tabla 1 y lee los capítulos que enumera; cada ruta termina en una salida terminada y se salta lo que se escribió para otras personas. Todas las rutas empiezan con el 1 Publicar algo que se reconstruye solo y el 2 Trabajar con un agente de programación, que son cortos y son el método.
| Tu perfil | Luego lee | Tu primera salida terminada |
|---|---|---|
| Analista que produce informes periódicos | 3 La vía rápida, 10 Un solo conjunto de resultados; luego el informe de métricas del epílogo | un informe en HTML y Word que se reconstruye con los datos del mes siguiente |
| Especialista en ciencia de datos, o en ingeniería de ML, de IA o de investigación | 3 La vía rápida, 10 Un solo conjunto de resultados | un informe de evaluación y una ficha del modelo (model card) a partir de un solo archivo de resultados, en una rama lista para revisión |
| Persona fundadora con perfil técnico, o equipo que recién empieza | 3 La vía rápida, 10 Un solo conjunto de resultados, 14 Informes que se generan solos, 16 En el trabajo y en una startup; luego el informe para inversionistas del epílogo | un informe de evaluación y una ficha del modelo que inversionistas y clientes pueden revisar, y un informe mensual para inversionistas que se renderiza solo |
| Profesional de la ingeniería de software | 3 La vía rápida, luego las revisiones de la Calcular una vez, comprobar de tres maneras y la integración continua (15 Pull requests y builds confiables); luego el documento de diseño del epílogo | un informe agregado a un repositorio en una rama, con una guarda, y una comprobación que lo reconstruye en cada pull request |
| Persona investigadora o estudiante de posgrado | Usar IA en una investigación: decláralo y hazte cargo, 3 La vía rápida (después de 4 Preparar tu computadora y 5 Un primer informe, a mano si la terminal es nueva para ti), 10 Un solo conjunto de resultados, luego el análisis del agua (del 17 La pregunta, los datos y las reglas en adelante) | un análisis publicado como informe, diapositivas y sitio web, y un material complementario de investigación |
| Docente | 4 Preparar tu computadora, 5 Un primer informe, a mano, Parte II (de 6 Markdown, renderizado y reglas del proyecto a 9 Publicar y demostrar la reconstrucción), Apéndice I — Darlo como taller | la guía de Londres como sitio web, y el taller para enseñarla |
| Estudiante | Usar IA en una investigación: decláralo y hazte cargo, 4 Preparar tu computadora, 5 Un primer informe, a mano, Parte II, el informe de curso del epílogo | un informe de curso que quien lo califica puede reconstruir |
| Sin experiencia con la terminal | 4 Preparar tu computadora, 5 Un primer informe, a mano, Parte II, el análisis del agua | la guía de Londres en su propio sitio web |
Si ya usas una terminal y Git, la vía rápida de la Parte I (3 La vía rápida) reemplaza sus dos capítulos para principiantes; si no, empieza por ellos, y toma la vía rápida después para llegar a la Parte III.
Los tres ejemplos del libro
Cada concepto está ligado a uno de tres proyectos, cada uno construido con datos reales y citados.
Una guía para visitantes de Londres (Parte II). Para la oficina de turismo de la ciudad, escribes una sola guía que se convierte en una página web, un informe en Word para los socios, un folleto impreso, un dashboard para la gerencia y un sitio web publicado. Cada cifra de visitantes que contiene, desde las 7,116,929 visitas al Natural History Museum (South Kensington) en 2025 hacia abajo, se calcula a partir de los conteos que publica la Association of Leading Visitor Attractions (ALVA).
Una evaluación de modelos en una startup (la vía rápida y la Parte III). Acme Signals, una empresa ficticia de dos personas, ordena los contactos de marketing de un banco para su centro de llamadas y evalúa cada versión de su modelo con los datos reales de Bank Marketing de UCI. Agregas Quarto a su repositorio existente y publicas un solo conjunto de resultados como un informe de evaluación y una ficha del modelo, con cada número leído de los resultados que calcula su propio script.
El riesgo del agua potable en los municipios de Colombia (el análisis del agua, Parte V). Agrupas las zonas municipales de Colombia en tipos según la calidad del agua, los servicios y el contexto, de 2016 a 2023, comparas resultados de salud y educación entre los tipos y publicas el análisis como informe, diapositivas, entrada de blog y sitio web, todo desde un solo script de análisis. La mayoría de los datos son datos abiertos colombianos, unidos por los códigos oficiales de los municipios; la precipitación viene de los datos CHIRPS del Climate Hazards Center y la altitud, de los datos de elevación SRTM de la NASA (Apéndice G — Fuentes de datos, licencias y créditos).
Cómo está organizado el libro
La Parte I cubre lo que necesitas primero: qué hace Quarto (1 Publicar algo que se reconstruye solo) y cómo trabajar con un agente de programación de forma segura (2 Trabajar con un agente de programación), y luego una de dos rutas. La vía rápida (3 La vía rápida) agrega Quarto a un repositorio existente; la ruta desde cero prepara tu computadora (4 Preparar tu computadora) y te hace construir a mano un primer informe (5 Un primer informe, a mano): lo renderizas, lo revisas contra sus datos, lo registras con Git y deshaces tú un cambio antes de que un agente haga alguno. La cuenta de GitHub que pide es gratuita; la de un agente puede no serlo. Claude Code, por ejemplo, necesita un plan de pago o facturación por uso (consultado el 2026-11-18; la Antes de empezar enumera lo que necesita cada agente, y una ruta de bajo costo). La Parte II construye la guía de Londres, un formato a la vez, y es donde se ven los fundamentos en profundidad. La Parte III es el oficio de los formatos de salida que se les piden a los profesionales, a partir de un solo conjunto de resultados de evaluación. La Parte IV los lleva a un equipo y a una organización: pull requests, integración continua, datos confidenciales y herramientas aprobadas. La Parte V, el análisis del agua, construye un análisis completo, explicando la estadística en el camino. Cada proyecto termina cambiando un dato de entrada o un ajuste y explicando qué cambió en la reconstrucción. El epílogo propone cinco proyectos que llevan el método a tu propio trabajo, un informe de métricas, un material complementario de investigación, un informe de curso, un informe mensual para inversionistas y un documento de diseño con números en vivo, cada uno reconstruido desde una copia nueva de su repositorio (Epílogo). Los apéndices contienen la preparación en Windows, las teclas y los hábitos de la terminal, una hoja de referencia, la solución de problemas, todos los puntos de control, las fuentes de datos, cómo está hecho este libro y los datos que cambian, con sus fechas.
Al terminar el libro podrás:
- explicar cómo Quarto convierte una sola fuente en muchos formatos, y por qué cada reconstrucción da el mismo resultado;
- dirigir un agente de programación de forma segura: una carpeta propia, reglas escritas, un paso por prompt, cada uno terminado en una comprobación, y tareas más grandes solo cuando sus comprobaciones pueden ejecutarse sin ti;
- agregar Quarto a un repositorio existente, y revisar el cambio de un agente como un pull request y como un clon nuevo;
- publicar un solo conjunto de resultados para varios lectores, con una guarda en cada oración cuyas palabras dependen de los datos;
- predecir qué salidas actualizará un dato de entrada que cambia, y comprobar que la reconstrucción hizo exactamente eso.
Tu primera tarde
La Parte I cabe en una tarde, y termina con algo que mostrar. El 1 Publicar algo que se reconstruye solo y el 2 Trabajar con un agente de programación son lectura: nada que instalar, nada que escribir. Si ya usas una terminal y Git, el 3 La vía rápida te lleva de ahí a un informe en tres formatos en menos de una hora. Si no, el 4 Preparar tu computadora prepara tu computadora en seis pasos, cada uno con una comprobación; calcula alrededor de una hora. El 5 Un primer informe, a mano es la primera recompensa, unos 45 minutos frente al teclado: copias un informe pequeño, lo renderizas tú, comparas sus números con los datos y encuentras el que está mal, empiezas un historial de Git, cambias un dato de entrada y lo deshaces, y cometes a propósito tres errores frecuentes para leer sus mensajes. Todo se escribe a mano excepto el último paso, la primera edición del agente, que revisas con Git antes de quedártela.
Cómo es un paso práctico
Cada paso es un recuadro de tres partes, explicado en la Cómo leer los recuadros del agente: el prompt exacto que le das a tu agente, lo que probablemente ejecutará y las pocas cosas que solo tú puedes hacer. Los prompts son ejemplos, no transcripciones: los agentes varían, así que revisa el resultado y no la redacción. Cinco tipos de recuadro se salen del texto principal; aquí va uno de cada uno.
Un número calculado a partir de los datos no puede contradecir a los datos. Los recuadros como este explican el mecanismo detrás de un paso, para que puedas adaptarlo a tu propio proyecto.
Un renderizado que empieza mientras una vista previa en vivo está renderizando el mismo archivo choca con ella. Los recuadros como este describen fallas que se ven en la práctica, y cómo evitarlas.
Pide un paso por prompt: un cambio pequeño se revisa rápido, y cuando algo se rompe sabes qué paso lo rompió. Los recuadros como este reúnen criterios y hábitos.
El agente informa que el renderizado terminó sin errores. ¿Está revisado el trabajo?
Todavía no: un renderizado limpio demuestra que el código se ejecutó, no que sus números sean correctos. Los recuadros como este hacen una pregunta para que la respondas antes de seguir leyendo; la respuesta viene después.
Los pasos marcados como opcionales son para quienes llevan ventaja; nada de lo que sigue depende de ellos.
Tres maneras de recorrerlo
Según tu perfil. Sigue tu ruta en la Tabla 1. Cada capítulo práctico termina en un punto de control o en un ejemplo terminado, donde puedes parar y retomar más tarde.
El camino esencial. Las partes II y V son largas porque explican, pero el camino que las recorre es más corto. En una primera lectura, deja para después las secciones marcadas (opcional) en su título, los desafíos adicionales del análisis del agua y su ruta que construye el modelo en lugar de usarlo: nada de lo que sigue depende de ellos. Lo que queda es lo esencial:
- Parte II: Markdown y las reglas de la guía (6 Markdown, renderizado y reglas del proyecto); números calculados y una sola fuente en tres formatos (7 Documentos que calculan); tres públicos desde un solo prompt (8 Una guía, cinco públicos); Git, la publicación y un dato de entrada cambiado (9 Publicar y demostrar la reconstrucción).
- Parte III: un solo conjunto de resultados, una ficha del modelo y un informe (10 Un solo conjunto de resultados), después de la vía rápida (3 La vía rápida).
- El análisis del agua: la pregunta, los datos y las reglas (17 La pregunta, los datos y las reglas); un capítulo por cada paso del análisis, desde la exploración (18 Mira antes de modelar) hasta la comprobación dentro de cada clúster (22 Correlación no es causalidad), copiando el script terminado de cada bloque a partir del agrupamiento (Usar el modelo, o construirlo); luego el informe, las diapositivas, el sitio web y un ajuste cambiado (23 Publicar en muchos formatos).
Al ritmo del taller. El libro nació de un taller de seis horas y conserva su forma, a la vez que explica lo que en el taller solo había tiempo de mostrar: por qué funciona cada paso, dónde falla y cuándo no conviene darlo. El Apéndice I — Darlo como taller tiene la agenda del día y los capítulos que cubre cada bloque (Tabla I.1 y Tabla I.2).
Cuando te trabes
Te vas a trabar: una instalación falla, un prompt sale mal, un renderizado se detiene con un error que nunca habías visto. Es lo esperable, y el libro está hecho para eso. Cada bloque práctico termina en un punto de control, una carpeta del repositorio del taller (checkpoints/), la copia de los archivos del taller que descargas durante la preparación (Paso 5: ejecuta la comprobación de la preparación). Contiene el proyecto tal como debería estar en ese punto, con un README que enumera los pasos para ponerte al día. En un taller, la regla es simple: dos minutos sin avanzar, ponte al día. Donde el libro llega a un punto de control, un recuadro para ponerte al día te da la línea que debes pegar en tu agente (Figura 2).
Si lees por tu cuenta, tienes un tiempo que la sala no tiene, así que dedica primero unos minutos a un diagnóstico. Cada paso usa solo lo que enseñan el 4 Preparar tu computadora y el 5 Un primer informe, a mano:
- ¿Dónde estás?
pwdmuestra la carpeta; los comandos del proyecto solo funcionan dentro de ella. - ¿Qué cambió?
git statusenumera los archivos que cambiaron desde tu último commit, ygit diffmuestra cómo, incluidos los cambios que no querías hacer. - ¿Qué dice el error? Lee su primera línea (Leer un error) y búscala en el Apéndice D — Solución de problemas.
- Prueba una corrección, la que señala esa línea, y vuelve a ejecutar el comando.
Si esa corrección no funciona, ponte al día. Después, haz una breve comprobación propia: abre la salida que nombra el README del punto de control y mira que muestre lo que el libro describe en ese punto.
El último paso del README nombra la diapositiva del taller donde reincorporarse. En el libro, ese lugar es el propio recuadro para ponerte al día, así que después de ponerte al día sigues leyendo desde el recuadro. Si te trabaste a mitad de un bloque, ve directo a su recuadro: el punto de control ya contiene los pasos entre donde te detuviste y el recuadro. El Apéndice E — Los puntos de control de un vistazo, y respuestas enumera todos los puntos de control.
Dos ediciones
Este libro viene como libro electrónico (EPUB) y como sitio web, construidos desde la misma fuente: es su propio primer ejemplo del método. La edición web ejecuta todo lo interactivo: las escenas 3-D del mapa de Londres, los pasos de k-means, los clústeres y el relieve de Colombia, y dos exploradores de datos. El libro electrónico muestra cada una como animación o imagen fija, con un enlace a la versión en vivo (la primera, el mapa de Londres, también tiene un código QR). Los lectores que no pueden reproducir animaciones muestran el primer cuadro, pensado como una imagen fija útil, y el sitio web respeta tu preferencia de movimiento reducido.
Versiones y fechas
El libro se construyó y revisó con Quarto 1.10.20 (con su Typst 0.15 integrado), Python 3.12 y uv, en noviembre de 2026. Los datos que cambian, como el precio de un modelo, la cuenta de un agente o los límites de un plan gratuito de alojamiento, llevan la fecha en que se consultaron, y se guardan en un solo lugar, el Apéndice K — Datos que cambian, que una reconstrucción actualiza en todas partes donde aparecen. Algunos habrán cambiado cuando los leas; los principios a su alrededor no deberían haber cambiado.
El Capítulo 1 no necesita nada instalado: empieza por ahí.