Prompts para Generar Documentación Técnica con IA

El README de tu repositorio tiene cuatro meses. Dice “npm install y npm start”, y el proyecto ahora necesita dos variables de entorno, un servicio de base de datos y una clave de API que nadie sabe dónde sacar. Quien entra nuevo tarda dos días en arrancar, y tú repites las mismas respuestas en el chat cada semana.

El problema no es que nadie quiera documentar. Es que documentar es una tarea diferida sin retorno inmediato, y el código cambia cada semana. Escribir a mano es caro justo cuando menos tiempo tienes, así que sale un README a medio hacer en el primer día del proyecto y no vuelve a tocarse.

La documentación generada por IA resuelve el problema de la velocidad, no el del mantenimiento. Y esa distinción es la clave de todo lo que viene aquí: hay documentación que se genera una vez y se queda vieja (la referencia de funciones internas), y documentación que se regenera desde la fuente de verdad (los changelogs, la API, los ejemplos). Solo la segunda aguanta el paso del tiempo.

Antes de nada, una advertencia honesta: esto no sustituye a escribir bien, cambia el reparto del esfuerzo. Tú decides qué merece existir; la IA se encarga del trabajo mecánico de redactarlo con el código delante. Si tienes claro qué necesita un equipo, esto te ahorra horas.

Si ya dominas los prompts básicos, los 20 mejores prompts para programar con IA son la base. Aquí vamos a un terreno distinto.

Cinco cosas que conviene decidir antes de empezar

1. Documenta desde el código, nunca desde la memoria. La IA que no ve el repositorio inventa comandos de instalación que no existen.
2. Une vez al commit, no al final del sprint. La documentación hecha a destiempo siempre pierde contra el código real.
3. Dime el público. “Para alguien que acaba de clonar el repo” y “para un equipo que va a mantener esto dos años” producen documentos completamente distintos.
4. Pide formato de salida explícito. Markdown con esa estructura concreta, YAML válido, tabla de endpoints. Sin formato, te devuelve una prosa que luego hay que limpiar.
5. Exige que omita lo que no puede verificar. Una sección marcada como “pendiente de confirmar” vale mucho más que un párrafo inventado con confianza.

README y el primer contacto

1. README generado desde el repositorio real

Genera un README.md para este repositorio. Antes de escribir, analiza:
- package.json (scripts, engines, dependencias)
- estructura de carpetas (solo a dos niveles)
- archivos de configuración (tsconfig, eslint, vite/next config)
- variables de entorno que aparezcan en el código

Estructura obligatoria:
1. Qué es el proyecto (2 líneas, sin superlativos)
2. Requisitos previos (versiones exactas extraídas del repo)
3. Instalación paso a paso con los comandos reales
4. Variables de entorno en tabla: nombre, ¿obligatoria?, ejemplo, dónde se consigue
5. Scripts disponibles en tabla: comando, qué hace
6. Estructura de carpetas con descripción de una línea por carpeta
7. Cómo ejecutar los tests

Reglas: no inventes nada. Si no puedes verificar un dato, escribe "[PENDIENTE: ...]".
Longitud máxima: 120 líneas.

Por qué funciona: obligar a leer el repositorio antes de escribir es lo que separa un README útil de un README de plantilla. Y el “[PENDIENTE: …]” explícito evita que rellene huecos con invenciones creíbles.

Ejemplo real de la sección que más aporta y que casi nadie incluye:

## Variables de entorno

| Variable | Obligatoria | Ejemplo | Dónde se consigue |
|---|---|---|---|
| `DATABASE_URL` | Sí | `postgresql://user:pass@host:5432/db` | Panel del proveedor |
| `JWT_SECRET` | Sí | (32+ caracteres aleatorios) | `openssl rand -base64 32` |
| `SENTRY_DSN` | No | `https://...@sentry.io/1` | Sentry → Settings |
| `NODE_ENV` | No | `production` | Lo define el despliegue |

2. Sección de instalación sin sorpresas

Tengo este README generado: [pegar].
La instalación real en un equipo nuevo falló porque [pegar error o describir].

Reescribe solo la sección de instalación para que funcione con un sistema
limpio: lista el orden exacto de pasos, qué hay que tener instalado antes,
qué comandos son opcionales y qué pasa si el usuario ya tiene la versión
correcta. Formato: lista numerada de máximo 8 pasos, cada uno con el comando
exacto y una línea de qué debería ver si funcionó.

Por qué funciona: convierte la documentación en algo que se puede ejecutar. Un paso con el comando exacto y el output esperado se depura solo cuando falla; una instrucción en prosa obliga a adivinar.

3. Actualizar el README cuando cambia el código

Este es el README actual: [pegar].
Y este es el diff de los últimos cambios: [pegar diff].

Devuélveme solo las líneas del README que quedan obsoletas, con el antes
y el después. No reescribas el documento entero. Si un cambio no afecta
a la documentación, dilo explícitamente y no toques nada.

Por qué funciona: un diff es la unidad de trabajo real de la documentación. Pedir solo las líneas que cambian convierte una tarea de veinte minutos en una de dos, y reduce mucho el riesgo de que la IA “mejore” partes del README que estaban bien.

4. Onboarding de un dev nuevo

Eres el mentor de un dev que acaba de entrar en este proyecto.
Lista de tareas de su primer día: [pegar].

Dado el repositorio [resumen], genera una guía de onboarding de 1 página con:
- Qué debe entender primero (conceptos del dominio, no carpetas)
- Los 5 archivos que debería leer y por qué, en ese orden
- Cómo levantar el entorno completo desde cero
- Cómo hacer un cambio pequeño y probarlo de punta a punta
- A quién preguntar cada tipo de cosa

Tono: técnico y directo. Sin jerga de empresa.

Por qué funciona: el README dice qué es el proyecto; el onboarding dice qué tiene que entender una persona. Son documentos distintos y casi nadie escribe el segundo.

JSDoc, tipos y documentación en el código

5. JSDoc que describe el comportamiento, no la firma

Documenta esta función con JSDoc: [pegar función con sus tipos].
Contexto de dominio: [qué representa, quién la llama, qué datos toca].

Requisitos:
- @param y @returns con el formato real (no solo el tipo)
- @throws con las condiciones exactas que lanzan error
- Una descripción que explique el porqué y las invariantes, no lo obvio
- Ejemplo de uso real copiado de un test existente: [pegar snippet]
- @see hacia las funciones relacionadas que aparezcan en el código

No documente lo que el tipo ya dice. Si algo no lo sabes, deja un TODO.

Por qué funciona: el fallo del JSDoc generado sin contexto es que repite la firma en prosa. Exigir invariantes, condiciones de error y un ejemplo real de un test obliga a que el comentario diga algo que el tipo no dice.

6. Tipos y contratos

Define los tipos TypeScript para este módulo: [pegar código].
Los datos vienen de: [API externa / base de datos / localStorage].
Formato de respuesta real: [pegar JSON de ejemplo].

Genera:
- Interfaces con los campos opcionales marcados explícitamente
- Tipos discriminados donde haya estados excluyentes
- Runtime validation (zod o equivalente) que coincida con los tipos
- Casos que el tipo no puede expresar y necesitan un comentario
Explica por qué has elegido tipo unión frente a campos opcionales.

Por qué funciona: los tipos generados sin un ejemplo real de payload fallan en los campos opcionales: todo acaba siendo opcional y nada compila. Pegar un JSON de ejemplo ancla la generación a la realidad.

7. Comentarios que sobreviven al refactor

Archivo: [pegar]. Puedo refactorizarlo pronto.
Marca en comentarios los puntos donde el código parece absurdo pero hay un
motivo: workarounds de producción, casos límite raros, decisiones de negocio
ocultas. Para cada uno explica la razón real en 2 líneas.

No comentes lo obvio. Si algo es suficientemente raro como para necesitar
comentario, explica por qué es necesario ese comentario.

Por qué funciona: los comentarios que sobreviven son los que explican el porqué. Este prompt es el inverso del típico “añade comentarios”, y produce documentación que sigue siendo útil cuando el código cambia de forma.

API reference y referencia automática

8. Referencia de API desde OpenAPI

Tengo este YAML de OpenAPI: [pegar extracto o ruta del fichero].

Genera:
- Tabla de endpoints agrupados por recurso: método, path, descripción corta,
  auth requerido, parámetros de path
- Para cada endpoint no trivial: ejemplo de request y response con curl
- Lista explícita de códigos de error que devuelve cada uno
- Notas de los casos límite que no se ven en el esquema
No inventes endpoints que no estén en el YAML.

Por qué funciona: generar desde el esquema es la única forma de que la referencia no se quede obsoleta, porque el esquema se regenera del código. La sección de casos límite es la parte que la IA aporta de verdad, y la que ningún generador automático añade.

Comparativa de fuentes de verdad:

Documento	¿Se regenera?	Herramienta	Cuándo se queda viejo
Changelog	Sí, desde commits	conventional-changelog	Nunca, si es automático
API reference	Sí, desde OpenAPI	docusaurus / redocly	Nunca, si se regenera
README	Parcialmente	Prompt + revisión	En cambios de scripts o env
JSDoc	Con hooks en pre-commit	typedoc / typedoc-plugin-markdown	Con cada refactor grande
ADRs	No, y está bien	Numanji / markdown plano	Cuando la decisión caduca
Tutoriales	No	Manual	En cada cambio de API

Por qué funciona: la tabla convierte el problema de documentación en un problema de arquitectura. Las tres primeras filas son automáticas y no requieren mantenimiento; las tres últimas son deliberadamente manuales.

Changelogs y ADRs

9. Changelog desde Conventional Commits

Genera el CHANGELOG.md para la versión [X.Y.Z] a partir de estos commits
(conventional commits): [pegar output de git log --oneline vX..vY].

Formato Keep a Changelog con estas secciones:
Added / Changed / Deprecated / Removed / Fixed / Security
Agrupa los commits bajo cada sección, reescribiendo el mensaje en lenguaje
de usuario final (no "fix(parser): corrige regex", sino "Se corrigió el error
al procesar archivos con acentos").
Añade la fecha de release y los enlaces de comparación (compare links).
Si un commit no encaja en ninguna sección, omítelo y dilo al final.

Por qué funciona: es una traducción. El commit dice qué cambió en el código; el changelog dice qué cambió para quien usa el software. Esa traducción es justo lo que una IA hace bien y un humano hace lento.

10. ADR para documentar una decisión

Contexto: [qué sistema estamos usando y qué problema queremos resolver].
Opciones consideradas: [A, B, C con sus trade-offs reales].
Decisión tomada: [cuál y por qué].
Consecuencias aceptadas: [qué perdemos por elegir esta].

Genera un ADR en formato MADR:
- Título con verbo en presente: "Adoptamos X para Y"
- 2 párrafos de contexto (sin jerga)
- Tabla de opciones con criterios marcados
- Decisión y sus consecuencias, incluyendo las negativas
- Fecha, estado (propuesto/aceptado) y participantes

Márcalo como "superado" si el ADR reemplaza a uno anterior: [indicar cuál].

Por qué funciona: seis meses después nadie recuerda por qué se eligió Redis. El ADR captura el porqué en el momento en que la decisión está fresca, y la tabla de opciones evita repetir el mismo debate en el futuro.

Mantener la documentación viva

11. Detector de documentación obsoleta

Proyecto: [estructura de carpetas + README + docs/ existentes].
Documentos que tenemos: [lista de rutas].
Código: [los archivos principales o resumen de qué hace cada uno].

Audita qué documentación está obsoleta y devuelve una tabla:
documento, sección, qué dice, qué hace ahora el código, severidad
(alta/media/baja), y qué fichero cambiaría.

Prioriza por severidad. No reescribas nada todavía, solo diagnostica.

Por qué funciona: el diagnóstico automático encuentra el desfase antes de que lo encuentre un usuario. Es el prompt más rentable de la lista cuando entras en un proyecto heredado.

12. Documentación para el equipo, no para el usuario

Audiencia: un equipo de [N] devs que va a mantener este servicio.
Sistema: [stack y servicios].

Genera un documento de contexto técnico que responda:
- Qué hace el sistema y qué NO hace (lo que no hace es lo más útil)
- Los 3 módulos de mayor riesgo y por qué
- Los 5 flujos que no se deben tocar sin revisar a [equipo/persona]
- Qué pasa si cada servicio crítico cae (blast radius)
- Dónde mirar cuando algo falla a las 3 de la mañana
- Qué deuda técnica está documentada y cuál es invisible

Tono: notas de traspaso entre devs, no manual de usuario.
Máximo una página.

Por qué funciona: la documentación que más valor tiene en un equipo es la que explica lo que no es evidente y qué no debes tocar. Eso no sale de un generador automático de README, y por eso es donde la IA sí aporta.

Anti-patrones de documentación con IA

❌ Documentar sin darle el código

❌ Prompts para documentar tu proyecto SaaS de gestión de tareas

Sin el repositorio, la IA produce un README de plantilla que podría ser de cualquier proyecto.

❌ Comentarios que repiten la firma

// ❌ No aporta nada: el tipo ya lo dice
/**
 * Calcula el total.
 * @param {number} price - El precio
 * @returns {number} El total
 */
function total(price, tax) { ... }

// ✅ Dice lo que el tipo no dice
/**
 * Aplica el IVA al precio. El taxRate llega sin decimales: 21 significa 21%.
 * @throws {RangeError} Si taxRate está fuera de [0, 100] o si no hay importe.
 */
function total(price, taxRate) { ... }

❌ Documentar todo por igual

# ❌ Termina documentando los 400 getters de un DTO que nadie lee
npx typedoc --entryPoints "src/**/*.ts" --exclude "**/*.test.ts"

# ✅ Documenta las fronteras del sistema, no cada getter
npx typedoc --entryPoints "src/domain/**/*.ts" "src/api/**/*.ts"

❌ Dejar que la IA escriba el documento final sin revisión

❌ "Genera el runbook de producción y lo subo tal cual"

✅ "Genera el runbook de producción y dame una lista de los puntos donde
   has supuesto algo que no estaba en el repo. Los reviso uno a uno."

Errores frecuentes y cómo salir de ellos

• “Genera documentación que contradice el código”: casi siempre porque le falta contexto. Añade el fichero real al prompt, no una descripción. En proyectos grandes, usa la ventana de contexto para darle el árbol entero, como explico en cómo aprovechar la context window.
• “Se inventa variables de entorno”: pide siempre la tabla con un ejemplo y la fuente. Si un valor no puede verificarlo, debería marcarlo como pendiente.
• “El README creció a 400 líneas”: es señal de que estás documentando implementación en lugar de uso. Recorta y mueve el detalle a ADRs o a la referencia de API.
• “La documentación se queda obsoleta en dos semanas”: vuelve al prompt 3 y al 11. La documentación que se escribe una vez y no se regenera es la que caduca; la tabla de la sección 8 te dice cuál es cuál.
• “La IA reescribe el documento entero y mete cambios de estilo”: pide siempre diffs de líneas concretas, nunca “reescribe el README”.
• “Consumo demasiados tokens documentando”: hay atajos. El caveman prompting funciona especialmente bien para estas tareas mecánicas como generar tablas de endpoints o listas de parámetros.

El flujo completo

┌───────────────────────────────────────────────────────────┐
│  PROBLEMA: el README tiene 4 meses y no arranca           │
└──────────────────────────┬────────────────────────────────┘
                           ▼
┌───────────────────────────────────────────────────────────┐
│  1. Prompt 1 + 2: README y sección de instalación        │
└──────────────────────────┬────────────────────────────────┘
                           ▼
┌───────────────────────────────────────────────────────────┐
│  2. Prompt 4: onboarding (una página, para devs)          │
└──────────────────────────┬────────────────────────────────┘
                           ▼
┌───────────────────────────────────────────────────────────┐
│  3. Prompt 8: API reference desde OpenAPI  (automático)   │
│  ✦ Prompts 9 + 10: changelog + ADRs        (convención)   │
└──────────────────────────┬────────────────────────────────┘
                           ▼
┌───────────────────────────────────────────────────────────┐
│  4. Prompt 3 en cada PR que toque scripts o env           │
│  ✦ Prompt 11 en la auditoría trimestral                   │
└──────────────────────────┬────────────────────────────────┘
                           ▼
┌───────────────────────────────────────────────────────────┐
│  RESULTADO: 3 docs automáticas (no caducan)              │
│            + ADRs, onboarding y contexto (a mano)        │
└───────────────────────────────────────────────────────────┘

Conclusión

La documentación no falla por falta de ganas, falla porque es una tarea diferida sin retorno inmediato. La IA no arregla esa motivación, pero convierte cada tarea concreta en un trabajo de minutos: leer el repo y redactar. Eso ya es la mitad de la batalla.

Lo que de verdad cambia el juego es el reparto. Todo lo que se puede regenerar desde una fuente de verdad (changelog, API reference, ejemplos desde tests) debería estar automatizado y no tocarlo nunca. Todo lo que depende de criterio humano (ADRs, contexto de equipo, decisiones) debería escribirse a mano con ayuda, porque su valor está en que alguien lo pensó.

Y no te lo creas todo. El prompt 11 existe precisamente porque la documentación obsoleta es más peligrosa que la ausencia de documentación: si alguien sigue una instrucción caducada, pierde más tiempo que si no hubiera ninguna. Si además el proyecto es de otro equipo al que estás heredando, el proceso de entenderlo antes de tocarlo lo cubro en prompts para migrar código legacy, y si el proyecto tiene estructura grande, la organización de carpetas importa tanto como la documentación.

Para montar tu prompt a medida, tienes el generador de prompts. Y si quieres ver el otro lado del problema, el código incompleto por lazy coding es lo que pasa cuando la IA se atasca y tú aprietas rápido.

---

Sigue aprendiendo:

• Los 20 Mejores Prompts para Programar con IA
• Prompts para Testear Apps Móviles con IA
• Prompts para Migrar Código Legacy con IA
• Estructura de carpetas en React y Next.js
• Cómo aprovechar la context window de la IA