Escribir documentación con IA: del README al changelog

Para escribir documentación con IA, deja que un agente de programación lea el código y ejecute los comandos que documenta, dale a cada documento un público claro y comprueba contra el repositorio cada función, flag y ejemplo que mencione. Agentes como Claude Code y Codex se manejan bien con las partes tediosas de la documentación: convertir un código en un README, completar docstrings, resumir una versión a partir del historial de git. Su punto débil es la seguridad con la que hablan: describen una opción que suena bien pero que nunca se implementó.

Esta guía cubre qué documentar con un agente, prompts que funcionan para cada tipo de documento, cómo generar changelogs desde git log, cómo mantener la documentación sincronizada, qué lugar ocupa AGENTS.md y cómo revisar la documentación escrita por IA en busca de APIs inventadas.

Un agente, no una ventana de chat

El mayor salto de calidad depende de dónde escribe el modelo. Pegar un archivo en una ventana de chat y pedir documentación le da al modelo un solo archivo y ninguna forma de comprobar nada. Un agente de programación que se ejecuta en tu repositorio puede:

• abrir los archivos a los que llama el código, no solo el que pegaste;
• ejecutar --help, los tests o el ejemplo que acaba de escribir;
• buscar todos los sitios donde se usa una función;
• leer la documentación existente y seguir su estilo.

Todos los prompts de esta guía dan por hecho que el agente se ejecuta en el repositorio. Si aún no tienes uno configurado, cómo usar Claude Code y cómo usar Codex CLI te ponen en marcha.

Decide primero el público

“Escribe la documentación de este proyecto” produce una página genérica. Cada tipo de documento tiene un lector distinto y una fuente de verdad distinta:

Pon el lector y la fuente en el prompt. Cambia el resultado más que cualquier instrucción de estilo.

README

Un buen README responde rápido a cuatro preguntas: qué es esto, cómo lo instalo, cómo lo uso y cómo contribuyo. Pide al agente que lo verifique mientras escribe:

Escribe README.md para este repositorio. Público: un desarrollador que lo ve
por primera vez. Secciones: qué hace (2-3 frases), requisitos,
instalación, inicio rápido, configuración, ejecutar los tests, estructura del proyecto.

Reglas:
- Saca los comandos de los scripts de package.json y del workflow de CI; ejecuta
  cada comando de instalación y de inicio rápido y corrige el README si alguno falla.
- Enumera solo las variables de entorno que el código lee de verdad;
  cita el archivo de cada una.
- Sin badges, sin lenguaje de marketing, sin funciones que no estén en el código.

“Ejecuta cada comando” es lo que convierte un README verosímil en uno correcto. Si el agente no puede ejecutar algo (porque necesita credenciales, por ejemplo), pídele que marque ese paso como no verificado para que lo compruebes a mano.

Referencia de API

En bibliotecas y servicios, genera desde el código fuente todo el material de referencia que puedas y usa el agente para lo que los generadores no saben escribir: visiones generales, ejemplos y explicaciones de comportamientos delicados.

Para una API HTTP, pide al agente que construya la referencia a partir de las propias definiciones de rutas:

Documenta todos los endpoints HTTP de src/routes. Para cada uno: método, ruta,
requisito de autenticación, cuerpo de la petición y parámetros de consulta con
sus tipos, forma de la respuesta, códigos de estado de error. Lee el handler y
el esquema de validación; no lo deduzcas de los nombres. Añade un ejemplo con
curl por endpoint y ejecútalo contra el servidor de desarrollo local.

Si el proyecto ya usa OpenAPI, haz que el agente actualice el archivo de especificación en lugar de escribir una referencia aparte en Markdown, y deja que tus herramientas actuales la rendericen. Una sola fuente de verdad es más fácil de mantener honesta que dos.

Docstrings y JSDoc

Los agentes completan docstrings en todo un módulo muy deprisa, y aquí es donde más a menudo describen lo que una función debería hacer en lugar de lo que hace. Pide el comportamiento que se ve en el cuerpo:

Añade JSDoc a todas las funciones exportadas de src/billing/. Para cada una:
resumen de una línea, @param con tipo y significado, @returns y @throws
para cada error que la función pueda lanzar de verdad (lee el cuerpo y
las funciones a las que llama). Añade un @example solo si lo ejecutas.
No cambies nada de código.

Dos comprobaciones baratas hacen fiables los docstrings:

• TypeScript en proyectos JS: con // @ts-check al principio de un archivo o checkJs en tsconfig.json, TypeScript comprueba los tipos de JSDoc, así que un tipo de @param incorrecto aparece como error.
• Python: los ejemplos escritos en formato doctest (líneas >>>) se pueden ejecutar con python -m doctest module.py -v, así que un ejemplo que se aleja del código falla.

Una regla práctica útil: un docstring debe decir por qué y para qué, no repetir la firma. “Devuelve el usuario” en getUser(id): User es ruido; “Devuelve null para los usuarios con borrado lógico; quien la llame debe gestionarlo” sí aporta. Díselo al agente.

Notas de arquitectura

La documentación de arquitectura es donde los agentes ahorran más tiempo, porque lo difícil es leer mucho código y resumirlo. También es donde mejor se esconden las alucinaciones, ya que nadie revisa un diagrama línea por línea. Ponle límites:

Escribe docs/architecture.md para ingenieros que llegan nuevos al código.
Cubre: los módulos principales y de qué se encarga cada uno, cómo fluye una
petición desde la capa HTTP hasta la base de datos, los trabajos en segundo
plano y los servicios externos.
Para cada afirmación, cita el archivo (y la función) de donde sale.
Incluye un diagrama Mermaid del flujo de una petición.
Marca todo aquello de lo que no estés seguro con "TODO: verify".

Las citas son lo importante: permiten que un revisor compruebe afirmaciones en segundos y muestran qué partes quedarán desactualizadas cuando cambien esos archivos. Deja constancia de por qué se tomaron las decisiones, no solo de lo que existe; un registro breve de decisiones (al estilo ADR: contexto, decisión, consecuencias) envejece mejor que una descripción del código actual. Un mapa del código para agentes de IA trata el problema relacionado de dar a los agentes una visión general por la que puedan moverse.

Changelogs desde git log

Las notas de versión son una tarea perfecta para un agente: la materia prima está en git y el trabajo consiste en filtrar y reescribir para los usuarios. Empieza por el rango desde la última etiqueta:

git describe --tags --abbrev=0
git log v1.4.0..HEAD --no-merges --pretty=format:'%h %s%n%b'

Después, el prompt:

Escribe la entrada de CHANGELOG.md para la próxima versión a partir de
git log v1.4.0..HEAD --no-merges. Público: usuarios que actualizan.
Usa los encabezados de Keep a Changelog (Added, Changed, Deprecated,
Removed, Fixed, Security). Omite refactorizaciones, tests, CI y tareas de mantenimiento.
Reescribe cada entrada en términos del usuario, pon primero los cambios
incompatibles con los pasos para actualizar y deja el hash corto junto a cada entrada.

Si tu equipo escribe Conventional Commits (feat:, fix:, feat!: para cambios incompatibles), menciónalo; el agente puede ordenar por tipo de forma fiable. Si los mensajes de commit son escuetos, deja que el agente lea el diff (git show <hash>) o la pull request enlazada en las entradas que importan. Mantener el hash junto a cada línea agiliza la revisión: compruebas una entrada abriendo su commit.

Mantener la documentación sincronizada

La documentación se pudre porque se actualiza en un paso aparte que nadie programa. La solución es que la documentación forme parte del cambio:

1. Mismo cambio, mismo agente. Añade una línea a las reglas de tu agente: “Cuando cambies comportamiento, flags, variables de entorno o APIs públicas, actualiza la documentación relacionada en el mismo commit”.

2. Pide una revisión de la documentación al final de cada tarea:

   Enumera todos los documentos, secciones del README, docstrings y ejemplos
   que mencionan el código que has cambiado. Actualiza los que ahora estén mal.

3. Comprueba una rama antes de fusionarla: dale al agente el diff (git diff main...HEAD) y la carpeta de documentación y pregúntale qué afirmaciones de la documentación deja en falso el diff.

4. Ejecuta los ejemplos como tests. Los doctests, un script que ejecuta los fragmentos del README o el JSDoc con comprobación de tipos convierten la documentación desactualizada en builds que fallan.

5. Genera lo que puedas. El texto de ayuda de la CLI, las especificaciones OpenAPI y las referencias de tipos generadas desde el código fuente no pueden desviarse.

AGENTS.md no es tu documentación

AGENTS.md (que leen Codex y muchos otros agentes) y CLAUDE.md (que lee Claude Code) son archivos de instrucciones para agentes de programación. Se cargan en cada sesión, así que deben ser breves: comandos de compilación y de tests, convenciones, carpetas que no hay que tocar. Ejecutar /init en Claude Code o Codex genera una primera versión.

Tu documentación para personas tiene otro trabajo y puede ser tan larga como haga falta. Mezclarlas provoca dos problemas: un AGENTS.md largo desperdicia el contexto del agente en cada tarea y un README lleno de reglas para agentes confunde a la gente. Mantenlos separados y enlaza entre ellos:

# AGENTS.md
## Commands
- Test: pnpm test
## Docs
- Architecture overview: docs/architecture.md (read before changing modules)
- When you change public APIs, update docs/api.md in the same commit.

CLAUDE.md vs AGENTS.md explica qué va en estos archivos y cómo compartir un mismo conjunto de reglas entre agentes.

Revisa la documentación escrita por IA en busca de APIs alucinadas

El bug de documentación más dañino es una API que no existe: una opción de configuración, un flag de la CLI o un método que el modelo se inventó porque proyectos parecidos lo tienen. Los lectores confían en la documentación, así que pierden tiempo antes de sospechar que está mal. Revísala a propósito para detectarlo:

• Haz grep de cada nombre. Pide al agente (o a un segundo agente) que extraiga todas las funciones, opciones, flags, variables de entorno y endpoints que menciona la nueva documentación y que busque cada uno en el código. Lo que no aparezca, fuera.

  Extrae todos los identificadores, flags de la CLI, claves de configuración y
  variables de entorno de docs/api.md. Para cada uno, muestra dónde se define en
  el código con archivo:línea, o di NOT FOUND. No edites nada.

• Ejecuta cada ejemplo. Los bloques de código que nunca se han ejecutado son suposiciones.

• Comprueba valores por defecto y límites. Los números (timeouts, tamaños, reintentos) suelen ser inventados; cada uno debería poder rastrearse hasta una constante del código.

• Ojo con el “también admite”. Frases como “también admite configuración en YAML” o “se puede usar con Redis” son relleno clásico. Pide el código que lo hace.

• Usa un segundo revisor. Un agente aparte que revisa la documentación contra el código está menos apegado a ella que el que la escribió. Revisión de código con IA explica cómo configurarlo.

Documentación con AgentVera

AgentVera es una app de escritorio para macOS, Windows y Linux que ejecuta Claude Code, Codex, Gemini CLI y otros agentes CLI uno al lado de otro. Algunas de sus herramientas ayudan con la documentación:

• Redactor y revisor en paralelo: ejecuta un agente que escribe la documentación y otro que la comprueba contra el código en el mismo workspace, o dale al trabajo de documentación su propio worktree.
• Pestaña Specs: enumera los archivos Markdown del repositorio, de más reciente a más antiguo, clasificados en specs, planes y documentos, incluidos los archivos sin commit que los agentes escribieron en otros worktrees. El Markdown se abre en vista previa.
• Brain: lee tu README, ARCHITECTURE, CHANGELOG, ADRs, commits y PRs, enumera las decisiones con sus motivos y marca aquellas cuyos términos ya no aparecen en el código, una señal útil de documentación desactualizada.
• Visita guiada del proyecto: una ejecución de Claude Code de solo lectura que resume el stack, los módulos y los archivos clave de un repositorio, un buen primer borrador para las notas de arquitectura.
• Revisión de código: revisa los cambios de documentación de un agente con el modelo de Claude que elijas, con los hallazgos enlazados a archivo y línea.
• Panel Git: recorre el historial a partir del que construyes los changelogs y deja que Claude Haiku escriba los mensajes de commit con el estilo de tu repositorio, lo que facilita el siguiente changelog.

Conclusión

La IA hace que escribir documentación sea barato, así que el verdadero trabajo es la precisión. Ejecuta el agente dentro del repositorio, dile quién es el lector y dónde está la verdad, haz que ejecute comandos y ejemplos, y construye los changelogs desde git log conservando los hashes. Actualiza la documentación en el mismo cambio que el código, deja AGENTS.md para los agentes y la documentación para las personas, y haz grep de cada nombre documentado antes de publicar. Cuando un documento destape un bug, depurar código con IA sigue a partir de ahí.