Cuando hablamos de documentar un proyecto, mucha gente piensa en comentarios que explican qué hace el código. Pero si hoy estás creando un proyecto real, necesitas archivos que ayuden a otros desarrolladores a usar tu sistema y, cada vez más, a los agentes de IA a entender tu proyecto sin que tengas que explicárselo en cada sesión.

En este artículo te cuento lo que uso a diario para documentar proyectos web con backend y frontend. No es una documentación superproducida, y lo mejor es que casi todo lo puede generar la IA por ti. Lo vemos con un e-commerce de demo, paso a paso.

¿Para quién es la documentación?

Lo más importante es entender a quién va dirigida, porque "documentación" es un término muy genérico:

  • Usuario no técnico: necesita manuales, guías básicas de cómo usar el producto.
  • Desarrollador: necesita mucho más. Referencias de la API, documentación del backend y del frontend y un registro de cambios, porque tiene que mantener, conectar y cambiar el proyecto.
  • Agente de IA: cada vez más código lo escribe un agente. Si la IA genera tu documentación y también la lee para hacer cambios, conviene tenerla como un registro claro de qué hay en el proyecto.

Y un aviso: no vale la pena romperse la cabeza generando toda la documentación posible. Se vuelve verbosa. Lo que sí debería existir es lo esencial, como una referencia de la API o un resumen de qué va el proyecto.

Documentar para la IA: contexto y planes

Cuando hablo de documentación para IA no me refiero solo a resúmenes de funciones. Hay dos piezas nuevas:

  • Archivos de contexto (CLAUDE.md, AGENTS.md): le dan al agente una idea del proyecto antes de que empiece a leer archivos.
  • Planes o specs: archivos Markdown con todas las tareas de un cambio grande. Algunos servicios los llaman artefactos.

¿Jira, Linear, Notion… o simples archivos?

Para planificar existen herramientas de toda la vida como Jira, Linear o Notion. Yo no uso solo una: depende del cliente. Pero si te fijas, todo lo que acabo de mencionar son archivos, y esos archivos pueden vivir junto a tu código. No se trata de qué suscripción pagar, sino de entender el concepto.

La demo: una API de e-commerce

Para el ejemplo pedí a la IA una API básica de e-commerce, con productos y categorías, usando Express y PostgreSQL con Prisma. El lenguaje da igual: la documentación es un concepto genérico que se aplica a cualquier stack.

Documentar la API

Lo primero que pido es la documentación de la API, empezando por una pregunta: "¿qué opciones tengo para documentar la API?". Hay varios enfoques:

  • Comentarios en el código con JSDoc, un generador de documentación para JavaScript a partir de comentarios. En TypeScript existe TSDoc, un estándar de Microsoft para esos comentarios.
  • Una página aparte generada desde tus esquemas. Es lo más ordenado y lo puedes compartir con otro desarrollador.

OpenAPI a partir de los esquemas de Zod

En mi proyecto, la IA propuso usar Zod (la biblioteca que valida que las rutas reciban los datos correctos) y convertir esos esquemas en documentación OpenAPI.

OpenAPI es una especificación estándar para describir APIs HTTP, de modo que personas y máquinas entiendan qué hace un servicio sin leer su código. Su versión más reciente es la 3.2.1. No la confundas con OpenAI: OpenAPI solo sirve para documentar.

En Node hay bibliotecas como @asteasolutions/zod-to-openapi o zod-openapi que generan el documento desde tus esquemas Zod. Para mostrarlo como página se usa swagger-ui-express (o alternativas como Scalar):

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(openApiDocument))

El resultado es una página con todas las rutas, sus categorías y ejemplos, sin que el modelo escriba estilos ni HTML. Es mucho más fácil de leer que revisar endpoint por endpoint, y si otro desarrollador necesita usar tu API, solo le pasas la URL de la documentación.

Ojo: esto no termina aquí. Cada cambio en la API obliga a revisar que la documentación siga al día. Por eso la documentación va de la mano del testing (tema para otro video).

Planes y specs en la carpeta docs

La documentación de la API es para alguien de fuera. Para quien trabaja dentro del proyecto, creo una carpeta docs en la raíz y ahí guardo los planes. Por ejemplo:

Crea un plan para añadir soporte de pagos con Stripe y guárdalo en docs.

Genera un Markdown con los pasos. Lo bueno es que los planes se pueden avanzar en paralelo: con otro agente puedo pedir un plan para un sistema de afiliados, y en Claude puedo pedir varios agentes a la vez (un acortador de URLs, analíticas, despliegue…).

Esto no es vibe coding, que es pedir un módulo pequeño e iterar. Aquí generas planificaciones o specs de módulos grandes, revisas que las tareas tengan sentido y recién entonces las implementas. Es la misma idea de herramientas como GitHub Spec Kit ("define el qué y el porqué antes de decidir el cómo"). La guía de buenas prácticas de Claude Code también la recomienda para features grandes: explorar, planificar, implementar (Claude Code best practices).

Dos consejos:

  • Lee los planes. En VS Code puedes abrir el Markdown en vista previa (F1 → Open Preview). Aunque no entiendas todo, investiga, porque la IA puede proponer cambios que no son los adecuados.
  • Borra los planes ya implementados. No hace falta guardarlos todos.

Si quieres avanzar varios planes a la vez, mira los git worktrees: permiten tener varias copias de trabajo del mismo repo, cada una en su rama, para que cada agente trabaje en la suya. Tengo un video sobre eso: Git Worktrees con agentes.

Archivos de contexto: CLAUDE.md y AGENTS.md

El archivo de contexto no es documentación del proyecto en sí. Sirve para que tu agente sepa de qué va y para dejarle reglas que no quieres repetir en cada sesión:

  • En Claude Code es CLAUDE.md. Con el comando /init, Claude analiza el proyecto y genera uno con los comandos, los tests y las convenciones.
  • AGENTS.md es un formato abierto para guiar agentes de código, y lo leen Codex, Cursor, GitHub Copilot, Gemini CLI y muchos más. Según la documentación de Claude Code, ahora Claude también lee AGENTS.md si no hay CLAUDE.md.

Qué sobra en tu CLAUDE.md

El archivo que genera /init suele ser largo y repetitivo. Como el modelo lo lee en cada sesión, no conviene llenarlo de cosas innecesarias:

  • Los comandos ya están en el package.json, y el agente los puede leer.
  • No hace falta explicarle que hay una carpeta frontend.
  • Lo que un modelo ya sabe hacer (cómo validar con Zod, cómo manejar errores) sobra. Basta con algo como "la documentación usa OpenAPI".
  • La arquitectura sí puede ir, si el proyecto es complejo.

Anthropic va en la misma línea: recomienda mantenerlo por debajo de 200 líneas, porque los archivos largos consumen contexto y reducen cuánto los sigue el modelo. Su prueba es simple: de cada línea, pregúntate si quitarla haría que Claude se equivocara; si no, bórrala (memoria de Claude Code).

Documentar el frontend con Storybook

Después pedí un frontend básico con Vite y React que consumiera la API. Para documentarlo hay dos niveles:

  • Código: TSDoc, igual que JSDoc en el backend, para funciones y utilidades.
  • Componentes: Storybook, que te da una página donde ves y pruebas cada componente sin instalarlo en otra parte, con sus propiedades y ejemplos.

Storybook vale la pena cuando tienes componentes reutilizables (tablas, formularios, botones) y un proyecto que va a crecer. En uno pequeño no compensa, y la propia IA me lo dijo. Para la demo le pedí crear páginas que reutilizaran componentes y luego montar Storybook.

Dos datos extra:

  • Storybook tiene un MCP oficial, todavía en preview, para que los agentes lean la documentación de tus componentes y los reutilicen (Storybook MCP).
  • Si buscas algo más ligero, Ladle es una alternativa basada en Vite: una página con la lista de tus componentes y un buscador.

Changelogs: el historial de cambios

Cuando el proyecto crece y tiene muchas versiones, ¿cómo te enteras de qué cambió? Los commits sirven de registro (git log), pero no son documentación. Para eso está el changelog:

Crea un changelog y guárdalo en docs.

Genera un CHANGELOG.md con un resumen por versión. Un formato muy usado es Keep a Changelog: agrupa los cambios en Added, Changed, Fixed, etc. Se acompaña de versionado semántico (MAJOR.MINOR.PATCH).

Lo interesante es que el changelog también tiene un destinatario:

  • Técnico, si haces una API, una biblioteca o un SDK.
  • Para el cliente, si quien lo lee no sabe de código. Algo como "se añadió una nueva página" o "se mejoró el rendimiento de tal sección". Le puedes pedir a la IA que lo reescriba en ese tono.

También puedes tener una carpeta docs/changelogs con un archivo por versión y fecha. Y si el proyecto ya existe, pídele "dame un changelog de todo lo que se hizo en el mes": como tiene acceso a tus commits, lo escribe por ti.

Documentación fuera del repositorio

No todo tiene que vivir en el repo. Si prefieres una herramienta externa, mi recomendación es Linear: sirve para administrar proyectos, guardar planificaciones divididas en tareas y changelogs. Además tiene MCP oficial para que tu agente trabaje con él (Linear MCP). Notion y Jira (vía el MCP de Atlassian) también tienen el suyo.

Mi propio sistema

Yo voy un paso más allá. Estas herramientas son, al final, sistemas de notas, así que creé mi propio project manager. Registro los proyectos activos e inactivos, genero tareas y guardo changelogs. Como es mío, lo conecto con un agente (por ejemplo Hermes) mediante una herramienta de consola. El agente escribe el código y la documentación, la guarda en mi sistema e incluso puede enviarle el changelog al cliente por correo.

Si sabes de desarrollo, crear algo así no es complicado, y tienes toda tu planificación en tu propia base de datos.

Conclusión

  • La API, documentada con OpenAPI: quien la use no tiene que preguntarte qué hace cada endpoint.
  • Planes en Markdown antes de escribir código: los revisas, los avanzas en paralelo y los borras al terminar.
  • Un CLAUDE.md corto y changelogs para el cliente: el agente arranca con contexto y tu cliente sabe qué cambió.

Una advertencia final: que la IA genere todo esto no lo vuelve mágico. Tienes que leerlo, sobre todo cuando el proyecto importa. Si no, estás dejando que la IA diseñe tu sistema sin supervisión. Tu trabajo ya no es tanto escribir código como verificar que el sistema esté bien hecho.

¿Qué tipo de documentación usas en tus proyectos? Déjamelo en los comentarios del video.

Fuentes